update ProfileProperties to tightly pack version, type and symmetry, add sample function overload to sampler.hlsl, create include/nbl/builtin/hlsl/ies/texture.hlsl to share texel write method between C++ & HLSL (the correct one including blending and corner sampling)

AnastaZIuk · AnastaZIuk · commit 83a83a489cf3 · 2025-12-03T10:53:07.000+01:00
TODO: need to update IES viewer example to compile again and clean bindings a bit (keep only octahedral image to write and sample from + add new ies::Texture::SInfo)
diff --git a/include/nbl/builtin/hlsl/ies/profile.hlsl b/include/nbl/builtin/hlsl/ies/profile.hlsl
@@ -26,22 +26,33 @@ struct ProfileProperties
     NBL_CONSTEXPR_STATIC_INLINE float32_t MAX_VANGLE = 180.f;
     NBL_CONSTEXPR_STATIC_INLINE float32_t MAX_HANGLE = 360.f;
 
-    enum Version : uint16_t
+	// TODO: could change to uint8_t once we get implemented
+    // https://github.com/microsoft/hlsl-specs/pull/538
+	using packed_flags_t = uint16_t;
+
+    NBL_CONSTEXPR_STATIC_INLINE packed_flags_t VERSION_BITS = 2u;
+    NBL_CONSTEXPR_STATIC_INLINE packed_flags_t TYPE_BITS    = 2u;
+    NBL_CONSTEXPR_STATIC_INLINE packed_flags_t SYMM_BITS    = 3u;
+    NBL_CONSTEXPR_STATIC_INLINE packed_flags_t VERSION_MASK = (packed_flags_t(1u) << VERSION_BITS) - packed_flags_t(1u);
+    NBL_CONSTEXPR_STATIC_INLINE packed_flags_t TYPE_MASK    = (packed_flags_t(1u) << TYPE_BITS)    - packed_flags_t(1u);
+    NBL_CONSTEXPR_STATIC_INLINE packed_flags_t SYMM_MASK    = (packed_flags_t(1u) << SYMM_BITS)    - packed_flags_t(1u);
+
+    enum Version : packed_flags_t
     {
         V_1995,
         V_2002,
         V_SIZE
     };
 
-    enum PhotometricType : uint16_t
+    enum PhotometricType : packed_flags_t
     {
         TYPE_NONE,
         TYPE_C,
         TYPE_B,
         TYPE_A
     };
 
-    enum LuminairePlanesSymmetry : uint16_t
+    enum LuminairePlanesSymmetry : packed_flags_t
     {
         ISOTROPIC,                  //! Only one horizontal angle present and a luminaire is assumed to be laterally axial symmetric
         QUAD_SYMETRIC,              //! The luminaire is assumed to be symmetric in each quadrant
@@ -50,13 +61,48 @@ struct ProfileProperties
         NO_LATERAL_SYMMET           //! The luminaire is assumed to exhibit no lateral symmet
     };
 
-    PhotometricType type;
-    Version version;
-    LuminairePlanesSymmetry symmetry;
+    Version getVersion() const
+    {
+        return static_cast<Version>( packed & VERSION_MASK );
+    }
+
+    PhotometricType getType() const
+    {
+        const packed_flags_t shift = VERSION_BITS;
+        return static_cast<PhotometricType>( (packed >> shift) & TYPE_MASK );
+    }
+
+    LuminairePlanesSymmetry getSymmetry() const
+    {
+        const packed_flags_t shift = VERSION_BITS + TYPE_BITS;
+        return static_cast<LuminairePlanesSymmetry>( (packed >> shift) & SYMM_MASK );
+    }
+
+    void setVersion(Version v)
+    {
+        packed_flags_t vBits = static_cast<packed_flags_t>(v) & VERSION_MASK;
+        packed = (packed & ~VERSION_MASK) | vBits;
+    }
+
+    void setType(PhotometricType t)
+    {
+        const packed_flags_t shift = VERSION_BITS;
+        packed_flags_t tBits = (static_cast<packed_flags_t>(t) & TYPE_MASK) << shift;
+        packed = (packed & ~(TYPE_MASK << shift)) | tBits;
+    }
+
+    void setSymmetry(LuminairePlanesSymmetry s)
+    {
+        const packed_flags_t shift = VERSION_BITS + TYPE_BITS;
+        packed_flags_t sBits = (static_cast<packed_flags_t>(s) & SYMM_MASK) << shift;
+        packed = (packed & ~(SYMM_MASK << shift)) | sBits;
+    }
 
