Lights dual packing

A scene author sets one thing: a `LightComponent` whose `LightType` runs Sphere = 0, Directional = 1, Spot = 2, AreaRect = 3.

Neither light buffer ends up holding only those. Both pipelines also synthesise one light per actor whose material carries an emissive texture — the ray-traced side stamps it in as a sphere at the mesh centre, the deferred side as a point light — so every count on this page is scene lights plus emissive stand-ins:

The path tracer takes the component enum unmodified — the value is cast straight to float and dropped into `positionAndType.w`:

The deferred pipeline does not. Its `LightData` uses the classic raster convention, 0 = directional, 1 = point, 2 = spot:

so `updateLightBuffer` swaps 0 and 1 on the way in. The remap is a single nested ternary, and it is written out verbatim in both overloads of the function — the immediate upload and the per-frame one — which is why it has no line of its own to cite:

int deferredType = (lightComp->getLightType() == LightType::Sphere) ? 1 : (lightComp->getLightType() == LightType::Directional) ? 0 : 2;

AreaRect = 3 has no raster equivalent, so the else-arm sends it to 2, and the deferred lighting loop treats the rectangle as a cone — attenuated by the component's cone angles, 30° and 45° on a default-constructed `LightComponent`, which nobody authoring an area light ever set:

Those two numbers do not come from where you would look for them. `LightComponent` declares default member initialisers of 15° and 30°, and its one constructor's initialiser list overrides them with 30° and 45°, along with the header's intensity and range. Only the members that list omits — `radius` and the area edges — keep the advertised defaults:

The two overloads are not the maintenance risk the duplicated block suggests; they are already the maintenance bug. The packing block is byte-identical, but a dozen lines below it the no-light fallbacks have diverged: the immediate path installs a warm default sun whose intensity is $\pi$, cancelling the diffuse BRDF's $1/\pi$, while the per-frame path installs a white one at intensity 1. An unlit scene is roughly $\pi$ times brighter through one than through the other, and which one you get depends on the render path: `renderDeferred` and `renderLegacy` call the immediate overload, `renderMultiFrame` calls the per-frame one:

The ray-traced pack is the small one. `GPULight` is five `vec4`s, std430, with a static assert pinning the size so a stray member cannot silently desynchronise it from the GLSL mirror:

`LightData` is 128 bytes, and 64 of those are a per-light shadow matrix the path tracer has no use for — it traces the shadow ray instead of projecting into a map:

The capacity story inverts too. The deferred UBO is a fixed array of `MAX_LIGHTS = 8`, and both loops that fill it — scene `LightComponent`s first, then the cached emissive stand-ins — `break` once it is full, so light nine is silently dropped and an emissive mesh can eat the slot a hand-placed light wanted:

The RT side declares a cap of 64 that nothing anywhere reads — the SSBO is sized from the collected vector at upload time, so the real limit is device memory, not the constant:

`GPULight` has `vec4` alignment, so std430 rounds the array base of any buffer that begins with a `uint` counter up to 16 regardless. The upload spends eight of those twelve leftover bytes — the bindless environment-map index at offset 4, an HDRI intensity scale at offset 8 — and leaves the last four as true padding, holding whatever the header fill left there:

The header is cleared to all-ones first, which makes the environment-map slot read `0xFFFFFFFF` — the sentinel the miss shader tests for "no HDRI" — before the real count is written over the first four bytes and the intensity scale over the third word:

Binding 11 is declared four times across the ray-tracing stages, in two shapes. All three raygen shaders name only `lightCount` and let std430 alignment skip the rest of the header. `pt_miss.rmiss` spells the header out in full — `lightCount`, `envMapTexIdx`, `envIntensity`, then a `uint _pad` it never reads — because it is the stage that samples the environment, and it needs the third word as much as the second: the index selects the HDRI, the scale multiplies it.

That side channel creates the sharpest ordering constraint on the page. `uploadLightBuffer` destroys and reallocates the buffer on every call, so nothing in the header survives a re-upload; even when the HDR reload is skipped because the path is unchanged, both the index and the intensity scale have to be stamped back into the fresh header, or the scene loses its sky the moment a light moves:

`dirAndParam.w` is overloaded: the packer fills it with the sphere radius, then, two lines later, overwrites it with the inner cone angle in degrees when the type is Spot.

The bounce-0 next-event-estimation block of the default `pt_raygen.rgen` converts intensity to radiance *before* it branches on type, using the surface area of a sphere of that radius:

Write $c$ and $I$ for the packed colour and intensity, $r=\max(\texttt{dirAndParam.w},0.01)$, $d$ for the distance from the shading point to the sampled light point, $\theta_\ell$ for the angle at the light between its normal and the incoming direction, $s$ for the clamped spot cone falloff, and $A$ for the rectangle area in `extra2.w`. The block forms $L_e = cI/\max(4\pi r^2, 0.01)$ once, then each branch multiplies by its own geometric weight, giving

