VkSamplerCustomBorderColorCreateInfoEXT(3)

C Specification

In addition to the predefined border color values, applications can provide a custom border color value by including the VkSamplerCustomBorderColorCreateInfoEXT structure in the VkSamplerCreateInfo::pNext chain.

The VkSamplerCustomBorderColorCreateInfoEXT structure is defined as:

// Provided by VK_EXT_custom_border_color
typedef struct VkSamplerCustomBorderColorCreateInfoEXT {
    VkStructureType      sType;
    const void*          pNext;
    VkClearColorValue    customBorderColor;
    VkFormat             format;
} VkSamplerCustomBorderColorCreateInfoEXT;

Members

sType is a VkStructureType value identifying this structure.
pNext is NULL or a pointer to a structure extending this structure.
customBorderColor is a VkClearColorValue representing the desired custom sampler border color.
format is a VkFormat representing the format of the sampled image view(s). This field may be VK_FORMAT_UNDEFINED if the customBorderColorWithoutFormat feature is enabled.

Description

Note

If format is a depth/stencil format, the aspect is determined by the value of VkSamplerCreateInfo::borderColor. If VkSamplerCreateInfo::borderColor is VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, the depth aspect is considered. If VkSamplerCreateInfo::borderColor is VK_BORDER_COLOR_INT_CUSTOM_EXT, the stencil aspect is considered.

If format is VK_FORMAT_UNDEFINED, the VkSamplerCreateInfo::borderColor is VK_BORDER_COLOR_INT_CUSTOM_EXT, and the sampler is used with an image with a stencil format, then the implementation must source the custom border color from either the first or second components of VkSamplerCreateInfo::borderColor and should source it from the first component.

In some cases, implementations may return undefined values instead of the specified custom border color when used on VK_QUEUE_COMPUTE_BIT queues that do not also support VK_QUEUE_GRAPHICS_BIT.

Note	Tests added in 2026 revealed issues around custom border colors on AMD in compute-only queues, that were not fixable in software. While this will be fixed in future hardware, there is no reasonable workaround for existing hardware. Use of standard border colors is unaffected.

Valid Usage

VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-07605
If format is not VK_FORMAT_UNDEFINED and format is not a depth/stencil format then the VkSamplerCreateInfo::borderColor type must match the sampled type of the provided format, as shown in the SPIR-V Type column of the https://registry.khronos.org/vulkan/specs/latest/html/vkspec.html#formats-numericformat table
VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04014
If the customBorderColorWithoutFormat feature is not enabled then format must not be VK_FORMAT_UNDEFINED
VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04015
If the sampler is used to sample an image view of VK_FORMAT_B4G4R4A4_UNORM_PACK16, VK_FORMAT_B5G6R5_UNORM_PACK16, VK_FORMAT_A1B5G5R5_UNORM_PACK16, or VK_FORMAT_B5G5R5A1_UNORM_PACK16 format then format must not be VK_FORMAT_UNDEFINED

Valid Usage (Implicit)

VUID-VkSamplerCustomBorderColorCreateInfoEXT-sType-sType
sType must be VK_STRUCTURE_TYPE_SAMPLER_CUSTOM_BORDER_COLOR_CREATE_INFO_EXT
VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-parameter
format must be a valid VkFormat value

Structure Chaining

Extends the structure

VkSamplerCreateInfo

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

SPDX-License-Identifier: CC-BY-4.0

VkSamplerCustomBorderColorCreateInfoEXT(3) Manual Page

Name

C Specification

Members

Description

See Also

Document Notes

Copyright