Env map importance sampling by kevyuu · Pull Request #969 · Devsh-Graphics-Programming/Nabla

kevyuu · 2025-12-19T14:43:32Z

Description

Rework environment map importance sampling to vulkan and hlsl

Testing

Rework example 0 to use vulkan and hlsl
Unit Test Pull Request

TODO list:

Implement Warpmap Generation in hlsl
Implement Warpmap hierarchical map sampling in hlsl

…mek's remove_core_matrix branch, added create from mat3x3

…c cast to/from truncated quat

include/nbl/builtin/hlsl/concepts/warp.hlsl

include/nbl/builtin/hlsl/warp/spherical.hlsl

include/nbl/builtin/hlsl/concepts/warp.hlsl

include/nbl/builtin/hlsl/warp/spherical.hlsl

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

…lImage class

devshgraphicsprogramming · 2026-02-25T22:15:24Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+	vector2_type binarySearch(const uint32_t2 coord)
+	{
+		// We use _lastWarpPixel here for corner sampling
+    float32_t2 xi = float32_t2(coord)/ _lastWarpPixel;
+		uint32_t2 p = uint32_t2(0, 0);
+		const uint32_t2 mip2x1 = findMSB(_mapSize.y);


to be able to use this as a sampler, I also need a codomain_type generate(const domaint_type xi) so best you construct this binarySearch in terms of that

you also wouldn't store _lastWarpPixel here then, because it would just be a warpmap agnostic sampler

devshgraphicsprogramming · 2026-02-25T22:16:48Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/accessors.hlsl

+// declare concept
+#define NBL_CONCEPT_NAME LuminanceReadAccessor
+#define NBL_CONCEPT_TPLT_PRM_KINDS (typename)(typename)
+#define NBL_CONCEPT_TPLT_PRM_NAMES (U)(ScalarT)
+// not the greatest syntax but works
+#define NBL_CONCEPT_PARAM_0 (a,U)
+#define NBL_CONCEPT_PARAM_1 (coord,uint32_t2)
+#define NBL_CONCEPT_PARAM_2 (level,uint32_t)
+// start concept
+NBL_CONCEPT_BEGIN(3)
+// need to be defined AFTER the concept begins
+#define a NBL_CONCEPT_PARAM_T NBL_CONCEPT_PARAM_0
+#define coord NBL_CONCEPT_PARAM_T NBL_CONCEPT_PARAM_1
+#define level NBL_CONCEPT_PARAM_T NBL_CONCEPT_PARAM_2
+NBL_CONCEPT_END(
+    ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((a.template texelFetch(coord,level)) , ::nbl::hlsl::is_same_v, ScalarT))
+    ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((a.template texelGather(coord,level)) , ::nbl::hlsl::is_same_v, vector<ScalarT, 4>))
+);
+#undef level
+#undef coord
+#undef a
+#include <nbl/builtin/hlsl/concepts/__end.hlsl>


if you merge latest path tracer branch, you can forego this concept in lieu of a LoadableImage with Components=1 and add a GatherableImage with all the other accessors , see #969 (comment)

