Docs menu: Quick start Documentation home
On this page Build A first scene Render to SVG Rasterize to PNG Compile to binary Check the roundtrip Validate and inspect Animation and shaders Run the tests

Quick start

Build the tools, render a first scene, compile it to binary and check the roundtrip.

This page builds the command line tool, renders a scene three ways, compiles it to binary and checks that the binary decodes to the same picture.

Build

The workspace needs the mbfa crate in a sibling directory (../mbfa). The root Cargo.toml lists where each dependency comes from.

cargo build --release

The GPU commands need the gpu feature, which pulls in wgpu and is off by default.

cargo build --release --features gpu

A first scene

The repository's basic_shapes example draws six rectangles, a circle and a line of text. The source and its rendering follow.

basic_shapes rendered
examples/basic_shapes.msx · 25 lines · open in playground · all samples
Source
@CONFIG( version -> "1.0.0" )
@QUICKFUNCS(
  ~shape<object>(type, x, y, w, h, color) {
    return {
      type = type
      x = x  y = y  width = w  height = h
      style = { fill = color, stroke = #ffffff, stroke_width = 1.5, opacity = 1.0 }
    }
  }
)
@DATA(
  scene = { width = 600, height = 400, background = #1a1a2e }
  elements::
    shape("rect",  20,  20, 160, 120, #e94560)
    shape("rect", 200,  20, 160, 120, #4a9eff)
    shape("rect", 400,  20, 160, 120, #22c55e)
    shape("rect",  20, 180, 160, 120, #f5a623)
    shape("rect", 200, 180, 160, 120, #a78bfa)
    shape("rect", 400, 180, 160, 120, #533483)
    { type = "circle", cx = 300, cy = 300, r = 60,
      style = { fill = #0f3460, stroke = #4a9eff, stroke_width = 3.0, opacity = 0.9 } }
    { type = "text", x = 300, y = 390, content = "MSX Basic Shapes",
      style = { fill = #ffffff, font_size = 14, text_anchor = "middle",
                stroke = "none", stroke_width = 0, opacity = 1.0 } }
)

Render to SVG

render evaluates the source and writes SVG. A compiled binary works as input too.

cargo run --release -- render examples/basic_shapes.msx -o out.svg

Rasterize to PNG

rasterize draws the scene on the CPU and always works, with no feature flag.

cargo run --release -- rasterize examples/basic_shapes.msx -o out.png

The CPU rasterizer does not draw text elements, so the caption in the example appears in the SVG output only. The Rendering backends page lists what each renderer supports.

Compile to binary

compile writes the binary form. The output path is required, and the payload is MBFA compressed unless --no-compress is given.

cargo run --release -- compile examples/basic_shapes.msx -o out.msx
cargo run --release -- render out.msx -o recovered.svg

Check the roundtrip

roundtrip compiles the source, decodes the binary, renders both and compares the SVG text. It also compares duration, loop mode and animation tracks with a float tolerance, because static SVG cannot show those.

cargo run --release -- roundtrip examples/basic_shapes.msx

Validate and inspect

cargo run --release -- validate examples/basic_shapes.msx
cargo run --release -- info out.msx

validate parses and checks the schema without producing output. info prints the header and scene statistics for a source or binary file.

Animation and shaders

animate samples a keyframed scene on the CPU and writes a looping GIF.

cargo run --release -- animate examples/orbit_pulse.msx -o out.gif

Shader fills run only on the GPU renderer. Both GPU commands need a build with --features gpu and a GPU adapter, which may be a software one.

cargo run --release --features gpu -- rasterize-gpu examples/shader_orb.msx -o out.png --time 1.5
cargo run --release --features gpu -- animate-gpu examples/shader_orb.msx -o out.gif --duration 4 --fps 24

The Command line reference lists every command and flag. To try a scene without installing anything, the playground runs the SVG renderer in the browser and plays keyframe animation. It has a dropdown of every example in the repository, and a link such as /playground/#example=blend_modes opens one directly.

Run the tests

cargo test -- --nocapture
cargo bench --bench compare