Structures

VkSamplerCustomBorderColorCreateInfoEXT

Structure specifying custom border color

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:

typedef struct VkSamplerCustomBorderColorCreateInfoEXT {
    VkStructureType sType;
    const void* pNext;
    VkClearColorValue customBorderColor;
    VkFormat format;
} VkSamplerCustomBorderColorCreateInfoEXT;
  • 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.
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.

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