Vulkan-Docs/doc/specs/vulkan/appendices/VK_KHR_sampler_ycbcr_conver...

// Copyright (c) 2017 Khronos Group. This work is licensed under a
// Creative Commons Attribution 4.0 International License; see
// http://creativecommons.org/licenses/by/4.0/

include::meta/VK_KHR_sampler_ycbcr_conversion.txt[]

*Last Modified Date*::
    2017-08-11
*IP Status*::
    No known IP claims.
*Interactions and External Dependencies*::
  - This extension interacts with +VK_EXT_debug_report+
*Contributors*::
  - Andrew Garrard, Samsung Electronics
  - Tobias Hector, Imagination Technologies
  - James Jones, NVIDIA
  - Daniel Koch, NVIDIA
  - Daniel Rakos, AMD
  - Romain Guy, Google
  - Jesse Hall, Google
  - Tom Cooksey, ARM Ltd
  - Jeff Leger, Qualcomm Technologies, Inc
  - Jan-Harald Fredriksen, ARM Ltd
  - Jan Outters, Samsung Electronics
  - Alon Or-bach, Samsung Electronics
  - Michael Worcester, Imagination Technologies
  - Jeff Bolz, NVIDIA
  - Tony Zlatinski, NVIDIA
  - Matthew Netsch, Qualcomm Technologies, Inc

This extension provides the ability to perform specified color space
conversions during texture sampling operations.
It also adds a selection of multi-planar formats, including the ability to
bind memory to the planes of an image collectively or separately.

=== New Enum Constants

  * Extending elink:VkStructureType:
  ** ename:VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO_KHR
  ** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES_KHR
  * Extending elink:VkFormat:
  ** ename:VK_FORMAT_G8B8G8R8_422_UNORM_KHR
  ** ename:VK_FORMAT_B8G8R8G8_422_UNORM_KHR
  ** ename:VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM_KHR
  ** ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM_KHR
  ** ename:VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM_KHR
  ** ename:VK_FORMAT_G8_B8R8_2PLANE_422_UNORM_KHR
  ** ename:VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM_KHR
  ** ename:VK_FORMAT_R10X6_UNORM_PACK16_KHR
  ** ename:VK_FORMAT_R10X6G10X6_UNORM_2PACK16_KHR
  ** ename:VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16_KHR
  ** ename:VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16_KHR
  ** ename:VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16_KHR
  ** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_R12X4_UNORM_PACK16_KHR
  ** ename:VK_FORMAT_R12X4G12X4_UNORM_2PACK16_KHR
  ** ename:VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16_KHR
  ** ename:VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16_KHR
  ** ename:VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16_KHR
  ** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16_KHR
  ** ename:VK_FORMAT_G16B16G16R16_422_UNORM_KHR
  ** ename:VK_FORMAT_B16G16R16G16_422_UNORM_KHR
  ** ename:VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM_KHR
  ** ename:VK_FORMAT_G16_B16R16_2PLANE_420_UNORM_KHR
  ** ename:VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM_KHR
  ** ename:VK_FORMAT_G16_B16R16_2PLANE_422_UNORM_KHR
  ** ename:VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM_KHR
  * Extending elink:VkImageAspectFlagBits:
  ** ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR
  ** ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR
  ** ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR
  * Extending elink:VkImageCreateFlagBits:
  ** ename:VK_IMAGE_CREATE_DISJOINT_BIT_KHR
  * Extending elink:VkFormatFeatureFlagBits:
  ** ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR
  ** ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR
  ** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR
  ** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR
  ** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR
  ** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR
  ** ename:VK_FORMAT_FEATURE_DISJOINT_BIT_KHR

=== New Enums

  * elink:VkSamplerYcbcrModelConversionKHR
  * elink:VkSamplerYcbcrRangeKHR
  * elink:VkChromaLocationKHR

=== New Structures

  * slink:VkSamplerYcbcrConversionInfoKHR
  * slink:VkSamplerYcbcrConversionCreateInfoKHR
  * slink:VkBindImagePlaneMemoryInfoKHR
  * slink:VkImagePlaneMemoryRequirementsInfoKHR
  * slink:VkPhysicalDeviceSamplerYcbcrConversionFeaturesKHR
  * slink:VkSamplerYcbcrConversionImageFormatPropertiesKHR

