namespace CultMath; public static partial class math { // Interval arithmetic over float2(lo, hi), lo <= hi, both finite (design.md, "Intervals"). Every // iv_* function returns an interval that contains f(x) for every x in its input intervals, where // f(x) is the same function evaluated pointwise in float32, mirrored by cultmath_iv_* in // shaders/CultMath.Interval.hlsl. Each bound is computed with the pointwise function's own float32 // operations; because IEEE round-to-nearest is monotone, an op that is monotone on its region // encloses its float32 evaluation with no widening. Where float32 evaluation is not monotone, or // the libm is not required to be, the bound is widened by exactly one ulp, and the doc comment // says so. There is no empty interval: a caller that needs "provably empty" tests hi < cutoff. // Lipschitz constant of snoise(float3) in its input: an upper bound on the length of its analytic // gradient. Provenance: NoiseBoundTests.MeasureLipschitz (slow, explicit) takes the largest gradient // length over 1e6 seeded points, refines the 1e4 largest by gradient ascent, and multiplies the // refined maximum by 1.10; NoiseBoundTests.LipschitzConstantPinsSampledGradients pins this value // against a fast re-measure and the ascent from MeasureLipschitz's witness. // Empirical with a margin, not a proof; the enclosure tests are the defence. A change to the // snoise kernel must re-run MeasureLipschitz and re-pin this constant. public const float SNOISE_LIPSCHITZ = 10.099261f; // Lipschitz constant of snoise(float2) in its input, with SNOISE_LIPSCHITZ's provenance rule: // NoiseBoundTests.MeasureLipschitz2 (slow, explicit) takes the largest gradient length (central // differences over exact float steps) over 1e6 seeded points, refines the 1e4 largest by ascent and // multiplies by 1.10; NoiseBoundTests.Lipschitz2ConstantPins pins it against a fast re-measure and // the ascent from MeasureLipschitz2's witness. A change to the 2D snoise kernel must re-run // MeasureLipschitz2 and re-pin this constant. public const float SNOISE2_LIPSCHITZ = 8.117002f; /// The point interval [x, x]. public static float2 iv_point(float value) => new(value, value); /// Encloses x + y for x in a, y in b. Monotone: no widening. public static float2 iv_add(float2 a, float2 b) => new(a.x + b.x, a.y + b.y); /// Encloses x - y for x in a, y in b. Monotone: no widening. public static float2 iv_sub(float2 a, float2 b) => new(a.x - b.y, a.y - b.x); /// Encloses -x for x in a. Exact. public static float2 iv_neg(float2 a) => new(-a.y, -a.x); /// /// Encloses x * y for x in a, y in b: the least and greatest of the four corner products. The /// product is monotone in each factor for a fixed sign of the other, so no widening. /// public static float2 iv_mul(float2 a, float2 b) { var p0 = a.x * b.x; var p1 = a.x * b.y; var p2 = a.y * b.x; var p3 = a.y * b.y; return new(min(min(p0, p1), min(p2, p3)), max(max(p0, p1), max(p2, p3))); } /// Encloses x * s for x in a. Monotone: no widening. public static float2 iv_scale(float2 a, float s) => s >= 0.0f ? new(a.x * s, a.y * s) : new(a.y * s, a.x * s); /// Encloses abs(x) for x in a; an interval straddling zero gives [0, max(-lo, hi)]. Exact. public static float2 iv_abs(float2 a) { if (a.x >= 0.0f) return a; if (a.y <= 0.0f) return new(-a.y, -a.x); return new(0.0f, max(-a.x, a.y)); } /// Encloses min(x, y) for x in a, y in b. Monotone: no widening. public static float2 iv_min(float2 a, float2 b) => new(min(a.x, b.x), min(a.y, b.y)); /// Encloses max(x, y) for x in a, y in b. Monotone: no widening. public static float2 iv_max(float2 a, float2 b) => new(max(a.x, b.x), max(a.y, b.y)); /// /// Encloses x * x for x in a; an interval straddling zero gives [0, max(lo * lo, hi * hi)]. Tighter /// than iv_mul(a, a), which cannot know both factors are the same x. Monotone on each side of zero: /// no widening. /// public static float2 iv_sqr(float2 a) { var l = a.x * a.x; var h = a.y * a.y; if (a.x >= 0.0f) return new(l, h); if (a.y <= 0.0f) return new(h, l); return new(0.0f, max(l, h)); } /// /// Encloses sqrt(x) for x in a with x >= 0 (sqrt's domain): lo is clamped at 0, so [-4, 9] gives [0, 3] /// and an interval wholly below zero gives [0, 0]. sqrt is correctly rounded, hence monotone: no /// widening. /// public static float2 iv_sqrt(float2 a) => new(sqrt(max(a.x, 0.0f)), sqrt(max(a.y, 0.0f))); /// /// Encloses exp(x) for x in a. Widened by one ulp on each side, because exp is not required to be /// correctly rounded, so a libm need not be monotone. Where exp(hi) overflows to infinity, hi is NaN, /// which a cull test hi < cutoff reads as "not provably below", the safe side. /// public static float2 iv_exp(float2 a) { var lo = exp(a.x); var hi = exp(a.y); return new(lo > 0.0f ? asfloat(asuint(lo) - 1u) : 0.0f, asfloat(asuint(hi) + 1u)); } /// Encloses clamp(x, minimum, maximum) for x in a. Monotone: no widening. public static float2 iv_clamp(float2 a, float minimum, float maximum) => new(clamp(a.x, minimum, maximum), clamp(a.y, minimum, maximum)); /// Encloses saturate(x) for x in a. Monotone: no widening. public static float2 iv_saturate(float2 a) => new(saturate(a.x), saturate(a.y)); /// /// Encloses smoothstep(minimum, maximum, x) for x in a. smoothstep is monotone in x (increasing when /// minimum < maximum, decreasing when minimum > maximum), so the bound is its value at the two /// endpoints, ordered. Its float32 evaluation t * t * (3 - 2t) is not monotone, by at most one ulp /// (IntervalTests.MeasureMonotonicity), so the bound is widened by one ulp inside [0, 1]. /// public static float2 iv_smoothstep(float minimum, float maximum, float2 a) { var s0 = smoothstep(minimum, maximum, a.x); var s1 = smoothstep(minimum, maximum, a.y); var lo = min(s0, s1); var hi = max(s0, s1); return new(lo > 0.0f ? asfloat(asuint(lo) - 1u) : 0.0f, hi < 1.0f ? asfloat(asuint(hi) + 1u) : 1.0f); } /// /// Encloses lerp(x, y, amount) = x + (y - x) * amount for x in a, y in b, by evaluating that expression /// with iv_sub, iv_scale and iv_add. Each step is monotone, so the result encloses the float32 lerp /// with no widening, for any amount. It is the natural interval extension: x appears twice, so for /// non-point a the width is (width(a) + width(b)) * |amount| + width(a), wider than the true range. /// public static float2 iv_lerp(float2 a, float2 b, float amount) => iv_add(a, iv_scale(iv_sub(b, a), amount)); /// /// Encloses snoise(x) for every x within distance radius of centre: [n - L r, n + L r] intersected /// with [-1, 1], where n = snoise(centre) and L = SNOISE_LIPSCHITZ. radius must be at least 0. One /// snoise evaluation, value only. A domain warp that moves x by at most D is enclosed by passing /// radius + D (NoiseBoundTests.WarpedPointsStayEnclosed). /// public static float2 iv_snoise_ball(float3 centre, float radius) { var n = snoise(centre); var e = SNOISE_LIPSCHITZ * radius; return new(max(n - e, -1.0f), min(n + e, 1.0f)); } /// /// Encloses snoise(x) for every 2D x within distance radius of centre: [n - L2 r, n + L2 r] intersected /// with [-1, 1], n = snoise(centre), L2 = SNOISE2_LIPSCHITZ. radius must be at least 0. One snoise /// evaluation, value only. A consumer's 2D flow built from snoise(float2) varies over a ball by at /// most the width this gives (NoiseBoundTests.CentredWarpStaysEnclosed). /// public static float2 iv_snoise_ball(float2 centre, float radius) { var n = snoise(centre); var e = SNOISE2_LIPSCHITZ * radius; return new(max(n - e, -1.0f), min(n + e, 1.0f)); } /// /// Encloses the fBm value, sum of a_i * snoise(x * f_i) over the octaves, for every x within distance /// radius of centre: the octave sum of iv_snoise_ball(centre * f_i, radius * |f_i|) scaled by a_i, /// with frequency f_i and amplitude a_i compounded exactly as the value-and-gradient fBm compounds /// them (its .w is what NoiseBoundTests.FbmBallEnclosesPoints encloses). octaves is clamped to [0, 16] /// as there. /// public static float2 iv_fbm_ball(float3 centre, float radius, int octaves, float lacunarity, float gain) { octaves = clamp(octaves, 0, 16); var amplitude = 1.0f; var frequency = 1.0f; var sum = new float2(0.0f, 0.0f); for (var i = 0; i < octaves; i++) { sum = iv_add(sum, iv_scale(iv_snoise_ball(centre * frequency, radius * abs(frequency)), amplitude)); frequency *= lacunarity; amplitude *= gain; } 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. /// The ball also carries its own float32 rounding: the radius is widened by (|c|_1 + radius) 2^-20. /// With u = 2^-24, each centre component carries at most two roundings (z_m, then the product), so the /// float centre is within 2u |c|_1 of the exact one; the radius carries at most seven, so the exact /// radius is at most (1 + 7u) times the float one; the widening rounds once more. 2^-20 = 16u covers /// 8u (|c|_1 + radius) twice over, and fma contraction only removes roundings. So every exact point of /// every ray, at any depth and slope, lies in the returned float ball /// (NoiseBoundTests.TileBallEnclosesEveryRaySegment, degenerate and far segments included). The caller /// rotates and translates the centre into world space (the radius is unchanged) and scales both by its /// noise frequency; the rounding of that transform is the caller's. /// 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 cx = centreSlope.x * zm; var cy = centreSlope.y * zm; var radius = (z1 - z0) * 0.5f * axis + z1 * footprintPerDepth + warp; radius += (abs(cx) + abs(cy) + abs(zm) + radius) * 9.5367431640625e-7f; return new float4(cx, cy, zm, radius); } }