devshgraphicsprogramming · 2026-02-25T22:22:45Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+template <typename ScalarT, typename LuminanceAccessorT, typename HierarchicalSamplerT, typename PostWarpT 
+  NBL_PRIMARY_REQUIRES(is_scalar_v<ScalarT> &&
+		concepts::accessors::GenericReadAccessor<LuminanceAccessorT, ScalarT, float32_t2> &&
+		hierarchical_image::HierarchicalSampler<HierarchicalSamplerT, ScalarT> &&
+		concepts::Warp<PostWarpT>)
+struct HierarchicalImage 
+{
+	using scalar_type = ScalarT;
+	using vector2_type = vector<ScalarT, 2>;
+	using vector3_type = vector<ScalarT, 3>;
+	using vector4_type = vector<ScalarT, 4>;
+	LuminanceAccessorT _lumaMap;
+	HierarchicalSamplerT _warpMap;
+	uint32_t2 _warpSize;
+	uint32_t2 _lastWarpPixel;
+	scalar_type _rcpAvgLuma;
+
+	static HierarchicalImage create(NBL_CONST_REF_ARG(LuminanceAccessorT) lumaMap, NBL_CONST_REF_ARG(HierarchicalSamplerT) warpMap, uint32_t2 warpSize, scalar_type avgLuma) 
+	{
+		HierarchicalImage<ScalarT, LuminanceAccessorT, HierarchicalSamplerT, PostWarpT> result;
+		result._lumaMap = lumaMap;
+		result._warpMap = warpMap;
+		result._warpSize = warpSize;
+		result._lastWarpPixel = warpSize - uint32_t2(1, 1);
+		result._rcpAvgLuma = ScalarT(1.0) / avgLuma;
+		return result;
+	}
+
+	vector2_type inverseWarp_and_deferredPdf(NBL_REF_ARG(scalar_type) pdf, vector3_type direction) NBL_CONST_MEMBER_FUNC
+  {
+		vector2_type envmapUv = PostWarpT::inverseWarp(direction);
+		scalar_type luma;
+		_lumaMap.get(envmapUv, luma);
+		pdf = (luma * _rcpAvgLuma) * PostWarpT::backwardDensity(direction);
+		return envmapUv;
+  }
+
+	scalar_type deferredPdf(vector3_type direction) NBL_CONST_MEMBER_FUNC
+	{
+		vector2_type envmapUv = PostWarpT::inverseWarp(direction);
+		scalar_type luma;
+		_lumaMap.get(envmapUv, luma);
+		return luma * _rcpAvgLuma * PostWarpT::backwardDensity(direction);
+	}
+
+	vector3_type generate_and_pdf(NBL_REF_ARG(scalar_type) pdf, NBL_REF_ARG(vector2_type) uv, vector2_type xi) NBL_CONST_MEMBER_FUNC
+	{
+		const vector2_type texelCoord = xi * float32_t2(_lastWarpPixel);
+
+		matrix<scalar_type, 4, 2> uvs = _warpMap.sampleUvs(uint32_t2(texelCoord));
+
+		const vector2_type interpolant = frac(texelCoord);
+
+		const vector2_type xDiffs[] = {
+			uvs[2] - uvs[3],
+			uvs[1] - uvs[0]
+		};
+		const vector2_type yVals[] = {
+			xDiffs[0] * interpolant.x + uvs[3],
+			xDiffs[1] * interpolant.x + uvs[0]
+		};
+		const vector2_type yDiff = yVals[1] - yVals[0];
+		uv = yDiff * interpolant.y + yVals[0];
+
+		const WarpResult<vector3_type> warpResult = PostWarpT::warp(uv);
+
+		const scalar_type detInterpolJacobian = determinant(matrix<scalar_type, 2, 2>(
+			lerp(xDiffs[0], xDiffs[1], interpolant.y), // first column dFdx
+			yDiff // second column dFdy
+		)) * _lastWarpPixel.x * _lastWarpPixel.y;
+
+		pdf = abs(warpResult.density / detInterpolJacobian);
+
+		return warpResult.dst;
+	}
+};


separate file, also struct needs better name like WarpMap sampler

devshgraphicsprogramming · 2026-02-25T22:23:36Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/accessors.hlsl

+#undef a
+#include <nbl/builtin/hlsl/concepts/__end.hlsl>
+
+// sampleUvs return 4 UVs in a square to calculate the jacobian matrix


replace "to calculate the jacobian matrix" with "for manual bilinear interpolation with differentiability"

devshgraphicsprogramming · 2026-02-25T22:25:41Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/common.hlsl

