xrQuerySpatialComponentDataEXT(3)

C Specification

The xrQuerySpatialComponentDataEXT function is defined as:

// Provided by XR_EXT_spatial_entity
XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

Parameters

Parameter Descriptions

snapshot is an XrSpatialSnapshotEXT previously provided by xrCreateSpatialDiscoverySnapshotCompleteEXT or xrCreateSpatialUpdateSnapshotEXT.
queryCondition is a pointer to an XrSpatialComponentDataQueryConditionEXT structure.
queryResult is a pointer to an XrSpatialComponentDataQueryResultEXT structure.

Description

The application can use xrQuerySpatialComponentDataEXT to query the component data of the entities in the snapshot by attaching a list structure to XrSpatialComponentDataQueryResultEXT::next corresponding to each XrSpatialComponentTypeEXT in XrSpatialComponentDataQueryConditionEXT::componentTypes.

If the application attaches a list structure to XrSpatialComponentDataQueryResultEXT::next that does not correspond to any of the components listed in XrSpatialComponentDataQueryConditionEXT::componentTypes, the runtime must return XR_ERROR_VALIDATION_FAILURE.

The application can choose to attach the list structures corresponding to only a subset of components listed in XrSpatialComponentDataQueryConditionEXT::componentTypes. The application can choose to omit the list structures altogether if it only wishes to know the ids and tracking state of the spatial entities that satisfy the queryCondition. The runtime must not treat the absence of list structures from the XrSpatialComponentDataQueryResultEXT::next chain as a failure.

If XrEventDataReferenceSpaceChangePending is queued and XrEventDataReferenceSpaceChangePending::changeTime elapsed while the application is querying component data from an XrSpatialSnapshotEXT, the application may use the event data to adjust the poses accordingly.

The runtime must populate XrSpatialComponentDataQueryResultEXT::entityIds only with entities that have all the components specified in XrSpatialComponentDataQueryConditionEXT::componentTypes. If XrSpatialComponentDataQueryConditionEXT::componentTypeCount is 0, the runtime must populate queryResult with all the entities (and their tracking states) that are in the snapshot. If additional query conditions are added to XrSpatialComponentDataQueryConditionEXT::next, the runtime must treat those as an "AND" with the component types availability i.e. the runtime must populate XrSpatialComponentDataQueryResultEXT::entityIds only with entities that satisfy all of the provided conditions. The runtime must populate the component data in the list structures in the same order as the entities in XrSpatialComponentDataQueryResultEXT::entityIds i.e. the component data at a given index in the list structure array must correspond to the entity at the same index.

If the tracking state for an entity is not XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT, the runtime must not change the data at the index corresponding to that entity in the array contained in the list structures attached to XrSpatialComponentDataQueryResultEXT.

Valid Usage (Implicit)

The XR_EXT_spatial_entity extension must be enabled prior to calling xrQuerySpatialComponentDataEXT
snapshot must be a valid XrSpatialSnapshotEXT handle
queryCondition must be a pointer to a valid XrSpatialComponentDataQueryConditionEXT structure
queryResult must be a pointer to an XrSpatialComponentDataQueryResultEXT structure

Return Codes

On success, this command returns

XR_SUCCESS
XR_SESSION_LOSS_PENDING

On failure, this command returns

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_VALIDATION_FAILURE
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_SIZE_INSUFFICIENT

As an example the application creates an XrSpatialSnapshotEXT which contains 5 entities, where -

Entity 1 and 2 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
Entity 3 and 4 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
Entity 5 has components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT.

Figure 1. Example snapshot

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT listed in the query condition will result in entity #1, #2, and #5 being returned to the application and the application can attach an array of XrSpatialBounded2DDataEXT as part of the XrSpatialComponentBounded2DListEXT structure to the next chain of XrSpatialComponentDataQueryResultEXT to get the bounded2D data.

Figure 2. Example query result

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT components listed in the query condition will result in entity #3 and #4 being returned to the application and the application can attach arrays of XrBoxf and XrSpatialMeshDataEXT as part of the XrSpatialComponentBounded3DListEXT and XrSpatialComponentMesh3DListEXT structures respectively to the next chain of XrSpatialComponentDataQueryResultEXT to get the component data.

Figure 3. Example query result

Document Notes

For more information, see the OpenXR Specification

This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

This work is licensed under a Creative Commons Attribution 4.0 International License.

xrQuerySpatialComponentDataEXT(3) Manual Page

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright