CultLib/packages/cultmath/README.md

CultMath

CultMath is the project name. Its clean .NET package identity is GameCult.Math, owned and released from the CultLib monorepo.

Clean-room math shaped for people who think in HLSL.

CultMath provides lowercase vector types, shader-style intrinsics, and native hot-path kernels so math-heavy renderer code can move between C#, Rust, and HLSL without turning every line into a translation exercise. It is not a Unity.Mathematics clone. It is a small, Aquarium-born library built from public shader semantics.

Current Surface

• float2, float3, float4
• component-wise arithmetic
• scalar-to-vector splats
• every HLSL swizzle (xyzw and rgba, repeats readable, non-repeating masks writable) and every HLSL mixed constructor, generated by tools/generate-swizzles.ps1
• conversions to and from System.Numerics
• Random, a compact deterministic XORShift stream with scalar and vector draws
• BatchMath SoA kernels over Span<float> / ReadOnlySpan<float> using System.Numerics.Vector<float> when available, including radial falloff acceleration and semi-implicit Euler integration
• math intrinsics: radians, degrees, abs, floor, ceil, frac, min, max, clamp, saturate, lerp, step, smoothstep, dot, cross, length, distance, normalize, reflect, csum, erf, erfinv (scalar only), exponential decay/damp, intercept/segment helpers (distance_to_segment in 2D and 3D, with and without out closest, and segment_closest), Catmull-Rom, Bezier curves, and deterministic value-noise primitives
• Site cells: power_cells and multiplicative_cells return the two nearest sites of a point as CultSiteCells, soft_gabriel_gate gates a pair of sites by the empty-disc margin. Each is a loop over the shader steps cultmath_power_score / cultmath_multiplicative_score, cultmath_site_cells_empty, cultmath_site_cells_insert, cultmath_site_cells_border, cultmath_power_border_step (the exact power cell border, power_border) and cultmath_gabriel_margin; a shader loops over its own buffer.
• Weighted lattice cells: weighted_lattice_cells returns float4(F1, F2, smooth, id) over a jittered, drifting lattice whose cell weights come from the exact power border of the body span at each cell centre, with a stretched metric and an exact ring search over the stated range (LatticeMaxBoost, LatticeMaxStretch, LatticeMaxSmoothing). It composes the public steps lattice_site, lattice_weight, lattice_distance and lattice_smooth_step. The shaders carry the four steps as cultmath_lattice_site, cultmath_lattice_weight, cultmath_lattice_distance and cultmath_lattice_smooth_step, and the whole function as cultmath_weighted_lattice_cells(p, time, bodies, count, ...) over a float4 bodies[CULTMATH_MAX_SITES] array (128 by default; define the macro before including to change it); cultmath_power_border(p, sites, count) is the matching border. The argument checks become the shader caller's preconditions.
• shaders/CultMath.hlsl, a canonical HLSL mirror include for shader-side parity. HLSL already owns float2, float3, and float4; the include exposes cultmath_* functions for shared semantics HLSL does not provide. It includes shaders/CultMath.Phacelle.hlsl (MPL-2.0), shaders/CultMath.Cycles.hlsl (Apache-2.0) and shaders/CultMath.Interval.hlsl and shaders/CultMath.Affine.hlsl from the same directory, so ship all five.
• Cycles node semantics (Apache-2.0): cycles_* functions that compute what Blender's Cycles renderer computes for the Math node operations whose results differ from a plain intrinsic (cycles_divide, cycles_power, cycles_modulo, cycles_wrap, cycles_pingpong, cycles_smooth_min, ...), Map Range (cycles_map_range_linear, _stepped, _smoothstep, _smootherstep), Clamp (cycles_clamp_minmax, cycles_clamp_range), Mix (cycles_mix_float, cycles_mix_vector and every colour blend mode as cycles_mix_<mode>), RGB to BW, and cycles_ramp_index, where a Color Ramp reads its table. cultmath_cycles_* in HLSL and GLSL. Operands are finite floats, and the tests hold every function to the results of Blender 5.2.2's own CPU Cycles (tools/cycles-oracle).
• interval arithmetic for culling empty space: iv_* functions over float2(lo, hi) (iv_add, iv_mul, iv_exp, iv_smoothstep, ...) and iv_snoise_ball/iv_fbm_ball, which bound snoise and fbm_grad over a ball, and iv_frustum_ball, the ball around a screen tile's rays over a depth segment, so one probe serves the whole tile (its radius carries its own float32 rounding bound). The arithmetic functions return an interval built to contain the function's value over their operand intervals, so a raymarch can skip a segment whose hi is below its cutoff; cultmath_iv_* in HLSL. The noise functions rest on empirical constants with a margin, not a proof: iv_snoise_ball(float3) on SNOISE_LIPSCHITZ (iv_fbm_ball through it), iv_snoise_ball(float2) on SNOISE2_LIPSCHITZ, and af_snoise on SNOISE_HESSIAN and SNOISE_LIPSCHITZ (af_fbm through it); the enclosure tests sample them. iv_frustum_ball and af_frustum_ball read no noise constant: the ball is geometry plus a rounding widening, and the noise call it feeds carries the constant. The bounds compose with a consumer's own analytic envelope (a height fog, a carved sphere): its interval over the segment proves empty space in one probe, and the noise ball is consulted only near the surface. See docs/design.md, "Intervals".
• shaders/CultMath.glsl (MIT), the same cultmath_* library in GLSL ES 3.00 for WebGL2, generated from CultMath.hlsl (never edited by hand), and shaders/CultMath.Phacelle.glsl (MPL-2.0), generated from CultMath.Phacelle.hlsl, which holds cultmath_phacelle alone, and shaders/CultMath.Cycles.glsl (Apache-2.0), generated from CultMath.Cycles.hlsl, which holds the cultmath_cycles_* functions. GLSL has no #include: a WebGL consumer concatenates CultMath.glsl after its own #version 300 es line and precision highp float; precision highp int; (the library declares no precision, and its hashes need 32-bit integers), then CultMath.Phacelle.glsl only if it calls cultmath_phacelle and CultMath.Cycles.glsl only if it calls a cultmath_cycles_ function, then its own shader source.
• Span primitives (math.Span.cs, cultmath_* in HLSL and GLSL): snoise_hessian, the analytic Hessian of snoise(float3) on the same lattice, hash and tie order as snoise_grad (a symmetric float3x3; GLSL mat3), and integral_clamp_linear(a, b, lo, hi, t0, t1), the closed-form integral over [t0, t1] of clamp(a + b t, lo, hi); and the octave stages span_fbm(path, stage, octaves, lacunarity, gain) and span_ridged (shader twins cultmath_span_fbm and cultmath_span_ridged, whose callers build the SpanStage themselves), over a SpanPath and a SpanStage (SpanStage.Identity is the plain fbm in C#), which return a SpanNoise (field as float4(gradient, value), curvature, fold) for a stretched, offset, shifted octave sum over a span. Three measured bounds describe snoise: SNOISE_LIPSCHITZ (gradient length, NoiseBoundTests.MeasureLipschitz), SNOISE_HESSIAN (Hessian spectral norm, MeasureHessian) and SNOISE_THIRD (third-derivative operator norm, MeasureThird); each is 1.10 times a seeded maximum refined by ascent, and a fast test pins it. They are empirical with a margin, not proofs.
• Voronoi.SampleTones, a C# batch surface that calls the Rust cultmath-core native kernel when cultmath_core is available and falls back to the managed parity path otherwise.

Native Core

The canonical hot-path body lives in native/cultmath-core. It exports a C ABI for batch kernels such as cultmath_apollonian_voronoi_tones.

Runtime wrappers own syntax and integration. Rust owns optimized primitive kernel behavior and parity fixtures.

Example

using CultMath;

float3 normal = math.normalize(new float3(0.25f, 1.0f, -0.1f));
float rim = math.saturate(1.0f - math.dot(normal, new float3(0.0f, 0.0f, -1.0f)));
float glow = math.smoothstep(0.2f, 1.0f, rim);
float grain = math.value_noise_bicubic(math.float2(12.0f, 3.5f));

#include "CultMath.hlsl"

float3 normal = normalize(float3(0.25, 1.0, -0.1));
float rim = cultmath_saturate(1.0 - dot(normal, float3(0.0, 0.0, -1.0)));
float glow = cultmath_smoothstep(0.2, 1.0, rim);
float grain = cultmath_value_noise_bicubic(float2(12.0, 3.5));

Provenance

The small spline, damping, and pursuit helpers were promoted from Aetheria's local AetheriaMath surface. The value-noise family follows public shader literature from Inigo Quilez's noise and mini-spline articles, expressed in CultMath names with tests instead of copied project-local helper drift.

Build

dotnet build packages/cultmath/src/CultMath/CultMath.csproj
dotnet test packages/cultmath/tests/CultMath.Tests/CultMath.Tests.csproj
cargo test --manifest-path packages/cultmath/native/cultmath-core/Cargo.toml
cargo build --release --manifest-path packages/cultmath/native/cultmath-core/Cargo.toml
.\packages\cultmath\scripts\build-unity-package.ps1

Unity package

CultMath's Unity 2021.3 surface is the tracked precompiled package at packages/cultmath/unity/org.gamecult.cultmath. Unity consumes CultMath.dll and the numeric CultMath.hlsl; it does not compile the repository's current-language C# source tree and does not require a consumer csc.rsp workaround.

"org.gamecult.cultmath": "https://github.com/GameCult/CultLib.git?path=/packages/cultmath/unity/org.gamecult.cultmath"

The repository root is not a Unity package. Build the tracked package with packages/cultmath/scripts/build-unity-package.ps1; the script fresh-builds the netstandard2.1 assembly and rejects stale binaries, missing metadata, unexpected assemblies, or leaked C# source.

Before tagging cultmath-unity-v*, run the import and dispatch smoke on a Windows machine with a GPU, alone: packages/cultmath/scripts/unity-smoke/run-unity-smoke.ps1 -UnityExe <path to Unity.exe>. It builds a scratch project outside the repository that references the package by a file: path, dispatches a compute shader that includes CultMath.Interval.hlsl and CultMath.Affine.hlsl, requires a deliberately broken control shader to be rejected, and deletes the project afterwards.

Shader Tooling

CultMath keeps portable DXC outside git under packages/cultmath/.tools/:

.\packages\cultmath\tools\get-dxc.ps1
.\packages\cultmath\tools\compile-hlsl.ps1
.\packages\cultmath\tools\get-spirv-cross.ps1
.\packages\cultmath\tools\compile-hlsl-spirv.ps1 `
  -ShaderPath E:\Projects\Odin\crates\muninn-move-tracker\shaders\MoveSphereCandidate.comp.hlsl `
  -OutputPath E:\Projects\Odin\crates\muninn-move-tracker\artifacts\shader\MoveSphereCandidate.comp.spv `
  -IncludePath E:\Projects\CultLib\packages\cultmath\shaders
.\packages\cultmath\tools\compile-spirv-metal.ps1 `
  -SpirvPath E:\Projects\Odin\crates\muninn-move-tracker\artifacts\shader\MoveSphereCandidate.comp.spv `
  -OutputPath E:\Projects\Odin\crates\muninn-move-tracker\artifacts\shader\MoveSphereCandidate.comp.metal

tools/glsl/build-glsl.sh <outdir> (Linux, repository root) builds the library GLSL from the HLSL with dxc, SPIRV-Cross and SPIRV-Tools and writes core.glsl, cycles.glsl and phacelle.glsl bodies into <outdir>. It does not yet own the committed GLSL; GlslLowering still does. GLSL_DIR=<outdir> tools/device/run-lavapipe.sh runs that output on lavapipe and compares it with the HLSL results bit for bit instead of judging the committed files. That comparison is in strict form (dxc -Gis and a NoContraction decoration on every float result of both modules), and a consumer overrides CULTMATH_MAX_SITES in the built GLSL the same way as in HLSL: define it before including core.glsl.

compile-hlsl.ps1 compiles both CultMath.hlsl copies as a lib_6_3 library with the x64 DXC; a warning fails it too (-WX).

DXC emits Vulkan SPIR-V with -spirv. -TargetEnv vulkan1.2 is exposed by the script, but the current Windows DXC release compiled this shader successfully with DXC's default Vulkan target while rejecting the dotted target-env value. The SPIR-V script applies default Vulkan register shifts for cbuffers, textures, UAVs, and samplers so cross-compiled Metal buffers do not alias by resource class. SPIRV-Cross emits Metal Shading Language from SPIR-V on Windows; building an iPad-ready .metallib still belongs to Apple's Metal compiler on an Apple toolchain.

The lavapipe conforming run executes every fixture family through the HLSL (dxc) and the committed GLSL (glslang) on Mesa lavapipe and judges the results in GlslMirrorTests.DeviceResultsHoldFixture. It needs a Linux container with apt: from the repo root, tools/stopgap/ygg-verify.sh <repo> <rev> mcr.microsoft.com/dotnet/sdk:10.0 'bash packages/cultmath/tools/device/run-lavapipe.sh'. WRITE_BOUNDS=1 in front of the script re-records the device's bounds file and prints it between BOUNDS-BEGIN and BOUNDS-END.

Doctrine

The goal is mechanical sympathy between CPU-side authoring, native kernels, and GPU-side shader math. If an intrinsic exists here, it should behave like the shader concept unless a runtime's numeric rules make that impossible. Weird deviations get tests and documentation, not folklore.

CultMath is still not a shader generator. Projects should include shaders/CultMath.hlsl directly or add that directory to their shader include path. If a shared operation needs CPU/GPU parity, put the primitive here and test it here before copying local math helpers into a renderer or daemon.