Hit & miss shaders

The RT vertex stream carries no tangent, so normal mapping in the closest-hit builds an orthonormal basis from the shading normal alone — Frisvad's $a = 1/(1+n_z)$ construction, which buys its speed by avoiding a normalisation and a square root, not a branch. The branch is unavoidable: the form is singular at $n_z = -1$, and the shader guards it explicitly.

The tangent-space normal is then applied in that basis:

The engine already documents why that basis is poor when direction matters: `ggx_aniso.glsl` rejected Frisvad for its anisotropy tangent for exactly this reason.

The rasteriser has the real thing — a per-vertex tangent with handedness, Gram-Schmidt orthogonalised against the shading normal:

So one normal map perturbs in a UV-aligned frame under the deferred pipeline and in an arbitrary, N-dependent frame under the path tracer. The `mapN.z` component — the bulk of most normal maps — survives either way, which is why RT renders still look bumpy. Directional detail does not: brushed metal, scratches and woven cloth rotate per pixel in the RT path and will not match the raster preview.

The material row is three `vec4`s indexed by material id, with texture handles smuggled through float bit patterns and `0xFFFFFFFF` meaning "none":

Binding 3, the per-instance buffer carrying an older sign-and-magnitude encoding, is still declared here and never indexed:

Scene textures arrive as layers of one `R8G8B8A8_UNORM` array image exposed through per-layer 2D views, which is why colour fetches need a manual transfer-function decode an `_SRGB` view would have applied for free:

The HDR environment map sits in the *same* GLSL array as an `R32G32B32A32_SFLOAT` image — legal because combined-image-sampler descriptors are independent — which is how the miss shader reads values above 1.0 from a binding whose other entries are clamped to `[0,1]`. The array has a single mip level and nothing in the RT path computes ray differentials, so minified textures alias.

`pt_miss.rmiss` signals escape by writing a negative distance, and that one float is the entire occlusion protocol:

This is what lets environment next-event estimation cost one ray instead of two. The raygen draws a direction from the environment CDF, traces a shadow ray along it, and if the ray escapes it consumes the radiance the miss shader just wrote — visibility and the light's emission resolved in a single traversal:

The same economy is a cost on every other shadow ray that escapes: area-light NEE traces through the identical miss shader, which fetches the environment texel and then evaluates `pdfEnvMap` — an `acos`, an `atan2` and up to four indexed CDF loads — to report a PDF that caller never reads. The expensive half is not shared: the two binary searches live in `sampleEnvMap`, which only the raygen calls.

The miss shader and the environment importance sampler both map directions to equirectangular UVs, and they do not agree. For a unit direction $d$ the miss shader uses

while `env_sampling.glsl`, which turns CDF texels into directions and inverts the map for MIS, uses

Since $\arccos x = \tfrac{\pi}{2} - \arcsin x$, the two are related by $v_{\text{miss}} = 1 - v_{\text{cdf}}$ — an exact vertical mirror. The horizontal axis agrees; both derive $u$ from $\operatorname{atan2}(d_z, d_x)$. They would still be consistent if the CDF's rows ran opposite to the texture's, but `EnvCDF::build` consumes the same `stbi_loadf` array that is memcpy'd unflipped into the image.

A direction drawn from the brightest row of the CDF is therefore looked up by the miss shader in the mirrored row. Engine-wide the convention splits two against two, not one outlier against the rest: the miss shader and `deferred_lighting.frag` both build $0.5 + \theta/\pi$ from $\theta = \arcsin d_y$, while `env_sampling.glsl` and the cinematic composite both land on $0.5 - \theta/\pi$. What matters is not the census but which pair shares a texture — and the two that disagree here are the sampler that picks the direction and the miss shader that shades it.

MIS still combines two well-formed weights, but the estimator underneath is not unbiased either. `sampleEnvMap` throws away the residual of $u_1,u_2$ after the two searches and returns `equirectPixelToDir`, which resolves the texel *centre* — so the procedure draws from a discrete set of $W \times H$ directions while reporting a continuous solid-angle density.

The env-NEE term is thus a midpoint Riemann sum over texel centres, evaluated against the bilinearly filtered radiance the miss shader fetches: a systematic quadrature error that no sample count removes, sitting on top of an importance distribution the mirrored $v$ leaves anti-correlated with the radiance it exists to track. Both are read from the code, not measured.

`pt_anyhit.rahit` implements a hard 0.5 cutout, and the shader itself is sound: it takes alpha from the diffuse texture, so any textured cutout material would be tested correctly if the stage ever ran.

It never runs. That is the whole of what makes it inert: every BLAS is built with `VK_GEOMETRY_OPAQUE_BIT_KHR` and every `traceRayEXT` passes `gl_RayFlagsOpaqueEXT`, either of which alone suppresses the stage.

A second, independent gap sits behind that one. The material row has no alpha slot — the `.a` lane of the base-colour row is where the diffuse texture index lives — so an untextured material with a transparent base colour could not be cut out even with traversal fixed. `MaterialData` does carry an alpha mode, but only the glTF loader ever writes it; the OBJ and FBX paths leave the default, and it reaches no GPU buffer in any case:

What ships instead is deletion at load time — the OBJ path drops alpha-card triangles by material name:

• `RayPayload` is duplicated across `pt_closesthit.rchit`, `pt_miss.rmiss` and all three raygen profiles with no shared header. Edit one and you must edit all five; a mismatch is silent.
• Shadow rays use miss index 0, so one that escapes clobbers `payload.color`, `payload.hitDist` and `payload.envPdf`; an occluded one runs no shader and leaves the payload alone. Read albedo, normal, position and emission into locals before tracing anything.
• `payload.hitDist < 0.0` is the only occlusion signal. A miss that stops writing it turns every shadow ray into a hit and every surface black.
• `pt_miss.rmiss` declares a `vec4 jitter` it never reads, purely so its push-constant block size matches the layout the raygen defines. Trimming it invalidates the layout.
• Only degenerate-normal geometry is flipped two-sided, and no shipped scene produces one; culling is disabled TLAS-wide, so a real mesh hit from behind keeps its outward normal and renders black through the `N·L` clamp.
• Normal maps use a Frisvad basis in the path tracer and a UV-derived tangent basis in the GBuffer. Directional detail will not match between the two.
• The closest-hit's header comment still describes a two-`vec4` material layout; the code reads three. Binding 3 is declared here and never indexed.