Skip to content

fix(idtech8): unify metric units, ReSTIR/GI estimators, pass order and radiance cache - #96

Open
f1ames0ff wants to merge 176 commits into
masterfrom
fix/idtech8-correctness
Open

f1ames0ff wants to merge 176 commits into
masterfrom
fix/idtech8-correctness

Conversation

@f1ames0ff

Copy link
Copy Markdown
Owner

Summary

Correctness audit & fixes for the id Tech 8 GI stack on top of master (14cd1788), updating the renderer submodule (6dfe04a -> b80703c, see QuakeRaySDK PR #8), host metric unit adapters, and docs/idtech8-*.md / docs/idtech8-handoff.md.

Public ABI in renderer/Include/qray/qray.h is unchanged (RadianceCacheEntry == 32 B, RestirGiReservoir == 48 B, RestirReservoir == 16 B, LightVolumeProbe == 48 B).

renderer slices (60b9044..b80703c) & host changes (092fc771, 3c2398c0)

Slice renderer commit Fixes
1 60b9044 Split Light-Volume Cull & Hit-Buffer Indexing: split trace in RtLightVolume.rgen.hlsl uses traceVolumeRay (RAY_FLAG_NONE) instead of culled traceIndirectRay; both RtLightVolume.rgen.hlsl and RtLightVolumeShade.rgen.hlsl index lightVolumeHits by invocation instead of probeIndex.
2 965f027 + host 092fc771 Metric Unit Unification (QR_QUAKE_UNIT_IN_METERS = 0.025f): unified LightGrid (2.0 m / 16.0 m / 0.8 m / 6.25e-4), LightVolume (32.0 m / 16.0 m), TransparencyFroxels (32.0 m / 1.6 m), RadianceCache (rt_radiance_cache_cell default "10" -> 0.25 m, 25.6 m LOD threshold, host QR_QuakeDrawFrame & SpatialFrame.cpp frame.Length scaling), and QuakePointToMeters for UploadClusterLightSources view origin (Quake/qr_spatial_adapter.cpp, Quake/gl_vidsdl.c).
3 832573a Glass Pass Ordering & Particle World Reconstruction: RhiRtDirectPass::EnsureLightSet accepts pUniformBuffer (worldUniformBuffer.Get() from NvrhiFrameSkeleton.cpp) and dispatches PrepareUniformSet, BuildLightGrid, and DispatchTransparencyFroxels before ReflRefr runs; RsParticle.frag.hlsl reconstructs particle world position from invProjection + inViewDepth + invView.
4 2dba65a Direct ReSTIR Target & Duplicate Luminance Removal: unified q2RestirTarget across grid candidates, uniform initial, fallback, and q2RestirMergeHistory in RestirSampling.hlsli, removing double luminance multiplication from q2SampleGridLights::outMass; added tests in RestirReservoirTests.cpp.
5 05870d0 ReSTIR GI Estimator W, Validation & Counter Cleanup: added RestirGiTarget / q2GiTarget, zeroed radiance.w, weighted current sample by currentTarget * max(oneOverSourcePdf, 0.0), shaded with shadingWeight = q2GiWeight(reservoir), gated reuse on frameId > 0, enforced q2GiUsable && q2GiHistoryValid && q2GiSurfaceMatches on history and all 4 spatial taps, reset skyBsdfWeight = 1.0 on visible geometry reuse, and deleted 5 bogus rayStatsAdd calls + duplicate RAY_STATS_CATEGORY_INDIRECT.
6 b80703c Radiance Cache Normal Key, 4-Slot Linear Probing & Outgoing Radiometry: added 9-bit quantized normal (7 bins/axis, +Z fallback) to hash key, 4-slot linear probing (kProbeSteps = 4), shared q2InterpolateLightVolumeSh + q2EvaluateLightVolumeIrradiance, bounceBrdf + volume irradiance miss fallback on second bounce, and removed second-bounce & final-gather cache puts.
Docs 092fc771, 3c2398c0 Updated docs/idtech8-{phase0,restir,volumes,radiance-cache,restir-gi,transparency-froxels,tuning}.md and added docs/idtech8-handoff.md.

Verification

Linux unit tests (g++ -std=c++20 -DQR_STATIC / gcc)

  • qray_light_grid_tests: 21 checks, 0 failures
  • qray_light_volume_tests: 85 checks, 0 failures
  • qray_radiance_cache_tests: 62 checks, 0 failures
  • qray_restir_reservoir_tests: 36 checks, 0 failures
  • qray_restir_gi_tests: 56 checks, 0 failures
  • qray_transparency_froxel_tests: 16 checks, 0 failures
  • qray_spatial_contract_tests: passed
  • prof_window_tests: passed
  • rt_light_admit_tests: 25 checks, 0 failures
  • g++ -fsyntax-only (Quake/qr_spatial_adapter.cpp + renderer/Source/SpatialFrame.cpp): exit 0
  • CheckMatrixReads.py: exit 0

Windows CI (44174810055) & Proton 11.0 Runtime (ci-windows-44174810055, RX 9070 XT, radv Mesa 26.2.6, e1m1, rt_gi_level 2)

  • Windows CI: Debug (4m45s, run job 134363226985) and Release (6m33s, run job 134363227500) — success (build_win.ps1 Debug -Tests, full dxc SPIR-V shader build, ctest -LE gpu).
  • Proton 11.0 runtime: 0 NVRHI::ERROR; cvarlist confirms rt_radiance_cache_cell "10" (0.25 m) and rt_radiance_cache_lod "1024" (25.6 m).
Dump (qperfdump.log) Configuration (e1m1, rt_gi_level 2) gpu.frame cache hit cache miss cache active indirect rays shadow dir Mean RGB (3840x2160)
1 (screenshot0000.png) split 1, gi 1, cache 1, vol 1 24.41 ms 3,368,783 23,654 23,083 7,146,818 2,356,487 [54.52, 35.94, 28.33]
2 (screenshot0001.png) + rt_light_volume_local_add 512 (split 1) 24.02 ms 3,388,325 7,641 23,357 7,161,759 2,383,505 [58.61, 35.06, 27.02]
3 (screenshot0002.png) split 0, gi 1, cache 1, vol 1 24.33 ms 3,366,019 27,816 23,777 7,143,932 2,403,461 [61.23, 35.52, 27.20]
4 (screenshot0003.png) split 0, gi 0, cache 1, vol 1 24.76 ms 3,365,537 24,614 23,010 7,143,981 2,410,525 [63.02, 35.94, 27.74]
5 (screenshot0004.png) split 0, gi 0, cache 0, vol 1 23.12 ms 0 0 0 7,142,953 2,427,968 [66.38, 39.24, 30.83]

f1ames0ff added 30 commits November 7, 2026 18:30
Rebuilds feat/idtech8-grid on top of the current renderer submodule split. The renderer keeps the 8-cascade typed grid, GPU builder, direct/indirect NEE and particle/glass sampling; the host keeps the rt_light_grid switch, grid stats/report commands and the view-origin publication. Renderer pointer advances to the port branch merge with current main. CPU LightGridTests pass 16/16.
The branch inherited the pre-submodule installer step, which hangs on the hosted runner. Use the same headers + checked-in import library + dxc + loader assembly as feature/linux-support, without changing the old build_win.ps1 path.
Ports the renderer QR_DXC hint order and the build_win.ps1 explicit -DQR_DXC so the GPU-test shader probes do not pick the Windows SDK dxc without SPIR-V codegen. Renderer pointer advances to 8254d3d.
Points the host at the renderer ReSTIR implementation (reservoir ABI, GPU reuse, set-6 binding) and records the design, approximations and validation status in docs/idtech8-restir.md. The Phase 0 next step now moves to the cascaded/local volumes.
Picks up the allocation-failure guard: a requested but unsized reservoir ring skips the direct trace instead of indexing the two-element stand-in.
Picks up the direct-pass G-buffer bindings for motion and history validation.
Picks up the disjoint reservoir salts.
The indirect ReSTIR GI path remains a later feature; this branch only replaces the direct-light selection.
Picks up the packed G-buffer addressing for the temporal and spatial history reads, the UAV state restore after the reservoir clear, and the doc clarification about the reflection-recording toolchain.
Points the host at the volume ABI/CPU-oracle commit and records the layout, schedule, lookup rules and test coverage in docs/idtech8-volumes.md.
SampleIrradiance returns false outside all cascades and local volumes; the final gather keeps the existing screen-space SH for that case.
Adds rt_light_volume and rt_light_volume_weight to the illumination params and bench report, points the host at the renderer volume atlas/update/final-gather commit, and documents the GPU path and its remaining limits.
Picks up the NVRHI buffer-state announcement that removes the runtime Unknown prior state errors.
Picks up the NVRHI reservoir state announcement.
Picks up the full-cell cluster/global fallback.
Picks up the grid full-cell fallback for the volume branch.
Picks up the grid full-cell fallback.
RT_LockCvar sets CVAR_ROM before the +commands execute, so +rt_restir 1 and +rt_light_volume 1 silently stayed at 0 and every Proton test exercised only the grid. These are runtime quality controls; the bench report already records them.
RT_LockCvar sets CVAR_ROM before the +commands execute, so +rt_restir 1 silently stayed at 0 and the Proton runs exercised only the grid. The bench report already records the values.
Picks up the grid-consistent ReSTIR target.
Picks up the grid-consistent ReSTIR target.
Records the Proton evidence, the runtime-settable cvar fix and the 0.25 default, and advances the renderer pointer.
Documents the cvar ROM-lock discovery, the NVRHI reservoir state fix, the grid full-cell fallback and the grid-consistent target, with the measured e1m1 means and release tags.
Picks up local-light NEE for probe hits and updates the volume limitations/next steps.
Adds rt_light_volume_rays (default 16, clamp 16..64), passes it through QrDrawFrameIlluminationParams and the global uniform, and records the tier in the volume docs.
Adds rt_light_volume_local_add/_clear/_list for up to eight 10^3 volumes at the view origin, passes the descriptors through QrDrawFrameIlluminationParams and records the runtime slice in the volume docs.
Picks up the full-slot list comparison in the volume atlas invalidation.
Updates the phase-0 next step with the volumes PR, the quality-tier and local-volume branches, and the world radiance cache / ReSTIR GI / transparency / AD order.
Adds the e1m1 means for 16/64 rays and local on/off, the run-to-run noise, and the debug-tint proof that the local lookup is selected.
Adds rt_radiance_cache and its cell/LOD/age cvars, fills the illumination parameters and records the first-slice design and limitations.
f1ames0ff and others added 29 commits November 11, 2026 16:45
…ive-cells

idtech8: count the radiance-cache active cells
volume: trace the probe rays without the primary front-face cull
volume: convert the probe cube from Quake units to the metric scene
idtech8: validate the ReSTIR GI history normal and age
docs: record the transparency blend A/B limitation
…-normal

idtech8: validate ReSTIR GI history and taps with the receiver normal
…-box

froxels: use a camera-centered metric world box
idtech8: static glass map and the froxel blend A/B
…umulation

radiance: multi-frame reuse for revisited cache cells
docs: idtech8 final merged status and evidence
radiance: feed the cache from the indirect raygen and reuse it on the second bounce
docs: record the radiance-cache indirect feed
…al-gather

radiance: feed the cache from the final gather
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