=== New Functions

  * flink:vkCreateSamplerYcbcrConversionKHR
  * flink:vkDestroySamplerYcbcrConversionKHR

=== New Objects

  * slink:VkSamplerYcbcrConversionKHR

=== Issues

=== Version History

 * Revision 1, 2017-01-24 (Andrew Garrard)
   - Initial draft
 * Revision 2, 2017-01-25 (Andrew Garrard)
   - After initial feedback
 * Revision 3, 2017-01-27 (Andrew Garrard)
   - Higher bit depth formats, renaming, swizzle
 * Revision 4, 2017-02-22 (Andrew Garrard)
   - Added query function, formats as RGB, clarifications
 * Revision 5, 2017-04 (Andrew Garrard)
   - Simplified query and removed output conversions
 * Version 6, 2017-4-24 (Andrew Garrard)
   - Tidying, incorporated new image query, restored transfer functions
 * Version 7, 2017-04-25 (Andrew Garrard)
   - Added cosited option/midpoint requirement for formats,
     "bypassConversion"
 * Version 8, 2017-04-25 (Andrew Garrard)
   - Simplified further
 * Version 9, 2017-04-27 (Andrew Garrard)
   - Disjoint no more
 * Version 10, 2017-04-28 (Andrew Garrard)
   - Restored disjoint
 * Version 11, 2017-04-29 (Andrew Garrard)
   - Now Ycbcr conversion, and KHR
 * Version 12, 2017-06-06 (Andrew Garrard)
   - Added conversion to image view creation
 * Version 13, 2017-07-13 (Andrew Garrard)
   - Allowed cosited-only chroma samples for formats
 * Version 14, 2017-08-11 (Andrew Garrard)
   - Reflected quantization changes in BT.2100-1
