dasOpenGL: async PBO ring for APNG capture

[borisbat]

Summary

Replace the sync glReadPixels in record_tick with a ring of N GL_PIXEL_PACK_BUFFER PBOs so the render loop never blocks on the GPU during APNG capture. Also drop the zlib compression level for the streaming encoder from stbi's default of 8 down to 4 — the encoder worker thread was the actual bottleneck at 1280x720+, and the level-4 tradeoff is right for tutorial-style recordings of bounded duration.

Design

Ring of PBOs (default 4, range [2,8], per-recording override via record_start args):

• write side every tick: glReadPixels into pbos[K%N] with a null offset — returns immediately, GPU finishes asynchronously. Frame's delay_ms is stashed in a parallel ring slot.
• read side (once frames_seen >= N): glMapBuffer on pbos[(K-N+1)%N] (oldest in flight, GPU has long since finished), feed pixels to stbi_apng_frame with the matching delay, glUnmapBuffer.
• record_stop drains remaining N-1 in-flight buffers via the same harvest_one_pbo helper, then glDeleteBuffers.

Knob: var public capture_pbo_count : int = 4 (module default, clamp [2,8]). RecordStartArgs.pbo_count per-recording override; 0 means use module default. RecordStartResult / RecordStatusResult report pbo_count so callers can see the effective ring size.

screenshot stays synchronous — single-shot, no benefit from amortization.

PNG compression level 4 at record_start:

Level 8 caps the single encoder thread around 25-27 fps on a 1280x720 stream — the row-flip + filter + stbi_zlib_compress pipeline is CPU-bound on level 8. Level 4 is 2-3x faster per frame for a minor file-size cost. The comment at the call site flags this as a tutorial-friendly baseline so it's clear where to promote to a compression_level arg if a future caller wants lossless-ish capture.

Numbers

Widgets-tour recording, 1024x720 / 30fps / 16.8s, on the master baseline vs this branch:

Path	frames	dropped	drop rate
sync glReadPixels + level 8	443	128	29%
PBO ring + level 4	448	0	0%

The PBO ring alone (level 8 retained) brought dropped count down modestly but the encoder still couldn't keep up — both knobs together get to zero drops.

Test plan

• Repeat-recording smoke at 1024x720 / 30fps — 0 dropped, 20 MB / 16.8s output
• record_stop drains in flight buffers cleanly (saved frame count matches frames_seen modulo the final partial drain)
• Regression test (test_record_pbo_drops.das) — pending; encoder-bottleneck reframing made it less load-bearing. Will land alongside any future compression_level arg.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates dasOpenGL’s live APNG capture path to avoid render-thread GPU stalls by replacing synchronous glReadPixels with an asynchronous ring of GL_PIXEL_PACK_BUFFER PBOs, and adjusts PNG compression settings to improve throughput of the APNG encoder worker.

Changes:

• Implement a configurable PBO ring (module default + per-recording override) for async readback during record_tick.
• Add PBO drain logic on record_stop, plus status/reporting of the effective PBO count.
• Reduce stb PNG compression level used by the APNG writer to improve encode speed.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

modules/dasOpenGL/opengl/opengl_live.das:318

• stbi_apng_dropped and stbi_apng_end are called without unsafe, but elsewhere (e.g. record_status and stbimage tests) these APNG writer APIs are treated as unsafe. This is likely a compile-time error and/or inconsistent safety annotation usage. Wrap these calls in unsafe(...) / an unsafe {} block (matching the old implementation).

    let dropped = stbi_apng_dropped(recorder.writer)
    let ok      = stbi_apng_end(recorder.writer)