[apotema]

Closes the first slice of #122. Extends the per-frame PBO readback that landed for raylib in #120 (labelle-engine#544) to sokol-backend games on GL paths — default sokol-zig picks GLCORE on Linux desktop and GLES3 on Android/web. Metal (Darwin) and D3D11 (Windows) are deferred to slices 2 and 3 of #122 and emit no-op fallbacks here.

What lands in the generated main

(a) Emit-point in the sokol template — new {{preview_readback}} placeholder in backends/sokol/templates/desktop.txt + mobile.txt, sitting right before window.endFrame(). window.endFrame internally calls sg.endPass(); sg.commit(); — glReadPixels on GL_BACK must run before the swap, mirroring raylib's pre-endDrawing placement.

(b) GL backend gating shape — module-scope _sokol_preview_gl_enabled: bool derived from builtin.os.tag (.linux → true, else false; Android is os.tag == .linux with abi == .android, so the single arm covers both desktop GLCORE and Android GLES3). The GL extern decls + constants live inside a _SokolPreviewGl = if (_sokol_preview_gl_enabled) struct { ... } else struct {} namespace — the else struct {} branch has no symbols, so a Metal / D3D11 sokol build never references unresolved GL externs at link time. sokol_clib on Linux already links libGL via the upstream sokol-zig build, so the GL path resolves transitively without needing the per-OS linker shim raylib's #120 added to src/templates/build_zig.txt. Per-frame block + init seed + cleanup teardown are also each wrapped in if (comptime _sokol_preview_gl_enabled) { ... } so the entire path evaporates on Metal / D3D11 builds.

PBO state lives at module scope (_preview_pbos: [3]c_uint, frame counter, last published dims, _preview_pixel_buf, _preview_allocator) because sokol's init / frame / cleanup callbacks have no shared local stack frame. The allocator is stashed in init so frame + cleanup can grow / free the CPU staging buffer without reaching back through g. Cleanup teardown (endFrameStream + glDeleteBuffers + free) runs BEFORE _p.sendBye(.normal) so SHM / PBO unwind happens while the engine still holds the socket open (LIFO with the graceful protocol close).

(c) Test additions:

• "sokol desktop emits PBO readback + publishFrame between flushScene and endFrame" — asserts the GL externs, the _sokol_preview_gl_enabled comptime gate + else struct {} branch, frame counters, beginFrameStream / publishFrame ordering, source-order placement relative to window.endFrame(), cleanup-teardown-before-bye ordering, and that the generated source parses cleanly via std.zig.Ast.parse.
• "raylib desktop still emits its own PBO readback after the sokol slice lands" — regression lock asserting the raylib codepath is untouched (no sokol identifiers leak into raylib output, and vice-versa).
• "non-loop, non-sokol backends do not pull in any preview pixel publish path" — locks the gate so sdl / bgfx / wgpu (loop branch) and wasm-raylib (callback branch, non-sokol) all regress loudly if the conditional ever drifts.

(d) Verified locally:

• zig build && zig build test (Zig 0.16): 297/301 pass (4 pre-existing skipped — Zig 0.16 preview migration stubs), up from baseline 294/298 with the 3 new tests all passing.
• Regenerated examples/sokol/.labelle/sokol_desktop + examples/sokol_imgui/.labelle/sokol_desktop via the assembler binary directly and built both with zig build and zig build -Doptimize=ReleaseSafe. On macOS the comptime gate elides the GL block (Metal default backend) so both link cleanly with the Metal framework and no undefined-symbol errors. Regenerated examples/raylib/.labelle/raylib_desktop and built — raylib codepath unchanged.