-    float32_t maxCandelaValue;            //! Max scalar value from candela data vector    
-    float32_t totalEmissionIntegral;      //! Total energy emitted
-    float32_t avgEmmision;                //! totalEmissionIntegral / <size of the emission domain where non zero emission values>
+	float32_t maxCandelaValue;        //! Max candela sample value
+	float32_t totalEmissionIntegral;  //! Total emitted intensity (integral over full angular domain)
+	float32_t fullDomainAvgEmission;  //! Mean intensity over full angular domain (including I == 0)
+	float32_t avgEmmision;            //! Mean intensity over emitting solid angle (I > 0)
+	packed_flags_t packed = 0u;		  //! Packed version, type and symmetry flags
 };
 
 }
diff --git a/include/nbl/builtin/hlsl/ies/sampler.hlsl b/include/nbl/builtin/hlsl/ies/sampler.hlsl
@@ -7,6 +7,7 @@
 
 #include "nbl/builtin/hlsl/cpp_compat.hlsl"
 #include "nbl/builtin/hlsl/math/polar.hlsl"
+#include "nbl/builtin/hlsl/math/octahedral.hlsl"
 #include "nbl/builtin/hlsl/concepts.hlsl"
 #include "nbl/builtin/hlsl/ies/profile.hlsl"
 
@@ -37,7 +38,7 @@ NBL_CONCEPT_END(
 
     ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((accessor.vAnglesCount()), is_same_v, req_key_t))
     ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((accessor.hAnglesCount()), is_same_v, req_key_t))
-    ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((accessor.symmetry()), is_same_v, ProfileProperties::LuminairePlanesSymmetry))
+    ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((accessor.getProperties()), is_same_v, ProfileProperties))
     ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((accessor.template vAngle<req_key_t>((req_key_t)0)), is_same_v, req_value_t))
     ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((accessor.template hAngle<req_key_t>((req_key_t)0)), is_same_v, req_value_t))
     ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((accessor.template value<req_key_t2>((req_key_t2)0)), is_same_v, req_value_t))
@@ -58,11 +59,13 @@ struct CandelaSampler
     using accessor_t = Accessor;
     using value_t = typename accessor_t::value_t;
     using symmetry_t = ProfileProperties::LuminairePlanesSymmetry;
+	using polar_t = math::Polar<float32_t>;
+	using octahedral_t = math::OctahedralTransform<float32_t>;
 
     static value_t sample(NBL_CONST_REF_ARG(accessor_t) accessor, NBL_CONST_REF_ARG(math::Polar<float32_t>) polar)
     {
         // TODO: DXC seems to have a bug and cannot use symmetry_t directly with == operator https://godbolt.devsh.eu/z/P9Kc5x
-        const ProfileProperties::LuminairePlanesSymmetry symmetry = accessor.symmetry();
+        const ProfileProperties::LuminairePlanesSymmetry symmetry = accessor.getProperties().getSymmetry();
         const float32_t vAngle = degrees(polar.theta);
         const float32_t hAngle = degrees(wrapPhi(polar.phi, symmetry));
 
@@ -87,6 +90,13 @@ struct CandelaSampler
         return s0 * (1.f - u) + s1 * u;
     }
 
