miniquad

Miniquad supports a wide range of platforms and graphics backends:

• Windows: OpenGL 3, OpenGL 2.2
• Linux: OpenGL 2.2, OpenGL 3, GLES 2, GLES 3
• macOS: OpenGL 3, Metal
• iOS: GLES 2, GLES 3, Metal
• WASM: WebGL 1 (tested on iOS Safari, Firefox, Chrome)
• Android: GLES 2, GLES 3

To target the web, add the wasm32-unknown-unknown target and build the example. To serve the resulting .wasm and .html files, you can use basic-http-server.

Build command:

rustup target add wasm32-unknown-unknown
cargo build --example quad --target wasm32-unknown-unknown

Serving the files:

cargo install basic-http-server
basic-http-server .

Miniquad supports both MSVC and GNU targets on Windows. First, add the desired target, then run the example.

Using MSVC:

rustup target add x86_64-pc-windows-msvc
cargo run --example quad

Using GNU:

rustup target add x86_64-pc-windows-gnu
cargo run --example quad

# both MSVC and GNU target is supported:
rustup target add x86_64-pc-windows-msvc
# or
rustup target add x86_64-pc-windows-gnu

cargo run --example quad

You can cross-compile for Windows from a Linux host by adding the x86_64-pc-windows-gnu target and running the example with that target specified.

rustup target add x86_64-pc-windows-gnu
cargo run --example quad --target x86_64-pc-windows-gnu

# windows target from linux host:
# this is how windows builds are tested from linux machine:
rustup target add x86_64-pc-windows-gnu
cargo run --example quad --target x86_64-pc-windows-gnu

To run the quad example on Linux, use cargo:

cargo run --example quad

On NixOS, you can use the provided shell.nix to set up a development environment.

The recommended way to build for Android is using Docker with a modified version of cargo-apk. This command builds the quad example and places the APK in target/android-artifacts/(debug|release)/apk.

docker run --rm -v $(pwd)":/root/src" -w /root/src notfl3/cargo-apk cargo quad-apk build --example quad

With log-impl enabled, all log calls are forwarded to the adb console. No code modifications are required for Android.

The rendering lifecycle follows this pattern:

1. Begin Pass: Use begin_default_pass to render to the screen or begin_pass(Some(render_pass), action) to render to an offscreen target.
2. Clear: Use clear to reset color, depth, or stencil buffers.
3. Draw: Apply pipeline, bindings, uniforms, and call draw.
4. End Pass: Call end_render_pass to finish the current pass.
5. Commit: Call commit_frame to finalize the frame.

Buffers are used to store vertex, index, or uniform data. Use new_buffer to create a resource and buffer_update to modify its contents.

#[repr(C)]
struct Vertex {
    pos: Vec2,
    uv: Vec2,
}
let vertices: [Vertex; 4] = [
    Vertex { pos : Vec2 { x: -0.5, y: -0.5 }, uv: Vec2 { x: 0., y: 0. } },
    Vertex { pos : Vec2 { x:  0.5, y: -0.5 }, uv: Vec2 { x: 0., y: 1. } },
    Vertex { pos : Vec2 { x:  0.5, y:  0.5 }, uv: Vec2 { x: 1., y: 1. } },
    Vertex { pos : Vec2 { x: -0.5, y:  0.5 }, uv: Vec2 { x: 0., y: 1. },
];
let buffer = ctx.new_buffer(
    BufferType::VertexBuffer,
    BufferUsage::Immutable,
    BufferSource::slice(&vertices),
);

To render, you must apply a Pipeline and set the Bindings (buffers and textures).

• Pipeline: Created via new_pipeline with buffer layouts, vertex attributes, a shader, and pipeline parameters. Apply it using apply_pipeline.
• Bindings: Use apply_bindings to set vertex buffers, an index buffer, and textures. You can also use apply_bindings_from_slice for manual control.
• Uniforms: Use apply_uniforms to upload uniform data.
• Viewport/Scissor: Use apply_viewport and apply_scissor_rect to define the rendering area. These should be applied after begin_pass.