vkRegisterCustomBorderColorEXT(3)

# vkRegisterCustomBorderColorEXT(3) Manual Page

## Name

vkRegisterCustomBorderColorEXT - Register a custom border color

## 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

- VUID-vkRegisterCustomBorderColorEXT-requestIndex-11287
  If `requestIndex` is VK_TRUE, the value stored in `pIndex` must be less than maxCustomBorderColorSamplers

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

  - VK_SUCCESS

On failure, this command returns

  - VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS

  - VK_ERROR_OUT_OF_DEVICE_MEMORY

  - VK_ERROR_OUT_OF_HOST_MEMORY

  - VK_ERROR_TOO_MANY_OBJECTS

  - VK_ERROR_UNKNOWN

  - VK_ERROR_VALIDATION_FAILED

## 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