+struct SLumaGenPushConstants
+{
+  float32_t3 lumaRGBCoefficients;
+  uint32_t2 lumaMapResolution;


you can use uint32_t bitfield of 16 bit each per axis (don't use uint16_t2 though because AMD doesn't support 16 bit push constants)

devshgraphicsprogramming · 2026-02-25T22:26:53Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/gen_luma.comp.hlsl

+[[vk::binding(0, 0)]] Texture2D<float32_t4> envMap;
+[[vk::binding(1, 0)]] RWTexture2D<float32_t> outImage;
+
+[numthreads(WORKGROUP_DIM, WORKGROUP_DIM, 1)]


imho don't pass a define, and hardcode to 16x16 (but obviously leave a cosntexpr in a shared header so the c++ can be in-sync)

devshgraphicsprogramming · 2026-02-25T22:27:35Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/gen_luma.comp.hlsl

+
+		const float uv_y = (float(threadID.y) + float(0.5f)) / pc.lumaMapResolution.y;
+		const float32_t3 envMapSample = envMap.Load(float32_t3(threadID.xy, 0));
+		const float32_t luma = hlsl::dot(envMapSample, pc.lumaRGBCoefficients) * sin(numbers::pi<float32_t> * uv_y);


this assumes a spherical warp

devshgraphicsprogramming · 2026-02-25T22:27:55Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/gen_luma.comp.hlsl

+[[vk::binding(0, 0)]] Texture2D<float32_t4> envMap;
+[[vk::binding(1, 0)]] RWTexture2D<float32_t> outImage;


this assumes a 2D map and not a cubemap/layered thing, use layered images instead

devshgraphicsprogramming · 2026-02-25T22:29:42Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/gen_warp.comp.hlsl

+        return float32_t4(
+            lumaMap.Load(uint32_t3(coord, level), uint32_t2(0, 1)),
+            lumaMap.Load(uint32_t3(coord, level), uint32_t2(1, 1)),
+            lumaMap.Load(uint32_t3(coord, level), uint32_t2(1, 0)),
+            lumaMap.Load(uint32_t3(coord, level), uint32_t2(0, 0))
+        );


btw OOB reads using texelFetch are undefined, asser that coord is between 0 and lastPixel-1 for both axes

devshgraphicsprogramming · 2026-02-25T22:30:11Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/accessors.hlsl

+#define NBL_CONCEPT_TPLT_PRM_KINDS (typename)(typename)
+#define NBL_CONCEPT_TPLT_PRM_NAMES (HierarchicalSamplerT)(ScalarT)
+// not the greatest syntax but works
+#define NBL_CONCEPT_PARAM_0 (sampler,HierarchicalSamplerT)


sampler is a reserved keyword in HLSL

devshgraphicsprogramming · 2026-02-25T22:31:03Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/accessors.hlsl

+#define sampler NBL_CONCEPT_PARAM_T NBL_CONCEPT_PARAM_0
+#define coord NBL_CONCEPT_PARAM_T NBL_CONCEPT_PARAM_1
+NBL_CONCEPT_END(
+    ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((sampler.template sampleUvs(coord)) , ::nbl::hlsl::is_same_v, matrix<ScalarT, 4, 2>))


signature should be template sampleUvs<matrix<>,vector<>>(outMatrix,coord)

devshgraphicsprogramming · 2026-02-25T22:32:02Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/gen_warp.comp.hlsl

+    LuminanceSampler luminanceSampler = 
+      LuminanceSampler::create(luminanceAccessor, uint32_t2(lumaMapWidth, lumaMapHeight), lumaMapWidth != lumaMapHeight, uint32_t2(lumaMapWidth, lumaMapHeight));


why are we passing the uint32_t2(lumaMapWidth, lumaMapHeight) resolution twice ?

devshgraphicsprogramming · 2026-02-25T22:32:53Z

include/nbl/builtin/hlsl/sampling/hierarchical_image/gen_warp.comp.hlsl

+    uint32_t2 pixelCoord = threadID.xy;
+
+    outImage[pixelCoord] = luminanceSampler.binarySearch(pixelCoord);
+


you need to handle OOB, I can have a 4x4 sphere map, but my workgroup is 16x16

devshgraphicsprogramming · 2026-02-25T22:38:34Z

include/nbl/builtin/hlsl/sampling/warps/spherical.hlsl

+template <typename T = float32_t>
+struct Spherical 
+{
+	using density_type = T;
+	using domain_type = vector<density_type, 2>;
+	using codomain_type = vector<density_type, 3>;
+
+	template <typename DomainT NBL_FUNC_REQUIRES(is_same_v<DomainT, domain_type>)
+	static WarpResult<codomain_type> warp(const DomainT uv)
+	{
+		codomain_type dir;
+		dir.x = cos(uv.x * density_type(2) * numbers::pi<density_type>);
+		dir.z = sqrt(density_type(1) - (dir.x * dir.x));
+    if (uv.x > density_type(0.5))
+			dir.z = -dir.z;
+		const density_type theta = uv.y * numbers::pi<density_type>;
+		const density_type cosTheta = cos(theta);
+		const density_type sinTheta = sqrt(density_type(1) - (cosTheta * cosTheta));
+		dir.xz *= sinTheta;
+		dir.y = cosTheta;
+
+		WarpResult<codomain_type> warpResult;
+		warpResult.dst = dir;
+		warpResult.density = density_type(1) / (density_type(2) * sinTheta * numbers::pi<density_type> * numbers::pi<density_type>);
+
+		return warpResult;
+	}
+
+	template <typename CodomainT NBL_FUNC_REQUIRES(is_same_v<CodomainT, codomain_type>) 
+	static domain_type inverseWarp(const CodomainT v)
+	{
+		const density_type phi = atan2(v.z, v.x);
+		const density_type theta = acos(v.y);
+		density_type uv_x = phi * density_type(0.5) * numbers::inv_pi<density_type>;
+		if (uv_x < density_type(0))
+			uv_x += density_type(1);
+		density_type uv_y = theta * numbers::inv_pi<density_type>;
+    return domain_type(uv_x, uv_y);
+	}
+
+
+	template <typename DomainT NBL_FUNC_REQUIRES(is_same_v<DomainT, domain_type>)
+	static density_type forwardDensity(const DomainT uv)
+	{
+		const density_type theta = uv.y * numbers::pi<density_type>;
+		return density_type(1) / (sin(theta) * density_type(2) * numbers::pi<density_type> * numbers::pi<density_type>);
+
+	}
+
+	template <typename CodomainT NBL_FUNC_REQUIRES(is_same_v<CodomainT, codomain_type>)
+	static density_type backwardDensity(const CodomainT dst)
+	{
+		const density_type cosTheta = dst.y;
+		const density_type sinTheta = sqrt(density_type(1) - (cosTheta * cosTheta));
+		return density_type(1) / (sinTheta * density_type(2) * numbers::pi<density_type> * numbers::pi<density_type>);
+	}
+};


under the framework of #1001 we can make this into a Bijective Sampler

devshgraphicsprogramming · 2026-02-25T22:45:02Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+	matrix<scalar_type, 4, 2> sampleUvs(uint32_t2 sampleCoord) NBL_CONST_MEMBER_FUNC
+	{
+		const vector2_type dir0 = binarySearch(sampleCoord + vector2_type(0, 1));
+		const vector2_type dir1 = binarySearch(sampleCoord + vector2_type(1, 1));
+		const vector2_type dir2 = binarySearch(sampleCoord + vector2_type(1, 0));
+		const vector2_type dir3 = binarySearch(sampleCoord);
+		return matrix<scalar_type, 4, 2>(
+			dir0,
+			dir1,
+			dir2,
+			dir3
+		);
+	}


not sure that sampleUvs should be exposed like that (if something needs it -like a test- let them call binarySearch 4 times), why?

if not using a warpmap you wouldn't actually importance sample 4 times to perform finite difference and get your jacobian, you'd use the Luma of the image (with NEAREST not linear sampler) as the PDF because thats 100% accurate

if using a warmap you'd textureGather it and work out the Jacobian from differntiating the bilinear interpolation equation

devshgraphicsprogramming · 2026-02-25T22:45:06Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+		is_scalar_v<ScalarT> && 
+		hierarchical_image::LuminanceReadAccessor<LuminanceAccessorT, ScalarT>
+	)
+struct LuminanceMapSampler


