// Copyright (c) 2019-2020 Microsoft Corporation
//
// SPDX-License-Identifier: CC-BY-4.0

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

*Overview*

[open,refpage='XrSpatialAnchorMSFT',type='handles',desc='Represents a spatial anchor']
--
This extension allows an application to create a **spatial anchor**, an
arbitrary freespace point in the user's physical environment that will then
be tracked by the runtime.
The runtime should: then adjust the position and orientation of that
anchor's origin over time as needed, independently of all other spaces and
anchors, to ensure that it maintains its original mapping to the real world.

include::{generated}/api/handles/XrSpatialAnchorMSFT.adoc[]

Spatial anchors are often used in combination with an `UNBOUNDED_MSFT`
reference space.
`UNBOUNDED_MSFT` reference spaces adjust their origin as necessary to keep
the viewer's coordinates relative to the space's origin stable.
Such adjustments maintain the visual stability of content currently near the
viewer, but may cause content placed far from the viewer to drift in its
alignment to the real world by the time the user moves close again.
By creating an `XrSpatialAnchorMSFT` where a piece of content is placed and
then always rendering that content relative to its anchor's space, an
application can ensure that each piece of content stays at a fixed location
in the environment.
--


[open,refpage='xrCreateSpatialAnchorMSFT',desc='Creates a spatial anchor',type='protos',xrefs='XrSpatialAnchorMSFT XrSpatialAnchorCreateInfoMSFT']
--
The flink:xrCreateSpatialAnchorMSFT function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:createInfo is a pointer to an slink:XrSpatialAnchorCreateInfoMSFT
  structure containing information about how to create the anchor.
* pname:anchor is a pointer to a handle in which the created
  slink:XrSpatialAnchorMSFT is returned.
****

Creates an slink:XrSpatialAnchorMSFT handle representing a spatial anchor
that will track a fixed location in the physical world over time.
That real-world location is specified by the position and orientation of the
specified slink:XrSpatialAnchorCreateInfoMSFT::pname:pose within
slink:XrSpatialAnchorCreateInfoMSFT::pname:space at
slink:XrSpatialAnchorCreateInfoMSFT::pname:time.

The runtime must: avoid long blocking operations such as networking or disk
operations for flink:xrCreateSpatialAnchorMSFT function.
The application may: safely use this function in UI thread.
Though, the created anchor handle may: not be ready immediately for certain
operations yet.
For example, the corresponding anchor space may: not return valid location,
or its location may: not be successfully saved in anchor store.

If slink:XrSpatialAnchorCreateInfoMSFT::pname:space cannot be located
relative to the environment at the moment of the call to
flink:xrCreateSpatialAnchorMSFT, the runtime must: return
ename:XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT.

After the anchor is created, the runtime should: then adjust its position
and orientation over time relative to other spaces so as to maintain maximum
alignment to its original real-world location, even if that changes the
anchor's relationship to the original
slink:XrSpatialAnchorCreateInfoMSFT::pname:space used to initialize it.

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

[open,refpage='XrSpatialAnchorCreateInfoMSFT',desc='Information to create a spatial anchor',type='structs',xrefs='XrSpatialAnchorMSFT xrCreateSpatialAnchorMSFT']
--
The slink:XrSpatialAnchorCreateInfoMSFT structure is defined as:

include::{generated}/api/structs/XrSpatialAnchorCreateInfoMSFT.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:space is a handle to the slink:XrSpace in which pname:pose is
  specified.
* pname:pose is the slink:XrPosef within pname:space at pname:time that
  specifies the point in the real world used to initialize the new anchor.
* pname:time is the basetype:XrTime at which pname:pose will be evaluated
  within pname:space.
****

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

[open,refpage='xrCreateSpatialAnchorSpaceMSFT',desc='Creates a space from a spatial anchor',type='protos',xrefs='XrSpatialAnchorMSFT XrSpatialAnchorSpaceCreateInfoMSFT XrSpace']
--
The flink:xrCreateSpatialAnchorSpaceMSFT function is defined as:

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

.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:createInfo is a pointer to an
  slink:XrSpatialAnchorSpaceCreateInfoMSFT structure containing information
  about how to create the anchor.
* pname:space is a pointer to a handle in which the created slink:XrSpace is
  returned.
****

Creates an slink:XrSpace handle based on a spatial anchor.
Application can: provide an slink:XrPosef to define the position and
orientation of the new space's origin relative to the anchor's natural
origin.

Multiple slink:XrSpace handles may exist for a given
slink:XrSpatialAnchorMSFT simultaneously, up to some limit imposed by the
runtime.
The slink:XrSpace handle must be eventually freed via the
flink:xrDestroySpace function or by destroying the parent
slink:XrSpatialAnchorMSFT handle.

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

[open,refpage='XrSpatialAnchorSpaceCreateInfoMSFT',desc='Information to create a space from a spatial anchor',type='structs',xrefs='XrSpatialAnchorMSFT xrCreateSpatialAnchorSpaceMSFT XrSpace']
--
The slink:XrSpatialAnchorSpaceCreateInfoMSFT structure is defined as:

include::{generated}/api/structs/XrSpatialAnchorSpaceCreateInfoMSFT.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:anchor is a handle to an slink:XrSpatialAnchorMSFT previously
  created with flink:xrCreateSpatialAnchorMSFT.
* pname:poseInAnchorSpace is an slink:XrPosef defining the position and
  orientation of the new space's origin relative to the anchor's natural
  origin.
****

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

[open,refpage='xrDestroySpatialAnchorMSFT',desc='Destroys a spatial anchor',type='protos',xrefs='XrSpatialAnchorMSFT xrCreateSpatialAnchorMSFT']
--
The flink:xrDestroySpatialAnchorMSFT function is defined as:

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

.Parameter Descriptions
****
* pname:anchor is a handle to an slink:XrSpatialAnchorMSFT previously
  created by flink:xrCreateSpatialAnchorMSFT.
****

slink:XrSpatialAnchorMSFT handles are destroyed using
flink:xrDestroySpatialAnchorMSFT.
By destroying an anchor, the runtime can: stop spending resources used to
maintain tracking for that anchor's origin.

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

*New Object Types*

slink:XrSpatialAnchorMSFT

*New Flag Types*

*New Enum Constants*

elink:XrObjectType enumeration is extended with:

* ename:XR_OBJECT_TYPE_SPATIAL_ANCHOR_MSFT

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT
* ename:XR_TYPE_SPATIAL_ANCHOR_SPACE_CREATE_INFO_MSFT

elink:XrResult enumeration is extended with:

* ename:XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT

*New Enums*

*New Structures*

slink:XrSpatialAnchorCreateInfoMSFT

slink:XrSpatialAnchorSpaceCreateInfoMSFT

*New Functions*

flink:xrCreateSpatialAnchorMSFT

flink:xrCreateSpatialAnchorSpaceMSFT

flink:xrDestroySpatialAnchorMSFT

*Issues*

*Version History*

* Revision 1, 2019-07-30 (Alex Turner)
** Initial extension description
* Revision 2, 2021-06-02 (Rylie Pavlik, Collabora, Ltd.)
** Note that the parameter to `xrDestroySpatialAnchorMSFT` must be
   externally synchronized
