diff --git a/packages/cultmath/docs/design.md b/packages/cultmath/docs/design.md index de09ee26..ad8409fd 100644 --- a/packages/cultmath/docs/design.md +++ b/packages/cultmath/docs/design.md @@ -52,7 +52,18 @@ That makes these HLSL rules, not options: operand returns the other (so `saturate(NaN)` is 0), `clamp(x, a, b)` is `min(max(x, a), b)`, and `saturate(x)` is `min(1, max(0, x))`, which maps -0 to +0; `any`/`all` accept numeric vectors (a component is true when it is - not 0); `min`, `max`, and `abs` on int vectors return int vectors. + not 0); `min`, `max`, and `abs` on int vectors return int vectors; int + `clamp` is `IMin(IMax(x, a), b)`, so inverted bounds return `b`. +- Same-size vector conversions (`intN(floatN)`, `floatN(intN)`, `boolN(floatN)`, + `boolN(intN)`, `floatN(boolN)`, `intN(boolN)`) exist as constructors and + `math` functions and follow dxc: float to int is `fptosi`, 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. +- dxc demotes double `frac`, `exp`, `lerp`, and `floor` to float. CultMath's + double overloads keep double precision instead: `frac(double)` is + `x - 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 diff --git a/packages/cultmath/src/CultMath/Swizzles.g.cs b/packages/cultmath/src/CultMath/Swizzles.g.cs index ce84bbc4..db1c56bd 100644 --- a/packages/cultmath/src/CultMath/Swizzles.g.cs +++ b/packages/cultmath/src/CultMath/Swizzles.g.cs @@ -7,6 +7,8 @@ namespace CultMath; public partial struct float2 { public float2(float2 xy) : this(xy.x, xy.y) { } + public float2(int2 value) : this(value.x, value.y) { } + public float2(bool2 value) : this(value.x ? 1.0f : 0.0f, value.y ? 1.0f : 0.0f) { } public float r { readonly get => x; set => x = value; } public float g { readonly get => y; set => y = value; } public readonly float2 xx => new(x, x); @@ -72,6 +74,8 @@ public partial struct float3 public float3(float x, float2 yz) : this(x, yz.x, yz.y) { } public float3(float2 xy, float z) : this(xy.x, xy.y, z) { } public float3(float3 xyz) : this(xyz.x, xyz.y, xyz.z) { } + public float3(int3 value) : this(value.x, value.y, value.z) { } + public float3(bool3 value) : this(value.x ? 1.0f : 0.0f, value.y ? 1.0f : 0.0f, value.z ? 1.0f : 0.0f) { } public float r { readonly get => x; set => x = value; } public float g { readonly get => y; set => y = value; } public float b { readonly get => z; set => z = value; } @@ -320,6 +324,8 @@ public partial struct float4 public float4(float2 xy, float2 zw) : this(xy.x, xy.y, zw.x, zw.y) { } public float4(float3 xyz, float w) : this(xyz.x, xyz.y, xyz.z, w) { } public float4(float4 xyzw) : this(xyzw.x, xyzw.y, xyzw.z, xyzw.w) { } + public float4(int4 value) : this(value.x, value.y, value.z, value.w) { } + public float4(bool4 value) : this(value.x ? 1.0f : 0.0f, value.y ? 1.0f : 0.0f, value.z ? 1.0f : 0.0f, value.w ? 1.0f : 0.0f) { } public float r { readonly get => x; set => x = value; } public float g { readonly get => y; set => y = value; } public float b { readonly get => z; set => z = value; } @@ -1001,6 +1007,8 @@ public partial struct float4 public partial struct int2 { public int2(int2 xy) : this(xy.x, xy.y) { } + public int2(float2 value) : this((int)value.x, (int)value.y) { } + public int2(bool2 value) : this(value.x ? 1 : 0, value.y ? 1 : 0) { } public int r { readonly get => x; set => x = value; } public int g { readonly get => y; set => y = value; } public readonly int2 xx => new(x, x); @@ -1066,6 +1074,8 @@ public partial struct int3 public int3(int x, int2 yz) : this(x, yz.x, yz.y) { } public int3(int2 xy, int z) : this(xy.x, xy.y, z) { } public int3(int3 xyz) : this(xyz.x, xyz.y, xyz.z) { } + public int3(float3 value) : this((int)value.x, (int)value.y, (int)value.z) { } + public int3(bool3 value) : this(value.x ? 1 : 0, value.y ? 1 : 0, value.z ? 1 : 0) { } public int r { readonly get => x; set => x = value; } public int g { readonly get => y; set => y = value; } public int b { readonly get => z; set => z = value; } @@ -1314,6 +1324,8 @@ public partial struct int4 public int4(int2 xy, int2 zw) : this(xy.x, xy.y, zw.x, zw.y) { } public int4(int3 xyz, int w) : this(xyz.x, xyz.y, xyz.z, w) { } public int4(int4 xyzw) : this(xyzw.x, xyzw.y, xyzw.z, xyzw.w) { } + public int4(float4 value) : this((int)value.x, (int)value.y, (int)value.z, (int)value.w) { } + public int4(bool4 value) : this(value.x ? 1 : 0, value.y ? 1 : 0, value.z ? 1 : 0, value.w ? 1 : 0) { } public int r { readonly get => x; set => x = value; } public int g { readonly get => y; set => y = value; } public int b { readonly get => z; set => z = value; } @@ -1995,6 +2007,8 @@ public partial struct int4 public partial struct bool2 { public bool2(bool2 xy) : this(xy.x, xy.y) { } + public bool2(float2 value) : this(value.x != 0.0f, value.y != 0.0f) { } + public bool2(int2 value) : this(value.x != 0, value.y != 0) { } public bool r { readonly get => x; set => x = value; } public bool g { readonly get => y; set => y = value; } public readonly bool2 xx => new(x, x); @@ -2060,6 +2074,8 @@ public partial struct bool3 public bool3(bool x, bool2 yz) : this(x, yz.x, yz.y) { } public bool3(bool2 xy, bool z) : this(xy.x, xy.y, z) { } public bool3(bool3 xyz) : this(xyz.x, xyz.y, xyz.z) { } + public bool3(float3 value) : this(value.x != 0.0f, value.y != 0.0f, value.z != 0.0f) { } + public bool3(int3 value) : this(value.x != 0, value.y != 0, value.z != 0) { } public bool r { readonly get => x; set => x = value; } public bool g { readonly get => y; set => y = value; } public bool b { readonly get => z; set => z = value; } @@ -2308,6 +2324,8 @@ public partial struct bool4 public bool4(bool2 xy, bool2 zw) : this(xy.x, xy.y, zw.x, zw.y) { } public bool4(bool3 xyz, bool w) : this(xyz.x, xyz.y, xyz.z, w) { } public bool4(bool4 xyzw) : this(xyzw.x, xyzw.y, xyzw.z, xyzw.w) { } + public bool4(float4 value) : this(value.x != 0.0f, value.y != 0.0f, value.z != 0.0f, value.w != 0.0f) { } + public bool4(int4 value) : this(value.x != 0, value.y != 0, value.z != 0, value.w != 0) { } public bool r { readonly get => x; set => x = value; } public bool g { readonly get => y; set => y = value; } public bool b { readonly get => z; set => z = value; } @@ -3102,9 +3120,15 @@ public partial struct double3 public static partial class math { public static float2 float2(float2 xy) => new(xy); + public static float2 float2(int2 value) => new(value); + public static float2 float2(bool2 value) => new(value); + public static float2 float2(int value) => new(value, value); public static float3 float3(float x, float2 yz) => new(x, yz); public static float3 float3(float2 xy, float z) => new(xy, z); public static float3 float3(float3 xyz) => new(xyz); + public static float3 float3(int3 value) => new(value); + public static float3 float3(bool3 value) => new(value); + public static float3 float3(int value) => new(value, value, value); public static float4 float4(float x, float y, float2 zw) => new(x, y, zw); public static float4 float4(float x, float2 yz, float w) => new(x, yz, w); public static float4 float4(float x, float3 yzw) => new(x, yzw); @@ -3112,10 +3136,17 @@ public static partial class math public static float4 float4(float2 xy, float2 zw) => new(xy, zw); public static float4 float4(float3 xyz, float w) => new(xyz, w); public static float4 float4(float4 xyzw) => new(xyzw); + public static float4 float4(int4 value) => new(value); + public static float4 float4(bool4 value) => new(value); + public static float4 float4(int value) => new(value, value, value, value); public static int2 int2(int2 xy) => new(xy); + public static int2 int2(float2 value) => new(value); + public static int2 int2(bool2 value) => new(value); public static int3 int3(int x, int2 yz) => new(x, yz); public static int3 int3(int2 xy, int z) => new(xy, z); public static int3 int3(int3 xyz) => new(xyz); + public static int3 int3(float3 value) => new(value); + public static int3 int3(bool3 value) => new(value); public static int4 int4(int x, int y, int2 zw) => new(x, y, zw); public static int4 int4(int x, int2 yz, int w) => new(x, yz, w); public static int4 int4(int x, int3 yzw) => new(x, yzw); @@ -3123,10 +3154,16 @@ public static partial class math public static int4 int4(int2 xy, int2 zw) => new(xy, zw); public static int4 int4(int3 xyz, int w) => new(xyz, w); public static int4 int4(int4 xyzw) => new(xyzw); + public static int4 int4(float4 value) => new(value); + public static int4 int4(bool4 value) => new(value); public static bool2 bool2(bool2 xy) => new(xy); + public static bool2 bool2(float2 value) => new(value); + public static bool2 bool2(int2 value) => new(value); public static bool3 bool3(bool x, bool2 yz) => new(x, yz); public static bool3 bool3(bool2 xy, bool z) => new(xy, z); public static bool3 bool3(bool3 xyz) => new(xyz); + public static bool3 bool3(float3 value) => new(value); + public static bool3 bool3(int3 value) => new(value); public static bool4 bool4(bool x, bool y, bool2 zw) => new(x, y, zw); public static bool4 bool4(bool x, bool2 yz, bool w) => new(x, yz, w); public static bool4 bool4(bool x, bool3 yzw) => new(x, yzw); @@ -3134,4 +3171,6 @@ public static partial class math public static bool4 bool4(bool2 xy, bool2 zw) => new(xy, zw); public static bool4 bool4(bool3 xyz, bool w) => new(xyz, w); public static bool4 bool4(bool4 xyzw) => new(xyzw); + public static bool4 bool4(float4 value) => new(value); + public static bool4 bool4(int4 value) => new(value); } diff --git a/packages/cultmath/src/CultMath/math.cs b/packages/cultmath/src/CultMath/math.cs index ca74857f..f5c81095 100644 --- a/packages/cultmath/src/CultMath/math.cs +++ b/packages/cultmath/src/CultMath/math.cs @@ -105,6 +105,9 @@ public static partial class math public static float2 frac(float2 value) => value - floor(value); public static float3 frac(float3 value) => value - floor(value); public static float4 frac(float4 value) => value - floor(value); + // dxc has no double Frc: it demotes to float, as it does for exp and lerp. CultMath's double + // overloads keep double precision instead, so frac(double) is x - floor(x) in double. + public static double frac(double value) => value - Math.Floor(value); // dxc lowers float min/max/clamp to DXIL FMin/FMax (saturate to Saturate, defined as FMin(1, FMax(0, x))). // DXIL.rst: FMin(a, b) is a < b ? a : b, FMax(a, b) is a >= b ? a : b, and a NaN operand returns the other. @@ -130,6 +133,11 @@ public static partial class math public static float2 clamp(float2 value, float2 minimum, float2 maximum) => min(max(value, minimum), maximum); public static float3 clamp(float3 value, float3 minimum, float3 maximum) => min(max(value, minimum), maximum); public static float4 clamp(float4 value, float4 minimum, float4 maximum) => min(max(value, minimum), maximum); + // dxc lowers int clamp to IMin(IMax(x, a), b): inverted bounds return b rather than throwing like Math.Clamp. + public static int clamp(int value, int minimum, int maximum) => min(max(value, minimum), maximum); + public static int2 clamp(int2 value, int2 minimum, int2 maximum) => min(max(value, minimum), maximum); + public static int3 clamp(int3 value, int3 minimum, int3 maximum) => min(max(value, minimum), maximum); + public static int4 clamp(int4 value, int4 minimum, int4 maximum) => min(max(value, minimum), maximum); // DXIL Saturate is FMin(1, FMax(0, x)); that operand order, unlike clamp(x, 0, 1), maps -0 to +0. public static float saturate(float value) => min(1.0f, max(0.0f, value)); diff --git a/packages/cultmath/tests/CultMath.Tests/HlslSemanticsTests.cs b/packages/cultmath/tests/CultMath.Tests/HlslSemanticsTests.cs index 7b845ea7..ac97f92f 100644 --- a/packages/cultmath/tests/CultMath.Tests/HlslSemanticsTests.cs +++ b/packages/cultmath/tests/CultMath.Tests/HlslSemanticsTests.cs @@ -311,6 +311,43 @@ public sealed class HlslSemanticsTests Assert.Equal(new int4(5, 5, 5, 5), math.int4(5)); } + [Fact] + public void VectorConversionsFollowDxc() + { + // fptosi truncates toward zero; NaN and out-of-range inputs are undefined in DXIL and not pinned. + Assert.Equal(new int2(-1, 2), math.int2(new float2(-1.7f, 2.9f))); + Assert.Equal(new int3(0, 0, 3), new int3(new float3(-0.5f, 0.5f, 3.99f))); + Assert.Equal(new float4(1.0f, -2.0f, 3.0f, 0.0f), math.float4(new int4(1, -2, 3, 0))); + // Numeric to bool is `!= 0` (fcmp une for float, so NaN is true); bool to numeric is 0 or 1. + Assert.Equal(new bool2(true, false), math.bool2(new float2(float.NaN, -0.0f))); + Assert.Equal(new bool3(false, true, true), math.bool3(new int3(0, 5, -1))); + Assert.Equal(new float2(1.0f, 0.0f), math.float2(new bool2(true, false))); + Assert.Equal(new int4(0, 1, 1, 0), math.int4(new bool4(false, true, true, false))); + // intN(intN) is exact; it must not promote through float and lose 2^24 + 1. + Assert.Equal(new int2(16777217, -16777217), math.int2(new int2(16777217, -16777217))); + float2 splat = math.float2(0); + Assert.Equal(float2.zero, splat); + } + + [Fact] + public void FracAndIntegerClampFollowHlsl() + { + // frac(double) keeps double precision; a float frac of 1e9 + 0.25 would return 0. + Assert.Equal(0.25, math.frac(1.0e9 + 0.25)); + Assert.Equal(0.75, math.frac(-0.25)); + Assert.Equal(0.5f, math.frac(2.5f)); + + // IMin(IMax(x, a), b): the result stays int, and inverted bounds return b. + int clamped = math.clamp(7, -1, 3); + Assert.Equal(3, clamped); + Assert.Equal(-1, math.clamp(-5, -1, 3)); + Assert.Equal(0, math.clamp(1, 3, 0)); + Assert.Equal(new int2(0, 3), math.clamp(new int2(-4, 9), 0, 3)); + Assert.Equal(new int3(1, 2, 3), math.clamp(new int3(1, 2, 3), new int3(0, 0, 0), new int3(5, 5, 5))); + Assert.Equal(new int4(2, 2, 4, 4), math.clamp(new int4(1, 2, 5, 4), new int4(2), new int4(4))); + Assert.Equal(1.0f, math.clamp(2.0f, -1, 1)); + } + [Fact] public void MatrixMulFollowsHlslRowMajorConvention() { diff --git a/packages/cultmath/tools/generate-swizzles.ps1 b/packages/cultmath/tools/generate-swizzles.ps1 index 9030f2be..e5f79011 100644 --- a/packages/cultmath/tools/generate-swizzles.ps1 +++ b/packages/cultmath/tools/generate-swizzles.ps1 @@ -21,6 +21,19 @@ $families = @( @{ Scalar = "bool"; Sizes = @(2, 3, 4); Functions = $true }, @{ Scalar = "double"; Sizes = @(2, 3); Functions = $false } ) +# Same-size vector conversions, as dxc lowers them: float to int is fptosi (toward zero; NaN +# and out-of-range are undefined in DXIL), int to float is sitofp, numeric to bool is `!= 0` +# (fcmp une, so NaN is true), bool to numeric is 0 or 1. Keyed "target<-source"; {0} is a +# source component. Identity forms (intN(intN), ...) come from the composition loop, which +# also keeps an int vector argument off the lossy intN(floatN) overload. +$conversions = [ordered]@{ + "float<-int" = "{0}" + "float<-bool" = "{0} ? 1.0f : 0.0f" + "int<-float" = "(int){0}" + "int<-bool" = "{0} ? 1 : 0" + "bool<-float" = "{0} != 0.0f" + "bool<-int" = "{0} != 0" +} $componentFields = @("x", "y", "z", "w") $namings = @(@("x", "y", "z", "w"), @("r", "g", "b", "a")) @@ -86,6 +99,20 @@ foreach ($family in $families) { } } + foreach ($source in @("float", "int", "bool")) { + $expression = $conversions["$scalar<-$source"] + if (-not $expression) { continue } + $converted = for ($i = 0; $i -lt $size; $i++) { $expression -f "value.$($componentFields[$i])" } + Line " public $type($source$size value) : this($($converted -join ', ')) { }" + if ($family.Functions) { + $functionLines.Add(" public static $type $type($source$size value) => new(value);") + } + } + if ($scalar -eq "float" -and $family.Functions) { + # floatN(int) splat: without it floatN(0) is ambiguous between floatN(float) and floatN(intN). + $functionLines.Add(" public static $type $type(int value) => new($((@('value') * $size) -join ', '));") + } + # Single-component color aliases; x/y/z/w are the fields themselves. $letters = $namings[1] for ($i = 0; $i -lt $size; $i++) {