Docs menu: Quick start
Documentation homeOn 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 testsQuick 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.
examples/basic_shapes.msx · 25 lines · open in playground · all samplesSource
@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