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

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

  • VK_ERROR_INVALID_OPAQUE_CAPTURE_ADDRESS_KHR

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

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.

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

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 OpImageWeightedSampleQCOM, OpImageBoxFilterQCOM, OpImageBlockMatchGatherSSDQCOM, OpImageBlockMatchGatherSADQCOM, OpImageBlockMatchWindowSSDQCOM, OpImageBlockMatchWindowSADQCOM, OpImageBlockMatchSSDQCOM, or OpImageBlockMatchSADQCOM.

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;

or the equivalent

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

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;

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.

  • 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

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, 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 is a deprecated 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:

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

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

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

  • 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, VkExternalFormatQNX, or VkSamplerYcbcrConversionYcbcrDegammaCreateInfoQCOM

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

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.

Applications can enable sRGB to linear conversion for the R, G, and B components of a Y′CBCR image during format conversion 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

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 a VkStructureType value identifying this structure.

  • pNext is NULL or a pointer to a structure extending this structure.

  • customBorderColor is a VkClearColorValue representing the desired custom sampler border color.

  • format is a VkFormat representing the format of the sampled image view(s). This field may be VK_FORMAT_UNDEFINED if the customBorderColorWithoutFormat feature is enabled.

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

If format is VK_FORMAT_UNDEFINED, the VkSamplerCreateInfo::borderColor is VK_BORDER_COLOR_INT_CUSTOM_EXT, and the sampler is used with an image with a stencil format, then the implementation must source the custom border color from either the first or second components of VkSamplerCreateInfo::customBorderColor 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

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

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

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.