perf(producer): cache transfer-converted hdr image buffers per render job

[vanceingalls]

Summary

Add HdrImageTransferCache — a per-render-job bounded LRU keyed by (imageId, targetTransfer) — so static HDR image layers whose source transfer differs from the render's effective transfer (PQ↔HLG) are converted once per job instead of once per composited frame.

Why

Chunk 8B of plans/hdr-followups.md. blitHdrImageLayer was running Buffer.from + convertTransfer on every composited frame, even though the converted buffer is identical for the entire job. For a multi-second comp at 30 fps this is hundreds of redundant transfer conversions on the hot path.

What changed

• New packages/producer/src/services/hdrImageTransferCache.ts — bounded LRU keyed by (imageId, targetTransfer) that owns the converted HDR rgb48 buffer for static HDR image layers:
  • Same-transfer requests return the source buffer untouched (zero copy).
  • Cross-transfer requests pay one Buffer.from + convertTransfer on first miss, reuse the cached copy on every subsequent frame.
• Wired into renderOrchestrator.ts via HdrCompositeContext.hdrImageTransferCache, instantiated once per render job, and consumed by blitHdrImageLayer on both the main composite path and the transition path.

Test plan

• packages/producer/src/services/hdrImageTransferCache.test.ts — 12 tests:
  • hit/miss semantics
  • distinct keys per image and per target transfer
  • LRU eviction + promotion
  • maxEntries=0 passthrough
  • source-buffer immutability for cached entries
  • invalid options
• Re-ran the Chunk 8A HDR benchmark — for the hdr-regression fixture (which has cross-transfer image layers) the cache hits 100% after the first frame; for HDR fixtures without cross-transfer images the same-transfer passthrough is a no-op.

Stack

Chunk 8B of plans/hdr-followups.md. Sits on top of Chunk 8C (logger gating) and Chunk 8A (benchmark harness) so the win is measurable.

[vanceingalls]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• docs(engine): document __name polyfill and add regression test #385
• perf(producer): cache transfer-converted hdr image buffers per render job #384 👈 (View in Graphite)
• perf(producer): gate per-frame debug meta via optional isLevelEnabled #383
• perf(producer): hdr benchmark harness — --tags filter, peak heap/RSS tracking, bench:hdr script #382
• test(producer): extract frameDirMaxIndexCache to its own module and pin cross-job isolation #381
• test(engine): cover spawnStreamingEncoder lifecycle and cleanup paths #380
• test(engine): add ffprobe-unavailable fallback regression tests #379
• test(shader-transitions): add midpoint (p=0.5) regression invariants for all shaders #378
• test(engine): lock down sRGB→BT.2020 LUT with byte-exact reference values #377
• build(lfs): track tests/*/src/*.png via Git LFS #376
• test(hdr-regression): tighten Window F maxFrameFailures budget after Chunk 4 fix #375
• fix(engine,shader): handle matrix3d transforms and hide non-first scenes #374
• refactor(producer): extract HDR compositing helpers and rename media metadata #373
• fix(producer): wire --crf and --video-bitrate CLI overrides into encoders #372
• fix(producer): tighten resource lifecycle and harden file server #371
• feat(engine): wire options.hdr through chunkEncoder + dynamic SDR→HDR transfer #370
• test(hdr-regression): tighten Window C maxFrameFailures budget after Chunk 1 fix #369
• fix(engine): stop clobbering native <video> opacity in HDR pipeline #368
• refactor(shader-transitions): extract DEFAULT_DURATION and DEFAULT_EASE constants #367
• refactor(types): tighten type safety, dedupe HfTransitionMeta, prune dead LUT export #366
• test(producer): add hdr-regression and hdr-hlg-regression test suites #365
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[vanceingalls]

Thanks for the careful review @jrusso1020 — confirming each point you raised landed in the merged commit:

1. Per-render-job scoping (no cross-job collisions). The cache is constructed once per render job inside the orchestrator and goes out of scope on job exit:

          // Per-job LRU cache for transfer-converted HDR image buffers. Static HDR
          // images that need PQ↔HLG conversion are converted exactly once per
          // (imageId, targetTransfer) and then reused for every subsequent frame
          // instead of paying a fresh `Buffer.from` + `convertTransfer` on every
          // composite. The cache is local to this render job so concurrent renders
          // do not share state.
          const hdrImageTransferCache = createHdrImageTransferCache();
          const hdrCompositeCtx: HdrCompositeContext = {
            ...
            hdrImageTransferCache,
            ...
          };

The HdrCompositeContext carries it through blitHdrImageLayer for both the main composite path and the transition path (the two getConverted call sites at lines 554, 718, and 2040).

2. Same-transfer zero-copy. When sourceTransfer === targetTransfer, getConverted returns source untouched — no allocation, no convertTransfer call, no cache write. The orchestrator also skips even calling getConverted when transfer info is unavailable, so the SDR/no-transfer path stays exactly as it was.

3. Source-buffer immutability. convertTransfer mutates in place, so the implementation always clones via Buffer.from(source) before converting on a miss — both the normal LRU path and the maxEntries=0 passthrough. Three of the 15 tests in hdrImageTransferCache.test.ts pin this invariant against future refactors:

• does not mutate the source buffer on a convert+cache miss
• does not mutate the source buffer on a convert+cache miss with maxEntries=0 passthrough
• does not mutate the source buffer on a cache hit

The full 15-test suite also covers hit/miss, distinct keys per (imageId, targetTransfer), LRU eviction + MRU promotion, maxEntries=0 disabling caching while still returning correct bytes, the default cap of 16, and validation that maxEntries rejects non-integers/negatives.

On metrics emission for hit/miss/eviction (non-blocking observation): Agreed it's worth having when we wire up benchmark observability more broadly — leaving as a future follow-up alongside the existing frameDirMaxIndexCache eviction metric in plans/hdr-followups.md. Not added in this PR to keep the change surgical and the cache implementation dependency-free of the logger interface.

[qodo-ai-reviewer]

Hi, createHdrImageTransferCache defaults to maxEntries=16, which can retain very large rgb48le buffers at higher resolutions (e.g., 4K ~53MB per entry → ~850MB worst-case), increasing peak RSS and OOM risk unless callers tune maxEntries.

Severity: remediation recommended | Category: performance

How to fix: Make cache bound configurable

Agent prompt to fix - you can give this to your LLM of choice:

Issue description

Default maxEntries=16 can retain hundreds of MB to ~1GB at 4K+, which can cause memory pressure/OOM on constrained machines.

Issue Context

Cache buffers are full-frame rgb48le images (width*height*6). Count-based LRU doesn’t account for resolution.

Fix Focus Areas

• packages/producer/src/services/hdrImageTransferCache.ts[74-90]
• packages/producer/src/services/renderOrchestrator.ts[1903-1921]

Suggested fix

• Plumb a configurable maxEntries from render/job config or an env var.
• Optionally set a smaller default when width*height exceeds a threshold (e.g., 4K), or switch to an approximate byte-budget eviction policy.
• Update docs/comments to mention 4K implications and how to tune.

---

Found by Qodo code review. FYI, Qodo is free for open-source.