Graphics

Flow draws through a native backend: Cocoa on macOS, SDL2 on Linux and Windows, canvas in the browser. The same source runs live, records deterministically, and compiles to WebAssembly.

Requires FLOW_HOST=python.

The three ways to run it

FLOW_HOST=python flow gfx program.flow                    # live window
FLOW_HOST=python flow window program.flow                 # SDL2 window
FLOW_HOST=python flow record program.flow --frames 200 --gif out.gif

record runs headless and writes PPM frames, or a GIF with --gif. It takes --skip, --out DIR, --fps, --stride, --width, and --keys SPEC for scripted input. Use it whenever you need to show a result rather than watch it, and in any environment without a display.

The API

import "stdlib/gfx.flow"
import "stdlib/keys.flow"     # named key codes

function main() -> i32 {
    let g: Gfx = gfx_open(760, 460, "Title")

    while !gfx_should_close(g) {
        gfx_poll(g)
        if gfx_key_down(g, KEY_ESC) { break }

        gfx_clear(g, 18, 22, 18)
        gfx_fill_rect(g, 100, 100, 60, 40, 30, 160, 60)
        gfx_present(g)

        gfx_wait_frame(g, 60)
    }

    gfx_close(g)
    return 0
}

Colours are i32 in the range 0 to 255. Coordinates put the origin at the top left.

Time behaves differently per backend, on purpose

gfx_time_ms is monotonic real time in a window, virtual in the recorder (exactly one frame per present), and performance.now() in the browser. A recorded run is therefore identical on every machine. gfx_wait_frame paces a live window and does nothing in the recorder.

Pace with gfx_wait_frame rather than a sleep. Without it, a demo runs as fast as the machine allows and its speed becomes hardware dependent.

Text

stdlib/text.flow is the most imported module in the repository. Use it rather than drawing glyphs from rectangles.

grep -n "^export function" lib/stdlib/text.flow | head -20

Read before writing

ls examples/games/           # snake, tetris, 2048, breakout, invaders, pong
ls examples/morphogenesis/   # reaction diffusion, growth
ls examples/graphics/        # gif writer, shaders, text
ls examples/planet/ examples/procgen/

examples/games/snake_gfx.flow is a complete, readable program with a title screen, input edge detection, and a game over state. Copy its structure.

Recording is the deliverable

When the user asks to see something, record it and give them the file:

FLOW_HOST=python flow record examples/games/snake_gfx.flow \
    --frames 200 --gif snake.gif

Frames go under $FLOW_HOME/build/frames_<name>/. The GIF goes where --gif says. Report both paths and the frame count that was actually written, which the recorder prints.

Shaders and 3D

FLOW_HOST=python flow shader program.flow     # Metal fill shader, macOS
FLOW_HOST=python flow demo vulkan basic

stdlib/render3d.flow, stdlib/vulkan_renderer.flow, and docs/language/shaders.md cover the rest. Vulkan on macOS runs through MoltenVK.

Pitfalls

• A window needs a display. In a headless session, use record.
• Key codes are platform values. Import stdlib/keys.flow rather than typing numbers, and say which platform a raw code came from.
• Sample input once per frame and compare against the previous frame for edge detection. Reading a key twice in one frame gives inconsistent results.
• Do not claim a visual result you have not rendered. Record it and look at the frame count.