// Copyright (c) 2017-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/XR_META_local_dimming.adoc[]

*Last Modified Date*::
    2022-05-05
*IP Status*::
    No known IP claims.
*Contributors*::
    Ross Ning, Meta Platforms +
    Haomiao Jiang, Meta Platforms +
    Remi Palandri, Meta Platforms +
    Xiang Wei, Meta Platforms


*Overview*

Local dimming allows to adjust backlight intensity of dark areas on the
screen in order to increase content dynamic range.
Local dimming feature is not intended for optical see-through HMDs.

An application can: request the local dimming mode on a frame basis by
chaining an slink:XrLocalDimmingFrameEndInfoMETA structure to the
slink:XrFrameEndInfo.

* Using XrFrameEndInfoLocalDimmingFB is considered as a hint and will not
  trigger flink:xrEndFrame errors whether or not the requested dimming mode
  is fulfilled by the runtime.
* The runtime will have full control of the local dimming mode and may:
  disregard app requests.
  For example, the runtime may: allow only one primary client to control the
  local dimming mode.

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_LOCAL_DIMMING_FRAME_END_INFO_META

*New Enums*

[open,refpage='XrLocalDimmingModeMETA',desc='Local dimming modes',type='enums']
--
The local dimming mode is specified by the elink:XrLocalDimmingModeMETA
enumeration:

include::{generated}/api/enums/XrLocalDimmingModeMETA.adoc[]

include::{generated}/api/enums/XrLocalDimmingModeMETA.comments-box.adoc[]

--

*New Structures*

[open,refpage='XrLocalDimmingFrameEndInfoMETA',type='structs',desc='Local dimming meta data for the current submitted frame',xrefs='XrFrameEndInfo']
--
The slink:XrLocalDimmingFrameEndInfoMETA structure is defined as:

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

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:localDimmingMode is the local dimming mode for current submitted
  frame.
****

The slink:XrLocalDimmingFrameEndInfoMETA is a structure that an application
can: chain in slink:XrFrameEndInfo in order to request a local dimming mode.

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

*New Functions*

*Issues*

*Version History*

* Revision 1, 2022-05-05 (Ross Ning)
** Initial draft
