Cameraz

include/nbl/asset/IAsset.h

@@ -5,6 +5,8 @@
 #define _NBL_ASSET_I_ASSET_H_INCLUDED_
 
 #include "nbl/core/decl/smart_refctd_ptr.h"
+// this header specializes `system::impl::to_string_helper` for `IAsset::E_TYPE` below
+#include "nbl/system/to_string.h"
 
 #include <string>
 

include/nbl/builtin/hlsl/README.md

@@ -78,7 +78,7 @@ library header. Those hold only what the standard header provides.
 | `type_traits.hlsl` | `<type_traits>` | Type trait structs and aliases. |
 | `utility.hlsl` | `<utility>` | Standard utilities (currently `declval`). |
 | `tgmath.hlsl` | `<tgmath>`/`<cmath>` | Type-generic math functions. |
-| `ieee754.hlsl` | | IEEE-754 float layout traits and bit helpers. |
+| `ieee754.hlsl` | | IEEE-754 float layout traits and bit helpers (including ULP distance). |
 | `mpl.hlsl` | | Template metaprogramming helpers (compile-time, boost::mpl style). |
 | `enums.hlsl` | | Engine enums shared host and device (e.g. `ShaderStage`). |
 | `format.hlsl` | | Texel block format enum and format pack/unpack (includes `format/`). |
@@ -99,6 +99,7 @@ library header. Those hold only what the standard header provides.
 
 | Folder | Contents and what belongs here |
 | --- | --- |
+| `approx/` | Approximate float comparison (ULP, absolute+relative), vector checks (perpendicular, orientation, squared length) and max-error tracking. |
 | `barycentric/` | Barycentric coordinate utilities. |
 | `bda/` | Buffer Device Address: typed pointers, references, and accessors. |
 | `blit/` | Image blit and normalization compute shaders and their parameters. |
@@ -111,7 +112,6 @@ library header. Those hold only what the standard header provides.
 | `fft/` | FFT building blocks. See [`fft/README.md`](fft/README.md). |
 | `format/` | Pixel/texel format pack and unpack (octahedral, shared exponent). |
 | `glsl_compat/` | GLSL builtin equivalents (core, subgroup ops). |
-| `ieee754/` | IEEE-754 implementation details. |
 | `ies/` | IES light profile sampling and textures. |
 | `math/` | Math routines: geometry, linalg, quaternions, equations, quadrature, and more. |
 | `matrix_utils/` | Matrix traits, compile-time and runtime. |
@@ -127,9 +127,9 @@ library header. Those hold only what the standard header provides.
 | `spirv_intrinsics/` | Raw SPIR-V intrinsic declarations. |
 | `subgroup/` | Subgroup-level collectives (ballot, arithmetic, basic, fft). |
 | `subgroup2/` | Newer subgroup collective API. |
-| `testing/` | Comparison helpers for tests (approx compare, max error). |
 | `text_rendering/` | Text rendering (MSDF). |
 | `tgmath/` | `tgmath` implementation details (isnan, output structs). |
+| `utils/` | Small generic helpers (bitfield, elementwise All/Any/None testers for scalars, vectors and matrices). |
 | `vector_utils/` | Vector traits. |
 | `visualization/` | Visualization helpers (turbo colormap). |
 | `workgroup/` | Workgroup-level collectives (arithmetic, ballot, scan, shuffle, fft). |

include/nbl/builtin/hlsl/approx/abs_rel.hlsl

