Jazz2/Rendering/SoftwareLightSplat.h file

Namespaces

namespace Jazz2
Root namespace of Jazz² Resurrection.
namespace Jazz2::Rendering
Scene rendering and viewport management.
namespace Jazz2::Rendering::SoftwareLighting

Functions

auto Distance(float d2) -> float
Reciprocal square root estimate of the platform, where it has one worth using.
auto ClampFalloff(float t) -> float
Clamps a falloff parameter into [0, 1].
auto FalloffStrength(float dist, float invDenom) -> float
The falloff of LightingFs.inc at distance dist (in units of the far radius), see SplatLight().
template<bool Coreless>
void SplatLightRows(float* lightmap, std::int32_t lmW, std::int32_t lmH, float cx, float cy, float rLm, float radiusNearNorm, float intensity, float brightness)
The row loop of SplatLight(), for a light with a flat core or (if Coreless) without one.
auto RowHalfWidth(float v) -> float
Returns $ \sqrt{v} $ for the half-width of a light's row, a positive value.
void SplatLight(float* lightmap, std::int32_t lmW, std::int32_t lmH, float cx, float cy, float rLm, float radiusNearNorm, float intensity, float brightness)
Adds one light to a two-channel (intensity, brightness) float lightmap.
void SplatRing(float* lightmap, std::int32_t lmW, std::int32_t lmH, float cx, float cy, float ringLm, float rLm, float radiusNearNorm, float intensity, float brightness, std::int32_t* litSpans)
Adds one ring light to a two-channel (intensity, brightness) float lightmap.

Function documentation

float Distance(float d2)

Reciprocal square root estimate of the platform, where it has one worth using.

The falloff needs one square root per texel of the lit annulus, and on the consoles without a pipelined one that is most of the splat: the Gekko/Broadway have no fsqrt at all, so std::sqrt is a software routine of a few hundred cycles, and the SH-4's fsqrt takes about 22 cycles and blocks the pipeline. Both do have a fast estimate of 1/sqrt(x) - frsqrte (the PowerPC architecture guarantees only 1 part in 32, so it is refined with two Newton steps, which lands within about 3e-6 from any estimate at least that good) and fsrra (accurate to the last bits on its own). The lightmap is quantized to 8 bits per channel before anything sees it, so a relative error of that size cannot change a single output value except at a quantization boundary.

Returns $ \sqrt{d2} $ for a squared distance, as cheaply as the platform allows

float ClampFalloff(float t)

Clamps a falloff parameter into [0, 1].

On the PS2 through fmax()/fmin(), which GCC turns into the EE's own MAX.S/MIN.S: written as comparisons the clamp is two compares and two branches per texel there, each compare followed by a stall slot before its branch, and the branches keep the annulus loops below from being unrolled as intended. Elsewhere fmin() is the slower spelling (an extra NaN test without fast math), so the comparisons stay. The two agree on every input except NaN, which this argument never is.

float RowHalfWidth(float v)

Returns $ \sqrt{v} $ for the half-width of a light's row, a positive value.

Twice a row, for the extents of the disc and of its flat core. Where the platform has a square root instruction that is what it uses; the Gekko/Broadway have none, and std::sqrt there is newlib's bit-by-bit software routine - two calls a row were a large part of a frame at a spot with a lot of lights. Distance() is just as good for this: its few parts in a million can move a bound only for a texel that lies on it to within that much, where the strength is 0 (the disc's edge) or 1 (the core's edge, which the falloff meets at exactly 1) either way.

void SplatLight(float* lightmap, std::int32_t lmW, std::int32_t lmH, float cx, float cy, float rLm, float radiusNearNorm, float intensity, float brightness)

Adds one light to a two-channel (intensity, brightness) float lightmap.

Parameters
lightmap lmW * lmH texels of two floats each, row-major
lmW Lightmap width in texels
lmH Lightmap height in texels
cx Light centre in lightmap texels
cy Light centre in lightmap texels
rLm Far radius in lightmap texels (at least 0.5)
radiusNearNorm Near radius as a fraction of the far radius (may exceed 1: no falloff)
intensity Added to the first channel of every texel the light reaches, scaled by the falloff
brightness Added to the second channel the same way

The falloff is the one in LightingFs.inc: strength is 1 out to the near radius and then ((1 - dist) / (1 - near))^3 to the far radius, in units of the far radius. Instead of visiting the whole bounding box and classifying every texel with two compares and a branch, each row is cut analytically into the texels inside the disc - |x - cx| <= sqrt(1 - dy^2) * rLm - and the flat core inside those - |x - cx| <= sqrt(near^2 - dy^2) * rLm. Texels outside the disc are never touched, core texels get two additions, and only the annulus pays for a square root. It is the same set of texels the per-texel tests select, up to floating-point rounding of a texel exactly on a boundary, where the strength is 0 or 1 to within ~1e-7 either way - except for a light with no falloff (near >= far), whose edge is a hard step and so lands one texel differently now and then; a host harness over 196 million texel values found no other difference above 1e-3. The annulus loops are branch-free so that the compiler can interleave several texels for the in-order cores this runs on; dx is recomputed from the texel's position rather than accumulated, so no iteration depends on the previous one beyond that position, which steps by one as a float - a whole number is exact in a float, so it is the very value converting x would give, and the conversion is a round trip through memory on PowerPC, which has no move between its integer and floating-point registers.

void SplatRing(float* lightmap, std::int32_t lmW, std::int32_t lmH, float cx, float cy, float ringLm, float rLm, float radiusNearNorm, float intensity, float brightness, std::int32_t* litSpans)

Adds one ring light to a two-channel (intensity, brightness) float lightmap.

Parameters
lightmap lmW * lmH texels of two floats each, row-major
lmW Lightmap width in texels
lmH Lightmap height in texels
cx Ring centre in lightmap texels
cy Ring centre in lightmap texels
ringLm Ring radius in lightmap texels
rLm Far radius in lightmap texels (at least 0.5), measured from the ring's circle
radiusNearNorm Near radius as a fraction of the far radius (may exceed 1: no falloff)
intensity Added to the first channel of every texel the light reaches, scaled by the falloff
brightness Added to the second channel the same way
litSpans Per-row [first, last] texel pairs, widened to cover every texel this changes

The falloff of SplatLight() of the distance from the ring's circle instead of from its centre, as in LightingFs.inc. Each row is cut analytically into the texels of the band - those inside the outer circle, less the hole inside the inner one where the row crosses it - so the hole, most of the ring's bounding box, is never touched. A ring has no flat core of its own to cut out (its core is a band too), so every texel of the band takes the square root and the same branch-free falloff, which is 1 across the core anyway. Unlike a light's, a ring's lit texels are far from its bounding box, so it reports them per row itself.