Author: The Khronos® Vulkan Working Group

# Vulkan® 1.4.350 - A Specification (with all registered extensions)

The Khronos® Vulkan Working Group
version 1.4.350, 2026-05-20 07:19:56Z
from git branch: makepkg commit: 81b1d516cbf42f04a3c7f781977c499945b5e5dc

Loading… please wait.

Search:

## 14. Samplers

`VkSampler` objects represent the state of an image sampler which is used by the implementation to read image data and apply filtering and other transformations for the shader.

Samplers are represented by `VkSampler` handles:

    // Provided by VK_VERSION_1_0
    VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSampler)

To create a sampler object, call:

    // Provided by VK_VERSION_1_0
    VkResult vkCreateSampler(
        VkDevice                                    device,
        const VkSamplerCreateInfo*                  pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSampler*                                  pSampler);

- `device` is the logical device that creates the sampler.

- `pCreateInfo` is a pointer to a VkSamplerCreateInfo structure specifying the state of the sampler object.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

- `pSampler` is a pointer to a VkSampler handle in which the resulting sampler object is returned.

Valid Usage

- VUID-vkCreateSampler-device-09668
  `device` must support at least one queue family with one of the VK_QUEUE_COMPUTE_BIT or VK_QUEUE_GRAPHICS_BIT capabilities

- VUID-vkCreateSampler-maxSamplerAllocationCount-04110
  There must be less than VkPhysicalDeviceLimits::`maxSamplerAllocationCount` VkSampler objects currently created on the device

- VUID-vkCreateSampler-maxSamplerAllocationCount-11412
  If there are any pipelines or shaders with embedded samplers currently created on the device, there must be less than (`maxSamplerAllocationCount` - (`minSamplerHeapReservedRangeWithEmbedded` / `samplerDescriptorSize`)) VkSampler objects currently created on the device

Valid Usage (Implicit)

- VUID-vkCreateSampler-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkCreateSampler-pCreateInfo-parameter
  `pCreateInfo` must be a valid pointer to a valid VkSamplerCreateInfo structure

- VUID-vkCreateSampler-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkCreateSampler-pSampler-parameter
  `pSampler` must be a valid pointer to a VkSampler handle

Return Codes

Success

  - VK_SUCCESS

Failure

  - VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

  - VK_ERROR_OUT_OF_DEVICE_MEMORY

  - VK_ERROR_OUT_OF_HOST_MEMORY

  - VK_ERROR_UNKNOWN

  - VK_ERROR_VALIDATION_FAILED

The `VkSamplerCreateInfo` structure is defined as:

    // Provided by VK_VERSION_1_0
    typedef struct VkSamplerCreateInfo {
        VkStructureType         sType;
        const void*             pNext;
        VkSamplerCreateFlags    flags;
        VkFilter                magFilter;
        VkFilter                minFilter;
        VkSamplerMipmapMode     mipmapMode;
        VkSamplerAddressMode    addressModeU;
        VkSamplerAddressMode    addressModeV;
        VkSamplerAddressMode    addressModeW;
        float                   mipLodBias;
        VkBool32                anisotropyEnable;
        float                   maxAnisotropy;
        VkBool32                compareEnable;
        VkCompareOp             compareOp;
        float                   minLod;
        float                   maxLod;
        VkBorderColor           borderColor;
        VkBool32                unnormalizedCoordinates;
    } VkSamplerCreateInfo;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `flags` is a bitmask of VkSamplerCreateFlagBits describing additional parameters of the sampler.

- `magFilter` is a VkFilter value specifying the magnification filter to apply to lookups.

- `minFilter` is a VkFilter value specifying the minification filter to apply to lookups.

- `mipmapMode` is a VkSamplerMipmapMode value specifying the mipmap filter to apply to lookups.

- `addressModeU` is a VkSamplerAddressMode value specifying the wrapping operation used when the i coordinate used to sample the image would be out of bounds.

- `addressModeV` is a VkSamplerAddressMode value specifying the wrapping operation used when the j coordinate used to sample the image would be out of bounds.

- `addressModeW` is a VkSamplerAddressMode value specifying the wrapping operation used when the k coordinate used to sample the image would be out of bounds. If `unnormalizedCoordinates` is VK_TRUE, `addressModeW` is ignored.

- `mipLodBias` is the bias to be added to mipmap LOD calculation and bias provided by image sampling functions in SPIR-V, as described in the LOD Operation section.

- `anisotropyEnable` is VK_TRUE to enable anisotropic filtering, as described in the Texel Anisotropic Filtering section, or VK_FALSE otherwise.

- `maxAnisotropy` is the anisotropy value clamp used by the sampler when `anisotropyEnable` is VK_TRUE. If `anisotropyEnable` is VK_FALSE, `maxAnisotropy` is ignored.

- `compareEnable` is VK_TRUE to enable comparison against a reference value during lookups, or VK_FALSE otherwise.

  - Note: Some implementations will default to shader state if this member does not match.

- `compareOp` is a VkCompareOp value specifying the comparison operator to apply to fetched data before filtering as described in the Depth Compare Operation section.

- `minLod` is used to clamp the minimum of the computed LOD value.

- `maxLod` is used to clamp the maximum of the computed LOD value. To avoid clamping the maximum value, set `maxLod` to the constant VK_LOD_CLAMP_NONE.

- `borderColor` is a VkBorderColor value specifying the predefined border color to use.

- `unnormalizedCoordinates` controls whether to use unnormalized or normalized texel coordinates to address texels of the image. When `unnormalizedCoordinates` is VK_TRUE, the range of the image coordinates used to lookup the texel is in the range of zero to the image size in each dimension. When `unnormalizedCoordinates` is VK_FALSE, the range of image coordinates is zero to one.

  When `unnormalizedCoordinates` is VK_TRUE, images the sampler is used with in the shader have the following requirements:

  - The `viewType` must be either VK_IMAGE_VIEW_TYPE_1D or VK_IMAGE_VIEW_TYPE_2D.

  - The image view must have a single layer and a single mip level.

    When `unnormalizedCoordinates` is VK_TRUE, image built-in functions in the shader that use the sampler have the following requirements:

  - The functions must not use projection.

  - The functions must not use offsets.

Note | Mapping of OpenGL to Vulkan Filter Modes `magFilter` values of VK_FILTER_NEAREST and VK_FILTER_LINEAR directly correspond to `GL_NEAREST` and `GL_LINEAR` magnification filters. `minFilter` and `mipmapMode` combine to correspond to the similarly named OpenGL minification filter of `GL_minFilter_MIPMAP_mipmapMode` (e.g. `minFilter` of VK_FILTER_LINEAR and `mipmapMode` of VK_SAMPLER_MIPMAP_MODE_NEAREST correspond to `GL_LINEAR_MIPMAP_NEAREST`). There are no Vulkan filter modes that directly correspond to OpenGL minification filters of `GL_LINEAR` or `GL_NEAREST`, but they can be emulated using VK_SAMPLER_MIPMAP_MODE_NEAREST, `minLod` = 0, and `maxLod` = 0.25, and using `minFilter` = VK_FILTER_LINEAR or `minFilter` = VK_FILTER_NEAREST, respectively. Note that using a `maxLod` of zero would cause magnification to always be performed, and the `magFilter` to always be used. This is valid, just not an exact match for OpenGL behavior. Clamping the maximum LOD to 0.25 allows the λ value to be non-zero and minification to be performed, while still always rounding down to the base level. If the `minFilter` and `magFilter` are equal, then using a `maxLod` of zero also works.

