XR_ANDROID_trackables_object OpenXR extension

Name String

XR_ANDROID_trackables_object

Extension Type

Instance extension

Registered Extension Number

467

Revision

1

Extension and Version Dependencies

XR_ANDROID_trackables

Last Modified Date

2024-11-01

IP Status

No known IP claims.

Contributors

Diego Tipaldi, Google

David Joseph Tan, Google

Christopher Doer, Google

Spencer Quin, Google

Jared Finder, Google

Levana Chen, Google

Kenny Vercaemer, Google

Overview

This extension enables physical object tracking. For example, keyboards, mice, and other objects in the environment.

Track objects

This extension adds XR_TRACKABLE_TYPE_OBJECT_ANDROID to XrTrackableTypeANDROID.

The application may create an XrTrackableTrackerANDROID by calling xrCreateTrackableTrackerANDROID and specifying XR_TRACKABLE_TYPE_OBJECT_ANDROID as the trackable type in XrTrackableTrackerCreateInfoANDROID::trackableType to track objects.

The XrTrackableObjectConfigurationANDROID structure is defined as: 

typedef struct XrTrackableObjectConfigurationANDROID {  XrStructureType type;  void* next;  uint32_t labelCount;  const XrObjectLabelANDROID* activeLabels; } XrTrackableObjectConfigurationANDROID;

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension.
  • labelCount is the count of activeLabels.
  • activeLabels is a pointer to the array of XRObjectLabelANDROID indicating the active objects in tracking.

The application may set an additional configuration by adding a XrTrackableObjectConfigurationANDROID to the next chain of XrTrackableTrackerCreateInfoANDROID. The output from xrGetAllTrackablesANDROID will be filtered to match the activeLabels.

If the application does not set XrTrackableObjectConfigurationANDROID, then all objects that the system has identified will be tracked.

Valid usage (implicit)

The XrObjectLabelANDROID enum is a label for a XrTrackableANDROID object. 

typedef enum XrObjectLabelANDROID {  XR_OBJECT_LABEL_UNKNOWN_ANDROID = 0,  XR_OBJECT_LABEL_KEYBOARD_ANDROID = 1,  XR_OBJECT_LABEL_MOUSE_ANDROID = 2,  XR_OBJECT_LABEL_LAPTOP_ANDROID = 3,  XR_OBJECT_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF } XrObjectLabelANDROID;

Get trackable object

The xrGetTrackableObjectANDROID function is defined as:

XrResult xrGetTrackableObjectANDROID(  XrTrackableTrackerANDROID tracker,  const XrTrackableGetInfoANDROID* getInfo,  XrTrackableObjectANDROID* objectOutput);

Parameter Descriptions

XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID will be returned if the trackable type of the XrTrackableANDROID is not XR_TRACKABLE_TYPE_OBJECT_ANDROID, or if the trackable type of the XrTrackableTrackerANDROID is not XR_TRACKABLE_TYPE_OBJECT_ANDROID.

Valid usage (implicit)

Return Codes

Success

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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_SESSION_NOT_RUNNING
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID

The XrTrackableObjectANDROID structure is defined as: 

typedef struct XrTrackableObjectANDROID {  XrStructureType type;  void* next;  XrTrackingStateANDROID trackingState;  XrPosef centerPose;  XrExtent3DfEXT extents;  XrObjectLabelANDROID objectLabel;  XrTime lastUpdatedTime; } XrTrackableObjectANDROID;

Member Descriptions

Valid usage (implicit)

Example code for getting trackable objects

The following example code demonstrates how to get trackable objects.

XrSession session; // previously initialized // The function pointers are previously initialized using xrGetInstanceProcAddr. PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // previously initialized PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // previously initialized PFN_xrGetTrackableObjectANDROID xrGetTrackableObjectANDROID; // previously initialized PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized XrTime updateTime; // Time used for the current frame's simulation update. XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL. XrTrackableTrackerCreateInfoANDROID  createInfo{XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID}; createInfo.trackableType = XR_TRACKABLE_TYPE_OBJECT_ANDROID; XrTrackableTrackerANDROID objectTrackableTracker; XrResult result = xrCreateTrackableTrackerANDROID(  session,  &createInfo,  &objectTrackableTracker); if (result != XR_SUCCESS) { /* Handle failures. */ } uint32_t trackableCountOutput = 0; std::vector<XrTrackableANDROID> allObjectTrackables; // Query the number of trackables available. result = xrGetAllTrackablesANDROID(  objectTrackableTracker,  0,  &trackableCountOutput,  nullptr ); if (result == XR_SUCCESS) {  allObjectTrackables.resize(trackableCountOutput, XR_NULL_TRACKABLE_ANDROID);  // Fetch the actual trackable handles in the appropriately resized array.  result = xrGetAllTrackablesANDROID(  objectTrackableTracker,  trackableCountOutput,  &trackableCountOutput,  allObjectTrackables.data());  if (result == XR_SUCCESS) {  for (XrTrackableANDROID trackable : allObjectTrackables) {  // Object trackable query information  XrTrackableGetInfoANDROID objectGetInfo;  objectGetInfo.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID;  objectGetInfo.next = nullptr;  objectGetInfo.trackable = trackable;  objectGetInfo.baseSpace = appSpace;  objectGetInfo.time = updateTime;  // Get the object trackable. Note that the tracker only returns object types.  XrTrackableObjectANDROID object = { XR_TYPE_TRACKABLE_OBJECT_ANDROID };  result = xrGetTrackableObjectANDROID(  objectTrackableTracker,  &objectGetInfo,  &object  );  if (result == XR_SUCCESS) {  /** Do Stuff with the object */  }  }  } } // Release trackable tracker. result = xrDestroyTrackableTrackerANDROID(objectTrackableTracker);

New Enum Constants

XrStructureType enumeration is extended with:

  • XR_TYPE_TRACKABLE_OBJECT_ANDROID
  • XR_TYPE_TRACKABLE_OBJECT_CONFIGURATION_ANDROID

XrTrackableTypeANDROID enumeration is extended with:

  • XR_TRACKABLE_TYPE_OBJECT_ANDROID

New Enums

New Structures

New Functions

Issues

Version History

  • Revision 1, 2024-10-03 (Kenny Vercaemer)
    • Initial extension description.

OpenXR™ and the OpenXR logo are trademarks owned by The Khronos Group Inc. and are registered as a trademark in China, the European Union, Japan and the United Kingdom.