VkSamplerYcbcrConversionCreateInfo(3)

# VkSamplerYcbcrConversionCreateInfo(3) Manual Page

## Name

VkSamplerYcbcrConversionCreateInfo - Structure specifying the parameters of the newly created conversion

## C Specification

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;

## Members

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

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

- `sType` must be `VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO`

- `pNext` must be `NULL` or a pointer to a valid instance of VkExternalFormatANDROID

- `format` must be a valid VkFormat value

- `ycbcrModel` must be a valid VkSamplerYcbcrModelConversion value

- `ycbcrRange` must be a valid VkSamplerYcbcrRange value

- `components` must be a valid `VkComponentMapping` structure

- `xChromaOffset` must be a valid VkChromaLocation value

- `yChromaOffset` must be a valid VkChromaLocation value

- `chromaFilter` must be a valid VkFilter value

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.

## See Also

`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 (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.