@@ -0,0 +1,65 @@
+// Copyright (C) 2018-2026 - DevSH Graphics Programming Sp. z O.O.
+// This file is part of the "Nabla Engine".
+// For conditions of distribution and use, see copyright notice in nabla.h
+#ifndef _NBL_BUILTIN_HLSL_APPROX_ABS_REL_INCLUDED_
+#define _NBL_BUILTIN_HLSL_APPROX_ABS_REL_INCLUDED_
+
+#include <nbl/builtin/hlsl/cpp_compat.hlsl>
+#include <nbl/builtin/hlsl/concepts/core.hlsl>
+#include <nbl/builtin/hlsl/tgmath.hlsl>
+#include <nbl/builtin/hlsl/utils/elementwise.hlsl>
+
+namespace nbl
+{
+namespace hlsl
+{
+namespace approx
+{
+
+// Scalar predicate: `lhs` and `rhs` are equal if they differ by at most `maxAbsoluteDifference`
+// OR by at most `maxRelativeDifference` times the larger magnitude.
+// The absolute bound is what makes comparisons against 0 work, a purely relative bound degrades to exact equality there.
+// IEEE semantics: NaN never compares equal, infinities only equal themselves.
+template<typename FloatingPoint NBL_PRIMARY_REQUIRES(concepts::FloatingPointScalar<FloatingPoint>)
+struct AbsRelEqualPred
+{
+    using this_t = AbsRelEqualPred<FloatingPoint>;
+
+    static this_t create(const FloatingPoint _maxAbsoluteDifference, const FloatingPoint _maxRelativeDifference)
+    {
+        this_t retval;
+        retval.maxAbsoluteDifference = _maxAbsoluteDifference;
+        retval.maxRelativeDifference = _maxRelativeDifference;
+        return retval;
+    }
+
+    bool operator()(const FloatingPoint lhs, const FloatingPoint rhs) NBL_CONST_MEMBER_FUNC
+    {
+        // exact matches, `+0 == -0` and same-signed infinities
+        if (lhs == rhs)
+            return true;
+        // no special case for NaN, `diff` will be NaN and every comparison below false
+        const FloatingPoint diff = hlsl::abs<FloatingPoint>(lhs - rhs);
+        const FloatingPoint largest = hlsl::max<FloatingPoint>(hlsl::abs<FloatingPoint>(lhs), hlsl::abs<FloatingPoint>(rhs));
+        // multiplying instead of dividing by `largest` is cheaper, but `inf <= maxRelativeDifference*inf` would hold,
+        // hence the infinity guard which uses a bit pattern test so it survives `/fp:fast` and `-ffast-math`
+        return diff <= maxAbsoluteDifference || (diff <= maxRelativeDifference * largest && !hlsl::isinf<FloatingPoint>(largest));
+    }
+
+    FloatingPoint maxAbsoluteDifference;
+    FloatingPoint maxRelativeDifference;
+};
+
+// Works on floating point scalars, vectors and matrices, every element has to pass.
+template<typename T>
+bool absRelEqual(NBL_CONST_REF_ARG(T) lhs, NBL_CONST_REF_ARG(T) rhs, const scalar_type_t<T> maxAbsoluteDifference, const scalar_type_t<T> maxRelativeDifference)
+{
+    using pred_t = AbsRelEqualPred<scalar_type_t<T> >;
+    return utils::elementwiseAll<T, pred_t>(lhs, rhs, pred_t::create(maxAbsoluteDifference, maxRelativeDifference));
+}
+
+}
+}
+}
+
+#endif

include/nbl/builtin/hlsl/testing/max_error.hlsl → include/nbl/builtin/hlsl/approx/max_error.hlsl

@@ -1,5 +1,5 @@
-#ifndef _NBL_BUILTIN_HLSL_TESTING_MAX_ERROR_INCLUDED_
-#define _NBL_BUILTIN_HLSL_TESTING_MAX_ERROR_INCLUDED_
+#ifndef _NBL_BUILTIN_HLSL_APPROX_MAX_ERROR_INCLUDED_
+#define _NBL_BUILTIN_HLSL_APPROX_MAX_ERROR_INCLUDED_
 
 #include <nbl/builtin/hlsl/cpp_compat/basic.h>
 #include <nbl/builtin/hlsl/concepts/core.hlsl>
