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

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

*Last Modified Date*::
    2019-08-16
*IP Status*::
    No known IP claims.
*Contributors*::
    Blake Taylor, Magic Leap +
    Gilles Cadet, Magic Leap +
    Michael Liebenow, Magic Leap +
    Supreet Suresh, Magic Leap +
    Alex Turner, Microsoft +
    Bryce Hutchings, Microsoft +
    Yin Li, Microsoft

*Overview*

For XR systems there may exist a per view recommended min/max depth range at
which content should be rendered into the virtual world.
The depth range may be driven by several factors, including user comfort, or
fundamental capabilities of the system.

Displaying rendered content outside the recommended min/max depth range
would violate the system requirements for a properly integrated application,
and can result in a poor user experience due to observed visual artifacts,
visual discomfort, or fatigue.
The near/far depth values will fall in the range of (0..+infinity] where
max(pname:recommendedNearZ, pname:minNearZ) < min(pname:recommendedFarZ,
pname:maxFarZ).
Infinity is defined matching the standard library definition such that
std::isinf will return true for a returned infinite value.

In order to provide the application with the appropriate depth range at
which to render content for each slink:XrViewConfigurationView, this
extension provides additional view configuration information, as defined by
slink:XrViewConfigurationDepthRangeEXT, to inform the application of the
min/max recommended and absolute distances at which content should be
rendered for that view.

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_VIEW_CONFIGURATION_DEPTH_RANGE_EXT

*New Enums*

*New Structures*

[open,refpage='XrViewConfigurationDepthRangeEXT',desc='View configuration depth range information',type='structs',xrefs='xrEnumerateViewConfigurationViews XrViewConfigurationView']
--
The slink:XrViewConfigurationDepthRangeEXT structure is defined as:

include::{generated}/api/structs/XrViewConfigurationDepthRangeEXT.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:recommendedNearZ is the recommended minimum positive distance in
  meters that content should be rendered for the view to achieve the best
  user experience.
* pname:minNearZ is the absolute minimum positive distance in meters that
  content should be rendered for the view.
* pname:recommendedFarZ is the recommended maximum positive distance in
  meters that content should be rendered for the view to achieve the best
  user experience.
* pname:maxFarZ is the absolute maximum positive distance in meters that
  content should be rendered for the view.
****

When enumerating the view configurations with
flink:xrEnumerateViewConfigurationViews, the application can: provide a
pointer to an slink:XrViewConfigurationDepthRangeEXT in the pname:next chain
of slink:XrViewConfigurationView.

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

*New Functions*

*Issues*

*Version History*

* Revision 1, 2019-10-01 (Blake Taylor)
** Initial proposal.