this one is actually the HierarchicalLuminanceSampler

devshgraphicsprogramming · 2026-02-25T22:46:14Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+		// We use _lastWarpPixel here for corner sampling
+    float32_t2 xi = float32_t2(coord)/ _lastWarpPixel;
+		uint32_t2 p = uint32_t2(0, 0);
+		const uint32_t2 mip2x1 = findMSB(_mapSize.y);


why are you using a uint32_t2 to store this, its a uint16_t at most, its a scalar quantity

Also should be precomputed

devshgraphicsprogramming · 2026-02-25T22:49:54Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+	LuminanceAccessorT _map;
+	uint32_t2 _mapSize;
+  uint32_t2 _lastWarpPixel;
+	bool _aspect2x1;


store these instead

float32_t2 rcpMapSize; uint16_t mip2x1 : 15; uint16_t aspect2x1 : 1;

devshgraphicsprogramming · 2026-02-25T22:53:46Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+template <typename ScalarT, typename LuminanceAccessorT 
+  NBL_PRIMARY_REQUIRES(
+		is_scalar_v<ScalarT> && 
+		hierarchical_image::LuminanceReadAccessor<LuminanceAccessorT, ScalarT>
+	)


add a bool for whether the accessor is corner sampled or not

devshgraphicsprogramming · 2026-02-25T22:57:12Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+
+
+		// If we don`t add xi, the sample will clump to the lowest corner of environment map texel. We add xi to simulate uniform distribution within a pixel and make the sample continuous. This is why we compute the pdf not from the normalized luminance of the texel, instead from the reciprocal of the Jacobian.
+		const vector2_type directionUV = (vector2_type(p.x, p.y) + xi) / vector2_type(_mapSize);


