VulkanHub
Structures

VkSamplerYcbcrConversionCreateInfo

Structure specifying the parameters of the newly created conversion

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 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 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::enableYDegammamust 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::enableCbCrDegammamust 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.