Author: The Khronos® Vulkan Working Group

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

The Khronos® Vulkan Working Group
version 1.3.217, 2022-06-14 16:15:01Z
from git branch: Git branch not available commit: Git commit not available

Loading… please wait.

Search:

## 13. 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-maxSamplerAllocationCount-04110
  There must be less than VkPhysicalDeviceLimits::`maxSamplerAllocationCount` 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_OUT_OF_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

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 the type of 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 addressing mode for U coordinates outside [0,1).

- `addressModeV` is a VkSamplerAddressMode value specifying the addressing mode for V coordinates outside [0,1).

- `addressModeW` is a VkSamplerAddressMode value specifying the addressing mode for W coordinates outside [0,1).

- `mipLodBias` is the bias to be added to mipmap LOD (level-of-detail) calculation and bias provided by image sampling functions in SPIR-V, as described in the Level-of-Detail 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 set to `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 set to `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.

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

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 anisotropic sampling 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 set to `VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE`

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

- VUID-VkSamplerCreateInfo-addressModeU-01079
  If samplerMirrorClampToEdge 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-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

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 VkSamplerBorderColorComponentMappingCreateInfoEXT, VkSamplerCustomBorderColorCreateInfoEXT, VkSamplerReductionModeCreateInfo, or VkSamplerYcbcrConversionInfo

- VUID-VkSamplerCreateInfo-sType-unique
  The `sType` value of each struct 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_non_seamless_cube_map
        VK_SAMPLER_CREATE_NON_SEAMLESS_CUBE_MAP_BIT_EXT = 0x00000004,
    } 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.

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

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

or the equivalent

    // Provided by VK_EXT_sampler_filter_minmax
    typedef VkSamplerReductionModeCreateInfo VkSamplerReductionModeCreateInfoEXT;

- `sType` is the type of 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

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

or the equivalent

    // Provided by VK_EXT_sampler_filter_minmax
    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.

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_IMG_filter_cubic
        VK_FILTER_CUBIC_IMG = 1000015000,
      // Provided by VK_EXT_filter_cubic
        VK_FILTER_CUBIC_EXT = VK_FILTER_CUBIC_IMG,
    } 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, specifying the behavior of sampling with coordinates outside the range [0,1] for the respective u, v, or w coordinate as defined in the Wrapping Operation section, 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 = 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 samplerMirrorClampToEdge 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` indicates 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` indicates 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 Texel 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

### 13.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 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;

or the equivalent

    // Provided by VK_KHR_sampler_ycbcr_conversion
    typedef VkSamplerYcbcrConversionInfo VkSamplerYcbcrConversionInfoKHR;

- `sType` is the type of 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

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)

or the equivalent

    // Provided by VK_KHR_sampler_ycbcr_conversion
    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);

or the equivalent command

    // Provided by VK_KHR_sampler_ycbcr_conversion
    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 sampler Y′CBCR conversion 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_HOST_MEMORY`

  - `VK_ERROR_OUT_OF_DEVICE_MEMORY`

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;

or the equivalent

    // Provided by VK_KHR_sampler_ycbcr_conversion
    typedef VkSamplerYcbcrConversionCreateInfo VkSamplerYcbcrConversionCreateInfoKHR;

- `sType` is the type of 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 was set to `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 conversion to RGBA

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

Valid Usage (Implicit)

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

- VUID-VkSamplerYcbcrConversionCreateInfo-pNext-pNext
  `pNext` must be `NULL` or a pointer to a valid instance of VkExternalFormatANDROID

- VUID-VkSamplerYcbcrConversionCreateInfo-sType-unique
  The `sType` value of each struct 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;

or the equivalent

    // Provided by VK_KHR_sampler_ycbcr_conversion
    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;

or the equivalent

    // Provided by VK_KHR_sampler_ycbcr_conversion
    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;

or the equivalent

    // Provided by VK_KHR_sampler_ycbcr_conversion
    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.

To destroy a sampler Y′CBCR conversion, call:

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

or the equivalent command

    // Provided by VK_KHR_sampler_ycbcr_conversion
    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

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 the type of 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.

Valid Usage

- VUID-VkSamplerCustomBorderColorCreateInfoEXT-format-04013
  If provided `format` is not `VK_FORMAT_UNDEFINED` then the VkSamplerCreateInfo::`borderColor` type must match the sampled type of the provided `format`, as shown in the SPIR-V Sampled 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`, 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

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 the type of 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