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

// 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 reference
monitor.
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='Set Hdr metadata',type='protos']
--
include::{generated}/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 an array of pname:swapchainCount
    slink:VkSwapchainKHR handles.
  * pname:pMetadata is a pointer to an array of pname:swapchainCount
    slink:VkHdrMetadataEXT structures.

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

[open,refpage='VkXYColorEXT',desc='Specify X,Y chromaticity coordinates',type='structs']
--
include::{generated}/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 reference monitor.

--

[open,refpage='VkHdrMetadataEXT',desc='Specify Hdr metadata',type='structs']
--
include::{generated}/api/structs/VkHdrMetadataEXT.txt[]

  * pname:sType is the type of this structure.
  * pname:pNext is `NULL` or a pointer to a structure extending this
    structure.
  * pname:displayPrimaryRed is the reference monitor's red primary in
    chromaticity coordinates
  * pname:displayPrimaryGreen is the reference monitor's green primary in
    chromaticity coordinates
  * pname:displayPrimaryBlue is the reference monitor's blue primary in
    chromaticity coordinates
  * pname:whitePoint is 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.txt[]

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

--