The maximum number of sampler objects which can be simultaneously created on a device is implementation-dependent and specified by the `maxSamplerAllocationCount` member of the VkPhysicalDeviceLimits structure.

Note | For historical reasons, if `maxSamplerAllocationCount` is exceeded, some implementations may return VK_ERROR_TOO_MANY_OBJECTS. Exceeding this limit will result in undefined behavior, and an application should not rely on the use of the returned error code in order to identify when the limit is reached.

Since VkSampler is a non-dispatchable handle type, implementations may return the same handle for sampler state vectors that are identical. In such cases, all such objects would only count once against the `maxSamplerAllocationCount` limit.

When this structure is used to write a descriptor via vkWriteSamplerDescriptorsEXT, applications can give the descriptor a debug name in a similar way to naming an object, via the VkDebugUtilsObjectNameInfoEXT structure. However, as there is no actual object, VkDebugUtilsObjectNameInfoEXT must be passed via the `pNext` chain of this structure, with a `objectType` of VK_OBJECT_TYPE_UNKNOWN and a `objectHandle` of VK_NULL_HANDLE. The name is attached to the unique set of descriptor bits written by the implementation, and writing the same bits again with new debug info may rename the original descriptor.

Note | Implementations are not prevented from returning the same bits for different descriptors. This can result in multiple different samplers mapping to the same name.

VkDescriptorSetAndBindingMappingEXT can also be chained in the same way when defining an embedded sampler via VkDescriptorSetAndBindingMappingEXT, naming the embedded sampler.

Valid Usage

- VUID-VkSamplerCreateInfo-mipLodBias-01069
  The absolute value of `mipLodBias` must be less than or equal to `VkPhysicalDeviceLimits`::`maxSamplerLodBias`

- VUID-VkSamplerCreateInfo-samplerMipLodBias-04467
  If the `VK_KHR_portability_subset` extension is enabled, and VkPhysicalDevicePortabilitySubsetFeaturesKHR::`samplerMipLodBias` is VK_FALSE, `mipLodBias` must be zero

- VUID-VkSamplerCreateInfo-maxLod-01973
  `maxLod` must be greater than or equal to `minLod`

- VUID-VkSamplerCreateInfo-anisotropyEnable-01070
  If the `samplerAnisotropy` feature is not enabled, `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-anisotropyEnable-01071
  If `anisotropyEnable` is VK_TRUE, `maxAnisotropy` must be between `1.0` and `VkPhysicalDeviceLimits`::`maxSamplerAnisotropy`, inclusive

- VUID-VkSamplerCreateInfo-minFilter-01645
  If sampler Y′CBCR conversion is enabled and the potential format features of the sampler Y′CBCR conversion do not support VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT, `minFilter` and `magFilter` must be equal to the sampler Y′CBCR conversion’s `chromaFilter`

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01072
  If `unnormalizedCoordinates` is VK_TRUE, `minFilter` and `magFilter` must be equal

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01073
  If `unnormalizedCoordinates` is VK_TRUE, `mipmapMode` must be VK_SAMPLER_MIPMAP_MODE_NEAREST

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01074
  If `unnormalizedCoordinates` is VK_TRUE, `minLod` and `maxLod` must be zero

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01075
  If `unnormalizedCoordinates` is VK_TRUE, `addressModeU` and `addressModeV` must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01076
  If `unnormalizedCoordinates` is VK_TRUE, `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-unnormalizedCoordinates-01077
  If `unnormalizedCoordinates` is VK_TRUE, `compareEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-addressModeU-01078
  If any of `addressModeU`, `addressModeV` or `addressModeW` are VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, `borderColor` must be a valid VkBorderColor value

- VUID-VkSamplerCreateInfo-addressModeU-01646
  If sampler Y′CBCR conversion is enabled, `addressModeU`, `addressModeV`, and `addressModeW` must be VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE, `anisotropyEnable` must be VK_FALSE, and `unnormalizedCoordinates` must be VK_FALSE

- VUID-VkSamplerCreateInfo-None-01647
  If sampler Y′CBCR conversion is enabled and the `pNext` chain includes a VkSamplerReductionModeCreateInfo structure, then the sampler reduction mode must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

- VUID-VkSamplerCreateInfo-pNext-06726
  If the `samplerFilterMinmax` feature is not enabled and the `pNext` chain includes a VkSamplerReductionModeCreateInfo structure, then the sampler reduction mode must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

- VUID-VkSamplerCreateInfo-addressModeU-01079
  If the `samplerMirrorClampToEdge` feature is not enabled, and if the `VK_KHR_sampler_mirror_clamp_to_edge` extension is not enabled, `addressModeU`, `addressModeV` and `addressModeW` must not be VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE

- VUID-VkSamplerCreateInfo-compareEnable-01080
  If `compareEnable` is VK_TRUE, `compareOp` must be a valid VkCompareOp value

- VUID-VkSamplerCreateInfo-magFilter-01081
  If either `magFilter` or `minFilter` is VK_FILTER_CUBIC_EXT, `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-magFilter-07911
  If the VK_EXT_filter_cubic extension is not enabled and either `magFilter` or `minFilter` is VK_FILTER_CUBIC_IMG, the `reductionMode` member of VkSamplerReductionModeCreateInfo must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

- VUID-VkSamplerCreateInfo-compareEnable-01423
  If `compareEnable` is VK_TRUE, the `reductionMode` member of VkSamplerReductionModeCreateInfo must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE

- VUID-VkSamplerCreateInfo-flags-02574
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `minFilter` and `magFilter` must be equal

- VUID-VkSamplerCreateInfo-flags-02575
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `mipmapMode` must be VK_SAMPLER_MIPMAP_MODE_NEAREST

- VUID-VkSamplerCreateInfo-flags-02576
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `minLod` and `maxLod` must be zero

- VUID-VkSamplerCreateInfo-flags-02577
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `addressModeU` and `addressModeV` must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

