Fix GPU device-loss when loading heavy captures (auto-disable Opacity Micromaps)

[skurtyyskirts]

What this does

Fixes a GPU device-loss (VK_ERROR_DEVICE_LOST) that crashes/freezes the Toolkit when opening or switching to a very heavy game capture. Reproduced with dense Tomb Raider: Legend captures (bolivia__2.usd ≈18k prims / ≈9k meshes, and the peru captures). During stage realization the path tracer builds geometry / BVH / Opacity-Micromap data for the whole capture at once; on an over-budget capture the OMM working set exceeds the GPU budget and faults the Vulkan device in-process (Aftermath GPU dump generated, no OS-level TDR).

The fix

lightspeed.trex.capture.core.shared now inspects a capture's prim count before it is realized and, if it is at or above a heavy-capture budget (12k prims), loads it in a degraded-safe renderer state:

• Forces rtx.graphicsPreset = Custom (so the User-layer write wins over the capture's Quality preset), then rtx.opacityMicromap.enable = 0, through the existing hdremix_set_configvar bridge.
• Applied on project open (the stage-opened event, before the renderer realizes the heavy geometry) and on manual capture switch.
• Gated by a new setting autoSafeModeOnHeavyCapture (default on); set it to false to always load captures at full quality.

The prim-count inspection is a cheap Sdf.Layer prim-spec walk (no stage composition). The HdRemix dependency is optional and imported defensively, so headless / CLI apps without the renderer are unaffected.

Deliberately minimal and game-agnostic — the whole change is contained in one extension. It does not touch performance tuning, diagnostics, or renderer internals.

Testing

• format_code and lint_code all: pass.
• Extension unit tests: 19 pass (OK, 0 failures), including 5 new tests covering prim-count estimation (nested count, missing layer) and the safe-mode push (over-budget pushes graphicsPreset=4 then opacityMicromap.enable=0 in order; under-budget no-op; setting-off no-op).
• Measured setup.py module coverage: 83% (> 75%).
• Behavioral verification (open the Tomb Raider: Legend project and confirm the capture realizes with Opacity Micromap: disabled and no device-loss over 2–3 min) should be run on the affected hardware — this is the original repro that motivated the change.

Housekeeping

• lightspeed.trex.capture.core.shared version bumped 1.4.0 → 1.5.0; extension docs/CHANGELOG.md and the root CHANGELOG.md updated.
• Opened as a draft for self-review. I'll sign the NVIDIA CLA when the bot prompts.

Follow-up (out of scope)

On the original hardware a second, later freeze can occur ~1 minute after a heavy capture realizes, when dxvk-remix re-applies the capture's own graphics preset and re-enables Opacity Micromaps without emitting a settings change. That is a separate issue; the underlying renderer should ideally bound its per-capture GPU allocation and surface a recoverable error on VK_ERROR_DEVICE_LOST rather than losing the device.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: e949ef36-b997-48fa-bef2-e24de81e4341

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}