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 2019-08-02 16:19:21 -05:00 committed by GitHub
commit 7db1a0895b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 271 additions and 6 deletions

View File

@ -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="&quot;XR_MSFT_unbounded_reference_space&quot;" 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="&quot;XR_MSFT_spatial_anchor&quot;" 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>

View File

@ -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

View File

@ -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