- VUID-VkSamplerCreateInfo-flags-02578
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-flags-02579
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `compareEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-flags-02580
  If `flags` includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then `unnormalizedCoordinates` must be VK_FALSE

- VUID-VkSamplerCreateInfo-nonSeamlessCubeMap-06788
  If the `nonSeamlessCubeMap` feature is not enabled, `flags` must not include VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT

- VUID-VkSamplerCreateInfo-borderColor-04011
  If `borderColor` is one of VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT, then a VkSamplerCustomBorderColorCreateInfoEXT must be included in the `pNext` chain

- VUID-VkSamplerCreateInfo-customBorderColors-04085
  If the `customBorderColors` feature is not enabled, `borderColor` must not be VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT

- VUID-VkSamplerCreateInfo-borderColor-04442
  If `borderColor` is one of VK_BORDER_COLOR_FLOAT_CUSTOM_EXT or VK_BORDER_COLOR_INT_CUSTOM_EXT, and VkSamplerCustomBorderColorCreateInfoEXT::`format` is not VK_FORMAT_UNDEFINED, VkSamplerCustomBorderColorCreateInfoEXT::`customBorderColor` must be within the range of values representable in `format`

- VUID-VkSamplerCreateInfo-None-04012
  The maximum number of samplers with custom border colors which can be simultaneously created on a device is implementation-dependent and specified by the `maxCustomBorderColorSamplers` member of the VkPhysicalDeviceCustomBorderColorPropertiesEXT structure

- VUID-VkSamplerCreateInfo-flags-08110
  If `flags` includes VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT, the `descriptorBufferCaptureReplay` feature must be enabled

- VUID-VkSamplerCreateInfo-pNext-08111
  If the `pNext` chain includes a VkOpaqueCaptureDescriptorDataCreateInfoEXT structure, `flags` must contain VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT

- VUID-VkSamplerCreateInfo-flags-06964
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `minFilter` and `magFilter` must be VK_FILTER_NEAREST

- VUID-VkSamplerCreateInfo-flags-06965
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `mipmapMode` must be VK_SAMPLER_MIPMAP_MODE_NEAREST

- VUID-VkSamplerCreateInfo-flags-06966
  [If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `minLod` and `maxLod` must be zero

- VUID-VkSamplerCreateInfo-flags-06967
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `addressModeU` and `addressModeV` must each be either VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE or VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER

- VUID-VkSamplerCreateInfo-flags-06968
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, and if `addressModeU` or `addressModeV` is VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, then `borderColor` must be VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK

- VUID-VkSamplerCreateInfo-flags-06969
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `anisotropyEnable` must be VK_FALSE

- VUID-VkSamplerCreateInfo-flags-06970
  If `flags` includes VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM, then `compareEnable` must be VK_FALSE

Valid Usage (Implicit)

- VUID-VkSamplerCreateInfo-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO

- VUID-VkSamplerCreateInfo-pNext-pNext
  Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkDebugUtilsObjectNameInfoEXT, VkOpaqueCaptureDescriptorDataCreateInfoEXT, VkSamplerBlockMatchWindowCreateInfoQCOM, VkSamplerBorderColorComponentMappingCreateInfoEXT, VkSamplerCubicWeightsCreateInfoQCOM, VkSamplerCustomBorderColorCreateInfoEXT, VkSamplerCustomBorderColorIndexCreateInfoEXT, VkSamplerReductionModeCreateInfo, or VkSamplerYcbcrConversionInfo

- VUID-VkSamplerCreateInfo-sType-unique
  The `sType` value of each structure in the `pNext` chain must be unique

- VUID-VkSamplerCreateInfo-flags-parameter
  `flags` must be a valid combination of VkSamplerCreateFlagBits values

- VUID-VkSamplerCreateInfo-magFilter-parameter
  `magFilter` must be a valid VkFilter value

- VUID-VkSamplerCreateInfo-minFilter-parameter
  `minFilter` must be a valid VkFilter value

- VUID-VkSamplerCreateInfo-mipmapMode-parameter
  `mipmapMode` must be a valid VkSamplerMipmapMode value

- VUID-VkSamplerCreateInfo-addressModeU-parameter
  `addressModeU` must be a valid VkSamplerAddressMode value

- VUID-VkSamplerCreateInfo-addressModeV-parameter
  `addressModeV` must be a valid VkSamplerAddressMode value

- VUID-VkSamplerCreateInfo-addressModeW-parameter
  `addressModeW` must be a valid VkSamplerAddressMode value

VK_LOD_CLAMP_NONE is a special constant value used for VkSamplerCreateInfo::`maxLod` to indicate that maximum LOD clamping should not be performed.

    #define VK_LOD_CLAMP_NONE                 1000.0F

Bits which can be set in VkSamplerCreateInfo::`flags`, specifying additional parameters of a sampler, are:

    // Provided by VK_VERSION_1_0
    typedef enum VkSamplerCreateFlagBits {
      // Provided by VK_EXT_fragment_density_map
        VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT = 0x00000001,
      // Provided by VK_EXT_fragment_density_map
        VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT = 0x00000002,
      // Provided by VK_EXT_descriptor_buffer
        VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT = 0x00000008,
      // Provided by VK_EXT_non_seamless_cube_map
        VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT = 0x00000004,
      // Provided by VK_QCOM_image_processing
        VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM = 0x00000010,
    } VkSamplerCreateFlagBits;

- VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT specifies that the sampler will read from an image created with `flags` containing VK_IMAGE_CREATE_SUBSAMPLED_BIT_EXT.

- VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT specifies that the implementation may use approximations when reconstructing a full color value for texture access from a subsampled image.

- VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT specifies that cube map edge handling is not performed.

- VK_SAMPLER_CREATE_IMAGE_PROCESSING_BIT_QCOM specifies that the sampler will read from images using only `OpImageSampleWeightedQCOM`, `OpImageBoxFilterQCOM`, `OpImageBlockMatchGatherSSDQCOM`, `OpImageBlockMatchGatherSADQCOM`, `OpImageBlockMatchWindowSSDQCOM`, `OpImageBlockMatchWindowSADQCOM`, `OpImageBlockMatchSSDQCOM`, or `OpImageBlockMatchSADQCOM`.

Note | The approximations used when VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT is specified are implementation defined. Some implementations may interpolate between fragment density levels in a subsampled image. In that case, this bit may be used to decide whether the interpolation factors are calculated per fragment or at a coarser granularity.

- VK_SAMPLER_CREATE_DESCRIPTOR_BUFFER_CAPTURE_REPLAY_BIT_EXT specifies that the sampler can be used with descriptor buffers when capturing and replaying (e.g. for trace capture and replay), see VkOpaqueCaptureDescriptorDataCreateInfoEXT for more detail.

    // Provided by VK_VERSION_1_0
    typedef VkFlags VkSamplerCreateFlags;

`VkSamplerCreateFlags` is a bitmask type for setting a mask of zero or more VkSamplerCreateFlagBits.

The `VkSamplerReductionModeCreateInfo` structure is defined as:

    // Provided by VK_VERSION_1_2
    typedef struct VkSamplerReductionModeCreateInfo {
        VkStructureType           sType;
        const void*               pNext;
        VkSamplerReductionMode    reductionMode;
    } VkSamplerReductionModeCreateInfo;

    // Provided by VK_EXT_sampler_filter_minmax
    // Equivalent to VkSamplerReductionModeCreateInfo
    typedef VkSamplerReductionModeCreateInfo VkSamplerReductionModeCreateInfoEXT;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `reductionMode` is a VkSamplerReductionMode value controlling how texture filtering combines texel values.

If the `pNext` chain of VkSamplerCreateInfo includes a `VkSamplerReductionModeCreateInfo` structure, then that structure includes a mode controlling how texture filtering combines texel values.

If this structure is not present, `reductionMode` is considered to be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE.

Valid Usage (Implicit)

- VUID-VkSamplerReductionModeCreateInfo-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO

- VUID-VkSamplerReductionModeCreateInfo-reductionMode-parameter
  `reductionMode` must be a valid VkSamplerReductionMode value

Structure Chaining

Extends the structure

  - VkSamplerCreateInfo

Reduction modes are specified by VkSamplerReductionMode, which takes values:

    // Provided by VK_VERSION_1_2
    typedef enum VkSamplerReductionMode {
        VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE = 0,
        VK_SAMPLER_REDUCTION_MODE_MIN = 1,
        VK_SAMPLER_REDUCTION_MODE_MAX = 2,
      // Provided by VK_QCOM_filter_cubic_clamp
        VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_RANGECLAMP_QCOM = 1000521000,
      // Provided by VK_EXT_sampler_filter_minmax
        VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT = VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE,
      // Provided by VK_EXT_sampler_filter_minmax
        VK_SAMPLER_REDUCTION_MODE_MIN_EXT = VK_SAMPLER_REDUCTION_MODE_MIN,
      // Provided by VK_EXT_sampler_filter_minmax
        VK_SAMPLER_REDUCTION_MODE_MAX_EXT = VK_SAMPLER_REDUCTION_MODE_MAX,
    } VkSamplerReductionMode;

    // Provided by VK_EXT_sampler_filter_minmax
    // Equivalent to VkSamplerReductionMode
    typedef VkSamplerReductionMode VkSamplerReductionModeEXT;

- VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE specifies that texel values are combined by computing a weighted average of values in the footprint, using weights as specified in the image operations chapter.

- VK_SAMPLER_REDUCTION_MODE_MIN specifies that texel values are combined by taking the component-wise minimum of values in the footprint with non-zero weights.

- VK_SAMPLER_REDUCTION_MODE_MAX specifies that texel values are combined by taking the component-wise maximum of values in the footprint with non-zero weights.

- VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_RANGECLAMP_QCOM specifies values are combined as described by VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE, followed by a texel range clamp.

The `VkSamplerCubicWeightsCreateInfoQCOM` structure is defined as:

    // Provided by VK_QCOM_filter_cubic_weights
    typedef struct VkSamplerCubicWeightsCreateInfoQCOM {
        VkStructureType             sType;
        const void*                 pNext;
        VkCubicFilterWeightsQCOM    cubicWeights;
    } VkSamplerCubicWeightsCreateInfoQCOM;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `cubicWeights` is a VkCubicFilterWeightsQCOM value controlling which cubic weights are used.

If the `pNext` chain of VkSamplerCreateInfo includes a `VkSamplerCubicWeightsCreateInfoQCOM` structure, then that structure specifies which cubic weights are used.

If that structure is not present, `cubicWeights` is considered to be VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM.

Valid Usage (Implicit)

- VUID-VkSamplerCubicWeightsCreateInfoQCOM-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_CUBIC_WEIGHTS_CREATE_INFO_QCOM

- VUID-VkSamplerCubicWeightsCreateInfoQCOM-cubicWeights-parameter
  `cubicWeights` must be a valid VkCubicFilterWeightsQCOM value

Structure Chaining

Extends the structure

  - VkSamplerCreateInfo

Possible values of the VkSamplerCubicWeightsCreateInfoQCOM::`cubicWeights`, specifying cubic weights used in Texel Cubic Filtering are:

    // Provided by VK_QCOM_filter_cubic_weights
    typedef enum VkCubicFilterWeightsQCOM {
        VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM = 0,
        VK_CUBIC_FILTER_WEIGHTS_ZERO_TANGENT_CARDINAL_QCOM = 1,
        VK_CUBIC_FILTER_WEIGHTS_B_SPLINE_QCOM = 2,
        VK_CUBIC_FILTER_WEIGHTS_MITCHELL_NETRAVALI_QCOM = 3,
    } VkCubicFilterWeightsQCOM;

- VK_CUBIC_FILTER_WEIGHTS_CATMULL_ROM_QCOM specifies Catmull-Rom weights.

- VK_CUBIC_FILTER_WEIGHTS_ZERO_TANGENT_CARDINAL_QCOM specifies Zero Tangent Cardinal weights.

- VK_CUBIC_FILTER_WEIGHTS_B_SPLINE_QCOM specifies B-Spline weights.

- VK_CUBIC_FILTER_WEIGHTS_MITCHELL_NETRAVALI_QCOM specifies Mitchell-Netravali weights.

Possible values of the VkSamplerCreateInfo::`magFilter` and `minFilter` parameters, specifying filters used for texture lookups, are:

    // Provided by VK_VERSION_1_0
    typedef enum VkFilter {
        VK_FILTER_NEAREST = 0,
        VK_FILTER_LINEAR = 1,
      // Provided by VK_EXT_filter_cubic
        VK_FILTER_CUBIC_EXT = 1000015000,
      // Provided by VK_IMG_filter_cubic
        VK_FILTER_CUBIC_IMG = VK_FILTER_CUBIC_EXT,
    } VkFilter;

- VK_FILTER_NEAREST specifies nearest filtering.

- VK_FILTER_LINEAR specifies linear filtering.

- VK_FILTER_CUBIC_EXT specifies cubic filtering.

These filters are described in detail in Texel Filtering.

Possible values of the VkSamplerCreateInfo::`mipmapMode`, specifying the mipmap mode used for texture lookups, are:

    // Provided by VK_VERSION_1_0
    typedef enum VkSamplerMipmapMode {
        VK_SAMPLER_MIPMAP_MODE_NEAREST = 0,
        VK_SAMPLER_MIPMAP_MODE_LINEAR = 1,
    } VkSamplerMipmapMode;

- VK_SAMPLER_MIPMAP_MODE_NEAREST specifies nearest filtering.

- VK_SAMPLER_MIPMAP_MODE_LINEAR specifies linear filtering.

These modes are described in detail in Texel Filtering.

Possible values of the VkSamplerCreateInfo::`addressMode*` parameters, corresponding to different wrapping operations used during sampling, are:

    // Provided by VK_VERSION_1_0
    typedef enum VkSamplerAddressMode {
        VK_SAMPLER_ADDRESS_MODE_REPEAT = 0,
        VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT = 1,
        VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE = 2,
        VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER = 3,
      // Provided by VK_VERSION_1_2, VK_KHR_sampler_mirror_clamp_to_edge
        VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE = 4,
      // Provided by VK_KHR_sampler_mirror_clamp_to_edge
      // VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE_KHR is a legacy alias
        VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE_KHR = VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE,
    } VkSamplerAddressMode;

- VK_SAMPLER_ADDRESS_MODE_REPEAT specifies that the repeat wrap mode will be used.

- VK_SAMPLER_ADDRESS_MODE_MIRRORED_REPEAT specifies that the mirrored repeat wrap mode will be used.

- VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE specifies that the clamp to edge wrap mode will be used.

- VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER specifies that the clamp to border wrap mode will be used.

- VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE specifies that the mirror clamp to edge wrap mode will be used. This is only valid if the `samplerMirrorClampToEdge` feature is enabled, or if the `VK_KHR_sampler_mirror_clamp_to_edge` extension is enabled.

Comparison operators compare a reference and a test value, and return a true (“passed”) or false (“failed”) value depending on the comparison operator chosen. The supported operators are:

    // Provided by VK_VERSION_1_0
    typedef enum VkCompareOp {
        VK_COMPARE_OP_NEVER = 0,
        VK_COMPARE_OP_LESS = 1,
        VK_COMPARE_OP_EQUAL = 2,
        VK_COMPARE_OP_LESS_OR_EQUAL = 3,
        VK_COMPARE_OP_GREATER = 4,
        VK_COMPARE_OP_NOT_EQUAL = 5,
        VK_COMPARE_OP_GREATER_OR_EQUAL = 6,
        VK_COMPARE_OP_ALWAYS = 7,
    } VkCompareOp;

- VK_COMPARE_OP_NEVER specifies that the comparison always evaluates false.

- VK_COMPARE_OP_LESS specifies that the comparison evaluates reference < test.

- VK_COMPARE_OP_EQUAL specifies that the comparison evaluates reference = test.

- VK_COMPARE_OP_LESS_OR_EQUAL specifies that the comparison evaluates reference ≤ test.

- VK_COMPARE_OP_GREATER specifies that the comparison evaluates reference > test.

- VK_COMPARE_OP_NOT_EQUAL specifies that the comparison evaluates reference ≠ test.

- VK_COMPARE_OP_GREATER_OR_EQUAL specifies that the comparison evaluates reference ≥ test.

- VK_COMPARE_OP_ALWAYS specifies that the comparison always evaluates true.

Comparison operators are used for:

- The Depth Compare Operation operator for a sampler, specified by VkSamplerCreateInfo::`compareOp`.

- The stencil comparison operator for the stencil test, specified by vkCmdSetStencilOp::`compareOp` or VkStencilOpState::`compareOp`.

- The Depth Comparison operator for the depth test, specified by vkCmdSetDepthCompareOp::`depthCompareOp` or VkPipelineDepthStencilStateCreateInfo::`depthCompareOp`.

Each such use describes how the reference and test values for that comparison are determined.

Possible values of VkSamplerCreateInfo::`borderColor`, specifying the border color used for texture lookups, are:

    // Provided by VK_VERSION_1_0
    typedef enum VkBorderColor {
        VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK = 0,
        VK_BORDER_COLOR_INT_TRANSPARENT_BLACK = 1,
        VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK = 2,
        VK_BORDER_COLOR_INT_OPAQUE_BLACK = 3,
        VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE = 4,
        VK_BORDER_COLOR_INT_OPAQUE_WHITE = 5,
      // Provided by VK_EXT_custom_border_color
        VK_BORDER_COLOR_FLOAT_CUSTOM_EXT = 1000287003,
      // Provided by VK_EXT_custom_border_color
        VK_BORDER_COLOR_INT_CUSTOM_EXT = 1000287004,
    } VkBorderColor;

- VK_BORDER_COLOR_FLOAT_TRANSPARENT_BLACK specifies a transparent, floating-point format, black color.

- VK_BORDER_COLOR_INT_TRANSPARENT_BLACK specifies a transparent, integer format, black color.

- VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK specifies an opaque, floating-point format, black color.

- VK_BORDER_COLOR_INT_OPAQUE_BLACK specifies an opaque, integer format, black color.

- VK_BORDER_COLOR_FLOAT_OPAQUE_WHITE specifies an opaque, floating-point format, white color.

- VK_BORDER_COLOR_INT_OPAQUE_WHITE specifies an opaque, integer format, white color.

- VK_BORDER_COLOR_FLOAT_CUSTOM_EXT specifies that a VkSamplerCustomBorderColorCreateInfoEXT structure is included in the VkSamplerCreateInfo::`pNext` chain containing the color data in floating-point format.

- VK_BORDER_COLOR_INT_CUSTOM_EXT specifies that a VkSamplerCustomBorderColorCreateInfoEXT structure is included in the VkSamplerCreateInfo::`pNext` chain containing the color data in integer format.

These colors are described in detail in Border Replacement.

To destroy a sampler, call:

    // Provided by VK_VERSION_1_0
    void vkDestroySampler(
        VkDevice                                    device,
        VkSampler                                   sampler,
        const VkAllocationCallbacks*                pAllocator);

- `device` is the logical device that destroys the sampler.

- `sampler` is the sampler to destroy.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage

- VUID-vkDestroySampler-sampler-01082
  All submitted commands that refer to `sampler` must have completed execution

- VUID-vkDestroySampler-sampler-01083
  If `VkAllocationCallbacks` were provided when `sampler` was created, a compatible set of callbacks must be provided here

- VUID-vkDestroySampler-sampler-01084
  If no `VkAllocationCallbacks` were provided when `sampler` was created, `pAllocator` must be `NULL`

Valid Usage (Implicit)

- VUID-vkDestroySampler-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkDestroySampler-sampler-parameter
  If `sampler` is not VK_NULL_HANDLE, `sampler` must be a valid VkSampler handle

- VUID-vkDestroySampler-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkDestroySampler-sampler-parent
  If `sampler` is a valid handle, it must have been created, allocated, or retrieved from `device`

Host Synchronization

- Host access to `sampler` must be externally synchronized

### 14.1. Sampler Y′CBCR Conversion

To create a sampler with Y′CBCR conversion enabled, add a VkSamplerYcbcrConversionInfo structure to the `pNext` chain of the VkSamplerCreateInfo structure. To create a sampler Y′CBCR conversion, the `samplerYcbcrConversion` feature must be enabled. Conversion must be fixed at pipeline creation time, through use of a combined embedded sampler and image mapping if using descriptor heaps, or a combined image sampler with an immutable sampler in `VkDescriptorSetLayoutBinding`.

A VkSamplerYcbcrConversionInfo must be provided for samplers to be used with image views that access VK_IMAGE_ASPECT_COLOR_BIT if the format is one of the formats that require a sampler Y′CBCR conversion , or if the image view has an external format .

The `VkSamplerYcbcrConversionInfo` structure is defined as:

    // Provided by VK_VERSION_1_1
    typedef struct VkSamplerYcbcrConversionInfo {
        VkStructureType             sType;
        const void*                 pNext;
        VkSamplerYcbcrConversion    conversion;
    } VkSamplerYcbcrConversionInfo;

    // Provided by VK_KHR_sampler_ycbcr_conversion
    // Equivalent to VkSamplerYcbcrConversionInfo
    typedef VkSamplerYcbcrConversionInfo VkSamplerYcbcrConversionInfoKHR;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `conversion` is a VkSamplerYcbcrConversion handle created with vkCreateSamplerYcbcrConversion.

Valid Usage (Implicit)

- VUID-VkSamplerYcbcrConversionInfo-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO

- VUID-VkSamplerYcbcrConversionInfo-conversion-parameter
  `conversion` must be a valid VkSamplerYcbcrConversion handle

Structure Chaining

Extends the structures

  - VkImageViewCreateInfo

  - VkSamplerCreateInfo

A sampler Y′CBCR conversion is an opaque representation of a device-specific sampler Y′CBCR conversion description, represented as a `VkSamplerYcbcrConversion` handle:

    // Provided by VK_VERSION_1_1
    VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSamplerYcbcrConversion)

    // Provided by VK_KHR_sampler_ycbcr_conversion
    // Equivalent to VkSamplerYcbcrConversion
    typedef VkSamplerYcbcrConversion VkSamplerYcbcrConversionKHR;

To create a VkSamplerYcbcrConversion, call:

    // Provided by VK_VERSION_1_1
    VkResult vkCreateSamplerYcbcrConversion(
        VkDevice                                    device,
        const VkSamplerYcbcrConversionCreateInfo*   pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSamplerYcbcrConversion*                   pYcbcrConversion);

    // Provided by VK_KHR_sampler_ycbcr_conversion
    // Equivalent to vkCreateSamplerYcbcrConversion
    VkResult vkCreateSamplerYcbcrConversionKHR(
        VkDevice                                    device,
        const VkSamplerYcbcrConversionCreateInfo*   pCreateInfo,
        const VkAllocationCallbacks*                pAllocator,
        VkSamplerYcbcrConversion*                   pYcbcrConversion);

- `device` is the logical device that creates the sampler Y′CBCR conversion.

- `pCreateInfo` is a pointer to a VkSamplerYcbcrConversionCreateInfo structure specifying the requested sampler Y′CBCR conversion.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

- `pYcbcrConversion` is a pointer to a VkSamplerYcbcrConversion handle in which the resulting sampler Y′CBCR conversion is returned.

The interpretation of the configured sampler Y′CBCR conversion is described in more detail in the description of sampler Y′CBCR conversion in the Image Operations chapter.

Valid Usage

- VUID-vkCreateSamplerYcbcrConversion-None-01648
  The `samplerYcbcrConversion` feature must be enabled

Valid Usage (Implicit)

- VUID-vkCreateSamplerYcbcrConversion-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkCreateSamplerYcbcrConversion-pCreateInfo-parameter
  `pCreateInfo` must be a valid pointer to a valid VkSamplerYcbcrConversionCreateInfo structure

- VUID-vkCreateSamplerYcbcrConversion-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkCreateSamplerYcbcrConversion-pYcbcrConversion-parameter
  `pYcbcrConversion` must be a valid pointer to a VkSamplerYcbcrConversion handle

Return Codes

Success

  - VK_SUCCESS

Failure

  - VK_ERROR_OUT_OF_DEVICE_MEMORY

  - VK_ERROR_OUT_OF_HOST_MEMORY

  - VK_ERROR_UNKNOWN

  - VK_ERROR_VALIDATION_FAILED

The `VkSamplerYcbcrConversionCreateInfo` structure is defined as:

    // Provided by VK_VERSION_1_1
    typedef struct VkSamplerYcbcrConversionCreateInfo {
        VkStructureType                  sType;
        const void*                      pNext;
        VkFormat                         format;
        VkSamplerYcbcrModelConversion    ycbcrModel;
        VkSamplerYcbcrRange              ycbcrRange;
        VkComponentMapping               components;
        VkChromaLocation                 xChromaOffset;
        VkChromaLocation                 yChromaOffset;
        VkFilter                         chromaFilter;
        VkBool32                         forceExplicitReconstruction;
    } VkSamplerYcbcrConversionCreateInfo;

    // Provided by VK_KHR_sampler_ycbcr_conversion
    // Equivalent to VkSamplerYcbcrConversionCreateInfo
    typedef VkSamplerYcbcrConversionCreateInfo VkSamplerYcbcrConversionCreateInfoKHR;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `format` is the format of the image from which color information will be retrieved.

- `ycbcrModel` describes the color matrix for conversion between color models.

- `ycbcrRange` describes whether the encoded values have headroom and foot room, or whether the encoding uses the full numerical range.

- `components` applies a swizzle based on VkComponentSwizzle enums prior to range expansion and color model conversion.

- `xChromaOffset` describes the sample location associated with downsampled chroma components in the x dimension. `xChromaOffset` has no effect for formats in which chroma components are not downsampled horizontally.

- `yChromaOffset` describes the sample location associated with downsampled chroma components in the y dimension. `yChromaOffset` has no effect for formats in which the chroma components are not downsampled vertically.

- `chromaFilter` is the filter for chroma reconstruction.

- `forceExplicitReconstruction` can be used to ensure that reconstruction is done explicitly, if supported.

Note | Setting `forceExplicitReconstruction` to VK_TRUE may have a performance penalty on implementations where explicit reconstruction is not the default mode of operation. If `format` supports VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT the `forceExplicitReconstruction` value behaves as if it were VK_TRUE.

If the `pNext` chain includes a VkExternalFormatANDROID structure with non-zero `externalFormat` member, the sampler Y′CBCR conversion object represents an external format conversion, and `format` must be VK_FORMAT_UNDEFINED. Such conversions must only be used to sample image views with a matching external format. When creating an external format conversion, the value of `components` is ignored.

Valid Usage

- VUID-VkSamplerYcbcrConversionCreateInfo-format-01904
  If an external format conversion is being created, `format` must be VK_FORMAT_UNDEFINED

- VUID-VkSamplerYcbcrConversionCreateInfo-format-04061
  If an external format conversion is not being created, `format` must represent unsigned normalized values (i.e. the format must be a `UNORM` format)

- VUID-VkSamplerYcbcrConversionCreateInfo-format-01650
  The potential format features of the sampler Y′CBCR conversion must support VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT

- VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01651
  If the potential format features of the sampler Y′CBCR conversion do not support VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, `xChromaOffset` and `yChromaOffset` must not be VK_CHROMA_LOCATION_COSITED_EVEN if the corresponding components are downsampled

- VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01652
  If the potential format features of the sampler Y′CBCR conversion do not support VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, `xChromaOffset` and `yChromaOffset` must not be VK_CHROMA_LOCATION_MIDPOINT if the corresponding components are downsampled

- VUID-VkSamplerYcbcrConversionCreateInfo-components-02581
  If the format has a `_422` or `_420` suffix, then `components.g` must be the identity swizzle

- VUID-VkSamplerYcbcrConversionCreateInfo-components-02582
  If the format has a `_422` or `_420` suffix, then `components.a` must be the identity swizzle, VK_COMPONENT_SWIZZLE_ONE, or VK_COMPONENT_SWIZZLE_ZERO

- VUID-VkSamplerYcbcrConversionCreateInfo-components-02583
  If the format has a `_422` or `_420` suffix, then `components.r` must be the identity swizzle or VK_COMPONENT_SWIZZLE_B

- VUID-VkSamplerYcbcrConversionCreateInfo-components-02584
  If the format has a `_422` or `_420` suffix, then `components.b` must be the identity swizzle or VK_COMPONENT_SWIZZLE_R

- VUID-VkSamplerYcbcrConversionCreateInfo-components-02585
  If the format has a `_422` or `_420` suffix, and if either `components.r` or `components.b` is the identity swizzle, both values must be the identity swizzle

- VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrModel-01655
  If `ycbcrModel` is not VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, then `components.r`, `components.g`, and `components.b` must correspond to components of the `format`; that is, `components.r`, `components.g`, and `components.b` must not be VK_COMPONENT_SWIZZLE_ZERO or VK_COMPONENT_SWIZZLE_ONE, and must not correspond to a component containing zero or one as a consequence of component substitution

- VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrRange-02748
  If `ycbcrRange` is VK_SAMPLER_YCBCR_RANGE_ITU_NARROW, then the R, G, and B components obtained by applying the `component` swizzle to `format` must each have a bit-depth greater than or equal to 8

- VUID-VkSamplerYcbcrConversionCreateInfo-forceExplicitReconstruction-01656
  If the potential format features of the sampler Y′CBCR conversion do not support VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT `forceExplicitReconstruction` must be VK_FALSE

- VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-01657
  If the potential format features of the sampler Y′CBCR conversion do not support VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, `chromaFilter` must not be VK_FILTER_LINEAR

- VUID-VkSamplerYcbcrConversionCreateInfo-pNext-09207
  If the `pNext` chain includes a VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM structure, and if the `ycbcrDegamma` feature is not enabled, then VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM::`enableYDegamma` must be VK_FALSE

- VUID-VkSamplerYcbcrConversionCreateInfo-pNext-09208
  If the `pNext` chain includes a VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM structure, and if the `ycbcrDegamma` feature is not enabled, then VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM::`enableCbCrDegamma` must be VK_FALSE

- VUID-VkSamplerYcbcrConversionCreateInfo-pNext-09209
  If the `pNext` chain includes a VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM structure, `format` must be a format with 8-bit R, G, and B components

Valid Usage (Implicit)

- VUID-VkSamplerYcbcrConversionCreateInfo-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO

- VUID-VkSamplerYcbcrConversionCreateInfo-pNext-pNext
  Each `pNext` member of any structure (including this one) in the `pNext` chain must be either `NULL` or a pointer to a valid instance of VkExternalFormatANDROID, VkExternalFormatOHOS, VkExternalFormatQNX, or VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM

- VUID-VkSamplerYcbcrConversionCreateInfo-sType-unique
  The `sType` value of each structure in the `pNext` chain must be unique

- VUID-VkSamplerYcbcrConversionCreateInfo-format-parameter
  `format` must be a valid VkFormat value

- VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrModel-parameter
  `ycbcrModel` must be a valid VkSamplerYcbcrModelConversion value

- VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrRange-parameter
  `ycbcrRange` must be a valid VkSamplerYcbcrRange value

- VUID-VkSamplerYcbcrConversionCreateInfo-components-parameter
  `components` must be a valid VkComponentMapping structure

- VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-parameter
  `xChromaOffset` must be a valid VkChromaLocation value

- VUID-VkSamplerYcbcrConversionCreateInfo-yChromaOffset-parameter
  `yChromaOffset` must be a valid VkChromaLocation value

- VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-parameter
  `chromaFilter` must be a valid VkFilter value

If `chromaFilter` is VK_FILTER_NEAREST, chroma samples are reconstructed to luma component resolution using nearest-neighbour sampling. Otherwise, chroma samples are reconstructed using interpolation. More details can be found in the description of sampler Y′CBCR conversion in the Image Operations chapter.

VkSamplerYcbcrModelConversion defines the conversion from the source color model to the shader color model. Possible values are:

    // Provided by VK_VERSION_1_1
    typedef enum VkSamplerYcbcrModelConversion {
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY = 0,
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY = 1,
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 = 2,
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 = 3,
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 = 4,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020,
    } VkSamplerYcbcrModelConversion;

    // Provided by VK_KHR_sampler_ycbcr_conversion
    // Equivalent to VkSamplerYcbcrModelConversion
    typedef VkSamplerYcbcrModelConversion VkSamplerYcbcrModelConversionKHR;

- VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY specifies that the input values to the conversion are unmodified.

- VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY specifies no model conversion but the inputs are range expanded as for Y′CBCR.

- VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709 specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.709 and described in the “BT.709 Y′CBCR conversion” section of the Khronos Data Format Specification.

- VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601 specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.601 and described in the “BT.601 Y′CBCR conversion” section of the Khronos Data Format Specification.

- VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020 specifies the color model conversion from Y′CBCR to R′G′B′ defined in BT.2020 and described in the “BT.2020 Y′CBCR conversion” section of the Khronos Data Format Specification.

In the `VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_*` color models, for the input to the sampler Y′CBCR range expansion and model conversion:

- the Y (Y′ luma) component corresponds to the G component of an RGB image.

- the CB (CB or “U” blue color difference) component corresponds to the B component of an RGB image.

- the CR (CR or “V” red color difference) component corresponds to the R component of an RGB image.

- the alpha component, if present, is not modified by color model conversion.

These rules reflect the mapping of components after the component swizzle operation (controlled by VkSamplerYcbcrConversionCreateInfo::`components`).

Note | For example, an “YUVA” 32-bit format comprising four 8-bit components can be implemented as VK_FORMAT_R8G8B8A8_UNORM with a component mapping: `components.a` = VK_COMPONENT_SWIZZLE_IDENTITY `components.r` = VK_COMPONENT_SWIZZLE_B `components.g` = VK_COMPONENT_SWIZZLE_R `components.b` = VK_COMPONENT_SWIZZLE_G

The VkSamplerYcbcrRange enum describes whether color components are encoded using the full range of numerical values or whether values are reserved for headroom and foot room. VkSamplerYcbcrRange is defined as:

    // Provided by VK_VERSION_1_1
    typedef enum VkSamplerYcbcrRange {
        VK_SAMPLER_YCBCR_RANGE_ITU_FULL = 0,
        VK_SAMPLER_YCBCR_RANGE_ITU_NARROW = 1,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_SAMPLER_YCBCR_RANGE_ITU_FULL_KHR = VK_SAMPLER_YCBCR_RANGE_ITU_FULL,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_SAMPLER_YCBCR_RANGE_ITU_NARROW_KHR = VK_SAMPLER_YCBCR_RANGE_ITU_NARROW,
    } VkSamplerYcbcrRange;

    // Provided by VK_KHR_sampler_ycbcr_conversion
    // Equivalent to VkSamplerYcbcrRange
    typedef VkSamplerYcbcrRange VkSamplerYcbcrRangeKHR;

- VK_SAMPLER_YCBCR_RANGE_ITU_FULL specifies that the full range of the encoded values are valid and interpreted according to the ITU “full range” quantization rules.

- VK_SAMPLER_YCBCR_RANGE_ITU_NARROW specifies that headroom and foot room are reserved in the numerical range of encoded values, and the remaining values are expanded according to the ITU “narrow range” quantization rules.

The formulae for these conversions is described in the Sampler Y′CBCR Range Expansion section of the Image Operations chapter.

No range modification takes place if `ycbcrModel` is VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY; the `ycbcrRange` field of VkSamplerYcbcrConversionCreateInfo is ignored in this case.

The VkChromaLocation enum defines the location of downsampled chroma component samples relative to the luma samples, and is defined as:

    // Provided by VK_VERSION_1_1
    typedef enum VkChromaLocation {
        VK_CHROMA_LOCATION_COSITED_EVEN = 0,
        VK_CHROMA_LOCATION_MIDPOINT = 1,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_CHROMA_LOCATION_COSITED_EVEN_KHR = VK_CHROMA_LOCATION_COSITED_EVEN,
      // Provided by VK_KHR_sampler_ycbcr_conversion
        VK_CHROMA_LOCATION_MIDPOINT_KHR = VK_CHROMA_LOCATION_MIDPOINT,
    } VkChromaLocation;

    // Provided by VK_KHR_sampler_ycbcr_conversion
    // Equivalent to VkChromaLocation
    typedef VkChromaLocation VkChromaLocationKHR;

- VK_CHROMA_LOCATION_COSITED_EVEN specifies that downsampled chroma samples are aligned with luma samples with even coordinates.

- VK_CHROMA_LOCATION_MIDPOINT specifies that downsampled chroma samples are located half way between each even luma sample and the nearest higher odd luma sample.

Applications can enable sRGB to linear conversion for the R, G, and B components of a Y′CBCR image during sampling by including `VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM` structure in the `pNext` chain of VkSamplerYcbcrConversionCreateInfo.

The `VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM` structure is defined as:

    // Provided by VK_QCOM_ycbcr_degamma
    typedef struct VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM {
        VkStructureType    sType;
        void*              pNext;
        VkBool32           enableYDegamma;
        VkBool32           enableCbCrDegamma;
    } VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `enableYDegamma` indicates sRGB to linear conversion is enabled for the G component.

- `enableCbCrDegamma` indicates sRGB to linear conversion is enabled for the R and B components.

Valid Usage (Implicit)

- VUID-VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_YCBCR_DEGAMMA_CREATE_INFO_QCOM

Structure Chaining

Extends the structure

  - VkSamplerYcbcrConversionCreateInfo

To destroy a sampler Y′CBCR conversion, call:

    // Provided by VK_VERSION_1_1
    void vkDestroySamplerYcbcrConversion(
        VkDevice                                    device,
        VkSamplerYcbcrConversion                    ycbcrConversion,
        const VkAllocationCallbacks*                pAllocator);

    // Provided by VK_KHR_sampler_ycbcr_conversion
    // Equivalent to vkDestroySamplerYcbcrConversion
    void vkDestroySamplerYcbcrConversionKHR(
        VkDevice                                    device,
        VkSamplerYcbcrConversion                    ycbcrConversion,
        const VkAllocationCallbacks*                pAllocator);

- `device` is the logical device that destroys the Y′CBCR conversion.

- `ycbcrConversion` is the conversion to destroy.

- `pAllocator` controls host memory allocation as described in the Memory Allocation chapter.

Valid Usage (Implicit)

- VUID-vkDestroySamplerYcbcrConversion-device-parameter
  `device` must be a valid VkDevice handle

- VUID-vkDestroySamplerYcbcrConversion-ycbcrConversion-parameter
  If `ycbcrConversion` is not VK_NULL_HANDLE, `ycbcrConversion` must be a valid VkSamplerYcbcrConversion handle

- VUID-vkDestroySamplerYcbcrConversion-pAllocator-parameter
  If `pAllocator` is not `NULL`, `pAllocator` must be a valid pointer to a valid VkAllocationCallbacks structure

- VUID-vkDestroySamplerYcbcrConversion-ycbcrConversion-parent
  If `ycbcrConversion` is a valid handle, it must have been created, allocated, or retrieved from `device`

Host Synchronization

- Host access to `ycbcrConversion` must be externally synchronized

### 14.2. Custom Border Colors

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;

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

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.

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 Interpretation of Numeric Format 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

If the sampler is created with VK_BORDER_COLOR_FLOAT_OPAQUE_BLACK, VK_BORDER_COLOR_INT_OPAQUE_BLACK, VK_BORDER_COLOR_FLOAT_CUSTOM_EXT, or VK_BORDER_COLOR_INT_CUSTOM_EXT `borderColor`, and that sampler will be combined with an image view that does not have an identity swizzle, and VkPhysicalDeviceBorderColorSwizzleFeaturesEXT::`borderColorSwizzleFromImage` is not enabled, then it is necessary to specify the component mapping of the border color, by including the `VkSamplerBorderColorComponentMappingCreateInfoEXT` structure in the VkSamplerCreateInfo::`pNext` chain, to get defined results.

The `VkSamplerBorderColorComponentMappingCreateInfoEXT` structure is defined as:

    // Provided by VK_EXT_border_color_swizzle
    typedef struct VkSamplerBorderColorComponentMappingCreateInfoEXT {
        VkStructureType       sType;
        const void*           pNext;
        VkComponentMapping    components;
        VkBool32              srgb;
    } VkSamplerBorderColorComponentMappingCreateInfoEXT;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `components` is a VkComponentMapping structure specifying a remapping of the border color components.

- `srgb` indicates that the sampler will be combined with an image view that has an image format which is sRGB encoded.

The VkComponentMapping `components` member describes a remapping from components of the border color to components of the vector returned by shader image instructions when the border color is used.

Valid Usage

- VUID-VkSamplerBorderColorComponentMappingCreateInfoEXT-borderColorSwizzle-06437
  The `borderColorSwizzle` feature must be enabled

Valid Usage (Implicit)

- VUID-VkSamplerBorderColorComponentMappingCreateInfoEXT-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_BORDER_COLOR_COMPONENT_MAPPING_CREATE_INFO_EXT

- VUID-VkSamplerBorderColorComponentMappingCreateInfoEXT-components-parameter
  `components` must be a valid VkComponentMapping structure

Structure Chaining

Extends the structure

  - VkSamplerCreateInfo

#### 14.2.1. Custom Border Color Registration

When using descriptor heaps, it is possible to create a sampler descriptor without creating a sampler object. Without this object, implementations using a fixed palette of border colors have no way to know which custom border colors are active or not.

In order to use custom border colors with descriptor heaps, border colors must instead be registered with the implementation and unregistered when they are no longer in use, and the registered index provided when writing the sampler descriptor.

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

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

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

Success

  - VK_SUCCESS

Failure

  - 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

To unregister a custom border color, call:

    // Provided by VK_EXT_custom_border_color with VK_EXT_descriptor_heap
    void vkUnregisterCustomBorderColorEXT(
        VkDevice                                    device,
        uint32_t                                    index);

- `device` is the logical device where the border color is registered.

- `index` is the `uint32_t` index value to unregister.

Valid Usage

- VUID-vkUnregisterCustomBorderColorEXT-index-11288
  `index` must be less than `maxCustomBorderColorSamplers`

Valid Usage (Implicit)

- VUID-vkUnregisterCustomBorderColorEXT-device-parameter
  `device` must be a valid VkDevice handle

The `VkSamplerCustomBorderColorIndexCreateInfoEXT` structure is defined as:

    // Provided by VK_EXT_custom_border_color with VK_EXT_descriptor_heap
    typedef struct VkSamplerCustomBorderColorIndexCreateInfoEXT {
        VkStructureType    sType;
        const void*        pNext;
        uint32_t           index;
    } VkSamplerCustomBorderColorIndexCreateInfoEXT;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `index` is the `uint32_t` index value to use with the sampler

If this structure is included in the `pNext` chain of VkSamplerCreateInfo, the value of `index` will be used for the custom border color registration. `index` does not need to be registered at the point that a sampler object is created or a sampler descriptor is written; as long as it is registered when any use of the sampler is recorded to a command, and remains registered while the sampler is in use. The color registered with the index and the color specified in the sampler must be identically defined.

If this structure is not provided when creating a sampler object with a custom border color, it is equivalent to registering a new custom border color by calling vkRegisterCustomBorderColorEXT with that custom border color value, and using that value as `index` in this structure. This implicit registration will be implicitly unregistered when the sampler is destroyed.

If this structure is not provided when creating a sampler object without a custom border color, it is equivalent to setting `index` to 0.

Valid Usage

- VUID-VkSamplerCustomBorderColorIndexCreateInfoEXT-index-11289
  `index` must be less than `maxCustomBorderColorSamplers`

Valid Usage (Implicit)

- VUID-VkSamplerCustomBorderColorIndexCreateInfoEXT-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_CUSTOM_BORDER_COLOR_INDEX_CREATE_INFO_EXT

Structure Chaining

Extends the structure

  - VkSamplerCreateInfo

### 14.3. Sampler block matching

The `VkSamplerBlockMatchWindowCreateInfoQCOM` structure is defined as:

    // Provided by VK_QCOM_image_processing2
    typedef struct VkSamplerBlockMatchWindowCreateInfoQCOM {
        VkStructureType                      sType;
        const void*                          pNext;
        VkExtent2D                           windowExtent;
        VkBlockMatchWindowCompareModeQCOM    windowCompareMode;
    } VkSamplerBlockMatchWindowCreateInfoQCOM;

- `sType` is a VkStructureType value identifying this structure.

- `pNext` is `NULL` or a pointer to a structure extending this structure.

- `windowExtent` is a VkExtent2D specifying a the width and height of the block match window.

- `windowCompareMode` is a VkBlockMatchWindowCompareModeQCOM specifying the compare mode.

Valid Usage

- VUID-VkSamplerBlockMatchWindowCreateInfoQCOM-WindowExtent-09210
  `WindowExtent` must not be larger than VkPhysicalDeviceImageProcessing2PropertiesQCOM::`maxBlockMatchWindow`

Valid Usage (Implicit)

- VUID-VkSamplerBlockMatchWindowCreateInfoQCOM-sType-sType
  `sType` must be VK_STRUCTURE_TYPE_SAMPLER_BLOCK_MATCH_WINDOW_CREATE_INFO_QCOM

- VUID-VkSamplerBlockMatchWindowCreateInfoQCOM-windowCompareMode-parameter
  `windowCompareMode` must be a valid VkBlockMatchWindowCompareModeQCOM value

Structure Chaining

Extends the structure

  - VkSamplerCreateInfo

The VkBlockMatchWindowCompareModeQCOM enum describes how block match values within the window are compared. VkBlockMatchWindowCompareModeQCOM is defined as:

    // Provided by VK_QCOM_image_processing2
    typedef enum VkBlockMatchWindowCompareModeQCOM {
        VK_BLOCK_MATCH_WINDOW_COMPARE_MODE_MIN_QCOM = 0,
        VK_BLOCK_MATCH_WINDOW_COMPARE_MODE_MAX_QCOM = 1,
    } VkBlockMatchWindowCompareModeQCOM;

- VK_BLOCK_MATCH_WINDOW_COMPARE_MODE_MIN_QCOM specifies that windowed block match operations return the minimum error within the window.

- VK_BLOCK_MATCH_WINDOW_COMPARE_MODE_MAX_QCOM specifies that windowed block match operations return the maximum error within the window.