(e) Out of scope (explicit, separate slices of #122):

• Metal / IOSurface readback — slice 2.
• D3D11 staging-texture readback — slice 3.
• macOS sokol pixel publish — depends on slice 2's IOSurface path; this PR's Metal build is a no-op fallback on macOS, the control-plane wiring (hello / heartbeat / bye) still works.
• WebGL2 / emscripten preview — limited PBO support, follow-up.
• Other loop backends (sdl / bgfx / wgpu) — separate tickets.

Test plan

• zig build && zig build test clean (297/301 pass, 4 pre-existing skipped)
• Regenerate sokol example with assembler binary and zig build it on macOS (Metal — comptime gate elides GL path)
• Regenerate sokol_imgui example and zig build it on macOS
• Confirm raylib generated game still builds (no regression in feat(raylib): per-frame PBO readback + publishFrame for PIE viewport #120's path)
• Linux end-to-end smoke against editor SHM consumer (depends on CI / Linux hardware; deferred to integration step)
• Real editor PIE viewport rendering — paired with the editor-side ack work

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Adds per-frame GPU readback and shared-memory publishing in the sokol callback lifecycle, which can affect frame timing, GL resource management, and platform-specific build/link behavior. The feature is comptime-gated to GL targets, reducing risk on Metal/D3D11 but still touches critical render-loop ordering.

Overview
Adds preview-mode pixel streaming for sokol builds on GL targets by generating a 3-PBO async glReadPixels readback path and publishing frames via Preview.publishFrame.

The sokol desktop/mobile templates now include a {{preview_readback}} hook placed just before window.endFrame() to ensure readback occurs before the swap/commit, and the main.zig generator injects comptime-gated GL externs + module-scope PBO/CPU buffer state, allocator seeding in init, and teardown (end stream + delete buffers + free) before the graceful bye.

Updates tests to assert the new codegen (gating, ordering, teardown) and adds regression checks that raylib’s existing readback path and non-sokol/non-loop backends remain unaffected.

^{Reviewed by Cursor Bugbot for commit b2a3977. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request introduces Sokol-specific PBO readback for preview mode, implementing a 3-deep PBO ring with asynchronous DMA for OpenGL-based platforms. The changes include new template blocks for initialization, per-frame readback, and cleanup, as well as comprehensive tests for the generated code. Reviewers identified a potential compatibility issue with glMapBuffer on Android GLES 3.0, a logic bug where dimension state is updated even if buffer allocation fails, and suggested checking the return value of glUnmapBuffer to prevent publishing corrupt data.

[gemini-code-assist]

The use of glMapBuffer via @extern may cause issues on Android (GLES 3.0). While glMapBuffer is standard in Desktop OpenGL, it is not part of the GLES 3.0 core specification (which uses glMapBufferRange). Many Android drivers provide it as an extension, but it is not guaranteed to be present as a linkable symbol.

Since this PR targets GLES3 for Android, consider using glMapBufferRange or verifying that glMapBuffer is indeed available on the target Android environments. If you switch to glMapBufferRange, you will also need the GL_MAP_READ_BIT constant (0x0001).

[apotema]

Applied — switched extern to glMapBufferRange (universal across GL 3.0+ and GLES 3.0+) with a new MAP_READ_BIT = 0x0001 constant. Avoids the GLES3 GL_OES_mapbuffer dependency entirely. See e75ed83.

[gemini-code-assist]

If the CPU staging buffer allocation fails (line 1348), the preview readback is effectively disabled until the next window resize. This happens because _preview_last_w and _preview_last_h are updated (lines 1350-1351) even if the allocation fails, preventing the resize block from re-running in subsequent frames.

To make the readback more resilient to transient memory pressure, consider only updating the 'last' dimensions if the allocation succeeds.

                    if (_preview_pixel_buf.len != _needed_bytes) {
                        if (_preview_pixel_buf.len != 0) _preview_allocator.free(_preview_pixel_buf);
                        _preview_pixel_buf = _preview_allocator.alloc(u8, _needed_bytes) catch &[_]u8{};
                    }
                    if (_preview_pixel_buf.len == _needed_bytes) {
                        _preview_last_w = _sw;
                        _preview_last_h = _sh;
                        _preview_frame_idx = 0;
                    }

[apotema]

Applied — _preview_last_w/h (and _preview_frame_idx = 0) now only commit when the alloc succeeded (_preview_pixel_buf.len == _needed_bytes). A transient OOM heals on the next frame instead of stranding the readback. See e75ed83.

[gemini-code-assist]

The return value of glUnmapBuffer is ignored. While usually safe, glUnmapBuffer returns GL_FALSE if the buffer content became corrupt during the mapping (e.g., due to a screen resolution change or context loss). In such cases, the data in _preview_pixel_buf might be invalid and should ideally not be published.

[apotema]

Applied — branched on glUnmapBuffer return; publishFrame only fires when it returns non-zero. Memcpy still runs with potentially-garbage data, but the editor won't see a torn frame. See e75ed83.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit dcaa08c. Configure here.}