for sphere, directional, spot and area respectively. The $4\pi r^2$ reappears inside the sphere and spot weights and cancels, which is why growing a sphere light softens its shadow without brightening it. It does not cancel for the other two: a directional light's brightness and a rect light's brightness both scale as $1/r^2$ in a radius that means nothing for either shape. The radius is one of the members the constructor leaves alone, so it really is 0.5 by default, which makes the divisor $4\pi r^2$ exactly $\pi$ — so out of the box both shapes are quietly *darkened* by $1/\pi$:

The spot branch is worse than a scale factor. It reads `dirAndParam.w` twice in the same block — once through `cos(radians(...))` as an angle, which is correct, and once unconverted as the radius of the sphere it jitters the sampled light point over. The C++ struct is the only place in the tree where both meanings are written down. `pt_raygen.rgen` and `pt_raygen_offline.rgen` copy the comment but keep only the `sphere:radius` half; `pt_raygen_realtime.rgen` carries no member comments at all. Anyone reading a shader alone sees one meaning:

A default-constructed spot, inner cone 30°, therefore has its sample point scattered over a sphere of radius 30 world units, so its direction and its shadow ray are close to meaningless. Sphere, directional and area lights do not share the fault — but every raygen does. The same clamp-then-jitter pairing sits in each next-event block of all three: three in `pt_raygen.rgen`, three in `pt_raygen_offline.rgen`, four in `pt_raygen_realtime.rgen`.

Each next-event sample picks a single light uniformly rather than looping over all of them. With $N_\ell$ entries in the buffer — scene lights plus the synthesised emissive ones — the selection density is $p(\ell)=1/N_\ell$, and an unbiased estimator divides by it, so the contribution is multiplied by the light count:

where $f_r$ is the Cook-Torrance value evaluated inline in the same block and $\theta_s$ is the angle at the shading point. That `* float(lightBuf.lightCount)` is the visible half of the division:

The whole decode-and-sample block appears three times in `pt_raygen.rgen` — once at the primary hit and once inside each of the two indirect bounce paths, where the identical expression is pre-multiplied by that path's specular or diffuse throughput. It was then copied wholesale into the two profile raygens: three more blocks in `pt_raygen_offline.rgen`, four in `pt_raygen_realtime.rgen`. Neither file is dead — both are bound by a live render profile:

The ten copies are not clones — the realtime sphere branch has since been replaced with solid-angle sampling, and the offline block's primary hit wraps the diffuse `NdotL` with a subsurface term the specular half does not get — but the header decode, the type dispatch and the `dirAndParam.w` overload are the same in all of them. A light-layout change lands in ten places across three files.

The shadow ray uses the sampled point's distance, not the light's radius, as `Tmax`, and the three positional branches shorten it by 0.02 so the ray stops just short of the light's own geometry; the origin is pushed 0.01 along the shading normal and `Tmin` is 0.001:

Directional lights get a hard-coded `Tmax` of 10000 instead, which is a scene-scale assumption rather than a computed bound.

`shaders/includes/lighting/light_types.glsl` defines the `LIGHT_*` constants, a `LightParams` struct, direction and distance extractors, and an ambient helper. No file in `shaders/` or `ohao/` includes it. Its formulas still ship, though, written out by hand: `forward.frag` branches on identically-named macros pulled from `includes/common/types.glsl`, and `deferred_lighting.frag` inlines the same direction selection and the same `ambient * albedo * ao` product with bare integer literals. Unused file, live math.

The header is not merely redundant, it is a trap: its `LIGHT_POINT` is 1, and 1 is *directional* in the `GPULight` table this page opened with.

Including it into a ray-tracing stage to avoid retyping three constants inverts the two most common light types in the engine.

• The environment-map index at byte 4 and the intensity scale at byte 8 die with the buffer on every `uploadLightBuffer`. Both must be re-stamped after the reallocation even when the HDR is not reloaded, or the sky goes black on the next light edit.
• `positionAndType.w` is the raw `LightType`; `LightData.position.w` is the remapped raster code. Anything reading a light type must know which buffer it came from.
• `dirAndParam.w` means radius for sphere/directional/area and inner cone angle in degrees for spot. Every spot branch in all three raygens reads both meanings; only the angle reading is correct.
• Both buffers are filled from `LightComponent`s *and* from lights synthesised per emissive-textured actor. `lightCount` — and therefore the estimator's $N_\ell$ — counts both, and the deferred eight-slot budget is shared between them.
• The deferred UBO holds exactly eight lights and drops the rest without warning; the RT SSBO is sized at upload and ignores its own `MAX_GPU_LIGHTS = 64`.
• The estimator multiplies by `lightCount` because it selects one light uniformly. Replacing uniform selection with importance sampling means replacing that factor with the real inverse density.
• The two `updateLightBuffer` overloads must be edited together. They already disagree on the no-light fallback, so a scene with zero `LightComponent`s renders at different brightness through `renderMultiFrame` than through `renderDeferred`.