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

include::{generated}/meta/XR_KHR_composition_layer_cube.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 +
    Sam Martin, ARM +
    Kaye Mason, Google, Inc. +
    Martin Renschler, Qualcomm
*Contacts*::
    Cass Everitt, Oculus +
    Paul Pedriana, Oculus

*Overview*

This extension adds an additional layer type that enables direct sampling
from cubemaps.

The cube layer is the natural layer type for hardware accelerated
environment maps.
Without updating the image source, the user can look all around, and the
compositor can display what they are looking at without intervention from
the application.

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_COMPOSITION_LAYER_CUBE_KHR

*New Enums*

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

include::{generated}/api/structs/XrCompositionLayerCubeKHR.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 is any flags to apply to this layer.
* pname:space is the slink:XrSpace in which the pname:orientation of the
  cube layer is evaluated over time.
* pname:eyeVisibility is the eye represented by this layer.
* pname:swapchain is the swapchain, which must: have been created with a
  slink:XrSwapchainCreateInfo::pname:faceCount of 6.
* pname:imageArrayIndex is the image array index, with 0 meaning the first
  or only array element.
* pname:orientation is the orientation of the environment map in the
  pname:space.
****

slink:XrCompositionLayerCubeKHR contains the information needed to render a
cube map when calling flink:xrEndFrame.
slink:XrCompositionLayerCubeKHR is an alias type for the base struct
slink:XrCompositionLayerBaseHeader used in slink:XrFrameEndInfo.

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

*New Functions*

*Issues*

*Version History*

* Revision 0, 2017-02-01 (Johannes van Waveren)
** Initial draft.
* Revision 1, 2017-05-19 (Sam Martin)
** Initial draft, moving the 3 layer types to an extension.
* Revision 2, 2017-08-30 (Paul Pedriana)
** Updated the specification.
* Revision 3, 2017-10-12 (Cass Everitt)
** Updated to reflect per-eye structs and the change to swapchains
* Revision 4, 2017-10-18 (Kaye Mason)
** Update to flatten structs to remove per-eye arrays.
* Revision 5, 2017-12-05 (Paul Pedriana)
** Updated to break out the cylinder and equirect features into separate
   extensions.
* Revision 6, 2017-12-07 (Paul Pedriana)
** Updated to use transform components instead of transform matrices.
* Revision 7, 2017-12-07 (Paul Pedriana)
** Updated to convert slink:XrPosef to slink:XrQuaternionf (there's no
   position component).
* Revision 8, 2019-01-24 (Martin Renschler)
** Updated struct to use slink:XrSwapchainSubImage, reformat and spec
   language changes, eye parameter description update