Change log for September 15, 2017 Vulkan 1.0.61 spec update: * Bump API patch number and header version number to 61 for this update. Github Issues: * Provide alternate length attributes (altlen=) in the XML schema, for those using length attributes to generate code instead of documentation (public issue 555). * Fix erroneous references to `latex:` being used for asciidoc math markup, rather than `latexmath:` (public pull request 556). * Add author ID to XML for Kazan software renderer (public pull request 557). Internal Issues: * Add the <<fundamentals-abi,Application Binary Interface>> section describing platform ABI requirements and recommendations, add examples of function and function pointer declarations to the <<boilerplate-platform-specific-calling-conventions, Platform-Specific Calling Conventions>> section, and remove related language that existed elsewhere in the specification (internal issue 64). * Describe where to document valid usage interactions of chained structures in the style guide, and fix one case now appearing in slink:VkBufferCreateInfo instead of the child slink:VkDedicatedAllocationBufferCreateInfoNV structure (internal issue 715). * Add example to the style guide of describing enumerated types which are empty when the spec is built without relevant extensions enabled, and apply it to existing examples for elink:VkDescriptorSetLayoutCreateFlagBits and elink:VkSubpassDescriptionFlagBits (internal issue 864). * Add a note to the <<fundamentals-validusage-enums, Valid Usage for Enumerated Types>> section that the special values suffixed with etext:_BEGIN_RANGE, etext:_END_RANGE, etext:_RANGE_SIZE and etext:_MAX_ENUM are not part of the API and should: not be used by applications (internal issue 872). * Added note to flink:vkCmdUpdateBuffers explaining the performance penalty for copies done in this way, and why the upper copy limit is what it is (internal issue 952). * Update `VK_KHX_device_group` to split some functionality into the new `VK_KHR_bind_memory2` extension, and rename that functionality (internal issue 969). * Remove Status fields from extension appendices, since they are by definition published and complete by the time they reach the public github repository (internal issue 973). Other Issues: * Update Data Format specification dependency to version 1.2 and change references to DF sections accordingly. * Update XML to make the pname:pAllocator parameter of flink:vkRegisterDeviceEventEXT and flink:vkRegisterDisplayEventEXT in the `VK_EXT_display_control` extension as optional. New Extensions: * `VK_KHR_bind_memory2` * `VK_KHR_image_format_list` * `VK_KHR_maintenance2` * `VK_KHR_sampler_ycbcr_conversion` 2017-09-15 05:41:33 +00:00			`// Copyright (c) 2017 Khronos Group. This work is licensed under a`
			`// Creative Commons Attribution 4.0 International License; see`
			`// http://creativecommons.org/licenses/by/4.0/`

			`include::meta/VK_KHR_sampler_ycbcr_conversion.txt[]`

			`Last Modified Date::`
			`2017-08-11`
			`IP Status::`
			`No known IP claims.`
			`Interactions and External Dependencies::`
			`- This extension interacts with +VK_EXT_debug_report+`
			`Contributors::`
			`- Andrew Garrard, Samsung Electronics`
			`- Tobias Hector, Imagination Technologies`
			`- James Jones, NVIDIA`
			`- Daniel Koch, NVIDIA`
			`- Daniel Rakos, AMD`
			`- Romain Guy, Google`
			`- Jesse Hall, Google`
			`- Tom Cooksey, ARM Ltd`
			`- Jeff Leger, Qualcomm Technologies, Inc`
			`- Jan-Harald Fredriksen, ARM Ltd`
			`- Jan Outters, Samsung Electronics`
			`- Alon Or-bach, Samsung Electronics`
			`- Michael Worcester, Imagination Technologies`
			`- Jeff Bolz, NVIDIA`
			`- Tony Zlatinski, NVIDIA`
			`- Matthew Netsch, Qualcomm Technologies, Inc`

			`This extension provides the ability to perform specified color space`
			`conversions during texture sampling operations.`
			`It also adds a selection of multi-planar formats, including the ability to`
			`bind memory to the planes of an image collectively or separately.`

			`=== New Enum Constants`

			`* Extending elink:VkStructureType:`
			`** ename:VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_CREATE_INFO_KHR`
			`** ename:VK_STRUCTURE_TYPE_SAMPLER_YCBCR_CONVERSION_INFO_KHR`
			`** ename:VK_STRUCTURE_TYPE_BIND_IMAGE_PLANE_MEMORY_INFO_KHR`
			`** ename:VK_STRUCTURE_TYPE_IMAGE_PLANE_MEMORY_REQUIREMENTS_INFO_KHR`
			`** ename:VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SAMPLER_YCBCR_CONVERSION_FEATURES_KHR`
			`* Extending elink:VkFormat:`
			`** ename:VK_FORMAT_G8B8G8R8_422_UNORM_KHR`
			`** ename:VK_FORMAT_B8G8R8G8_422_UNORM_KHR`
			`** ename:VK_FORMAT_G8_B8_R8_3PLANE_420_UNORM_KHR`
			`** ename:VK_FORMAT_G8_B8R8_2PLANE_420_UNORM_KHR`
			`** ename:VK_FORMAT_G8_B8_R8_3PLANE_422_UNORM_KHR`
			`** ename:VK_FORMAT_G8_B8R8_2PLANE_422_UNORM_KHR`
			`** ename:VK_FORMAT_G8_B8_R8_3PLANE_444_UNORM_KHR`
			`** ename:VK_FORMAT_R10X6_UNORM_PACK16_KHR`
			`** ename:VK_FORMAT_R10X6G10X6_UNORM_2PACK16_KHR`
			`** ename:VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16_KHR`
			`** ename:VK_FORMAT_G10X6B10X6G10X6R10X6_422_UNORM_4PACK16_KHR`
			`** ename:VK_FORMAT_B10X6G10X6R10X6G10X6_422_UNORM_4PACK16_KHR`
			`** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_420_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G10X6_B10X6R10X6_2PLANE_420_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_422_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G10X6_B10X6R10X6_2PLANE_422_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G10X6_B10X6_R10X6_3PLANE_444_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_R12X4_UNORM_PACK16_KHR`
			`** ename:VK_FORMAT_R12X4G12X4_UNORM_2PACK16_KHR`
			`** ename:VK_FORMAT_R12X4G12X4B12X4A12X4_UNORM_4PACK16_KHR`
			`** ename:VK_FORMAT_G12X4B12X4G12X4R12X4_422_UNORM_4PACK16_KHR`
			`** ename:VK_FORMAT_B12X4G12X4R12X4G12X4_422_UNORM_4PACK16_KHR`
			`** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_420_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G12X4_B12X4R12X4_2PLANE_420_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_422_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G12X4_B12X4R12X4_2PLANE_422_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G12X4_B12X4_R12X4_3PLANE_444_UNORM_3PACK16_KHR`
			`** ename:VK_FORMAT_G16B16G16R16_422_UNORM_KHR`
			`** ename:VK_FORMAT_B16G16R16G16_422_UNORM_KHR`
			`** ename:VK_FORMAT_G16_B16_R16_3PLANE_420_UNORM_KHR`
			`** ename:VK_FORMAT_G16_B16R16_2PLANE_420_UNORM_KHR`
			`** ename:VK_FORMAT_G16_B16_R16_3PLANE_422_UNORM_KHR`
			`** ename:VK_FORMAT_G16_B16R16_2PLANE_422_UNORM_KHR`
			`** ename:VK_FORMAT_G16_B16_R16_3PLANE_444_UNORM_KHR`
			`* Extending elink:VkImageAspectFlagBits:`
			`** ename:VK_IMAGE_ASPECT_PLANE_0_BIT_KHR`
			`** ename:VK_IMAGE_ASPECT_PLANE_1_BIT_KHR`
			`** ename:VK_IMAGE_ASPECT_PLANE_2_BIT_KHR`
			`* Extending elink:VkImageCreateFlagBits:`
			`** ename:VK_IMAGE_CREATE_DISJOINT_BIT_KHR`
			`* Extending elink:VkFormatFeatureFlagBits:`
			`** ename:VK_FORMAT_FEATURE_MIDPOINT_CHROMA_SAMPLES_BIT_KHR`
			`** ename:VK_FORMAT_FEATURE_COSITED_CHROMA_SAMPLES_BIT_KHR`
			`** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER_BIT_KHR`
			`** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_SEPARATE_RECONSTRUCTION_FILTER_BIT_KHR`
			`** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_BIT_KHR`
			`** ename:VK_FORMAT_FEATURE_SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE_BIT_KHR`
			`** ename:VK_FORMAT_FEATURE_DISJOINT_BIT_KHR`

			`=== New Enums`

			`* elink:VkSamplerYcbcrModelConversionKHR`
			`* elink:VkSamplerYcbcrRangeKHR`
			`* elink:VkChromaLocationKHR`

			`=== New Structures`

			`* slink:VkSamplerYcbcrConversionInfoKHR`
			`* slink:VkSamplerYcbcrConversionCreateInfoKHR`
			`* slink:VkBindImagePlaneMemoryInfoKHR`
			`* slink:VkImagePlaneMemoryRequirementsInfoKHR`
			`* slink:VkPhysicalDeviceSamplerYcbcrConversionFeaturesKHR`
			`* slink:VkSamplerYcbcrConversionImageFormatPropertiesKHR`

			`=== New Functions`

			`* flink:vkCreateSamplerYcbcrConversionKHR`
			`* flink:vkDestroySamplerYcbcrConversionKHR`

			`=== New Objects`

			`* slink:VkSamplerYcbcrConversionKHR`

			`=== Issues`

			`=== Version History`

			`* Revision 1, 2017-01-24 (Andrew Garrard)`
			`- Initial draft`
			`* Revision 2, 2017-01-25 (Andrew Garrard)`
			`- After initial feedback`
			`* Revision 3, 2017-01-27 (Andrew Garrard)`
			`- Higher bit depth formats, renaming, swizzle`
			`* Revision 4, 2017-02-22 (Andrew Garrard)`
			`- Added query function, formats as RGB, clarifications`
			`* Revision 5, 2017-04 (Andrew Garrard)`
			`- Simplified query and removed output conversions`
			`* Version 6, 2017-4-24 (Andrew Garrard)`
			`- Tidying, incorporated new image query, restored transfer functions`
			`* Version 7, 2017-04-25 (Andrew Garrard)`
			`- Added cosited option/midpoint requirement for formats,`
			`"bypassConversion"`
			`* Version 8, 2017-04-25 (Andrew Garrard)`
			`- Simplified further`
			`* Version 9, 2017-04-27 (Andrew Garrard)`
			`- Disjoint no more`
			`* Version 10, 2017-04-28 (Andrew Garrard)`
			`- Restored disjoint`
			`* Version 11, 2017-04-29 (Andrew Garrard)`
			`- Now Ycbcr conversion, and KHR`
			`* Version 12, 2017-06-06 (Andrew Garrard)`
			`- Added conversion to image view creation`
			`* Version 13, 2017-07-13 (Andrew Garrard)`
			`- Allowed cosited-only chroma samples for formats`
			`* Version 14, 2017-08-11 (Andrew Garrard)`
			`- Reflected quantization changes in BT.2100-1`