Merge pull request #26 from KhronosGroup/yl/unbounded_space_spatial_anchor
Proposal for unbounded space and spatial anchor extensions.
This commit is contained in:
Ryan A. Pavlik
GitHub
commit
7db1a0895b
|
|
@ -232,6 +232,7 @@ maintained in the master branch of the Khronos OpenXR GitHub project.
|
|||
<type category="handle" parent="XrSession"><type>XR_DEFINE_HANDLE</type>(<name>XrSwapchain</name>)</type>
|
||||
<type category="handle" parent="XrSession"><type>XR_DEFINE_HANDLE</type>(<name>XrSpace</name>)</type>
|
||||
<type category="handle" parent="XrInstance"><type>XR_DEFINE_HANDLE</type>(<name>XrDebugUtilsMessengerEXT</name>)</type>
|
||||
<type category="handle" parent="XrSession"><type>XR_DEFINE_HANDLE</type>(<name>XrSpatialAnchorMSFT</name>)</type>
|
||||
|
||||
<!-- enums and flag bits generated from corresponding <enums> tags below -->
|
||||
<type name="XrStructureType" category="enum"/>
|
||||
|
|
@ -966,6 +967,22 @@ maintained in the master branch of the Khronos OpenXR GitHub project.
|
|||
const <type>XrDebugUtilsMessengerCallbackDataEXT</type>* callbackData,
|
||||
<type>void</type>* userData);
|
||||
</type>
|
||||
|
||||
<!-- types for XR_MSFT_spatial_anchor -->
|
||||
<type category="struct" name="XrSpatialAnchorCreateInfoMSFT">
|
||||
<member values="XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT"><type>XrStructureType</type><name>type</name></member>
|
||||
<member>const <type>void</type>* <name>next</name></member>
|
||||
<member><type>XrSpace</type> <name>space</name></member>
|
||||
<member><type>XrPosef</type> <name>pose</name></member>
|
||||
<member><type>XrTime</type> <name>time</name></member>
|
||||
</type>
|
||||
<type category="struct" name="XrSpatialAnchorSpaceCreateInfoMSFT">
|
||||
<member values="XR_TYPE_ACTION_SPACE_CREATE_INFO"><type>XrStructureType</type> <name>type</name></member>
|
||||
<member>const <type>void</type>* <name>next</name></member>
|
||||
<member><type>XrSpatialAnchorMSFT</type> <name>anchor</name></member>
|
||||
<member><type>XrPosef</type> <name>poseInAnchorSpace</name></member>
|
||||
</type>
|
||||
|
||||
</types>
|
||||
|
||||
<!-- SECTION: OpenXR enumerant (token) definitions. -->
|
||||
|
|
@ -1764,6 +1781,25 @@ maintained in the master branch of the Khronos OpenXR GitHub project.
|
|||
<param><type>XrVisibilityMaskTypeKHR</type> <name>visibilityMaskType</name></param>
|
||||
<param><type>XrVisibilityMaskKHR</type>* <name>visibilityMask</name></param>
|
||||
</command>
|
||||
|
||||
<!-- commands for XR_MSFT_spatial_anchor -->
|
||||
<command successcodes="XR_SUCCESS" errorcodes="XR_ERROR_INSTANCE_LOST,XR_ERROR_OUT_OF_MEMORY,XR_ERROR_FUNCTION_UNSUPPORTED,XR_ERROR_VALIDATION_FAILURE,XR_ERROR_HANDLE_INVALID,XR_ERROR_POSE_INVALID,XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT,XR_ERROR_TIME_INVALID,XR_ERROR_SESSION_LOST,XR_SESSION_LOSS_PENDING">
|
||||
<proto><type>XrResult</type> <name>xrCreateSpatialAnchorMSFT</name></proto>
|
||||
<param><type>XrSession</type> <name>session</name></param>
|
||||
<param>const <type>XrSpatialAnchorCreateInfoMSFT</type>* <name>createInfo</name></param>
|
||||
<param><type>XrSpatialAnchorMSFT</type>* <name>anchor</name></param>
|
||||
</command>
|
||||
<command successcodes="XR_SUCCESS" errorcodes="XR_ERROR_INSTANCE_LOST,XR_ERROR_OUT_OF_MEMORY,XR_ERROR_FUNCTION_UNSUPPORTED,XR_ERROR_VALIDATION_FAILURE,XR_ERROR_HANDLE_INVALID,XR_ERROR_POSE_INVALID,XR_ERROR_SESSION_LOST,XR_SESSION_LOSS_PENDING">
|
||||
<proto><type>XrResult</type> <name>xrCreateSpatialAnchorSpaceMSFT</name></proto>
|
||||
<param><type>XrSession</type> <name>session</name></param>
|
||||
<param>const <type>XrSpatialAnchorSpaceCreateInfoMSFT</type>* <name>createInfo</name></param>
|
||||
<param><type>XrSpace</type>* <name>space</name></param>
|
||||
</command>
|
||||
<command successcodes="XR_SUCCESS" errorcodes="XR_ERROR_HANDLE_INVALID,XR_ERROR_FUNCTION_UNSUPPORTED">
|
||||
<proto><type>XrResult</type> <name>xrDestroySpatialAnchorMSFT</name></proto>
|
||||
<param><type>XrSpatialAnchorMSFT</type> <name>anchor</name></param>
|
||||
</command>
|
||||
|
||||
</commands>
|
||||
|
||||
<!-- SECTION: OpenXR API interface definitions -->
|
||||
|
|
@ -2263,17 +2299,27 @@ maintained in the master branch of the Khronos OpenXR GitHub project.
|
|||
</require>
|
||||
</extension>
|
||||
|
||||
<extension name="XR_MSFT_unbounded_reference_space" number="39" type="instance" supported="disabled">
|
||||
<extension name="XR_MSFT_unbounded_reference_space" number="39" type="instance" supported="openxr">
|
||||
<require>
|
||||
<enum value="1" name="XR_MSFT_unbounded_reference_space_SPEC_VERSION"/>
|
||||
<enum value=""XR_MSFT_unbounded_reference_space"" name="XR_MSFT_UNBOUNDED_REFERENCE_SPACE_EXTENSION_NAME"/>
|
||||
|
||||
<enum offset="0" extends="XrReferenceSpaceType" name="XR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT"/>
|
||||
</require>
|
||||
</extension>
|
||||
|
||||
<extension name="XR_MSFT_spatial_anchor" number="40" type="instance" supported="disabled">
|
||||
<extension name="XR_MSFT_spatial_anchor" number="40" type="instance" supported="openxr">
|
||||
<require>
|
||||
<enum value="1" name="XR_MSFT_spatial_anchor_SPEC_VERSION"/>
|
||||
<enum value=""XR_MSFT_spatial_anchor"" name="XR_MSFT_SPATIAL_ANCHOR_EXTENSION_NAME"/>
|
||||
|
||||
<enum offset="0" extends="XrStructureType" name="XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT"/>
|
||||
<enum offset="1" extends="XrStructureType" name="XR_TYPE_SPATIAL_ANCHOR_SPACE_CREATE_INFO_MSFT"/>
|
||||
<command name="xrCreateSpatialAnchorMSFT" />
|
||||
<command name="xrCreateSpatialAnchorSpaceMSFT" />
|
||||
<command name="xrDestroySpatialAnchorMSFT" />
|
||||
<enum offset="0" extends="XrObjectType" name="XR_OBJECT_TYPE_SPATIAL_ANCHOR_MSFT" comment="XrSpatialAnchorMSFT" />
|
||||
<enum offset="1" dir="-" extends="XrResult" name="XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT" comment="Spatial anchor could not be created at that location." />
|
||||
</require>
|
||||
</extension>
|
||||
|
||||
|
|
|
|||
|
|
@ -2,22 +2,179 @@ include::../meta/XR_MSFT_spatial_anchor.adoc[]
|
|||
|
||||
*Overview*
|
||||
|
||||
This extension supports creation of spatial anchor for application to render world locked hologram in world scale tracked system.
|
||||
[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.txt[]
|
||||
|
||||
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.txt[]
|
||||
|
||||
.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:session 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 pname:pose within pname:space at pname:time.
|
||||
|
||||
If 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 pname:space used to initialize it.
|
||||
|
||||
include::../../../../generated/validity/protos/xrCreateSpatialAnchorMSFT.txt[]
|
||||
--
|
||||
|
||||
[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.txt[]
|
||||
|
||||
.Member Descriptions
|
||||
****
|
||||
* pname:type is the elink:XrStructureType of this structure.
|
||||
* pname:next is code:NULL or a pointer to an extension-specific structure.
|
||||
* 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.txt[]
|
||||
--
|
||||
|
||||
[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.txt[]
|
||||
|
||||
.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.txt[]
|
||||
--
|
||||
|
||||
[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.txt[]
|
||||
|
||||
.Member Descriptions
|
||||
****
|
||||
* pname:type is the elink:XrStructureType of this structure.
|
||||
* pname:next is code:NULL or a pointer to an extension-specific structure.
|
||||
* 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.txt[]
|
||||
--
|
||||
|
||||
[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.txt[]
|
||||
|
||||
.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.txt[]
|
||||
--
|
||||
|
||||
*New Object Types*
|
||||
|
||||
slink:XrSpatialAnchorMSFT
|
||||
|
||||
*New Flag Types*
|
||||
|
||||
*New Enum Constants*
|
||||
|
||||
ename:XR_OBJECT_TYPE_SPATIAL_ANCHOR_MSFT
|
||||
|
||||
ename:XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT
|
||||
|
||||
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, TODO: https://gitlab.khronos.org/openxr/openxr/merge_requests/1258
|
||||
* Revision 1, 2019-07-30 (Alex Turner)
|
||||
** Initial extension description
|
||||
|
|
@ -2,14 +2,75 @@ include::../meta/XR_MSFT_unbounded_reference_space.adoc[]
|
|||
|
||||
*Overview*
|
||||
|
||||
This extension allows application to create an unbounded reference space, also known as UNBOUNDED reference space in WebXR.
|
||||
This extension allows an application to create an `UNBOUNDED_MSFT` reference space.
|
||||
This reference space enables the viewer to move freely through a complex environment,
|
||||
often many meters from where they started, while always optimizing
|
||||
for coordinate system stability near the viewer.
|
||||
This is done by allowing the origin of the reference space to drift as necessary
|
||||
to keep the viewer's coordinates relative to the space's origin stable.
|
||||
|
||||
To create an `UNBOUNDED_MSFT` reference space, the application can:
|
||||
pass ename:XR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT to flink:xrCreateReferenceSpace.
|
||||
|
||||
The `UNBOUNDED_MSFT` reference space establishes a world-locked origin,
|
||||
gravity-aligned to exclude pitch and roll, with +Y up, +X to the right,
|
||||
and -Z forward.
|
||||
This space begins with an arbitrary initial position and orientation, which the
|
||||
runtime may: define to be either the initial position at app launch or
|
||||
some other initial zero position.
|
||||
Unlike a `STAGE` reference space, the runtime may: place the origin of an `UNBOUNDED_MSFT`
|
||||
reference space at any height, rather than fixing it at the floor.
|
||||
This is because the viewer may move through various rooms and levels of their
|
||||
environment, each of which has a different floor height.
|
||||
Runtimes should: not automatically adjust the position of the origin when
|
||||
the viewer moves to a room with a different floor height.
|
||||
|
||||
`UNBOUNDED_MSFT` space is useful when an app needs to render *world-scale* content
|
||||
that spans beyond the bounds of a single `STAGE`,
|
||||
for example, an entire floor or multiple floors of a building.
|
||||
|
||||
An `UNBOUNDED_MSFT` space maintains stability near the viewer by slightly adjusting
|
||||
its origin over time. The runtime must: not queue the
|
||||
slink:XrEventDataReferenceSpaceChangePending event in response to these
|
||||
minor adjustments.
|
||||
|
||||
When views, controllers or other spaces experience tracking loss relative to
|
||||
the `UNBOUNDED_MSFT` space, runtimes should: continue to provide inferred or
|
||||
last-known pname:position and pname:orientation values.
|
||||
These inferred poses can, for example, be based on neck model updates,
|
||||
inertial dead reckoning, or a last-known position, so long as it is still
|
||||
reasonable for the application to use that pose.
|
||||
While a runtime is providing position data, it must: continue to set
|
||||
ename:XR_SPACE_LOCATION_POSITION_VALID_BIT and
|
||||
ename:XR_VIEW_STATE_POSITION_VALID_BIT but it can: clear
|
||||
ename:XR_SPACE_LOCATION_POSITION_TRACKED_BIT and
|
||||
ename:XR_VIEW_STATE_POSITION_TRACKED_BIT to indicate that the position is
|
||||
inferred or last-known in this way.
|
||||
|
||||
When tracking is recovered, runtimes should: snap the pose of other spaces
|
||||
back into position relative to the `UNBOUNDED_MSFT` space's original origin.
|
||||
However, if tracking recovers into a new tracking volume in which the
|
||||
original origin can no longer be located (e.g. the viewer moved through
|
||||
a dark hallway and regained tracking in a new room), the runtime may: recenter
|
||||
the origin arbitrarily, for example moving the origin to coincide with the viewer.
|
||||
If such recentering occurs, the runtime must: queue the
|
||||
slink:XrEventDataReferenceSpaceChangePending event with pname:poseValid set to false.
|
||||
|
||||
If the viewer moves far enough away from the origin of an `UNBOUNDED_MSFT` reference space
|
||||
that floating point error would introduce noticeable error when locating the viewer
|
||||
within that space, the runtime may: recenter the space's origin to a new location
|
||||
closer to the viewer. If such recentering occurs, the runtime must: queue the
|
||||
slink:XrEventDataReferenceSpaceChangePending event with pname:poseValid set to true.
|
||||
|
||||
Runtimes must: support the `UNBOUNDED_MSFT` reference space when this extension is enabled.
|
||||
*New Object Types*
|
||||
|
||||
*New Flag Types*
|
||||
|
||||
*New Enum Constants*
|
||||
|
||||
ename:XR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT
|
||||
|
||||
*New Enums*
|
||||
|
||||
*New Structures*
|
||||
|
|
@ -20,4 +81,5 @@ This extension allows application to create an unbounded reference space, also k
|
|||
|
||||
*Version History*
|
||||
|
||||
* Revision 1, TODO: https://gitlab.khronos.org/openxr/openxr/merge_requests/1258
|
||||
* Revision 1, 2019-07-30 (Alex Turner)
|
||||
** Initial extension description
|
||||
Loading…
Reference in New Issue