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

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

*Last Modified Date*::
    2019-01-24
*IP Status*::
    No known IP claims.
*Contributors*::
    Johannes van Waveren, Oculus +
    Cass Everitt, Oculus +
    Paul Pedriana, Oculus +
    Gloria Kennickell, Oculus +
    Martin Renschler, Qualcomm
*Contacts*::
    Cass Everitt, Oculus +

*Overview*

This extension adds an additional layer type where the XR runtime must map
an equirectangular coded image stemming from a swapchain onto the inside of
a sphere.

The equirect layer type provides most of the same benefits as a cubemap, but
from an equirect 2D image source.
This image source is appealing mostly because equirect environment maps are
very common, and the highest quality you can get from them is by sampling
them directly in the compositor.

This is not a projection type of layer but rather an object-in-world type of
layer, similar to slink:XrCompositionLayerQuad.
Only the interior of the sphere surface must: be visible; the exterior of
the sphere is not visible and must: not be drawn by the runtime.

This extension uses a different parameterization more in keeping with the
formulation of KHR_composition_layer_cylinder but is functionally equivalent
to KHR_composition_layer_equirect.

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_COMPOSITION_LAYER_EQUIRECT2_KHR

*New Enums*

*New Structures*
[open,refpage='XrCompositionLayerEquirect2KHR',desc='Equirectangular layer composition info',type='structs',xrefs='XrCompositionLayerBaseHeader XrFrameEndInfo xrEndFrame']
--
The slink:XrCompositionLayerEquirect2KHR structure is defined as:

include::{generated}/api/structs/XrCompositionLayerEquirect2KHR.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:layerFlags specifies options for the layer.
* pname:space is the slink:XrSpace in which the pname:pose of the equirect
  layer is evaluated over time.
* pname:eyeVisibility is the eye represented by this layer.
* pname:subImage identifies the image slink:XrSwapchainSubImage to use.
  The swapchain must: have been created with a
  slink:XrSwapchainCreateInfo::pname:faceCount of 1.
* pname:pose is an slink:XrPosef defining the position and orientation of
the center point of the sphere onto which the equirect image data is mapped,
relative to the reference frame of the pname:space.
* pname:radius is the non-negative radius of the sphere onto which the
  equirect image data is mapped.
  Values of zero or floating point positive infinity are treated as an
  infinite sphere.
* pname:centralHorizontalAngle defines the visible horizontal angle of the
  sphere, based at 0 radians, in the range of [eq]#[0, 2{pi}]#.
  It grows symmetrically around the 0 radian angle.
* pname:upperVerticalAngle defines the upper vertical angle of the visible
  portion of the sphere, in the range of [eq]#[-{pi}/2, {pi}/2]#.
* pname:lowerVerticalAngle defines the lower vertical angle of the visible
  portion of the sphere, in the range of [eq]#[-{pi}/2, {pi}/2]#.
****

slink:XrCompositionLayerEquirect2KHR contains the information needed to
render an equirectangular image onto a sphere when calling flink:xrEndFrame.
slink:XrCompositionLayerEquirect2KHR is an alias type for the base struct
slink:XrCompositionLayerBaseHeader used in slink:XrFrameEndInfo.


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

*New Functions*

*Issues*

*Version History*

* Revision 1, 2020-05-08 (Cass Everitt)
** Initial version.
** Kept contributors from the original equirect extension.
