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

VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSampler)

To create a sampler object, call:

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 an instance of the VkSamplerCreateInfo structure specifying the state of the sampler object.

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

  • pSampler points to a VkSampler handle in which the resulting sampler object is returned.

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • pCreateInfo must be a valid pointer to a valid VkSamplerCreateInfo structure

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

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

The VkSamplerCreateInfo structure is defined as:

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 an extension-specific 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 outside [0..1] range for U coordinate.

  • addressModeV is a VkSamplerAddressMode value specifying the addressing mode for outside [0..1] range for V coordinate.

  • addressModeW is a VkSamplerAddressMode value specifying the addressing mode for outside [0..1] range for W coordinate.

  • 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 function to apply to fetched data before filtering as described in the Depth Compare Operation section.

  • minLod and maxLod are the values used to clamp the computed LOD value, as described in the Level-of-Detail Operation section.

  • 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 dimensions for x, y and z. 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. If maxSamplerAllocationCount is exceeded, vkCreateSampler will return VK_ERROR_TOO_MANY_OBJECTS.

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

  • The absolute value of mipLodBias must be less than or equal to VkPhysicalDeviceLimits::maxSamplerLodBias

  • maxLod must be greater than or equal to minLod

  • If the anisotropic sampling feature is not enabled, anisotropyEnable must be VK_FALSE

  • If anisotropyEnable is VK_TRUE, maxAnisotropy must be between 1.0 and VkPhysicalDeviceLimits::maxSamplerAnisotropy, inclusive

  • If sampler Y’CBCR conversion is enabled and VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT is not set for the format, minFilter and magFilter must be equal to the sampler Y’CBCR conversion’s chromaFilter

  • If unnormalizedCoordinates is VK_TRUE, minFilter and magFilter must be equal

  • If unnormalizedCoordinates is VK_TRUE, mipmapMode must be VK_SAMPLER_MIPMAP_MODE_NEAREST

  • If unnormalizedCoordinates is VK_TRUE, minLod and maxLod must be zero

  • 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

  • If unnormalizedCoordinates is VK_TRUE, anisotropyEnable must be VK_FALSE

  • If unnormalizedCoordinates is VK_TRUE, compareEnable must be VK_FALSE

  • If any of addressModeU, addressModeV or addressModeW are VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_BORDER, borderColor must be a valid VkBorderColor value

  • 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

  • The sampler reduction mode must be set to VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT if sampler Y’CBCR conversion is enabled

  • 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

  • If compareEnable is VK_TRUE, compareOp must be a valid VkCompareOp value

  • If either magFilter or minFilter is VK_FILTER_CUBIC_EXT, anisotropyEnable must be VK_FALSE

  • If compareEnable is VK_TRUE, the reductionMode member of VkSamplerReductionModeCreateInfoEXT must be VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT

  • If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then minFilter and magFilter must be equal.

  • If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then mipmapMode must be VK_SAMPLER_MIPMAP_MODE_NEAREST.

  • If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then minLod and maxLod must be zero.

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

  • If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then anisotropyEnable must be VK_FALSE.

  • If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then compareEnable must be VK_FALSE.

  • If flags includes VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT, then unnormalizedCoordinates must be VK_FALSE.

Valid Usage (Implicit)

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

typedef enum VkSamplerCreateFlagBits {
    VK_SAMPLER_CREATE_SUBSAMPLED_BIT_EXT = 0x00000001,
    VK_SAMPLER_CREATE_SUBSAMPLED_COARSE_RECONSTRUCTION_BIT_EXT = 0x00000002,
    VK_SAMPLER_CREATE_FLAG_BITS_MAX_ENUM = 0x7FFFFFFF
} 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.

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.

 
typedef VkFlags VkSamplerCreateFlags;

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

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

The VkSamplerReductionModeCreateInfoEXT structure is defined as:

typedef struct VkSamplerReductionModeCreateInfoEXT {
    VkStructureType              sType;
    const void*                  pNext;
    VkSamplerReductionModeEXT    reductionMode;
} VkSamplerReductionModeCreateInfoEXT;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to an extension-specific structure.

  • reductionMode is an enum of type VkSamplerReductionModeEXT that controls how texture filtering combines texel values.

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

Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SAMPLER_REDUCTION_MODE_CREATE_INFO_EXT

  • reductionMode must be a valid VkSamplerReductionModeEXT value

Reduction modes are specified by VkSamplerReductionModeEXT, which takes values:

