VkSamplerYcbcrConversionCreateInfo(3)

# VkSamplerYcbcrConversionCreateInfo(3) Manual Page

## Name

VkSamplerYcbcrConversionCreateInfo - Structure specifying the parameters of the newly created conversion

Loading… please wait.

## 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-2024 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0