// This section is included inside VK_KHR_swapchain

== Hdr Metadata

To improve color reproduction of content it is useful to have information
that can be used to better reproduce the colors as seen on the mastering
display.
That information can be provided to an implementation by calling
fname:vkSetHdrMetadataEXT.
The metadata will be applied to the specified sname:VkSwapchainKHR objects
at the next fname:vkQueuePresentKHR call using that sname:VkSwapchainKHR
object.
The metadata will persist until a subsequent fname:vkSetHdrMetadataEXT
changes it.
The definitions below are from the associated SMPTE 2086, CTA 861.3 and CIE
15:2004 specifications.

The definition of fname:vkSetHdrMetadataEXT is:

[open,refpage='vkSetHdrMetadataEXT',desc='function to set Hdr metadata',type='protos']
--
include::../api/protos/vkSetHdrMetadataEXT.txt[]

  * pname:device is the logical device where the swapchain(s) were created.
  * pname:swapchainCount is the number of swapchains included in
    pname:pSwapchains.
  * pname:pSwapchains is a pointer to the array of pname:swapchainCount
    sname:VkSwapchainKHR handles.
  * pname:pMetadata is a pointer to the array of pname:swapchainCount
    sname:VkHdrMetadataEXT structures.

include::../validity/protos/vkSetHdrMetadataEXT.txt[]
--

[open,refpage='VkXYColorEXT',desc='structure to specify X,Y chromaticity coordinates',type='structs']
--
include::../api/structs/VkXYColorEXT.txt[]
Chromaticity coordinates x and y are as specified in CIE 15:2004
"Calculation of chromaticity coordinates" (Section 7.3) and are limited to
between 0 and 1 for real colors for the mastering display.

--

[open,refpage='VkHdrMetadataEXT',desc='structure to specify Hdr metadata',type='structs']
--
include::../api/structs/VkHdrMetadataEXT.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to an extension-specific structure.
  * pname:displayPrimaryRed is the mastering display's red primary in
    chromaticity coordinates
  * pname:displayPrimaryGreen is the mastering display's green primary in
    chromaticity coordinates
  * pname:displayPrimaryBlue is the mastering display's blue primary in
    chromaticity coordinates
  * pname:whitePoint is the mastering display's white-point in chromaticity
    coordinates
  * pname:maxLuminance is the maximum luminance of the mastering display in
    nits
  * pname:minLuminance is the minimum luminance of the mastering display in
    nits
  * pname:maxContentLightLevel is content's maximum luminance in nits
  * pname:maxFrameAverageLightLevel is the maximum frame average light level
    in nits

[NOTE]
.note
====
The validity and use of this data is outside the scope of Vulkan and thus no
+Valid Usage+ is given.
====

--