- smin_grad is Quilez's quadratic-polynomial smin, not cubic. - cellular's search radius is 5x5x5 (F6), not 3x3x3; adds the exactness proof and the pruning claim. - id source is now pcg4d over the winning cell, not the pcg3d hash that produced its jitter (F4). - F2 = 0 is documented as reachable (past |p| of about 2^23), not unreachable; removes the false "unreachable" claim and adds a "Precision domain" note stating the float32 feature-spacing/tie behaviour honestly (F3, minor finding). - The struct-mirror comparison note now says it also matches field name and type in declaration order, not just position (F2). No entry added to THIRD-PARTY-NOTICES for the Quilez/Worley formulas: per Self's standing ruling, a published formula is not ported code. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
15 KiB
Design
CultMath exists to make renderer math readable in every place it needs to live: Rust hot kernels, C# host code, and HLSL shader code.
Parity Target: HLSL
HLSL is the semantic authority for every type and intrinsic HLSL defines. The
goal is source compatibility: HLSL-shaped math compiles as C# under
using static CultMath.math;. C# forces float literal suffixes (0.5f); the
rest of the spelling should survive the move.
That makes these HLSL rules, not options:
- Every swizzle exists.
float2/3/4,int2/3/4, andbool2/3/4expose every read swizzle of length 2 to 4, repeats included (v.wwxy), in bothxyzwandrgbanaming (never mixed), plus single-componentr/g/b/a.double2/3get lengths 2 and 3 only, because there is nodouble4. Components and swizzles are writable:v.xz = f2;,c.rgb *= 0.5f;, andv[1] = s;work. Setters exist only for non-repeating masks, because HLSL rejectsv.xx = .... - Every HLSL mixed constructor exists, as a struct constructor and as a
mathfunction:float4(float2, float2),float4(float, float2, float),float3(float, float2), the copy formfloat3(float3), and the rest, for the float, int, and bool families (double gets constructors only; amath.double3function would hide thedouble3type name). - Swizzles and mixed constructors are generated.
tools/generate-swizzles.ps1writes the checked-insrc/CultMath/Swizzles.g.cs(partial structs plus a partialmath). Edit the generator, rerun it, and commit both; never edit the output by hand. - Comparison operators (
<,>,<=,>=,==,!=) are component-wise and returnbool2/bool3/bool4. Reduce them withanyandall.Equals/GetHashCodestay value-based so vectors still work as dictionary keys. select(condition, whenTrue, whenFalse)uses HLSL's argument order.- Matrices are row-major: constructors take rows,
m[i]returns a reference to row i (som[1][2] = s;writes one element),_mRCis row R column C, and products go throughmul(mul(m, v)treatsvas a column,mul(v, m)as a row).*on matrices would be component-wise in HLSL, so CultMath does not define it. m[r][c] = vwrites through locals, array elements, fields of classes, and ref locals. Through a readonly field, aninparameter, a property (auto-properties included), or a static readonly value such asfloat3x3.identity, C# takes a defensive copy: the write compiles and is silently lost. Copy the matrix to a local, write to it, and assign it back.- Scalar/vector arithmetic and comparisons have explicit overloads on both sides rather than leaning on implicit scalar splat.
- Intrinsics return HLSL's types and edge cases:
signreturnsint/intN(NaN gives 0);step(y, x)isx < y ? 0 : 1(NaN gives 1), which is how dxc lowers it, in C# and in the HLSL mirror; float and doubleminandmax, and floatclampandsaturate, follow the DXILFMin/FMax/Saturateoperations dxc emits for them:min(a, b)isa < b ? a : b,max(a, b)isa >= b ? a : b, a NaN operand returns the other (sosaturate(NaN)is 0),clamp(x, a, b)ismin(max(x, a), b), andsaturate(x)ismin(1, max(0, x)), which maps -0 to +0;any/allaccept numeric vectors (a component is true when it is not 0);min,max, andabson int vectors return int vectors; intclampisIMin(IMax(x, a), b), so inverted bounds returnb. - Same-size vector conversions (
intN(floatN),floatN(intN),boolN(floatN),boolN(intN),floatN(boolN),intN(boolN)) exist as constructors andmathfunctions and follow dxc: float to int isfptosi, truncating toward zero; numeric to bool is!= 0(fcmp une, so NaN is true); bool to numeric is 0 or 1. DXIL leaves float-to-int undefined for NaN and out-of-range values, and so does C#; CultMath does not pin them. normalize(x)isx * Rsqrt(Dot(x, x)), which is how dxc lowers it, and DXIL.rst definesRsqrtas1 / sqrt(src). A zero vector therefore normalizes to NaN (0 * inf), and a NaN component makes every component NaN. (The special-value table underRsqrtin DXIL.rst is a copy of theRoundtable and contradicts that definition, so CultMath follows the definition.)lengthanddistanceareSqrtof the summed squares, so a zero vector gives 0. Callers that can meet zero-length vectors guard them before callingnormalize.- dxc demotes double
frac,exp,lerp, andfloorto float. CultMath's double overloads keep double precision instead:frac(double)isx - floor(x)in double. That is a deliberate divergence for CPU simulation time, which shaders do not carry.
dxc marks float arithmetic and compares fast (no NaNs) unless a value is
precise, so drivers may optimize NaN handling away and NaN results on real
GPUs are not guaranteed. CultMath defines the CPU result by dxc's lowering and
the DXIL operation spec (DirectXShaderCompiler docs/DXIL.rst).
NaN does not reliably propagate through CultMath, just as it does not on the
GPU. Because min, max, and saturate return the non-NaN operand, some
functions turn NaN or infinity into numbers: smoothstep(a, a, a) is 0;
infinite inputs to smoothstep and the intercept helpers give numbers; the
bezier, smoothstep01, and smootherstep functions return finite values for
NaN input. Callers that must detect bad data should check isnan before calling these
functions.
Deferred until a consumer needs them: float4x4, transpose, determinant,
and HLSL's one-based _11.._33 element names.
HLSL Target: Source Transformations
HlslSourceCompatibilityTests compiles the real shaders/CultMath.hlsl with
Roslyn against CultMath. These transformations are the complete list; if a body
needs anything else, the test fails:
- Include guards (
#ifndef/#define/#endif) are dropped. - Functions taking
Texture2D/SamplerStateare dropped; GPU resources have no CultMath analog. - File-scope
static constbecomesconst. - Floating literals gain
f(0.5becomes0.5f). - Struct fields gain
public. HLSL struct members have no access-modifier concept; a C# struct's fields default toprivate, which would hide them from the mirror test's reflection-based field comparison. - The file body is wrapped in a class, since C# has no free functions; HLSL functions become private instance methods.
HLSL constructs that stay outside the target and must not appear in the mirror:
const locals of vector type (C# const is primitives only; write a plain
local) and writes through a swizzle component (v.xy.x = s, which C# rejects as
modifying a temporary).
The HLSL side is checked too: tools/get-dxc.ps1 fetches Microsoft's
DirectXShaderCompiler, and
dxc -T lib_6_3 -HV 2021 shaders/CultMath.hlsl must compile cleanly.
The mirror test compares bit patterns (any NaN equals any NaN; -0 differs from
0). It proves the text of CultMath.hlsl computes the same float32 results as
C# math on the CPU, not that a GPU agrees: driver sin precision alone makes
cultmath_hash and value noise differ bit for bit on hardware. The mirror is
compiled under using static CultMath.math;, so its intrinsics are C# math
itself: the test proves the composition in the text, not the intrinsic rules,
which only HlslSemanticsTests pins.
The comparison also allows exactly one struct return shape: a mirror function
whose HLSL return type is a plain struct of float/floatN/int/intN
fields is compared to its C# counterpart field by field, recursing into each
field's own components, down to bit-for-bit scalars, matching each leaf's
declaration path (field names, not just position) and declared type as well
as its value. CultCellular (math.cs, cellular) is the first and, for
now, only consumer. A struct return with a mismatched, reordered-by-name, or
retyped field does not get a second comparison path or a shape of its own;
it fails the same walk that already handles a bare vector return.
Invariant 8: Value-and-Gradient Primitives
A primitive tagged invariant 8 returns its value and analytic gradient
together, laid out as float4(gradient.xyz, value.w), with no value-only twin
(a value-only form would be a second path with no consumer). smin_grad and
cellular are the first primitives in this family:
-
smin_grad(float4 a, float4 b, float k)is Inigo Quilez's quadratic-polynomial smooth minimum ("smooth minimum", https://iquilezles.org/articles/smin/), carried to value-and-gradient form. Its blend factorhis affine inb.w - a.w, so differentiating the value with respect to position, the terms carryingdh/dpcancel exactly; the surviving gradient islerp(∇b, ∇a, h), the samehthe value uses. This is the analytic gradient, not an approximation, and it is continuous across the|a.w - b.w| = kseam wherehsaturates to 0 or 1. -
cellular(float3 p)is Worley's cellular texture basis function ("A Cellular Texture Basis Function", SIGGRAPH 1996), searched over the jittered 5×5×5 neighbourhood of feature points selected bypcg3d(never the sin-basedhash), with cells whose position-only lower bound already exceeds the running F2 skipped before their hash is even computed. It returnsCultCellular { nearest, edge, id }:nearestis(∇F1, F1),edgeis(∇F2 - ∇F1, F2 - F1), andidis the nearest cell'spcg4dhash (over the cell coordinate alone, never thepcg3dhash that produced its jitter) mapped to[0, 1).∇F1and∇F2are each undefined exactly at their own feature point (F1 = 0orF2 = 0);cellularfollows the repo's existing degenerate-normal convention (GameCult.Geometry.CultGeometryIsoSurface.EmitOrientedTriangle, which guards a zero-length normal and returns the zero vector instead of the NaN a barenormalizegives there) and returns the zero vector rather than NaN for either.F1 = 0is ordinary (psits on a feature point);F2 = 0needs two distinct cells'pcg3d-jittered feature points to land on the same float32 value in every component, which is unreachable at ordinary magnitudes but confirmed reachable (see "Precision domain" below). The identity of the nearest and second-nearest feature point changes discontinuously across theF1 = F2set (a genuine kink, not a numerical artifact), so∇F1and∇F2are only continuous away from that set.The 5×5×5 radius is exact, not merely safer than the classic 3×3×3 radius: for a query at position
uinside its own cell (uin[0, 1)^3per component) and a candidate feature at integer cell offsetdwith jitterjin[0, 1)^3, the per-axis displacement(u_i - j_i) - d_iis always strictly greater in magnitude thanmax(0, |d_i| - 1), becauseu_i - j_iis always strictly inside(-1, 1). So any cell with|d_i| >= 3on some axis is strictly farther than 2 from the query. Two real, always-present candidates — the query's own cell, and whichever single-axis-offset neighbour sits on the near side of the query's position in that axis — each have distance strictly less thansqrt(3); F2 is at most the larger of these two (any two real candidates upper-bound the 2nd-smallest value over the full infinite candidate set), soF1 < sqrt(3)andF2 < sqrt(3)always, comfortably under the radius-2 exclusion distance of 2. 3×3×3's matching argument only reaches radius 1, whose excluded cells start at distance 1, short of thesqrt(3)ceiling — the gap its measured failures (9 of 400,000 points in[-50, 50]^3, worst error 0.088) live in.CellularAndSminGradTestspins both the prune's bit-identical equivalence to an unpruned 5×5×5 reference and the search's exact agreement with an independent 7×7×7 brute-force oracle.Precision domain:
cellular's exactness above is a statement about the search radius, not about float32. Past|p|of roughly2^23, adjacent integer cells stop being distinguishable from their neighbours at float32 precision in some directions, and distinct cells' jittered features can round onto the same value, makingF1 = F2ties (and, per-component,F2 = 0) increasingly common from about1e6and confirmed at2^24(measured: 4096 of 4096 sampled integer points at2^24hit this before the guard above).cellularstays finite there; it does not stay accurate in the sense of matching the idealized real-valued Worley field.
Integer hashing uses the PCG hashes from Jarzynski and Olano, "Hash Functions
for GPU Rendering" (JCGT 9(3), 2020): pcg(uint) is O'Neill's RXS-M-XS 32/32
permutation over one LCG step, and pcg3d/pcg4d are the paper's (3 → 3) and
(4 → 4) hashes. They use only uint multiply, add, xor, and shifts. dxc wraps
uint multiply and add modulo 2^32 exactly as C# unchecked arithmetic does, so
they are integer-exact in HLSL and on the CPU, GPU included, unlike the
sin-based hash. CultMath has no uint vectors, so pcg3d(int3) and
pcg4d(int4) carry uint bit patterns in int components. The float2/float3/float4
overloads hash the IEEE-754 bits (asuint), so -0 and 0 hash differently.
pcg3d(float2) holds z at 0, which is the paper's route for (2 → N) inputs.
Seeds and other scalar uses take one output component.
Where HLSL is silent, CultMath keeps its own decisions and does not defer to
Unity.Mathematics: hash returns float, and Random is CultMath's own xorshift32. Engine-shaped
helpers that HLSL lacks (float2x2.Rotate, float3x3.Euler, quaternion,
snoise) enter only when a consumer needs them, with their semantics stated in
code.
Known C# friction: under using static CultMath.math; the constructor
functions (float3(...), float3x3(...)) hide the type names in member access,
so static members need a qualified type (CultMath.float3x3.Euler(...)).
Rules
- Keep type names HLSL-shaped:
float2,float3,float4,float3x3, andmath. - Keep Rust as the owner of native hot-path kernels and parity fixtures.
- Keep C#, shader, and scripting surfaces as runtime wrappers, not competing math authorities.
- Keep
shaders/CultMath.hlslas the canonical shader mirror for shared CultMath functions HLSL does not already provide (HLSL intrinsics such asmul,any, andlogneed no mirror). Project-local shader helpers should move here once more than one organ needs them or once CPU/GPU parity matters. - Implement public shader semantics directly; do not copy Unity.Mathematics.
- Prefer plain mutable value types with public component fields, as HLSL does.
- Prefer component-wise overloads over clever generic machinery until the API earns that complexity.
- Keep the surface boring and exact. Fill what a consumer uses, guided by HLSL semantics; noise primitives, matrices, quaternions, and packing helpers need an owner before they enter.
- Keep the core assembly engine-free. Unity conversions live in the Unity
package's
CultMath.UnityBridgeassembly.
Non-Goals
- Compiling C# to shaders.
- Generating HLSL from Rust or Rust from HLSL.
- Replacing
System.Numericsfor general .NET work. - Recreating every Unity.Mathematics type because a spreadsheet somewhere says “coverage.” That way lies decorative obesity.