Capture

Write one PNG of the app's rendered output.

The framebuffer is read back at the end of the frame that asked -- after the draw batch is flushed and before the buffers are swapped, so the pixels are the ones just drawn -- and the PNG is encoded and written off the frame thread. This call waits for that write, so it parks the task until the file exists and answers with the write's own outcome.

Legal only in a task, where it parks the task; refused in init!, update!, and render!. Every other waiting effect also works in init!, where it blocks; a screenshot cannot, because what it waits for is the end of a frame and init! runs before the frame loop has drawn one. Spawn a task from update! instead -- on the first cycle if the shot is meant to be of the first frame:

if input.time.cycle_count == 0 {
    Task.spawn!(input, || Shot(Capture.screenshot!("frame0.png")))
}

A headless run has no framebuffer at all and answers Ok({}) without writing, so a screenshotting app still runs under --host-headless.

Only one screenshot can be in flight: a second one while the first is still waiting for its frame is AlreadyPending.

Write one PNG of what a render target holds, at the target's own size.

This is how an app exports an image larger than its window: draw the composition into a Draw.RenderTexture of the size the output needs and export the target rather than the frame. Transparency survives, unlike a screenshot!, whose framebuffer readback is always opaque.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!. Nothing here waits on the frame loop, which is why init! is allowed where a screenshot! cannot be -- but drawing into a target is only possible during render!, so a target no render! has drawn into holds undefined pixels.

The pixels are the ones the last completed render! left in the target, so an app that draws its composition every frame exports what it last showed. The path is resolved under the output directory exactly as screenshot! resolves one.

A headless run has no pixels to read and answers Ok({}) without writing, so an exporting app still runs under --host-headless.

Task.spawn!(input, || Exported(Capture.screenshot_texture!(poster, "poster.png")))

Read the colour of one pixel.

Legal in init!, update!, and tasks; refused in render!.

This is the cheap read. A point needs no allocation and no delivery slot, which a one-pixel read_region! would still take for the same four bytes, so a colour picker should ask for a point.

picked = match Capture.pixel_at!(Screen, { x: 40, y: 24 }) {
    Ok(color) => color
    Err(_) => Color.black
}

Reading Screen costs one full framebuffer readback per frame for as long as the app keeps reading: the host snapshots the frame it presents so that a later update! has defined pixels to look at, and stops snapshotting once a frame goes by with no read. Nothing is snapshotted before the first read, so the first Screen read of a run -- and every Screen read from init!, which runs before any frame -- is Unavailable, and the next cycle's read is not.

Reading Target costs one readback of the whole target per call, however small the point, because that is what the graphics API will give. Read a region once rather than a point many times.

A headless run has no pixels of any kind and answers Unavailable, so an app that reads pixels has to say what it does without them before it can run under --host-headless.

Read a rectangle of a source as packed RGBA8 bytes.

Legal in init!, update!, and tasks; refused in render!.

The bytes are row-major and top-down: four bytes per pixel in red, green, blue, alpha order, width pixels per row, the source's topmost requested row first. A Screen region is always opaque, because reading the framebuffer forces alpha; a Target region keeps the alpha the app drew.

strip = Capture.read_region!(Target(poster), { x: 0, y: 0, width: 64, height: 1 })?

The list is handed over rather than copied, so a large region costs no second buffer -- and, like every other handed-over byte list, it occupies one of a bounded number of delivery slots until the app drops it. A read with no slot free is Busy.

The bound is Capture.max_readback_bytes: a region above it is RegionOutOfBounds rather than something a later frame could take. The per-call and per-frame costs are the ones pixel_at! describes; this is not a per-frame operation on a whole window.

Most RGBA bytes one read_region! may deliver: 128 mebibytes, which is 8192 by 4096 pixels.

screenshot_texture! draws on the same budget, for the same reason: each holds one whole RGBA image in host memory while it works, so the two cannot both be given the whole of it.

A 25 FPS half-scale GIF of at most 300 frames, using fixed-input timing and balanced encoder quality.

Begin recording.

Legal in init!, update!, and tasks; refused in render!.

Frames accumulate until the recording hits its frame cap, Capture.stop! is called, or the app exits -- all three finalize the file.

A rejected start appears as Failed in input.capture on the next cycle; the call itself reports nothing, so the recording's outcome is observed the same way whichever phase started it.

Finish the current recording and write its file.

Legal in init!, update!, and tasks; refused in render!. An encode and a file write would otherwise land in the middle of drawing a frame.

Stopping while idle does nothing. The next input reports the frame count and file size as Finished.