arkavo-org / arkavo-org/VRMMetalKit

GLTFMetalKit: replace fixed-delta diffuse irradiance with Hammersley importance sampling

Open
#249 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.