@@ -11,7 +11,7 @@ namespace nbl
 {
 namespace hlsl
 {
-namespace testing
+namespace approx
 {
 
 struct SMaxError

include/nbl/builtin/hlsl/approx/orientation.hlsl

@@ -0,0 +1,47 @@
+#ifndef _NBL_BUILTIN_HLSL_APPROX_ORIENTATION_INCLUDED_
+#define _NBL_BUILTIN_HLSL_APPROX_ORIENTATION_INCLUDED_
+
+#include <nbl/builtin/hlsl/approx/abs_rel.hlsl>
+#include <nbl/builtin/hlsl/limits.hlsl>
+
+namespace nbl
+{
+namespace hlsl
+{
+namespace approx
+{
+namespace impl
+{
+
+template<typename FloatingPointVector NBL_PRIMARY_REQUIRES(concepts::FloatingPointVectorial<FloatingPointVector>)
+struct OrientationEqualHelper
+{
+    static bool __call(NBL_CONST_REF_ARG(FloatingPointVector) lhs, NBL_CONST_REF_ARG(FloatingPointVector) rhs, const typename vector_traits<FloatingPointVector>::scalar_type maxRelativeDifference)
+    {
+        using scalar_t = typename vector_traits<FloatingPointVector>::scalar_type;
+
+        const scalar_t dotLR = hlsl::abs(hlsl::dot(lhs, rhs));
+        const scalar_t dotLL = hlsl::dot(lhs,lhs);
+        const scalar_t dotRR = hlsl::dot(rhs,rhs);
+        if (dotLL < numeric_limits<scalar_t>::min || dotRR < numeric_limits<scalar_t>::min)
+            return false;
+
+        const scalar_t scale = hlsl::sqrt(dotLL * dotRR);
+        return absRelEqual<scalar_t>(dotLR, scale, scalar_t(0), maxRelativeDifference);
+    }
+};
+
+}
+
+// true if `lhs` and `rhs` point along the same line (either direction), ignoring their lengths
+template<typename T>
+bool orientationEqual(NBL_CONST_REF_ARG(T) lhs, NBL_CONST_REF_ARG(T) rhs, const typename vector_traits<T>::scalar_type maxRelativeDifference)
+{
+	return impl::OrientationEqualHelper<T>::__call(lhs, rhs, maxRelativeDifference);
+}
+
+}
+}
+}
+
+#endif

include/nbl/builtin/hlsl/approx/ulp.hlsl

@@ -0,0 +1,60 @@
+// Copyright (C) 2018-2026 - DevSH Graphics Programming Sp. z O.O.
+// This file is part of the "Nabla Engine".
+// For conditions of distribution and use, see copyright notice in nabla.h
+#ifndef _NBL_BUILTIN_HLSL_APPROX_ULP_INCLUDED_
+#define _NBL_BUILTIN_HLSL_APPROX_ULP_INCLUDED_
+
+#include <nbl/builtin/hlsl/cpp_compat.hlsl>
+#include <nbl/builtin/hlsl/concepts/core.hlsl>
+#include <nbl/builtin/hlsl/ieee754.hlsl>
+#include <nbl/builtin/hlsl/tgmath.hlsl>
+#include <nbl/builtin/hlsl/utils/elementwise.hlsl>
+
+namespace nbl
+{
+namespace hlsl
+{
+namespace approx
+{
+
+// Scalar predicate: `lhs` and `rhs` are equal if they are at most `maxULPs` representable values apart, see `ieee754::ulpDistance`.
+template<typename FloatingPoint NBL_PRIMARY_REQUIRES(concepts::FloatingPointScalar<FloatingPoint>)
+struct ULPEqualPred
+{
+    using this_t = ULPEqualPred<FloatingPoint>;
+    using uint_type = typename unsigned_integer_of_size<sizeof(FloatingPoint)>::type;
+
+    static this_t create(const uint_type _maxULPs)
+    {
+        this_t retval;
+        retval.maxULPs = _maxULPs;
+        return retval;
+    }
+
+    bool operator()(const FloatingPoint lhs, const FloatingPoint rhs) NBL_CONST_MEMBER_FUNC
+    {
+        // NaN payloads can be a single ULP apart when looked at as integers, so NaN has to be rejected explicitly
+        if (hlsl::isnan<FloatingPoint>(lhs) || hlsl::isnan<FloatingPoint>(rhs))
+            return false;
+        // the largest finite value is a single ULP away from infinity, so infinities have to match exactly
+        if (hlsl::isinf<FloatingPoint>(lhs) || hlsl::isinf<FloatingPoint>(rhs))
+            return ieee754::impl::bitCastToUintType(lhs) == ieee754::impl::bitCastToUintType(rhs);
+        return ieee754::ulpDistance<FloatingPoint>(lhs, rhs) <= maxULPs;
+    }
+
+    uint_type maxULPs;
+};
+
+// Works on floating point scalars, vectors and matrices, every element has to pass.
+template<typename T>
+bool ulpEqual(NBL_CONST_REF_ARG(T) lhs, NBL_CONST_REF_ARG(T) rhs, const typename ULPEqualPred<scalar_type_t<T> >::uint_type maxULPs)
+{
+    using pred_t = ULPEqualPred<scalar_type_t<T> >;
+    return utils::elementwiseAll<T, pred_t>(lhs, rhs, pred_t::create(maxULPs));
+}
+
+}
+}
+}
+
+#endif

include/nbl/builtin/hlsl/approx/vector.hlsl

@@ -0,0 +1,71 @@
+#ifndef _NBL_BUILTIN_HLSL_APPROX_VECTOR_INCLUDED_
+#define _NBL_BUILTIN_HLSL_APPROX_VECTOR_INCLUDED_
+
+#include <nbl/builtin/hlsl/approx/abs_rel.hlsl>
+
+// TODO: move `impl::OrientationEqualHelper`/`orientationEqual` from `approx/orientation.hlsl` here and rename to `isParallel`
+
+namespace nbl
+{
+namespace hlsl
+{
+namespace approx
+{
+namespace impl
+{
+
+template<typename FloatingPointVector NBL_PRIMARY_REQUIRES(concepts::FloatingPointVectorial<FloatingPointVector>)
+struct IsPerpendicularHelper
+{
+    using scalar_t = typename vector_traits<FloatingPointVector>::scalar_type;
+
+    // Vectors `a` and `b` are perpendicular when the angle `theta` between them is 90deg. From the dot product formula:
+    //     dot(a,b) = |a| * |b| * cos(theta)
+    //     cos(theta) = dot(a,b) / (|a| * |b|)
+    // so perpendicular means cos(theta) == 0.
+    //
+    // We accept |cos(theta)| <= epsilon. For a small deviation `delta` from 90deg, cos(90deg - delta) = sin(delta) ~= delta (in radians),
+    // so this allows a deviation of asin(epsilon) ~= epsilon radians, e.g. epsilon = 1e-5 is ~5.73e-4 degrees (~2 arcseconds).
+    //
+    // Only the absolute error is used: we compare against 0.0 and an error relative to 0 is meaningless
+    // (a relative bound scaled by a magnitude of 0 degenerates into requiring an exact match).
+    //
+    // To avoid the division, `|a| * |b|` moves to the other side of the inequality:
+    //     |dot(a,b)| / (|a| * |b|) <= epsilon
+    //     |dot(a,b)| <= epsilon * |a| * |b| = epsilon * sqrt(dot(a,a) * dot(b,b))
+    // `maxAbsoluteDifference` is that right hand side (a single `sqrt`, since dot(v,v) = |v|^2), and `absRelEqual` checks `dot(a,b)` against it.
+    // The bound grows with the lengths, so uniformly scaled vectors give the same answer.
+    //
+    // A zero length vector counts as perpendicular to everything (the dot product and the bound are both 0).
+    static bool __call(NBL_CONST_REF_ARG(FloatingPointVector) lhs, NBL_CONST_REF_ARG(FloatingPointVector) rhs, const scalar_t cosThetaEpsilon)
+    {
+        // NOTE: we considered getting rid of the `sqrt` by squaring both sides, `dot(a,b)^2 <= epsilon^2 * dot(a,a) * dot(b,b)`,
+        // and decided against it: squaring the already squared lengths makes floating point overflow much more likely for larger values.
+        const scalar_t maxAbsoluteDifference = cosThetaEpsilon * hlsl::sqrt(hlsl::dot(lhs, lhs) * hlsl::dot(rhs, rhs));
+        return absRelEqual<scalar_t>(hlsl::dot(lhs, rhs), scalar_t(0.0), maxAbsoluteDifference, scalar_t(0.0));
+    }
+};
+
+}
+
+// compares the squared lengths of `lhs` and `rhs` with `absRelEqual`
+template<typename T NBL_FUNC_REQUIRES(concepts::FloatingPointVectorial<T>)
+bool squaredLengthEqual(NBL_CONST_REF_ARG(T) lhs, NBL_CONST_REF_ARG(T) rhs, const typename vector_traits<T>::scalar_type maxAbsoluteDifference, const typename vector_traits<T>::scalar_type maxRelativeDifference)
+{
+    using scalar_t = typename vector_traits<T>::scalar_type;
+    return absRelEqual<scalar_t>(hlsl::dot(lhs,lhs), hlsl::dot(rhs,rhs), maxAbsoluteDifference, maxRelativeDifference);
+}
+
+// true if |cos(theta)| <= `cosThetaEpsilon` for the angle `theta` between `lhs` and `rhs`, regardless of their lengths
+// (about `cosThetaEpsilon` radians of deviation from 90deg), see `impl::IsPerpendicularHelper` for the math
+template<typename T>
+bool isPerpendicular(NBL_CONST_REF_ARG(T) lhs, NBL_CONST_REF_ARG(T) rhs, const typename vector_traits<T>::scalar_type cosThetaEpsilon)
+{
+    return impl::IsPerpendicularHelper<T>::__call(lhs, rhs, cosThetaEpsilon);
+}
+
+}
+}
+}
+
+#endif