C Specification

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;

Members

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

Description

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

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

See Also

VK_VERSION_1_1, VkBool32, VkChromaLocation, VkComponentMapping, VkFilter, VkFormat, VkSamplerYcbcrModelConversion, VkSamplerYcbcrRange, VkStructureType, vkCreateSamplerYcbcrConversion, vkCreateSamplerYcbcrConversionKHR

Document Notes

For more information, see the Vulkan Specification

This page is extracted from the Vulkan Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2023 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0