Skip to content

CF_Readback

Category: graphics
GitHub: cute_graphics.h

An opaque handle representing an async GPU readback operation.

Code Example

Rendering to a canvas with cf_render_to, then reading back pixel data.

// Create a canvas.
CF_Canvas canvas = cf_make_canvas(cf_canvas_defaults(256, 256));

// Queue up draw calls and flush them to the canvas.
cf_draw_sprite(&my_sprite);
cf_render_to(canvas, true);

// Initiate async readback (ends the active render pass automatically).
// Save this [CF_Readback](../../graphics/struct/cf_readback.md) for later! This is an *async* object.
CF_Readback readback = cf_canvas_readback(canvas);

// ...Elsewhere, and some # of frames later...
// Poll each frame until the GPU finishes the download.
if (cf_readback_ready(readback)) {
    int size = cf_readback_size(readback);
    void* pixels = cf_alloc(size);
    cf_readback_data(readback, pixels, size);
    // pixels now holds RGBA8 data (256 * 256 * 4 bytes).
    // ... use the pixel data ...
    cf_free(pixels);
    cf_destroy_readback(readback);
}

Remarks

A readback initiates an async GPU-to-CPU copy of pixel data from a canvas. Poll with cf_readback_ready and retrieve data with cf_readback_data. The pixel format matches the canvas target format (typically RGBA8, 4 bytes per pixel). The GLES backend (which is what web/Emscripten builds use) implements readback synchronously: the copy has already happened by the time cf_canvas_readback returns and cf_readback_ready is immediately true. The API shape is the same either way, so polling code stays portable, but expect a pipeline stall there rather than an async copy.

CF_Canvas
cf_canvas_readback
cf_readback_ready
cf_readback_data
cf_readback_size
cf_destroy_readback