Can someone please explain DescriptorHandle for Bindless Descriptor Access

[Please-just-dont]

I've read through the documentation about 4 times and I still don't understand what it does or how it's used. Please someone help and explain?

In GLSL to use bindless with Vulkan I'd do:

layout(set = 1, binding = 2) uniform texture2D textures[];

And in Slang I can do:

[[vk::binding(2,1)]] Texture2D textures[];

or

layout(set = 1, binding = 2) Texture2D textures[];

This is a descriptor array bound to a certain descriptor set, that I bind manually in Vulkan API on the host-side.

OK, now we have:

DescriptorHandle<T>

And the example shows this:

uniform StructuredBuffer<DescriptorHandle<Texture2D>> textures;
uniform int textureIndex;

// define a descriptor handle using builtin convenience typealias:
uniform StructuredBuffer<float4>.Handle output;


[numthreads(1,1,1)]
void main()
{
    output[0] = textures[textureIndex].Load(int3(0));

    // Alternatively, this syntax is also valid:
    (*output)[0] = textures[textureIndex]->Load(int3(0));
}

What I want to know is, leaving out the explicit binding, this:

uniform StructuredBuffer<DescriptorHandle<Texture2D>> textures;

What is the relation between this and simply:

uniform Texture2D textures[];

A StructuredBuffer as a uniform is basically equivalent to:
uniform T name[]

???

And then what is the difference between:

uniform StructuredBuffer<DescriptorHandle<Texture2D>> my_array;

and
uniform Textured2D my_array[];

?

In uniform Texture2D my_array[]; I bind an array of texture descriptors to that uniform and what I am indexing in that array are 'Descriptors' which have been bound. I understand DescriptorHandle is an id (two integers), but how are they supposed to be set? Am I supposed to bind a buffer of integers instead of an array of image descriptors?

[szihs]

uniform Texture2D textures[]; // Approach A
uniform StructuredBuffer<DescriptorHandle> textures; // Approach B

They are fundamentally different:

• Approach A: You bind actual texture descriptors directly

• Approach B: You bind a buffer containing integers that reference textures elsewhere

  DescriptorHandle is essentially a uint64 (or uint2) index into a global descriptor heap. Think of it like a pointer - it's just a number that tells the GPU where to find the actual texture.

How Handles Actually Work

CPU Side - Create Global Heap (One Time Setup)

// DX12 Example
D3D12_DESCRIPTOR_HEAP_DESC heapDesc = {
    .Type = D3D12_DESCRIPTOR_HEAP_TYPE_CBV_SRV_UAV,
    .NumDescriptors = 1000000,  // Million descriptors!
    .Flags = D3D12_DESCRIPTOR_HEAP_FLAG_SHADER_VISIBLE
};
device->CreateDescriptorHeap(&heapDesc, &globalHeap);

// Put textures into the heap
for (int i = 0; i < numTextures; i++) {
    device->CreateShaderResourceView(
        textures[i],
        nullptr,
        globalHeap->GetCPUDescriptorHandleForHeapStart()
            + i * heapIncrement
    );
}

CPU Side - Create Handle Buffer (Per-Frame/Material)

  // Create a buffer containing indices into the global heap
  struct MaterialHandles {
      uint64_t textureHandle;  // = 42 (index into heap)
      uint64_t samplerHandle;  // = 5  (index into heap)
  };

  MaterialHandles materials[100] = {
      { 42, 5 },  // Mat 0: tex at heap[42], samp at heap[5]
      { 17, 3 },  // Mat 1: tex at heap[17], samp at heap[3]
      { 99, 5 },  // Mat 2: tex at heap[99], samp at heap[5]
      // ...
  };

  // Upload this TINY buffer (just numbers!)
  uploadToGPU(handleBuffer, materials, sizeof(materials));