if your spheremap or octahedral maps are corner sampled, the edge pixels need special treatment

Essentially whenever your X or Y coordinate is an edge coordinate, you'd need to weight their luma contribution down by 50% and also change how the remaining xi gets added:

coord==0 then xi gets rescaled to [0.5,1.0]

coord==Last then xi gets rescaled to [0,0.5]

then you'd actually rescale that final UV from [0.5/size,1-0.5/size] to [0,1] before outputting it in the warpmap

devshgraphicsprogramming · 2026-02-25T23:02:19Z

include/nbl/builtin/hlsl/sampling/warp.hlsl

+#ifndef _NBL_BUILTIN_HLSL_SAMPLING_CONCEPTS_WARP_INCLUDED_
+#define _NBL_BUILTIN_HLSL_SAMPLING_CONCEPTS_WARP_INCLUDED_
+
+#include <nbl/builtin/hlsl/concepts.hlsl>
+
+namespace nbl
+{
+namespace hlsl
+{
+namespace sampling
+{
+
+template <typename CodomainT, typename DensityT = float32_t>
+struct WarpResult
+{
+  CodomainT dst;
+  DensityT density;
+};
+}
+
+namespace concepts
+{
+
+// declare concept
+#define NBL_CONCEPT_NAME Warp
+#define NBL_CONCEPT_TPLT_PRM_KINDS (typename)
+#define NBL_CONCEPT_TPLT_PRM_NAMES (U)
+// not the greatest syntax but works
+#define NBL_CONCEPT_PARAM_0 (warper,U)
+#define NBL_CONCEPT_PARAM_1 (xi,typename U::domain_type)
+#define NBL_CONCEPT_PARAM_2 (dst,typename U::codomain_type)
+// start concept
+NBL_CONCEPT_BEGIN(3)
+#define warper NBL_CONCEPT_PARAM_T NBL_CONCEPT_PARAM_0
+#define xi NBL_CONCEPT_PARAM_T NBL_CONCEPT_PARAM_1
+#define dst NBL_CONCEPT_PARAM_T NBL_CONCEPT_PARAM_2
+NBL_CONCEPT_END(
+    ((NBL_CONCEPT_REQ_TYPE)(U::domain_type))
+    ((NBL_CONCEPT_REQ_TYPE)(U::codomain_type))
+    ((NBL_CONCEPT_REQ_TYPE)(U::density_type))
+    ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((warper.template warp<typename U::domain_type>(xi)) , ::nbl::hlsl::is_same_v, sampling::WarpResult<typename U::codomain_type, typename U::density_type>))
+    ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((warper.template forwardDensity<typename U::domain_type>(xi)) , ::nbl::hlsl::is_same_v, typename U::density_type))
+    ((NBL_CONCEPT_REQ_EXPR_RET_TYPE)((warper.template backwardDensity<typename U::codomain_type>(dst)) , ::nbl::hlsl::is_same_v, typename U::density_type))
+);
+#undef dst
+#undef xi
+#undef warper
+#include <nbl/builtin/hlsl/concepts/__end.hlsl>
+
+}
+
+}
+}
+
+#endif


I think this file will be made obsolete by #1001 s Bijective Sampler concept

devshgraphicsprogramming · 2026-02-25T23:03:01Z

include/nbl/core/sampling/EnvmapSampler.h

