Performance: first-time asset display causes frame hitches, then stabilizes

[harrytyp]

Description

HD textures are loaded lazily on first use (HdObjectManager / HdCostumeManager texture caches with synchronous PNG decode). The first time an asset is displayed — an object, a costume or a background — the frame rate drops noticeably for a moment, then returns to stable levels.

Observed e.g. in the cannon scene (room 10): the first time the skeleton boats render, there is a visible hitch; subsequent frames are smooth.

Likely cause

Synchronous loadObject / loadCostume / loadBackground (PNG decode + cache insert) running inside the render path (renderHDComposite), blocking the frame while a large texture is decoded.

Possible directions

• Preload / prewarm the texture cache when entering a room
• Asynchronous (background) texture loading
• Move decode out of the render path

Environment

• comiupscale ScummVM fork, HD mode 4x (2560x1920)
• Reproduced headless and on desktop

[harrytyp]

Fixed in 1badac6b — prewarm texture caches on room enter.

Root cause: PNG decode + cache insert ran synchronously inside renderHDComposite whenever an object changed state or a costume cel animated (first ~28 frames after entering a room all at 200-330ms, spikes up to 618ms).

Fix:

• Room-change block prewarms all object states (0-15) + all frames of visible actors' costumes (HdCostumeManager::preloadCostume)
• LRU cache limits raised 64/512 → 2000

Benchmark (room 10, headless): before F1-30 avg=262ms max=618ms; after: one ~15s prewarm frame at room enter, then immediately stable 75-80ms avg / ~120ms max. Room transitions are longer (decode cost lands there); gameplay frames no longer hitch. Async/partial prewarm tracked as later optimization.

[harrytyp]

Progress so far (fixes shipped per release)

v0.0.66 — First attempt: full prewarm on room enter (1badac6b)

Decoded ALL animation frames of every visible actor's costume synchronously on room enter + raised LRU limits (object cache 64 → 2000).

Result: gameplay hitches were gone (27 sluggish frames at 200–330 ms → immediately stable at 75–80 ms), but room transitions took ~15 s, switching back to a room reloaded everything (LRU evicted the old room), and animations could end up half-loaded mid-play. Rejected by user testing.

v0.0.67 — Second iteration: time-sliced prefetch + budget cache (dce22af1)

Replaced the approach with the industry-standard combination:

• Room enter now preloads only the current cels of visible actors + the next ~30 frames of their playing animation (room 10: 561 frames instead of 1.306; ~2–3 s on desktop hardware, once per room)
• Per-frame time-sliced prefetch (max ~12 ms, runs after frame presentation, never blocks rendering): priority 1 = current cels, priority 2 = upcoming animation frames, priority 3 = lazy background loading of all other rooms' object textures (only 600 object PNGs total)
• Budget-based LRU cache (1.5 GB) instead of entry counts — current + previous room stay resident, switching back costs nothing
• Missing frames fall back to 8-bit for 1–2 frames while the prefetch catches up

Benchmark (headless, room 10): one ~7 s prewarm frame (headless CPU; ~2–3 s desktop), then immediately stable at ~76 ms/frame. Room 9: 94 frames prewarm (~2 s), then steady 30 FPS.

Post-v0.0.67: HD hourglass wait cursor (8fda71fc, not yet released)

The original game shows an hourglass while loading; the HD wait icon (obj 257, 0003_system-wait-icon) is now set as the OS cursor during the room-enter prewarm — visible live while the frame is being composited.

Remaining optimization options (analysis)

Option	Effect	Effort	Risk
Parallel PNG decode (thread pool)	3–5× faster load times on multi-core; also speeds up the per-frame prefetch	Medium (~100–150 lines, Common::Thread + queue)	Low (libpng is thread-safe for separate decodes) — recommended next step
Eliminate copyFrom copies (2–3 × 14 MB memcpy per texture in the decode path)	~10–20 %	Small	Low
Re-compress PNGs (filter None + zlib level 1)	20–50 % faster decode	Script only (one-time asset re-save)	Files ~10–30 % larger, assets release must be rebuilt
RGBA raw-disk cache	Decode gone entirely (read only)	Medium	+12 GB disk, invalidation on asset changes
ZIP container (STORE, per AKOS)	Reduces per-file open overhead (matters on SMB)	Medium	Small gain; decode still dominates; hurts asset maintainability — rejected
DDS/BC7 GPU-compressed	No CPU decode, 4–8× less RAM	Large	Software renderer can't use it; alpha-edge quality risk (we just removed halos); asset edits require re-conversion — deferred until assets are final

The dominant cost remains PNG decode (~80–90 % of load time); file-open overhead is secondary (only relevant over SMB). Keeping single PNG files is intentional for maintainability (assets are still being edited/added).

Keeping this issue open until the parallel-decode optimization is done.

[harrytyp]

Parallel PNG decode implemented (d169a445)

The recommended next step from the analysis above is done:

• hd_batch_decode.h: batch PNG decoding with SDL_Thread workers (static partitioning — each thread decodes its own slice, no shared state, no locks; thread-creation failures fall back to inline decode)
• preloadCostumeRange and preloadRoom now decode their batches in parallel (4 workers), results are inserted into the caches by the main thread after join
• Bonus: preloadCostumeRange now only loads frames that actually exist in the requested range — the old version's modulo-wrap also pulled in whole small animations outside the range (room 10: 561 frames → 161)

Benchmark (headless, room 10, 4 cores)

Metric	Before	After
Prewarm frame (room enter)	7.737 ms	1.345 ms (5.8×)
F1–30 average	350 ms	148 ms
Steady state	~78 ms/frame	~80 ms/frame (unchanged)

On desktop hardware the room-enter load should now be well under a second. Remaining options from the analysis (copyFrom elimination, PNG re-compression, RGBA disk cache) are still open — keeping this issue open.