diff --git a/packages/cultmath/shaders/CultMath.Interval.hlsl b/packages/cultmath/shaders/CultMath.Interval.hlsl index 3fdac41d..732ef3a0 100644 --- a/packages/cultmath/shaders/CultMath.Interval.hlsl +++ b/packages/cultmath/shaders/CultMath.Interval.hlsl @@ -104,4 +104,15 @@ float2 cultmath_iv_fbm_ball(float3 centre, float radius, int octaves, float lacu return sum; } +// A ball (xyz centre, w radius) enclosing every point of every ray of a screen tile over the depth segment +// [z0, z1], warped by at most warp. Camera frame: pinhole at the origin looking down +z, ray (m z, z). +// footprintPerDepth = N / (sqrt(2) f) for an N x N tile at focal length f. Derivation in math.Interval.cs. +float4 cultmath_iv_frustum_ball(float2 centreSlope, float z0, float z1, float footprintPerDepth, float warp) +{ + float zm = (z0 + z1) * 0.5; + float axis = sqrt(centreSlope.x * centreSlope.x + centreSlope.y * centreSlope.y + 1.0); + float radius = (z1 - z0) * 0.5 * axis + z1 * footprintPerDepth + warp; + return float4(centreSlope.x * zm, centreSlope.y * zm, zm, radius); +} + #endif diff --git a/packages/cultmath/src/CultMath/math.Interval.cs b/packages/cultmath/src/CultMath/math.Interval.cs index 7c2ba6c9..547c4acc 100644 --- a/packages/cultmath/src/CultMath/math.Interval.cs +++ b/packages/cultmath/src/CultMath/math.Interval.cs @@ -164,4 +164,27 @@ public static partial class math return sum; } + + /// + /// A ball (xyz centre, w radius) enclosing every point of every ray of a screen tile over the depth + /// segment [z0, z1], each point then moved by a warp of length at most warp: the ball to hand + /// iv_snoise_ball (scaled by the noise frequency) when one probe serves the whole tile. Camera frame: + /// a pinhole at the origin looking down +z, where the ray of slope m is the points (m z, z). + /// centreSlope is the tile's central slope m_c; footprintPerDepth is the largest distance of any + /// ray's slope from m_c, N / (sqrt(2) f) for an N x N pixel tile at focal length f pixels (the full + /// pixel footprint, so sub-pixel jitter is covered). The centre is (m_c z_m, z_m), z_m = (z0 + z1) / 2; + /// the radius is ((z1 - z0) / 2) |(m_c, 1)| + z1 footprintPerDepth + warp. Derivation: a point of slope + /// m_c + e (|e| <= footprintPerDepth) at depth z is c + (z - z_m)(m_c, 1) + z (e, 0); the first term is + /// at most the first radius term, the second at most the second, and the warp adds at most warp + /// (NoiseBoundTests.TileBallEnclosesEveryRaySegment). The two vectors are never parallel, so the + /// triangle inequality is strict. The caller rotates and translates the centre into world space (the + /// radius is unchanged) and scales both by its noise frequency. + /// + public static float4 iv_frustum_ball(float2 centreSlope, float z0, float z1, float footprintPerDepth, float warp) + { + var zm = (z0 + z1) * 0.5f; + var axis = sqrt(centreSlope.x * centreSlope.x + centreSlope.y * centreSlope.y + 1.0f); + var radius = (z1 - z0) * 0.5f * axis + z1 * footprintPerDepth + warp; + return new float4(centreSlope.x * zm, centreSlope.y * zm, zm, radius); + } } diff --git a/packages/cultmath/tests/CultMath.Tests/HlslSourceCompatibilityTests.cs b/packages/cultmath/tests/CultMath.Tests/HlslSourceCompatibilityTests.cs index 07f026ff..a5965a3d 100644 --- a/packages/cultmath/tests/CultMath.Tests/HlslSourceCompatibilityTests.cs +++ b/packages/cultmath/tests/CultMath.Tests/HlslSourceCompatibilityTests.cs @@ -133,7 +133,7 @@ public sealed class HlslSourceCompatibilityTests } Assert.True(mismatches.Count == 0, $"{mismatches.Count} mismatches:{Environment.NewLine}{string.Join(Environment.NewLine, mismatches.Take(12))}"); - Assert.Equal(52, compared.Count); + Assert.Equal(53, compared.Count); } /// diff --git a/packages/cultmath/tests/CultMath.Tests/NoiseBoundTests.cs b/packages/cultmath/tests/CultMath.Tests/NoiseBoundTests.cs index 45578ec7..0235b322 100644 --- a/packages/cultmath/tests/CultMath.Tests/NoiseBoundTests.cs +++ b/packages/cultmath/tests/CultMath.Tests/NoiseBoundTests.cs @@ -7,8 +7,12 @@ namespace CultMath.Tests; /// /// The noise bounds (design.md, "Intervals"): iv_snoise_ball and iv_fbm_ball enclose their functions over /// a ball, a domain warp bounded by D is enclosed by enlarging the radius by D, SNOISE_LIPSCHITZ has -/// measured provenance, and an interval-culled march spends fewer snoise evaluations than a dense one for -/// the same transmittance. Lines starting IV-REPORT carry the numbers the cut report quotes. +/// measured provenance, iv_frustum_ball encloses a screen tile's rays over a depth segment, and an +/// interval-culled march spends fewer snoise evaluations than a dense one for the same transmittance. +/// Lines starting IV-REPORT carry the numbers the cut report quotes. +/// +/// Hand mutations of iv_frustum_ball that TileBallEnclosesEveryRaySegment must kill: z0 for z1 in the +/// lateral term (z0 * footprintPerDepth); |m_c| for |(m_c, 1)| in the depth term; the warp dropped. /// public sealed class NoiseBoundTests { @@ -107,6 +111,57 @@ public sealed class NoiseBoundTests } } + // ---- The tile ball and the composed bound ---- + + /// + /// iv_frustum_ball encloses every point of every ray of an N x N tile over a depth segment, sub-pixel + /// jitter included, each point then moved by a flow of length at most warp, with no tolerance: 2,000 + /// seeded tiles (N in {1, 4, 8, 16}, f in [500, 3000], |m_c| up to 1.1, segments over the slab's, the + /// fog's and the void's depth ranges, a quarter starting at the camera) x 64 points, the first eight at + /// a corner of the footprint at either end of the segment with a full-length flow. It also pins the + /// ball to the derivation: centre and radius equal the formula evaluated in double to one part in + /// 1e5, so a ball that grows (sound but wasteful) fails too. Each tile's camera is drawn on its own, as + /// a moving camera's frames are: no ball, mask or probe result is carried from one to the next. + /// + [Fact] + public void TileBallEnclosesEveryRaySegment() + { + var random = new System.Random(0x711E); + int[] sizes = { 1, 4, 8, 16 }; + float[] depths = { 12.0f, 1000.0f, 2400.0f }; + for (var t = 0; t < 2000; t++) + { + var n = sizes[random.Next(sizes.Length)]; + var focal = Uniform(random, 500.0f, 3000.0f); + var slope = new float2(Uniform(random, -0.77f, 0.77f), Uniform(random, -0.77f, 0.77f)); + var depth = depths[random.Next(depths.Length)]; + var z0 = random.Next(4) == 0 ? 0.0f : Uniform(random, 0.0f, depth * 0.9f); + var z1 = z0 + LogUniform(random, 1.0e-3f * depth, depth - z0); + var warp = random.Next(4) == 0 ? 0.0f : LogUniform(random, 1.0e-3f, 60.0f); + var half = n / (2.0f * focal); + var footprint = n / (MathF.Sqrt(2.0f) * focal); + var ball = iv_frustum_ball(slope, z0, z1, footprint, warp); + var centre = new float3(ball.x, ball.y, ball.z); + + var zm = (z0 + (double)z1) / 2.0; + var radius = (z1 - (double)z0) / 2.0 * Math.Sqrt((double)slope.x * slope.x + (double)slope.y * slope.y + 1.0) + z1 * (double)footprint + warp; + Assert.True(Math.Abs(ball.w - radius) <= 1.0e-5 * radius, $"radius {ball.w:R}, derivation {radius:R}"); + Assert.True(Math.Abs(ball.x - slope.x * zm) + Math.Abs(ball.y - slope.y * zm) + Math.Abs(ball.z - zm) <= 1.0e-5 * zm, $"centre {centre}, derivation ({slope.x * zm:R}, {slope.y * zm:R}, {zm:R})"); + + for (var i = 0; i < 64; i++) + { + var offset = i < 8 + ? new float2((i & 1) == 0 ? -half : half, (i & 2) == 0 ? -half : half) + : new float2(Uniform(random, -half, half), Uniform(random, -half, half)); + var z = i < 8 ? ((i & 4) == 0 ? z0 : z1) : Uniform(random, z0, z1); + var m = slope + offset; + var flow = UnitVector(random) * (i < 8 ? warp : warp * MathF.Sqrt(random.NextSingle())); + var p = new float3(m.x * z, m.y * z, z) + flow; + Assert.True(length(p - centre) <= ball.w, $"iv_frustum_ball({slope}, {z0:R}, {z1:R}, {footprint:R}, {warp:R}) = {ball} misses {p} (slope {m}, depth {z:R}), distance {length(p - centre):R}"); + } + } + } + // ---- The Lipschitz constant ---- private static float GradientNorm(float3 p) @@ -281,6 +336,7 @@ public sealed class NoiseBoundTests Assert.All(snoiseRatios.Concat(fbmRatios), t => Assert.True(double.IsFinite(t.Item2))); } + // ---- The saving ---- /// diff --git a/packages/cultmath/unity/org.gamecult.cultmath/Shaders/CultMath.Interval.hlsl b/packages/cultmath/unity/org.gamecult.cultmath/Shaders/CultMath.Interval.hlsl index 3fdac41d..732ef3a0 100644 --- a/packages/cultmath/unity/org.gamecult.cultmath/Shaders/CultMath.Interval.hlsl +++ b/packages/cultmath/unity/org.gamecult.cultmath/Shaders/CultMath.Interval.hlsl @@ -104,4 +104,15 @@ float2 cultmath_iv_fbm_ball(float3 centre, float radius, int octaves, float lacu return sum; } +// A ball (xyz centre, w radius) enclosing every point of every ray of a screen tile over the depth segment +// [z0, z1], warped by at most warp. Camera frame: pinhole at the origin looking down +z, ray (m z, z). +// footprintPerDepth = N / (sqrt(2) f) for an N x N tile at focal length f. Derivation in math.Interval.cs. +float4 cultmath_iv_frustum_ball(float2 centreSlope, float z0, float z1, float footprintPerDepth, float warp) +{ + float zm = (z0 + z1) * 0.5; + float axis = sqrt(centreSlope.x * centreSlope.x + centreSlope.y * centreSlope.y + 1.0); + float radius = (z1 - z0) * 0.5 * axis + z1 * footprintPerDepth + warp; + return float4(centreSlope.x * zm, centreSlope.y * zm, zm, radius); +} + #endif