+#include "nbl/video/declarations.h"
+
+namespace nbl::core
+{


completely wrong namespace, you're using video, this file needs to live in nbl/video/sampling

devshgraphicsprogramming · 2026-02-25T23:04:00Z

src/nbl/CMakeLists.txt

 set(NBL_CORE_SOURCES
 	core/alloc/refctd_memory_resource.cpp
 	core/hash/blake.cpp
+	core/sampling/EnvmapSampler.cpp


again, this should be video

devshgraphicsprogramming · 2026-02-25T23:04:13Z

CMakeLists.txt

 option(NBL_BUILD_MITSUBA_LOADER "Enable nbl::ext::MitsubaLoader?" ON)
 option(NBL_BUILD_IMGUI "Enable nbl::ext::ImGui?" ON)
 option(NBL_BUILD_DEBUG_DRAW "Enable Nabla Debug Draw extension?" ON)
+option(NBL_BUILD_ENVMAP_IMPORTANCE_SAMPLING "Enable Nabla Envmap Importance Sampling extension?" ON)


no longer an extension, dont need the option

devshgraphicsprogramming · 2026-02-25T23:26:32Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+	vector2_type inverseWarp_and_deferredPdf(NBL_REF_ARG(scalar_type) pdf, vector3_type direction) NBL_CONST_MEMBER_FUNC
+  {
+		vector2_type envmapUv = PostWarpT::inverseWarp(direction);
+		scalar_type luma;
+		_lumaMap.get(envmapUv, luma);
+		pdf = (luma * _rcpAvgLuma) * PostWarpT::backwardDensity(direction);
+		return envmapUv;
+  }
+
+	scalar_type deferredPdf(vector3_type direction) NBL_CONST_MEMBER_FUNC
+	{
+		vector2_type envmapUv = PostWarpT::inverseWarp(direction);
+		scalar_type luma;
+		_lumaMap.get(envmapUv, luma);
+		return luma * _rcpAvgLuma * PostWarpT::backwardDensity(direction);
+	}
+
+	vector3_type generate_and_pdf(NBL_REF_ARG(scalar_type) pdf, NBL_REF_ARG(vector2_type) uv, vector2_type xi) NBL_CONST_MEMBER_FUNC


make it conform to #1001 's ResamplableSampler

devshgraphicsprogramming · 2026-02-25T23:28:20Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+template <typename ScalarT, typename LuminanceAccessorT, typename HierarchicalSamplerT, typename PostWarpT 
+  NBL_PRIMARY_REQUIRES(is_scalar_v<ScalarT> &&
+		concepts::accessors::GenericReadAccessor<LuminanceAccessorT, ScalarT, float32_t2> &&
+		hierarchical_image::HierarchicalSampler<HierarchicalSamplerT, ScalarT> &&
+		concepts::Warp<PostWarpT>)
+struct HierarchicalImage 


this should be called WarpmapSampler or something like that

devshgraphicsprogramming · 2026-02-25T23:29:51Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+		const vector2_type texelCoord = xi * float32_t2(_lastWarpPixel);
+
+		matrix<scalar_type, 4, 2> uvs = _warpMap.sampleUvs(uint32_t2(texelCoord));
+


warpmap should convert you from [0,1] normalized xi to its own texels,the sampleUvs should really work same as textureGather, it should take normalized uvs as input

devshgraphicsprogramming · 2026-02-25T23:30:48Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+
+		matrix<scalar_type, 4, 2> uvs = _warpMap.sampleUvs(uint32_t2(texelCoord));
+
+		const vector2_type interpolant = frac(texelCoord);


make the _warpMap.gather spit out the interpolant so its cleaner (requires a specialized gather overload, adding on top of Gatherable concept)

devshgraphicsprogramming · 2026-02-25T23:32:44Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+	LuminanceAccessorT _lumaMap;
+	HierarchicalSamplerT _warpMap;
+	uint32_t2 _warpSize;
+	uint32_t2 _lastWarpPixel;


you actually only need to store the _lastWarpPixel.x * _lastWarpPixel.y prodct, I expect the warpmap to handle gathering

devshgraphicsprogramming · 2026-02-25T23:57:22Z

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl

+      if (choseSecond(wx_0, wx_1, xi.x))
+        p.x |= 1;


btw you can get the PDF of the finally chosen texel as metadata if on the final call to choseSecond you save wx_0 or wx_1 and thats your chosen pixel luminance, you just need to know the average to and total number of texels (corner sampled edges count as half pixels) get the PDF

(obvioulsy if mip2x1 is 0, the PDF is either 1.0 or the dummy from the choice on line 64)

kevyuu and others added 12 commits November 11, 2025 15:50

Fix small bug in GenericDataAccessor definition

b99ae6e

First draft of Warpmap Generation workgroup implementation

b9537ea

Add warp concept

a737173

Add spherical warp

64349db

Remove envmap accessors.hlsl

e44fcf4

Hierarchical image sampling implementation

9b29dfd

changed quaternion struct name, brought in quaternion stuff from prze…

9be65a0

…mek's remove_core_matrix branch, added create from mat3x3

_static_create quaternion to matrix, create quaternion from axis-angle

3e03467

added more quaternion funcs: transformVec, inverse, normalize + stati…

34d1385

…c cast to/from truncated quat

Merge branch 'master' into env_map_importance_sampling

06ae3e4

Merge branch 'master' into env_map_importance_sampling

16ecb52

Remove envmap.hlsl

8d682b9

devshgraphicsprogramming reviewed Dec 21, 2025

View reviewed changes

include/nbl/builtin/hlsl/concepts/warp.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 21, 2025

View reviewed changes

include/nbl/builtin/hlsl/concepts/warp.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 21, 2025

View reviewed changes

include/nbl/builtin/hlsl/concepts/warp.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 21, 2025

View reviewed changes

include/nbl/builtin/hlsl/warp/spherical.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 21, 2025

View reviewed changes

include/nbl/builtin/hlsl/warp/spherical.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 22, 2025

View reviewed changes

include/nbl/builtin/hlsl/concepts/warp.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 22, 2025

View reviewed changes

include/nbl/builtin/hlsl/warp/spherical.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 22, 2025

View reviewed changes

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 22, 2025

View reviewed changes

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 22, 2025

View reviewed changes

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl Outdated Show resolved Hide resolved

devshgraphicsprogramming reviewed Dec 22, 2025

View reviewed changes

include/nbl/builtin/hlsl/sampling/hierarchical_image.hlsl Outdated Show resolved Hide resolved

kevyuu added 7 commits December 22, 2025 23:59

Move to sampling namespace and implement backward density

890f7c6

Remove private, public from hierarchical_image

f99c63b

Refactor hierarchical image to keep accessor and common data as member

3ff2791

Refactor hierarchical image to separate binarySearch from Hierarchica…

76ef536

…lImage class

Fix Spherical warp indentation

ef773fd

Add some comment why we add xi to the sample uvs

b9467fe

Merge branch 'master' into env_map_importance_sampling

3682604

devshgraphicsprogramming reviewed Feb 25, 2026

View reviewed changes

		[[vk::binding(0, 0)]] Texture2D<float32_t4> envMap;
		[[vk::binding(1, 0)]] RWTexture2D<float32_t> outImage;

		LuminanceSampler luminanceSampler =
		LuminanceSampler::create(luminanceAccessor, uint32_t2(lumaMapWidth, lumaMapHeight), lumaMapWidth != lumaMapHeight, uint32_t2(lumaMapWidth, lumaMapHeight));

		uint32_t2 pixelCoord = threadID.xy;

		outImage[pixelCoord] = luminanceSampler.binarySearch(pixelCoord);



		// If we don`t add xi, the sample will clump to the lowest corner of environment map texel. We add xi to simulate uniform distribution within a pixel and make the sample continuous. This is why we compute the pdf not from the normalized luminance of the texel, instead from the reciprocal of the Jacobian.
		const vector2_type directionUV = (vector2_type(p.x, p.y) + xi) / vector2_type(_mapSize);

		const vector2_type texelCoord = xi * float32_t2(_lastWarpPixel);

		matrix<scalar_type, 4, 2> uvs = _warpMap.sampleUvs(uint32_t2(texelCoord));


		matrix<scalar_type, 4, 2> uvs = _warpMap.sampleUvs(uint32_t2(texelCoord));

		const vector2_type interpolant = frac(texelCoord);

Conversation

kevyuu commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing

TODO list:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devshgraphicsprogramming Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devshgraphicsprogramming Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devshgraphicsprogramming Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devshgraphicsprogramming Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevyuu commented Dec 19, 2025 •

edited

Loading

devshgraphicsprogramming Feb 25, 2026 •

edited

Loading

devshgraphicsprogramming Feb 25, 2026 •

edited

Loading

devshgraphicsprogramming Feb 25, 2026 •

edited

Loading

devshgraphicsprogramming Feb 25, 2026 •

edited

Loading

devshgraphicsprogramming Feb 25, 2026 •

edited

Loading