GPU Side - Shader Accesses Handle

  // Slang shader receives the handle buffer
  uniform StructuredBuffer<DescriptorHandle<Texture2D>>
      textureHandles;
  uniform uint materialID;  // = 0 (use material 0)

  void main() {
      // Read handle: gets {42, 0} as uint2
      DescriptorHandle<Texture2D> handle =
          textureHandles[materialID];

      // Implicit conversion calls getDescriptorFromHandle()
      Texture2D tex = handle;

      // tex now points to globalHeap[42]
      float4 color = tex.Sample(...);
  }

Slang - Backend Code Generation

  HLSL (DX12):
  // Slang input:
  Texture2D tex = textureHandles[materialID];

  // Generated HLSL:
  uint2 handleValue = handleBuffer[materialID];
  Texture2D tex = ResourceDescriptorHeap[handleValue.x];
  //              ^^^^^^^^^^^^^^^^^^^^^
  //              Global heap access!

  SPIRV (Vulkan):
  // Generated with descriptor indexing
  layout(set = 10, binding = 0)
      uniform texture2D globalTextureHeap[];

  uint2 handleValue = handleBuffer[materialID];
  texture2D tex = globalTextureHeap[handleValue.x];

Note:

1. DescriptorHandle is just uint2 (or uint64_t)
   - Literally an index into the heap
2. "Handles" = indices into a giant global array
   - All your resources live there
3. You store/pass indices in regular buffers
   - They're just numbers - treat them like data!
4. getDescriptorFromHandle() translates:
   - uint2 → globalHeap[uint2.x] → Texture

[Please-just-dont]

@szihs Ah thank you so much for this explanation. So... in the Vulkan case, (I'm not familiar with DirectX), when you do:

 // Slang shader receives the handle buffer
  uniform StructuredBuffer<DescriptorHandle<Texture2D>> textureHandles;
  uniform uint materialID;  // = 0 (use material 0)

The 'textureHandles' would be something like a storage buffer bound to a descriptor set, containing a list of indices. You use materialID to index into textureHandle, and that just gives another integer (or two or whatever). Then, with this integer you index into what you call the DescriptorHeap, which in DirectX is something I don't understand, but in Vulkan is just simply this:

layout (set = 0, binding = 0) uniform texture2D textures[];

So ^^^ that is basically the equivalent of the 'descriptor heap'. Ahh thank you for explaining it. The DescriptorHandle is just an integer (or two), which is bound as a storage buffer in Vulkan. Now that I know that DescriptorHandle is just an integer bound to a storage buffer, I think I'll skip it and just use my own integers.

Why in the Slang backend code did you write:

layout(set = 10, binding = 0)
      uniform texture2D globalTextureHeap[];

Why set = 10?

Also, I never understood how in Slang documentation binding descriptor sets is recommended to be done automatically, not manually by specifying the set and binding, but just letting Slang select the descriptor set. This is because in your host-side code you still have to bind particular descriptor sets, and at least in Vulkan the sequence of them is important, so like if you have descriptor sets 1, 2, 3, 4 bound, and you then bind another descriptor set at 2, then 3 and 4 are invalid and need to be set again. What I'm saying is that descriptor sets, at least in Vulkan, are very specific and the programmer has to know exactly which ones need to be bound, I can't understand how automatic deduction of descriptor set binding numbers is possible or a good idea.

[Please-just-dont]

@szihs Hmm, I know that in the documentation here it explains that DescriptorHandle is just an integer (or two), but it might be good to explain that:

uniform StructuredBuffer<DescriptorHandle<Texture2D>>
      textureHandles;

Is just a buffer (either storage or uniform) of integers that you set from the host side. And also that the "Descriptor Heap" in something like Vulkan is just:

uniform texture2D textures[];

or
uniform DescriptorType array_of_stuff[];

[szihs]

The set = 10 in the example was illustrative. You can control which descriptor set is used for the global bindless heap with the -bindless-space-index

slangc -target spirv -bindless-space-index 10 shader.slang

You can also query the assigned bindings using Slang's reflection API to know what to bind on the host side.