// Copyright (c) 2022 Magic Leap
//
// SPDX-License-Identifier: CC-BY-4.0

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

*Last Modified Date*::
    2022-11-08

*Contributors*::
    Ron Bessems, Magic Leap

*Overview*

This extension provides functionality to facilitate transitioning from Magic
Leap SDK to OpenXR SDK, most notably interoperability between Coordinate
Frame UUIDs and slink:XrSpace.

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_COORDINATE_SPACE_CREATE_INFO_ML

*New Structures*

[open,refpage='XrCoordinateSpaceCreateInfoML',type='structs',desc='Structure used to create an XrSpace from a cfuid',xrefs='']
--

The slink:XrCoordinateSpaceCreateInfoML structure is defined as:

include::{generated}/api/structs/XrCoordinateSpaceCreateInfoML.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:cfuid is the sname:MLCoordinateFrameUID as generated by the
  non-OpenXR API in the Magic Leap SDK.
* pname:poseInCoordinateSpace is an slink:XrPosef defining the position and
  orientation of the new space's origin within the natural reference frame
  of the pname:cfuid.
****

slink:XrCoordinateSpaceCreateInfoML is provided as input when calling
flink:xrCreateSpaceFromCoordinateFrameUIDML to convert a Magic Leap SDK
generated sname:MLCoordinateFrameUID to an slink:XrSpace.
The conversion only needs to be done once even if the underlying
sname:MLCoordinateFrameUID changes its pose.

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

*New Functions*

[open,refpage='xrCreateSpaceFromCoordinateFrameUIDML',desc='Creates a space based on a cfuid',type='protos',xrefs='XrSpace XrCoordinateSpaceCreateInfoML']
--
The flink:xrCreateSpaceFromCoordinateFrameUIDML function is defined as:

include::{generated}/api/protos/xrCreateSpaceFromCoordinateFrameUIDML.adoc[]

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession previously created with
  flink:xrCreateSession.
* pname:createInfo is the slink:XrCoordinateSpaceCreateInfoML used to
  specify the space.
* pname:space is the returned space handle.
****

The service that created the underlying
slink:XrCoordinateSpaceCreateInfoML::pname:cfuid must: remain active for the
lifetime of the slink:XrSpace.
If flink:xrLocateSpace is called on a space created from an
slink:XrCoordinateSpaceCreateInfoML::pname:cfuid from a no-longer-active
service, the runtime may: set slink:XrSpaceLocation::pname:locationFlags to 0.

slink:XrSpace handles are destroyed using flink:xrDestroySpace.

include::{generated}/validity/protos/xrCreateSpaceFromCoordinateFrameUIDML.adoc[]
--

*Issues*

*Version History*

* Revision 1, 2022-11-08 (Ron Bessems)

** Initial extension description
