Crate miniquad

Help

Available on crate feature dep_miniquad only.

Expand description

miniquad Cross-platform window context and rendering library.

§Miniquad

Miniquad is a manifestation of a dream in a world where we do not need a deep dependencies tree and thousands lines of code to draw things with a computer.

Miniquad aims to provide a graphics abstraction that works the same way on any platform with a GPU, being as light weight as possible while covering as many machines as possible.

§Supported Platforms

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.

§Examples

Imgur

examples/quad.rs: web demo
examples/offscreen.rs: web demo

PonasKovas/miniquad-mandelbrot: web demo

§Building examples

§Linux

cargo run --example quad

On NixOS Linux you can use shell.nix to start a development environment where Miniquad can be built and run.

§Windows

# 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

§WASM

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

And then use the following .html to load .wasm:

index.html

<html lang="en">

<head>
    <meta charset="utf-8">
    <title>TITLE</title>
    <style>
        html,
        body,
        canvas {
            margin: 0px;
            padding: 0px;
            width: 100%;
            height: 100%;
            overflow: hidden;
            position: absolute;
            background: black;
            z-index: 0;
        }
    </style>
</head>

<body>
    <canvas id="glcanvas" tabindex='1'></canvas>
    <!-- Minified and statically hosted version of https://github.com/not-fl3/miniquad/blob/master/native/sapp-wasm/js/gl.js -->
    <script src="https://not-fl3.github.io/miniquad-samples/gl.js"></script>
    <script>load("quad.wasm");</script> <!-- Your compiled wasm file -->
</body>

</html>

One of the ways to server static .wasm and .html:

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

§Android

Recommended way to build for android is using Docker.
miniquad uses slightly modifed version of cargo-apk

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

APK file will be in target/android-artifacts/(debug|release)/apk

With “log-impl” enabled all log calls will be forwarded to adb console. No code modifications for Android required, everything should just works.

§iOS

To run on the simulator:

mkdir MyGame.app
cargo build --target x86_64-apple-ios --release
cp target/release/mygame MyGame.app
cp -r assets MyGame.app
cat > MyGame.app/Info.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleExecutable</key>
<string>mygame</string>
<key>CFBundleIdentifier</key>
<string>com.mygame</string>
<key>CFBundleName</key>
<string>mygame</string>
<key>CFBundleVersion</key>
<string>1</string>
<key>CFBundleShortVersionString</key>
<string>1.0</string>
</dict>
</plist>
EOF

xcrun simctl install booted MyGame.app/
xcrun simctl launch booted com.mygame

For details and instructions on provisioning for real iphone, check https://macroquad.rs/articles/ios/

§Cross Compilation


# 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

§Goals

Fast compilation time. Right now it is ~5s from “cargo clean” for both desktop and web.
Cross platform. Amount of platform specific user code required should be kept as little as possible.
Low-end devices support.
Hackability. Working on your own game, highly probable some hardware incompability will be found. Working around that kind of bugs should be easy, implementation details should not be hidden under layers of abstraction.
Forkability. Each platform implementation is, usually, just one pure Rust file. And this file is very copy-paste friendly - it doesnt use any miniquad specific abstractions. It is very easy to just copy some part of miniquad’s platform implementation and use it standalone.

§Non-goals

Ultimate type safety. Library should be entirely safe in Rust’s definition of safe - no UB or memory unsafety. But correct GPU state is not type guaranteed. Feel free to provide safety abstraction in the user code then!
High-end API, like Vulkan/DirectX 12. Take a look on gfx-rs or vulkano instead!

§Platinum sponsors

Miniquad is supported by:

SourceGear

Modules§

conf: Context creation configuration
date
fs
gl
graphics
log
window: Window and associated to window rendering context related functions. in macroquad <= 0.3, it was ctx.screen_size(). Now it is window::screen_size()

Macros§

count
debug
error
info
log
method_consts
trace
warn
wayland_interface
wl_request
wl_request_constructor

Structs§

Arg: A vtable-erased generic argument. Basically, the same thing as fn f<U>(a: &U), but trait-object friendly.
Bindings: Geometry bindings
BlendState: Pixel arithmetic description for blending operations. Will be used in an equation: equation(sfactor * source_color, dfactor * destination_color) Where source_color is the new pixel color and destination color is color from the destination buffer.
BufferId
BufferLayout
ContextInfo
ElapsedQuery: ElapsedQuery is used to measure duration of GPU operations.
Features
GlContext
GlslSupport
KeyMods
Pipeline
PipelineLayout
PipelineParams
RenderPass
ShaderId
ShaderMeta
StencilFaceState
StencilState
TextureId
TextureParams
Touch
UniformBlockLayout
UniformDesc
UniformsSource
VertexAttribute

Enums§

Backend
BlendFactor: Blend factors.
BlendValue: Blend values.
BufferSource
BufferType
BufferUsage
CompareFunc: Depth and stencil compare function
Comparison: A pixel-wise comparison function.
CullFace: Specify whether front- or back-facing polygons can be culled.
CursorIcon
Equation: Specifies how incoming RGBA values (source) and the RGBA in framebuffer (destination) are combined.
FilterMode
FrontFaceOrder: Define front- and back-facing polygons.
KeyCode: These keycode values are based off of X11’s keysymdef.h. Missing keycodes from that list are given the prefix 0x01.
MipmapFilterMode
MouseButton
PassAction
PrimitiveType
RawId
ShaderError
ShaderSource
ShaderType
StencilOp: Operations performed on current stencil value when comparison test passes or fails.
TextureAccess
TextureFormat: List of all the possible formats of input data when uploading to texture. The list is built by intersection of texture formats supported by 3.3 core profile and webgl1.
TextureKind
TextureSource
TextureWrap: Sets the wrap parameter for texture.
TouchPhase
UniformType
VertexFormat
VertexStep

Constants§

MAX_SHADERSTAGE_IMAGES
MAX_VERTEX_ATTRIBUTES

Traits§

EventHandler: A trait defining event callbacks.
RenderingBackend

Functions§

start: Start miniquad.

Type Aliases§

Context

Crate miniquadCopy item path