Partially Bound Descriptors¶

This example shows how to use the descriptorBindingPartiallyBound feature to create descriptor sets where some bindings haven't been initialized yet. Normally, binding an incomplete descriptor set causes validation errors. Partially bound descriptors allow conditional resource access in shaders - you only need to populate bindings that the shader will actually use. This enables dynamic resource management, lazy loading, and optional shader features.

The example uses the KDGpuExample helper API for simplified setup.

Overview¶

What this example demonstrates:

Enabling descriptorBindingPartiallyBound feature
Creating descriptor set layouts with PartiallyBoundBit flag
Binding descriptor sets with uninitialized bindings
Updating partially bound descriptors at runtime
Conditional resource access in shaders

Use cases:

Optional shader features (enable/disable via uniforms)
Lazy resource loading (populate descriptors on demand)
Conditional texture sampling (material variations)
Resource streaming (bind textures as they load)
Shader permutations without pipeline changes

Vulkan Requirements¶

Vulkan Version: 1.2+ (descriptor indexing promoted to core)
Extensions: VK_EXT_descriptor_indexing (core in 1.2)
Features:
- descriptorBindingPartiallyBound
Validation: Only accessed bindings must be valid

Key Concepts¶

Traditional Descriptor Binding:

Normally, all bindings in a descriptor set must be initialized:

// Descriptor set layout:
binding 0: Uniform buffer
binding 1: Combined image sampler

// Create descriptor set:
resources = {
    {binding 0, uniformBuffer},  // Must be provided!
    {binding 1, texture}         // Must be provided!
};

Binding without initializing all resources causes validation error:

VUID-vkCmdDraw-None-02699: Descriptor at binding 1 not initialized!

Partially Bound Descriptors:

With PartiallyBoundBit, uninitialized bindings are allowed:

// Layout with partially bound flag:
binding 0: Uniform buffer (required)
binding 1: Combined image sampler (PartiallyBoundBit - optional!)

// Create descriptor set (binding 1 left empty):
resources = {
    {binding 0, uniformBuffer}  // Only provide binding 0
};

// Valid! Shader must not access binding 1, or update it before access

Shader:

layout(set = 0, binding = 0) uniform Params {
    bool useTexture;
};

layout(set = 0, binding = 1) uniform sampler2D optionalTexture;

void main() {
    if (params.useTexture) {
        color = texture(optionalTexture, uv);  // Only access if bound!
    } else {
        color = baseColor;
    }
}

Rules:

Uninitialized bindings must not be accessed
Accessing uninitialized binding causes undefined behavior (not validated!)
Programmer responsible for ensuring correctness

Spec: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_descriptor_indexing.html

Update After Bind:

Partially bound is often used with "update after bind" to modify descriptors after binding:

Bind descriptor set with empty binding
Update binding later (before shader accesses it)
Draw with updated binding

Implementation¶

Creating Texture:

    // Create a texture
    {
        // Load the image data and size
        auto imageFile = KDGpuExample::assetDir().file("textures/samuel-ferrara-1527pjeb6jg-unsplash.jpg");
        ImageData image = loadImage(imageFile);

        const TextureOptions textureOptions = {
            .type = TextureType::TextureType2D,
            .format = image.format,
            .extent = { .width = image.width, .height = image.height, .depth = 1 },
            .mipLevels = 1,
            .usage = TextureUsageFlagBits::SampledBit | TextureUsageFlagBits::TransferDstBit,
            .memoryUsage = MemoryUsage::GpuOnly,
            .initialLayout = TextureLayout::Undefined
        };
        m_texture = m_device.createTexture(textureOptions);

        // Upload the texture data and transition to ShaderReadOnlyOptimal
        const std::vector<BufferTextureCopyRegion> regions = {
            {
                    .textureSubResource = { .aspectMask = TextureAspectFlagBits::ColorBit },
                    .textureExtent = { .width = image.width, .height = image.height, .depth = 1 },
            },
        };
        const TextureUploadOptions uploadOptions = {
            .destinationTexture = m_texture,
            .dstStages = PipelineStageFlagBit::AllGraphicsBit,
            .dstMask = AccessFlagBit::MemoryReadBit,
            .data = image.pixelData,
            .byteSize = image.byteSize,
            .oldLayout = TextureLayout::Undefined,
            .newLayout = TextureLayout::ShaderReadOnlyOptimal,
            .regions = regions
        };
        uploadTextureData(uploadOptions);

        // Create a view and sampler
        m_textureView = m_texture.createView();
        m_sampler = m_device.createSampler();
    }