feat(codegen): route compressed (ASTC) atlases through the catalog adapter

[apotema]

Problem

The async streaming asset catalog (labelle-engine#450) loads atlases via the assembler-generated ImageBackendAdapter, whose decode/upload call BackendGfx.decodeImage/uploadTexture directly — bypassing gfx's synchronous compressed seam (loadTextureFromMemory). So ASTC blobs always hit the CPU decoder and fail.

Proven on the real flying-platform-labelle game (sokol / Android, Galaxy Tab A7): the menu atlas returned error.LoadFailed until this fix. With it, cold start dropped from ~24s to ~1s.

Fix

The generated adapter now branches on isCompressed:

• decode: if BackendGfx.isCompressed(data), dupe the raw bytes verbatim (the catalog frees them after upload), read dims from the ASTC header via BackendGfx.compressedDims, set .compressed = true, and skip the CPU decoder. Otherwise CPU-decode as before.
• upload: .compressed blobs route through BackendGfx.uploadCompressed (uploaded as-is); RGBA8 goes through uploadTexture unchanged.

Both branches are @hasDecl-guarded (isCompressed/compressedDims for decode, uploadCompressed for upload), so any backend without ASTC support — or a future headless backend — still generates valid code and always CPU-decodes.

compressedDims added to all 4 backends

Added a header-only pub fn compressedDims(data) ?struct { width: u32, height: u32 } helper + gfx.zig re-export to sokol, bgfx, raylib, and wgpu, each reusing its existing validateAstc to read width/height from the ASTC header without decoding. This lets the adapter set correct DecodedImage dims before the (later, main-thread) upload.

Tests

• zig build test passes (assembler codegen + backend_wiring_tests, updated to assert the new compressed branch + @hasDecl guards in the generated text).
• All four backend packages build + pass their unit tests with the new helper: zig build --build-file backends/{sokol,bgfx,raylib,wgpu}/build.zig test.

Required paired PRs (cross-repo)

The generated code references engine.DecodedImage.compressed and the backends' compressed methods. For consumers to compile, these must be released / pinned:

• labelle-engine flow_scanner: prune orphaned generated flow sidecars #632 — DecodedImage.compressed field
• labelle-gfx feat(backends): relocate windowless-SDL desktop gamepad source out of core into assembler (core#28) #271 — Backend wrapper compressed methods
• labelle-cli Android on-device verification: gamepad detection (#248) + analog state (#250) #261 — backend-aware ASTC block size

Epic

Part of the ASTC cold-start epic: labelle-gfx#269.

[cursor]

PR Summary

Medium Risk
Changes the default image load path for streaming catalogs and ASTC atlases; mitigated by comptime @hasDecl gating and requires paired engine/gfx releases for DecodedImage.compressed.

Overview
The generated ImageBackendAdapter now handles ASTC on the async asset-catalog path (engine#450), which previously always CPU-decoded via decodeImage/uploadTexture and bypassed gfx’s synchronous compressed seam.

When a backend exposes the full compressed API (isCompressed, compressedDims, uploadCompressed), decode dupes raw ASTC bytes, reads width/height from the header with compressedDims, sets engine.DecodedImage.compressed = true, and skips CPU decode. upload sends .compressed blobs to uploadCompressed; RGBA8 still uses uploadTexture with an inline struct literal. A comptime supports_compressed flag wraps both branches so backends missing any decl never reference absent symbols at compile time.

compressedDims is added and re-exported on bgfx, raylib, sokol, and wgpu (shared validateAstc logic). backend_wiring_tests assert the new emitted strings and upload call shape.

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

[gemini-code-assist]

Code Review

This pull request introduces a header-only dimensions reading mechanism (compressedDims) for compressed ASTC textures across multiple backends (bgfx, raylib, sokol, and wgpu), allowing the async asset-catalog adapter to retrieve image dimensions without CPU decoding. Additionally, the code generator in asset_wiring.zig is updated to route compressed textures directly to uploadCompressed when supported. The review feedback highlights a potential issue where a backend implementing isCompressed and compressedDims but lacking uploadCompressed could cause a runtime crash. It is recommended to strengthen the @hasDecl guard in the generated code to also verify the presence of uploadCompressed and update the corresponding test assertions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If a backend implements isCompressed and compressedDims but does not implement uploadCompressed (or if it is temporarily disabled/removed), the decode function will still divert and return raw compressed bytes in decoded.pixels. Then, in upload, since uploadCompressed is missing, it will fall back to calling BackendGfx.uploadTexture with the raw compressed bytes, leading to runtime crashes or rendering corruption.

To prevent this, the decode guard should also check for the presence of uploadCompressed to ensure the backend fully supports the entire compressed texture lifecycle before diverting.

    try w.print("{s}        if (@hasDecl(BackendGfx, \"isCompressed\") and @hasDecl(BackendGfx, \"compressedDims\") and @hasDecl(BackendGfx, \"uploadCompressed\")) {{\n", .{indent});

[gemini-code-assist]

Update the test assertion to match the strengthened @hasDecl guard in the generated code.

        try std.testing.expect(std.mem.indexOf(u8, main_zig, "@hasDecl(BackendGfx, \"isCompressed\") and @hasDecl(BackendGfx, \"compressedDims\") and @hasDecl(BackendGfx, \"uploadCompressed\")") != null);

[apotema]

Addressed both Gemini HIGH findings in 2360004.

Fix: The generated ImageBackendAdapter now derives a single comptime flag

const supports_compressed = @hasDecl(BackendGfx, "isCompressed") and @hasDecl(BackendGfx, "compressedDims") and @hasDecl(BackendGfx, "uploadCompressed");

requiring the entire compressed lifecycle (probe + dims + upload). Both the decode divert and the upload arm are wrapped in if (comptime supports_compressed), so a backend that exposes isCompressed+compressedDims but not uploadCompressed no longer emits a dangling reference to the missing decl — the inner block isn't semantically analyzed when the flag is comptime-false, so it compiles and just always CPU-decodes. The previous runtime if (@hasDecl(...) and decoded.compressed) form still analyzed the BackendGfx.uploadCompressed arm and would fail to compile for such a backend.

test/backend_wiring_tests.zig updated to assert the strengthened 3-decl guard and the comptime-gated upload arm.

Verification:

• zig build test green (backend_wiring + codegen tests).
• All 4 real backends standalone EXIT 0: sokol, bgfx, raylib, wgpu.
• The null backend (no compressed decls at all) also compiles EXIT 0 — exercises the comptime-false gate, proving a backend lacking uploadCompressed generates code that still compiles.

[apotema]

The Examples integration test failure was a forward-reference to an unreleased engine field: the generated catalog adapter referenced engine.DecodedImage.compressed and BackendGfx.uploadCompressed for any compressed-capable backend (raylib), but the released/main engine's DecodedImage doesn't have the compressed field yet (it only lands in engine#632). Hence error: no field named 'compressed' in struct DecodedImage at main.zig:486 / :504.

Fixed by adding @hasField(engine.DecodedImage, "compressed") to the supports_compressed conjunction in src/codegen/blocks/asset_wiring.zig. Building against an engine without the field makes the flag comptime-false → the entire compressed decode/upload path is pruned and the example falls back to CPU decode (compiles clean). Against engine#632 + a compressed backend it stays true → ASTC fast path active. This makes the adapter back-compatible, so this PR no longer needs the engine release to land first.

Verified locally (Zig 0.16.0):

• zig build test green (incl. backend_wiring_tests + codegen).
• All 4 backend packages standalone zig build test exit 0 (sokol/bgfx/raylib/wgpu).
• Reproduced the CI Examples integration step (labelle generate + zig build) for the raylib example against a fresh main engine checkout (no compressed field): builds clean now. Confirmed the old gate still fails with the exact no field named 'compressed' error at main.zig:486/:504, and the new @hasField gate fixes it. asset-streaming-smoke (also raylib) builds clean too.

[apotema]

Reverted the `@hasField(engine.DecodedImage, "compressed")` back-compat gate (commit a78b339) per maintainer preference. A silent CPU-decode fallback against an old engine hides misconfigurations, so the codegen now gates `supports_compressed` on exactly the three backend decls (`isCompressed` + `compressedDims` + `uploadCompressed`) again, and this PR simply depends on the engine version that ships `DecodedImage.compressed`.

The Examples integration check will stay RED until engine #632 (which adds `DecodedImage.compressed`) is released and this PR's example engine pin is bumped. That is an intentional stacked-PR forward dependency, not a defect — all other PR work (the comptime-gated decode/upload divert, `compressedDims` on all 4 backends) is intact, `zig build test` is green, and all 4 backend packages build standalone (EXIT 0).