arkavo-org / arkavo-org/VRMMetalKit
GLTFMetalKit: replace fixed-delta diffuse irradiance with Hammersley importance sampling
- Dominant language
- Swift
- Stars
- 6
- Forks
- 2
- Avg merge
- 18h 51m
- Merged PRs (30d)
- 26
Description
## Context
Reviewer feedback on PR #241 (Minor #7):
> `gltf_ibl_diffuse_irradiance` uses a fixed Δ of 0.025 radians (`IBLPrefilter.metal:144`). This is ~80,000 samples per output texel via the phi × theta nested loop. For a 32×32×6 = 6,144-texel diffuse cubemap the dispatch is 491M sample reads — fine on Apple Silicon, but a hot path during init and noticeably slower than the Hammersley-importance-sampled alternative (which would converge in ~64–256 samples). Consider replacing with cosine-weighted Hammersley sampling for a 100×+ speedup at equivalent quality.
## What's needed
- Replace the nested `phi × theta` fixed-step loop in `gltf_ibl_diffuse_irradiance` with cosine-weighted Hammersley sampling, mirroring the pattern used by the specular prefilter kernel (which already uses Hammersley).
- 64-256 samples per output texel should converge to equivalent quality; benchmark to confirm.
- Cosine-weighted sphere sampling: `sinθ = √Xi.y`, `cosθ = √(1-Xi.y)`, `phi = 2π·Xi.x`, evaluate `f(L) * cosθ / pdf` — the cosθ/pdf cancels for cosine-weighted PDF, leaving just `f(L)` (the source-cubemap sample).
- The BRDF LUT kernel (`gltf_ibl_brdf_lut`) already uses this exact pattern at 1024 samples; copy the structure.
## Acceptance
- Visual output (Avocado / MetalRoughSpheres / DamagedHelmet under HDR env) is within tolerance of the current implementation.
- Init time for `GLTFEnvironment.makeProcedural(...)` and `makeFromRadianceHDR(...)` drops measurably (target: ≥10× speedup on the irradiance dispatch).
## Estimate
~2 hours. The kernel is ~40 lines and the change is mostly mechanical, but it needs a side-by-side visual comparison test to confirm convergence quality.
Source: surfaced in PR #241 review.
Contributor guide
Research direction
Start in IBLPrefilter.metal at gltf_ibl_diffuse_irradiance and compare its fixed-step loop with the Hammersley structure in gltf_ibl_brdf_lut and the existing specular prefilter kernel. Replace the irradiance sampling and run visual comparisons with Avocado, MetalRoughSpheres, and DamagedHelmet under an HDR environment. Confirm equivalent output and measure init-time improvement for makeProcedural(...) and makeFromRadianceHDR(...).
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- computer-graphics, performance
- Issue type
- Refactor
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100