+	static value_t sample(NBL_CONST_REF_ARG(accessor_t) accessor, NBL_CONST_REF_ARG(float32_t2) uv)
+	{
+		const float32_t3 dir = octahedral_t::uvToDir(uv);
+        const polar_t polar = polar_t::createFromCartesian(dir);
+		return sample(accessor, polar);
+	}
+
     static float32_t wrapPhi(const float32_t phi, const symmetry_t symmetry)
     {
         switch (symmetry)
diff --git a/include/nbl/builtin/hlsl/ies/texture.hlsl b/include/nbl/builtin/hlsl/ies/texture.hlsl
@@ -0,0 +1,90 @@
+// Copyright (C) 2018-2025 - 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_IES_TEXTURE_INCLUDED_
+#define _NBL_BUILTIN_HLSL_IES_TEXTURE_INCLUDED_
+
+#include "nbl/builtin/hlsl/ies/sampler.hlsl"
+
+namespace nbl
+{
+namespace hlsl
+{
+namespace ies
+{
+
+template<typename Accessor NBL_FUNC_REQUIRES(concepts::IsIESAccessor<Accessor>)
+struct Texture
+{
+    using accessor_t = Accessor;
+    using value_t = typename accessor_t::value_t;
+	using sampler_t = CandelaSampler<accessor_t>;
+	using polar_t = math::Polar<float32_t>;
+	using octahedral_t = math::OctahedralTransform<float32_t>;
+
+    struct SInfo
+    {
+        float32_t2 inv;
+        float32_t flatten;
+        float32_t maxValueRecip;
+        float32_t flattenTarget;
+        float32_t domainLo;
+        float32_t domainHi;
+        bool fullDomainFlatten;
+    };
+
+    static SInfo createInfo(NBL_CONST_REF_ARG(accessor_t) accessor, NBL_CONST_REF_ARG(uint32_t2) size, float32_t flatten, bool fullDomainFlatten)
+    {
+        SInfo retval;
+		const ProfileProperties props = accessor.getProperties();
+
+        // There is one huge issue, the IES files love to give us values for degrees 0, 90, 180 an 360
+        // So standard octahedral mapping won't work, because for above data points you need corner sampled images.
+
+        retval.inv = float32_t2(1.f, 1.f) / float32_t2(size - 1u);
+        retval.flatten = flatten;
+        retval.maxValueRecip = 1.0f / props.maxCandelaValue; // Late Optimization TODO: Modify the Max Value for the UNORM texture to be the Max Value after flatten blending
+        retval.domainLo = radians(accessor.vAngle(0u));
+        retval.domainHi = radians(accessor.vAngle(accessor.vAnglesCount() - 1u));
+        retval.fullDomainFlatten = fullDomainFlatten;
+
+		if(fullDomainFlatten)
+			retval.flattenTarget = props.fullDomainAvgEmission;
+		else
+			retval.flattenTarget = props.avgEmmision;
+
+        return retval;
+    }
+
+	static float32_t eval(NBL_CONST_REF_ARG(accessor_t) accessor, NBL_CONST_REF_ARG(SInfo) info, NBL_CONST_REF_ARG(uint32_t2) position)
+    {
+	    // We don't currently support generating IES images that exploit symmetries or reduced domains, all are full octahederal mappings of a sphere.
+		// If we did, we'd rely on MIRROR and CLAMP samplers to do some of the work for us while handling the discontinuity due to corner sampling. 
+
+        const float32_t2 uv = float32_t2(position) * info.inv;
+        const float32_t3 dir = octahedral_t::uvToDir(uv);
+        const polar_t polar = polar_t::createFromCartesian(dir);
+
+		sampler_t sampler;
+        const float32_t intensity = sampler.sample(accessor, polar);
+
+		//! blend the IES texture with "flatten"
+        float32_t blendV = intensity * (1.f - info.flatten);
+
+        const bool inDomain = (info.domainLo <= polar.theta) && (polar.theta <= info.domainHi);
+
+        if ((info.fullDomainFlatten && inDomain) || intensity > 0.0f)
+            blendV += info.flattenTarget * info.flatten;
+
+        blendV *= info.maxValueRecip;
+
+        return blendV;
+    }
+};
+
+}
+}
+}
+
+#endif // _NBL_BUILTIN_HLSL_IES_TEXTURE_INCLUDED_
diff --git a/src/nbl/asset/utils/CIESProfile.cpp b/src/nbl/asset/utils/CIESProfile.cpp
@@ -2,8 +2,6 @@
 
 #include <atomic>
 #include "nbl/asset/filters/CBasicImageFilterCommon.h"
-#include "nbl/builtin/hlsl/math/octahedral.hlsl"
-#include "nbl/builtin/hlsl/math/polar.hlsl"
 
 using namespace nbl;
 using namespace asset;
@@ -70,42 +68,15 @@ core::smart_refctd_ptr<asset::ICPUImageView> CIESProfile::createIESTexture(Execu
         state.outRange.extent = creationParams.extent;
 
         const IImageFilter::IState::ColorValue::WriteMemoryInfo wInfo(creationParams.format, outImg->getBuffer()->getPointer());
+		const auto tInfo = texture_t::createInfo(accessor, hlsl::uint32_t2(width, height), flatten, fullDomainFlatten);
 
-        // Late Optimization TODO: Modify the Max Value for the UNORM texture to be the Max Value after flatten blending 
-        const auto maxValue = accessor.properties.maxCandelaValue;
-        const auto maxValueRecip = 1.f / maxValue;
-
-        // There is one huge issue, the IES files love to give us values for degrees 0, 90, 180 an 360
-        // So standard octahedral mapping won't work, because for above data points you need corner sampled images.
-        const float vertInv = 1.0 / (height-1);
-        const float horiInv = 1.0 / (width-1);
-
-        const double flattenTarget = getAvgEmmision(fullDomainFlatten);
-        const double domainLo = core::radians(accessor.vAngles.front());
-        const double domainHi = core::radians(accessor.vAngles.back());
         auto fill = [&](uint32_t blockArrayOffset, core::vectorSIMDu32 position) -> void
         {
-            // We don't currently support generating IES images that exploit symmetries or reduced domains, all are full octahederal mappings of a sphere.
-            // If we did, we'd rely on MIRROR and CLAMP samplers to do some of the work for us while handling the discontinuity due to corner sampling. 
-            
-            using Octahedral = hlsl::math::OctahedralTransform<hlsl::float32_t>;
-            using Polar = hlsl::math::Polar<hlsl::float32_t>;
-            const auto uv = Octahedral::vector2_type(position.x * vertInv, position.y * horiInv);
-            const auto dir = Octahedral::uvToDir(uv);
-            const auto polar = Polar::createFromCartesian(dir);
-            const auto intensity = sampler_t::sample(accessor, polar);
-
-            //! blend the IES texture with "flatten"
-            float blendV = intensity * (1.f - flatten);
-            if (fullDomainFlatten && domainLo<= polar.theta && polar.theta<=domainHi || intensity >0.0)
-                blendV += flattenTarget * flatten;
-
-            blendV *= maxValueRecip;
+			auto texel = texture_t::eval(accessor, tInfo, hlsl::uint32_t2(position.x, position.y));
 
             asset::IImageFilter::IState::ColorValue color;
-            //asset::encodePixels<CIESProfile::IES_TEXTURE_STORAGE_FORMAT>(color.asDouble, &blendV); TODO: FIX THIS ENCODE, GIVES ARTIFACTS
             constexpr float UI16_MAX_D = static_cast<float>(std::numeric_limits<std::uint16_t>::max());
-            const uint16_t encodeV = static_cast<uint16_t>(std::clamp(blendV * UI16_MAX_D + 0.5f, 0.f, UI16_MAX_D));
+            const uint16_t encodeV = static_cast<uint16_t>(std::clamp(texel * UI16_MAX_D + 0.5f, 0.f, UI16_MAX_D)); // TODO: use asset::encodePixels when its fixed (no artifacts)
             *color.asUShort = encodeV;
             color.writeMemory(wInfo, blockArrayOffset);
         };
diff --git a/src/nbl/asset/utils/CIESProfile.h b/src/nbl/asset/utils/CIESProfile.h
@@ -6,7 +6,7 @@
 #define __NBL_ASSET_C_IES_PROFILE_H_INCLUDED__
 
 #include "nbl/asset/metadata/CIESProfileMetadata.h"
-#include "nbl/builtin/hlsl/ies/sampler.hlsl"
+#include "nbl/builtin/hlsl/ies/texture.hlsl"
 
 namespace nbl 
 {
@@ -15,10 +15,14 @@ namespace asset
 class CIESProfile 
 {
     public:
+        CIESProfile() = default;
+        ~CIESProfile() = default;
+
         struct properties_t : public nbl::hlsl::ies::ProfileProperties
         {
+			using base_t = nbl::hlsl::ies::ProfileProperties;
             NBL_CONSTEXPR_STATIC_INLINE auto IES_TEXTURE_STORAGE_FORMAT = asset::EF_R16_UNORM;
-            hlsl::uint32_t2 optimalIESResolution; //! Optimal resolution for IES CDC texture
+            hlsl::uint32_t2 optimalIESResolution; //! Optimal resolution for IES Octahedral Candela Map texture
         };
 
         struct accessor_t
@@ -45,33 +49,17 @@ class CIESProfile
 
             inline key_t vAnglesCount() const { return (key_t)vAngles.size(); }
             inline key_t hAnglesCount() const { return (key_t)hAngles.size(); }
-            inline properties_t::LuminairePlanesSymmetry symmetry() const { return properties.symmetry; }
+			inline const properties_t::base_t& getProperties() const { return static_cast<const properties_t::base_t&>(properties); }
 
             core::vector<value_t> hAngles;          //! The angular displacement indegreesfrom straight down, a value represents spherical coordinate "theta" with physics convention. Note that if symmetry is OTHER_HALF_SYMMETRIC then real horizontal angle provided by IES data is (hAngles[index] + 90) - the reason behind it is we patch 1995 IES OTHER_HALF_SYMETRIC case to be HALF_SYMETRIC
             core::vector<value_t> vAngles;          //! Measurements in degrees of angular displacement measured counterclockwise in a horizontal plane for Type C photometry and clockwise for Type A and B photometry, a value represents spherical coordinate "phi" with physics convention
             core::vector<value_t> data;             //! Candela scalar values
             properties_t properties;                //! Profile properties
         };
-
-        using sampler_t = nbl::hlsl::ies::CandelaSampler<accessor_t>;
-
-        CIESProfile() = default;
-        ~CIESProfile() = default;
+		using texture_t = nbl::hlsl::ies::Texture<accessor_t>;
          
 		inline const accessor_t& getAccessor() const { return accessor; }
 
-        inline hlsl::float32_t getAvgEmmision(const bool fullDomain=false) const
-        {
-            if (fullDomain)
-            {
-                const float cosLo = std::cos(core::radians(accessor.vAngles.front()));
-                const float cosHi = std::cos(core::radians<float>(accessor.vAngles.back()));
-                const float dsinTheta = cosLo - cosHi;
-                return accessor.properties.totalEmissionIntegral*(0.5/core::PI<float>())/dsinTheta;
-            }
-            return accessor.properties.avgEmmision;
-        }
-
         template<class ExecutionPolicy>
         core::smart_refctd_ptr<asset::ICPUImageView> createIESTexture(ExecutionPolicy&& policy, const float flatten = 0.0, const bool fullDomainFlatten=false, uint32_t width = properties_t::CDC_DEFAULT_TEXTURE_WIDTH, uint32_t height = properties_t::CDC_DEFAULT_TEXTURE_HEIGHT) const;
         core::smart_refctd_ptr<asset::ICPUImageView> createIESTexture(const float flatten = 0.0, const bool fullDomainFlatten=false, uint32_t width = properties_t::CDC_DEFAULT_TEXTURE_WIDTH, uint32_t height = properties_t::CDC_DEFAULT_TEXTURE_HEIGHT) const;
diff --git a/src/nbl/asset/utils/CIESProfileParser.cpp b/src/nbl/asset/utils/CIESProfileParser.cpp
