Skip to content

feat(resources): load prepared image packs on the 3DS SD worker - #381

Draft
doodlewind wants to merge 5 commits into
feat/offload-imagesfrom
feat/local-resource-packs
Draft

feat(resources): load prepared image packs on the 3DS SD worker#381
doodlewind wants to merge 5 commits into
feat/offload-imagesfrom
feat/local-resource-packs

Conversation

@doodlewind

@doodlewind doodlewind commented Sep 7, 2026

Copy link
Copy Markdown
Collaborator

Apps with a complete local atlas currently stream every missed raster tile from a paired desktop and convert its pixels on the 3DS render path. Add optional io.resource-pack support so installed, prepared images load from SD through a native worker and the existing resource collection lifecycle.

  • createPackedImageCollection uses one cache for an indexed local image and an optional desktop fallback. Views still own demand; cancellation, stale-response release and texture eviction remain in the framework. Disconnected read loaders refuse admission so local work can continue.
  • The desktop writer prepares PICA RGB565 layout and independent zlib records. The reader bounds entries, indices, lengths, staging, file handles and frame admission; validates CRC; and fences old realms. No filesystem calls or pixel arrays enter guest JS.
  • GPU-owned core texture descriptors eliminate the retained CPU pixel copy. The renderer adopts/retires storage after its GPU fence. A 256×256 tile uses 128 KiB GPU RGB565 instead of 256 KiB RGBA8; a shared one-image/mesh materialization budget remains.
  • Document the pack format, installation contract, budgets and diagnostics. PSP and other unsupported hosts retain the explicit desktop fallback.

Validation: 134 core tests; 113 resource/offload/platform tests; actual C worker under ASan/UBSan (stalled reads, corrupted and incompressible entries, exhausted slots, stale tickets, realm reset); TypeScript check; full Pocket Map production and diagnostic 3DS builds. Prepared color-grid bytes matched devkitPro tex3ds 2.3.0 after applying the renderer's vertical origin.

Physical 3DS validation: Pocket Map completed four SD/Mac cold-view pairs and two eight-second diagonal pans, with the requested storage source in every leg and zero native pack failures. Mean resource-ready time was 292.75 ms from SD versus 1,177.50 ms from Mac (4.02×). During the same 320 px/s route, callbacks with at least one target-level tile not ready fell from 96.36% to 13.10%. SD pan completed 63 reads and 61 uploads; Mac pan performed no SD reads or uploads. Both binaries and the complete 354 MiB atlas passed device readback and are installed.

This is one fixed-route run with a 40-entry guest cache, the same prediction policy, annotations disabled and Mac caching enabled. Callback frequency was 54.35/s on SD versus 51.40/s on Mac; it is not a GPU presentation measurement or a sustained-60-FPS result. Target-not-ready counts do not measure blank pixel area. The connected comparison does not verify offline cold startup. Measurement method, receipts and limits.

This is stacked on Draft #377, which remains unmerged; only the SD resource work is in this diff.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant