// Copyright 2018-2022 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

// This section is included inside VK_KHR_swapchain

== Hdr Metadata

This section describes how to improve color reproduction of content to
better reproduce colors as seen on the reference monitor.
Definitions below are from the associated SMPTE 2086, CTA 861.3 and CIE
15:2004 specifications.

[open,refpage='vkSetHdrMetadataEXT',desc='Set Hdr metadata',type='protos']
--
To provide Hdr metadata to an implementation, call:

include::{generated}/api/protos/vkSetHdrMetadataEXT.adoc[]

  * 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 an array of pname:swapchainCount
    slink:VkSwapchainKHR handles.
  * pname:pMetadata is a pointer to an array of pname:swapchainCount
    slink:VkHdrMetadataEXT structures.

The metadata will be applied to the specified slink:VkSwapchainKHR objects
at the next fname:vkQueuePresentKHR call using that slink:VkSwapchainKHR
object.
The metadata will persist until a subsequent fname:vkSetHdrMetadataEXT
changes it.

include::{generated}/validity/protos/vkSetHdrMetadataEXT.adoc[]
--

[open,refpage='VkHdrMetadataEXT',desc='Specify Hdr metadata',type='structs']
--
The sname:VkHdrMetadataEXT structure is defined as:

include::{generated}/api/structs/VkHdrMetadataEXT.adoc[]

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

include::{generated}/validity/structs/VkHdrMetadataEXT.adoc[]

[NOTE]
.Note
====
The validity and use of this data is outside the scope of Vulkan.
====
--

[open,refpage='VkXYColorEXT',desc='Specify X,Y chromaticity coordinates',type='structs']
--
The sname:VkXYColorEXT structure is defined as:

include::{generated}/api/structs/VkXYColorEXT.adoc[]

  * pname:x is the [eq]#x# chromaticity coordinate.
  * pname:y is the [eq]#y# chromaticity coordinate.

Chromaticity coordinates 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 reference monitor.
--