typedef enum VkSamplerReductionModeEXT {
    VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT = 0,
    VK_SAMPLER_REDUCTION_MODE_MIN_EXT = 1,
    VK_SAMPLER_REDUCTION_MODE_MAX_EXT = 2,
    VK_SAMPLER_REDUCTION_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} VkSamplerReductionModeEXT;

  • VK_SAMPLER_REDUCTION_MODE_WEIGHTED_AVERAGE_EXT 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_EXT 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_EXT 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:

typedef enum VkFilter {
    VK_FILTER_NEAREST = 0,
    VK_FILTER_LINEAR = 1,
    VK_FILTER_CUBIC_IMG = 1000015000,
    VK_FILTER_CUBIC_EXT = VK_FILTER_CUBIC_IMG,
    VK_FILTER_MAX_ENUM = 0x7FFFFFFF
} 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:

typedef enum VkSamplerMipmapMode {
    VK_SAMPLER_MIPMAP_MODE_NEAREST = 0,
    VK_SAMPLER_MIPMAP_MODE_LINEAR = 1,
    VK_SAMPLER_MIPMAP_MODE_MAX_ENUM = 0x7FFFFFFF
} 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:

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,
    VK_SAMPLER_ADDRESS_MODE_MIRROR_CLAMP_TO_EDGE = 4,
    VK_SAMPLER_ADDRESS_MODE_MAX_ENUM = 0x7FFFFFFF
} 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 VK_KHR_sampler_mirror_clamp_to_edge extension is enabled.

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

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,
    VK_BORDER_COLOR_MAX_ENUM = 0x7FFFFFFF
} 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.

These colors are described in detail in Texel Replacement.

To destroy a sampler, call:

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

  • All submitted commands that refer to sampler must have completed execution

  • If VkAllocationCallbacks were provided when sampler was created, a compatible set of callbacks must be provided here

  • If no VkAllocationCallbacks were provided when sampler was created, pAllocator must be NULL

Valid Usage (Implicit)

  • device must be a valid VkDevice handle

  • If sampler is not VK_NULL_HANDLE, sampler must be a valid VkSampler handle

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • 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

12.1. Sampler Y’CBCR conversion

To create a sampler with Y’CBCR conversion enabled, add a VkSamplerYcbcrConversionInfo 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 appears in Formats requiring sampler Y’CBCR conversion for VK_IMAGE_ASPECT_COLOR_BIT image views , or if the image view has an external format .

The VkSamplerYcbcrConversionInfo structure is defined as:

typedef struct VkSamplerYcbcrConversionInfo {
    VkStructureType             sType;
    const void*                 pNext;
    VkSamplerYcbcrConversion    conversion;
} VkSamplerYcbcrConversionInfo;

or the equivalent

typedef VkSamplerYcbcrConversionInfo VkSamplerYcbcrConversionInfoKHR;
Valid Usage (Implicit)

  • sType must be VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO

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

VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSamplerYcbcrConversion)

or the equivalent

typedef VkSamplerYcbcrConversion VkSamplerYcbcrConversionKHR;

To create a VkSamplerYcbcrConversion, call:

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

or the equivalent command

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 an instance of the VkSamplerYcbcrConversionCreateInfo specifying the requested sampler Y’CBCR conversion.

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

  • pYcbcrConversion points 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)

  • device must be a valid VkDevice handle

  • pCreateInfo must be a valid pointer to a valid VkSamplerYcbcrConversionCreateInfo structure

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

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

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

