C Specification

To register a custom border color, call:

// Provided by VK_EXT_custom_border_color with VK_EXT_descriptor_heap
VkResult vkRegisterCustomBorderColorEXT(
    VkDevice                                    device,
    const VkSamplerCustomBorderColorCreateInfoEXT* pBorderColor,
    VkBool32                                    requestIndex,
    uint32_t*                                   pIndex);

Parameters

  • device is the logical device where the border color is registered.

  • pBorderColor is a pointer to a VkSamplerCustomBorderColorCreateInfoEXT structure specifying the custom border color value to register.

  • requestIndex is a Boolean value indicating if a specific index is requested or not.

  • pIndex is a pointer to a uint32_t index value that will be written by the command upon success.

Description

If requestIndex is VK_TRUE, the value present in pIndex when passed to the command is a requested index, and rather than returning a new index, the implementation will attempt to register that index, leaving the value intact. If the implementation is unable to register a requested index, VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS will be returned. If an index has not been registered (either explicitly or implicitly by creating a sampler object), or if it has been subsequently unregistered, the implementation must register that index successfully.

If requestIndex is VK_FALSE, the value stored in pIndex is ignored, and a new index will be returned if the implementation is able to register a new index. If the implementation is unable to register a new index, VK_ERROR_TOO_MANY_OBJECTS will be returned.

If an index is successfully registered, it can be used when writing a sampler descriptor or creating a sampler object to use with the custom border color, via VkSamplerCustomBorderColorIndexCreateInfoEXT.

Note

The type of border color is not specified by this command (VK_BORDER_COLOR_FLOAT_CUSTOM_EXT vs. VK_BORDER_COLOR_INT_CUSTOM_EXT); the data will be interpreted at the point the border color is sampled with an actual sampler. Implementations are expected to store the data as raw bytes if they do not need the format to be specified.
Valid Usage
Valid Usage (Implicit)

  • VUID-vkRegisterCustomBorderColorEXT-device-parameter
    device must be a valid VkDevice handle

  • VUID-vkRegisterCustomBorderColorEXT-pBorderColor-parameter
    pBorderColor must be a valid pointer to a valid VkSamplerCustomBorderColorCreateInfoEXT structure

  • VUID-vkRegisterCustomBorderColorEXT-pIndex-parameter
    pIndex must be a valid pointer to a uint32_t value

Return Codes
On success, this command returns
On failure, this command returns

See Also

VK_EXT_custom_border_color, VK_EXT_descriptor_heap, VkBool32, VkDevice, VkSamplerCustomBorderColorCreateInfoEXT

Document Notes

For more information, see the Vulkan Specification.

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0