typedef VkSamplerYcbcrConversionCreateInfo VkSamplerYcbcrConversionCreateInfoKHR;

  • sType is the type of this structure.

  • pNext is NULL or a pointer to an extension-specific 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 channels in the x dimension. xChromaOffset has no effect for formats in which chroma channels are the same resolution as the luma channel.

  • yChromaOffset describes the sample location associated with downsampled chroma channels in the y dimension. yChromaOffset has no effect for formats in which the chroma channels 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 the pNext chain has an instance of VkExternalFormatANDROID 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

  • If an external format conversion is being created, format must be VK_FORMAT_UNDEFINED, otherwise it must not be VK_FORMAT_UNDEFINED.

  • format must support VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT or VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT

  • If the format does not support VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT, xChromaOffset and yChromaOffset must not be VK_CHROMA_LOCATION_COSITED_EVEN

  • If the format does not support VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT, xChromaOffset and yChromaOffset must not be VK_CHROMA_LOCATION_MIDPOINT

  • format must represent unsigned normalized values (i.e. the format must be a UNORM format)

  • If the format has a _422 or _420 suffix, then components.g must be VK_COMPONENT_SWIZZLE_IDENTITY

  • If the format has a _422 or _420 suffix, then components.a must be VK_COMPONENT_SWIZZLE_IDENTITY, VK_COMPONENT_SWIZZLE_ONE, or VK_COMPONENT_SWIZZLE_ZERO

  • If the format has a _422 or _420 suffix, then components.r must be VK_COMPONENT_SWIZZLE_IDENTITY or VK_COMPONENT_SWIZZLE_B

  • If the format has a _422 or _420 suffix, then components.b must be VK_COMPONENT_SWIZZLE_IDENTITY or VK_COMPONENT_SWIZZLE_R

  • If the format has a _422 or _420 suffix, and if either components.r or components.b is VK_COMPONENT_SWIZZLE_IDENTITY, both values must be VK_COMPONENT_SWIZZLE_IDENTITY

  • If ycbcrModel is not VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY, then components.r, components.g, and components.b must correspond to channels 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 channel which contains zero or one as a consequence of conversion to RGBA

  • If ycbcrRange is VK_SAMPLER_YCBCR_RANGE_ITU_NARROW then the R, G and B channels obtained by applying the component swizzle to format must each have a bit-depth greater than or equal to 8.

  • If the format does not support VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT, forceExplicitReconstruction must be FALSE

  • If the format does not support VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT, chromaFilter must be VK_FILTER_NEAREST

Valid Usage (Implicit)

If chromaFilter is VK_FILTER_NEAREST, chroma samples are reconstructed to luma channel 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:

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,
    VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_RGB_IDENTITY,
    VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_IDENTITY,
    VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_709,
    VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_601,
    VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020_KHR = VK_SAMPLER_YCBCR_MODEL_CONVERSION_YCBCR_2020,
    VK_SAMPLER_YCBCR_MODEL_CONVERSION_MAX_ENUM = 0x7FFFFFFF
} VkSamplerYcbcrModelConversion;

or the equivalent

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) channel corresponds to the G channel of an RGB image.

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

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

  • the alpha channel, if present, is not modified by color model conversion.

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

Note

For example, an “YUVA” 32-bit format comprising four 8-bit channels 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 channels are encoded using the full range of numerical values or whether values are reserved for headroom and foot room. VkSamplerYcbcrRange is defined as:

typedef enum VkSamplerYcbcrRange {
    VK_SAMPLER_YCBCR_RANGE_ITU_FULL = 0,
    VK_SAMPLER_YCBCR_RANGE_ITU_NARROW = 1,
    VK_SAMPLER_YCBCR_RANGE_ITU_FULL_KHR = VK_SAMPLER_YCBCR_RANGE_ITU_FULL,
    VK_SAMPLER_YCBCR_RANGE_ITU_NARROW_KHR = VK_SAMPLER_YCBCR_RANGE_ITU_NARROW,
    VK_SAMPLER_YCBCR_RANGE_MAX_ENUM = 0x7FFFFFFF
} VkSamplerYcbcrRange;

or the equivalent

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, which defines the location of downsampled chroma channel samples relative to the luma samples, is defined as:

typedef enum VkChromaLocation {
    VK_CHROMA_LOCATION_COSITED_EVEN = 0,
    VK_CHROMA_LOCATION_MIDPOINT = 1,
    VK_CHROMA_LOCATION_COSITED_EVEN_KHR = VK_CHROMA_LOCATION_COSITED_EVEN,
    VK_CHROMA_LOCATION_MIDPOINT_KHR = VK_CHROMA_LOCATION_MIDPOINT,
    VK_CHROMA_LOCATION_MAX_ENUM = 0x7FFFFFFF
} VkChromaLocation;

or the equivalent

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:

void vkDestroySamplerYcbcrConversion(
    VkDevice                                    device,
    VkSamplerYcbcrConversion                    ycbcrConversion,
    const VkAllocationCallbacks*                pAllocator);

or the equivalent command

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)

  • device must be a valid VkDevice handle

  • If ycbcrConversion is not VK_NULL_HANDLE, ycbcrConversion must be a valid VkSamplerYcbcrConversion handle

  • If pAllocator is not NULL, pAllocator must be a valid pointer to a valid VkAllocationCallbacks structure

  • 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