OpenXR Specification 1.1

https://registry.khronos.org/OpenXR/specs/1.1
Admin
OpenXR is an open and royalty-free standard for high-performance access to virtual reality and...
Tokens:6,259,615
Snippets:31,885
Trust Score:10
Update:20 hours ago
Show doc for...
Tokens:
Raw
### Example: Getting Trackable Images

Source: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html

Example code demonstrating how to get trackable images using the XR_ANDROID_trackables_image extension, including system capability inspection and function pointer initialization.

```APIDOC
## Example: Getting Trackable Images

### Description
Example code demonstrating how to get trackable images using the XR_ANDROID_trackables_image extension.

### Code
```c
XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.
```
```

--------------------------------

### Camera Capabilities Filtering and Device Creation Example

Source: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html

This example shows how to set up capability filters for image format and camera model, enumerate available cameras, create a camera device asynchronously, and complete the creation. It includes error handling for no cameras and async failures.

```C++
XrCameraCapabilityImageFormatBD imageFormatFilter {
  .type = XR_TYPE_CAMERA_CAPABILITY_IMAGE_FORMAT_BD,
  .format = XR_CAMERA_IMAGE_FORMAT_RGBA_8888_BD,
};

XrCameraCapabilityCameraModelBD cameraModelFilter {
  .type = XR_TYPE_CAMERA_CAPABILITY_CAMERA_MODEL_BD,
  .model = XR_CAMERA_MODEL_PINHOLE_BD,
};

std::vector<XrCameraCapabilityBaseHeaderBD*> capabilityFilters{
    (XrCameraCapabilityBaseHeaderBD *)&transferTypeFilter,
    (XrCameraCapabilityBaseHeaderBD *)&imageFormatFilter,
    (XrCameraCapabilityBaseHeaderBD *)&cameraModelFilter,
};

XrCameraCapabilitiesBD filterCapabilities {
  .type = XR_TYPE_CAMERA_CAPABILITIES_BD,
  .capabilityCount = static_cast<uint32_t>(capabilityFilters.size()),
  .capabilities = capabilityFilters.data(),
};

XrAvailableCamerasEnumerateInfoBD enumerateInfo {
  .type = XR_TYPE_AVAILABLE_CAMERAS_ENUMERATE_INFO_BD,
  .properties = &filterProperties,
  .capabilities = &filterCapabilities,
};

uint32_t cameraCount;
xrEnumerateAvailableCamerasBD(instance, &enumerateInfo, 0, &cameraCount, NULL);

std::vector<XrAvailableCameraBD> cameras(cameraCount);

xrEnumerateAvailableCamerasBD(instance, &enumerateInfo, cameraCount, &cameraCount, cameras.data());
if (cameraCount == 0)
{
    // Handle no camera available
}

// Get the 1st camera
XrCameraIdBD targetCameraId = cameras[0].cameraId;

// Create camera device
XrCameraDeviceCreateInfoBD createDeviceInfo {
  .type = XR_TYPE_CAMERA_DEVICE_CREATE_INFO_BD,
  .cameraId = targetCameraId,
};
XrFutureEXT createDeviceFuture {XR_NULL_FUTURE_EXT};
XrResult result = xrCreateCameraDeviceAsyncBD(instance, &createDeviceInfo, &createDeviceFuture);
if (result != XR_SUCCESS)
{
    // Handle creation error
}

// Wait for device creation to complete
waitUntilReady(createDeviceFuture);

XrCreateCameraDeviceCompletionBD deviceCompletion {
  .type = XR_TYPE_CREATE_CAMERA_DEVICE_COMPLETION_BD,
};
result = xrCreateCameraDeviceCompleteBD(instance, createDeviceFuture, &deviceCompletion);
if (deviceCompletion.futureResult != XR_SUCCESS)
{
    // Handle async failure
}
XrCameraDeviceBD cameraDevice = deviceCompletion.device;
```

--------------------------------

### OpenXR Action Creation and Usage Example

Source: https://registry.khronos.org/OpenXR/specs/1.1/pdf/xrspec.pdf

Complete example showing how to create an action set, create input and output actions, suggest bindings, attach action sets, sync actions, and query boolean action state. Uses CHK_XR for error checking and assumes XrInstance and XrSession are already initialized.

```cpp
XrInstance instance; // previously initialized
XrSession session; // previously initialized
// Create an action set
XrActionSetCreateInfo actionSetInfo {
.type = XR_TYPE_ACTION_SET_CREATE_INFO,
.actionSetName = "gameplay",
.localizedActionSetName = "Gameplay",
.priority = 0,
};
XrActionSet inGameActionSet {XR_NULL_HANDLE};
CHK_XR(xrCreateActionSet(instance, &actionSetInfo, &inGameActionSet));
// create a "teleport" input action
XrActionCreateInfo actioninfo {
.type = XR_TYPE_ACTION_CREATE_INFO,
.actionName = "teleport",
.actionType = XR_ACTION_TYPE_BOOLEAN_INPUT,
.localizedActionName = "Teleport",
};
XrAction teleportAction {XR_NULL_HANDLE};
CHK_XR(xrCreateAction(inGameActionSet, &actioninfo, &teleportAction));
// create a "player_hit" output action
XrActionCreateInfo hapticsactioninfo {
.type = XR_TYPE_ACTION_CREATE_INFO,
.actionName = "player_hit",
.actionType = XR_ACTION_TYPE_VIBRATION_OUTPUT,
.localizedActionName = "Player hit",
};
XrAction hapticsAction {XR_NULL_HANDLE};
CHK_XR(xrCreateAction(inGameActionSet, &hapticsactioninfo, &hapticsAction));
XrPath triggerClickPath {XR_NULL_PATH}, hapticPath {XR_NULL_PATH};
CHK_XR(xrStringToPath(instance, "/user/hand/right/input/trigger/click", &triggerClickPath));
CHK_XR(xrStringToPath(instance, "/user/hand/right/output/haptic", &hapticPath))
XrPath interactionProfilePath {XR_NULL_PATH};
CHK_XR(xrStringToPath(instance, "/interaction_profiles/vendor_x/profile_x", &interactionProfilePath));
XrActionSuggestedBinding bindings[2] = {
{
.action = teleportAction,
.binding = triggerClickPath,
},
{
.action = hapticsAction,
.binding = hapticPath,
},
};
XrInteractionProfileSuggestedBinding suggestedBindings {
.type = XR_TYPE_INTERACTION_PROFILE_SUGGESTED_BINDING,
.interactionProfile = interactionProfilePath,
.countSuggestedBindings = 2,
.suggestedBindings = bindings,
};
CHK_XR(xrSuggestInteractionProfileBindings(instance, &suggestedBindings));
XrSessionActionSetsAttachInfo attachInfo {
.type = XR_TYPE_SESSION_ACTION_SETS_ATTACH_INFO,
.countActionSets = 1,
.actionSets = &inGameActionSet,
};
CHK_XR(xrAttachSessionActionSets(session, &attachInfo));
// application main loop
while (1)
{
// sync action data
XrActiveActionSet activeActionSet {
.actionSet = inGameActionSet,
.subactionPath = XR_NULL_PATH,
};
XrActionsSyncInfo syncInfo {
.type = XR_TYPE_ACTIONS_SYNC_INFO,
.countActiveActionSets = 1,
.activeActionSets = &activeActionSet,
};
CHK_XR(xrSyncActions(session, &syncInfo));
// query input action state
XrActionStateBoolean teleportState {
.type = XR_TYPE_ACTION_STATE_BOOLEAN,
};
XrActionStateGetInfo getInfo {
.type = XR_TYPE_ACTION_STATE_GET_INFO,
.action = teleportAction,
};
CHK_XR(xrGetActionStateBoolean(session, &getInfo, &teleportState));
if (teleportState.changedSinceLastSync && teleportState.currentState)
{
// fire haptics using output action
XrHapticVibration vibration {
.type = XR_TYPE_HAPTIC_VIBRATION,
.duration = 300000000, // 300 ms
.frequency = 150,
.amplitude = 0.5,
};
XrHapticActionInfo hapticActionInfo {
.type = XR_TYPE_HAPTIC_ACTION_INFO,
.action = hapticsAction,
};
CHK_XR(xrApplyHapticFeedback(session, &hapticActionInfo, (const XrHapticBaseHeader*)&vibration));
}
}
```

--------------------------------

### XR_EXT_eye_gaze_interaction setup and usage example

Source: https://registry.khronos.org/OpenXR/specs/1.1/pdf/xrspec.pdf

Complete example for using the XR_EXT_eye_gaze_interaction extension. It creates an action set and a pose action, suggests bindings for the eye gaze interaction profile, attaches the action set, creates action and reference spaces, and in a loop syncs actions, gets the pose state, and locates the gaze space. Requires an XrInstance, XrSession, and an identity pose. Uses CHK_XR for error checking.

```cpp
extern XrInstance instance;
extern XrSession session;
extern XrPosef pose_identity;
// Create action set
XrActionSetCreateInfo actionSetInfo {
.type = XR_TYPE_ACTION_SET_CREATE_INFO,
.actionSetName = "gameplay",
.localizedActionSetName = "Gameplay",
.priority = 0,
};
XrActionSet gameplayActionSet {XR_NULL_HANDLE};
CHK_XR(xrCreateActionSet(instance, &actionSetInfo, &gameplayActionSet));
// Create user intent action
XrActionCreateInfo actionInfo {
.type = XR_TYPE_ACTION_CREATE_INFO,
.actionName = "user_intent",
.actionType = XR_ACTION_TYPE_POSE_INPUT,
.localizedActionName = "User Intent",
};
XrAction userIntentAction {XR_NULL_HANDLE};
CHK_XR(xrCreateAction(gameplayActionSet, &actionInfo, &userIntentAction));
// Create suggested bindings
XrPath eyeGazeInteractionProfilePath {XR_NULL_PATH};
CHK_XR(xrStringToPath(instance, "/interaction_profiles/ext/eye_gaze_interaction",
&eyeGazeInteractionProfilePath));
XrPath gazePosePath {XR_NULL_PATH};
CHK_XR(xrStringToPath(instance, "/user/eyes_ext/input/gaze_ext/pose", &gazePosePath));
XrActionSuggestedBinding bindings {
.action = userIntentAction,
.binding = gazePosePath,
};
XrInteractionProfileSuggestedBinding suggestedBindings{
.type = XR_TYPE_INTERACTION_PROFILE_SUGGESTED_BINDING,
.interactionProfile = eyeGazeInteractionProfilePath,
.countSuggestedBindings = 1,
.suggestedBindings = &bindings,
};
CHK_XR(xrSuggestInteractionProfileBindings(instance, &suggestedBindings));
XrSessionActionSetsAttachInfo attachInfo{
.type = XR_TYPE_SESSION_ACTION_SETS_ATTACH_INFO,
.countActionSets = 1,
.actionSets = &gameplayActionSet,
};
CHK_XR(xrAttachSessionActionSets(session, &attachInfo));
XrActionSpaceCreateInfo createActionSpaceInfo{
.type = XR_TYPE_ACTION_SPACE_CREATE_INFO,
.action = userIntentAction,
.poseInActionSpace = pose_identity,
};
XrSpace gazeActionSpace {XR_NULL_HANDLE};
CHK_XR(xrCreateActionSpace(session, &createActionSpaceInfo, &gazeActionSpace));
XrReferenceSpaceCreateInfo createReferenceSpaceInfo{
.type = XR_TYPE_REFERENCE_SPACE_CREATE_INFO,
.referenceSpaceType = XR_REFERENCE_SPACE_TYPE_LOCAL,
.poseInReferenceSpace = pose_identity,
};
XrSpace localReferenceSpace {XR_NULL_HANDLE};
CHK_XR(xrCreateReferenceSpace(session, &createReferenceSpaceInfo, &localReferenceSpace));
while(true)
{
XrActiveActionSet activeActionSet{
.actionSet = gameplayActionSet,
.subactionPath = XR_NULL_PATH,
};
XrTime time = 0;
XrActionsSyncInfo syncInfo{
.type = XR_TYPE_ACTIONS_SYNC_INFO,
.countActiveActionSets = 1,
.activeActionSets = &activeActionSet,
};
CHK_XR(xrSyncActions(session, &syncInfo));
XrActionStatePose actionStatePose{
.type = XR_TYPE_ACTION_STATE_POSE,
};
XrActionStateGetInfo getActionStateInfo{
.type = XR_TYPE_ACTION_STATE_GET_INFO,
.action = userIntentAction,
};
CHK_XR(xrGetActionStatePose(session, &getActionStateInfo, &actionStatePose));
if(actionStatePose.isActive){
XrEyeGazeSampleTimeEXT eyeGazeSampleTime{
.type = XR_TYPE_EYE_GAZE_SAMPLE_TIME_EXT,
};
XrSpaceLocation gazeLocation{
.type = XR_TYPE_SPACE_LOCATION,
.next = &eyeGazeSampleTime,
};
CHK_XR(xrLocateSpace(gazeActionSpace, localReferenceSpace, time, &gazeLocation));
// Do things
}
}
```

--------------------------------

### Create Spatial Audio Renderer and Set Up Free-Field Spatialization

Source: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html

This example shows how to initialize function pointers, enumerate supported audio sample rates, query the frames per buffer range, create a spatial audio renderer, and set up free-field spatialization for sound fields. It assumes an XrInstance, XrSession, and XrSpace are already initialized.

```cpp
XrInstance instance; // previously initialized
XrSession session;   // previously initialized
XrSpace space; //previously initialized
/***************************************************/
/* xrCreateSpatialAudioRendererBD */
/***************************************************/

PFN_xrQueryFramesPerBufferRangeBD xrQueryFramesPerBufferRangeBD;
CHK_XR(xrGetInstanceProcAddr(instance, "xrQueryFramesPerBufferRangeBD",
                             reinterpret_cast<PFN_xrVoidFunction*>(
                             &xrQueryFramesPerBufferRangeBD)));

PFN_xrEnumerateSupportedAudioSampleRateBD xrEnumerateSupportedAudioSampleRateBD;
CHK_XR(xrGetInstanceProcAddr(instance, "xrEnumerateSupportedAudioSampleRateBD",
                             reinterpret_cast<PFN_xrVoidFunction*>(
                             &xrEnumerateSupportedAudioSampleRateBD)));

PFN_xrCreateSpatialAudioRendererBD xrCreateSpatialAudioRendererBD;
CHK_XR(xrGetInstanceProcAddr(instance, "xrCreateSpatialAudioRendererBD",
                             reinterpret_cast<PFN_xrVoidFunction*>(
                             &xrCreateSpatialAudioRendererBD)));

uint32_t sampleRateCount = 0;
CHK_XR(xrEnumerateSupportedAudioSampleRateBD(session, 0, &sampleRateCount, nullptr));
std::vector<XrAudioSampleRateBD> sampleRates;
if (sampleRateCount != 0) {
    sampleRates.resize(sampleRateCount);
    CHK_XR(xrEnumerateSupportedAudioSampleRateBD(session, sampleRateCount, &sampleRateCount, sampleRates.data()));
}

uint32_t minFramePerBuffer = 0;
uint32_t maxFramePerBuffer = 0;
CHK_XR(xrQueryFramesPerBufferRangeBD(session, sampleRates[0], &minFramePerBuffer, &maxFramePerBuffer));

uint32_t framePerBuffer = 4096;
framePerBuffer = framePerBuffer < minFramePerBuffer ? minFramePerBuffer : framePerBuffer;
framePerBuffer = framePerBuffer > maxFramePerBuffer ? maxFramePerBuffer : framePerBuffer;

// Setup context config struct
XrSpatialAudioRendererCreateInfoBD createInfo {
  .type = XR_TYPE_SPATIAL_AUDIO_RENDERER_CREATE_INFO_BD,
  .next = nullptr,
  .framesPerBuffer = framePerBuffer,  //  frames_per_buffer
  .sampleRate = sampleRates[0],  //  sample rate
};

// Create and initialize spatial audio renderer for session
XrSpatialAudioRendererBD renderer {XR_NULL_HANDLE};
CHK_XR(xrCreateSpatialAudioRendererBD(session, &createInfo, &renderer));

/****************************************************************************/
/* Setting-up free-field spatialization for sound fields. The following functions are used: */
/* - xrCreateSoundFieldBD */
/* - xrUpdateSoundFieldConfigBD */
/* - xrSubmitSoundFieldBufferBD */
/****************************************************************************/
```

--------------------------------

### xrGetAudioOutputDeviceGuidOculus

Source: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html

Gets the GUID of the audio output device.

```APIDOC
## xrGetAudioOutputDeviceGuidOculus

### Description
Gets the GUID of the audio output device.

### Function Signature
```c
XrResult xrGetAudioOutputDeviceGuidOculus(
    XrInstance instance,
    char guidBuffer[XR_MAX_AUDIO_DEVICE_STR_SIZE_OCULUS]);
```

### Parameters
- **instance** (XrInstance) - The instance to query.
- **guidBuffer** (char[XR_MAX_AUDIO_DEVICE_STR_SIZE_OCULUS]) - Buffer to receive the GUID string.

### Return Value
- **XrResult** - Result code indicating success or failure.
```

--------------------------------

### xrGetAudioInputDeviceGuidOculus

Source: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html

Gets the GUID of the audio input device.

```APIDOC
## xrGetAudioInputDeviceGuidOculus

### Description
Gets the GUID of the audio input device.

### Function Signature
```c
XrResult xrGetAudioInputDeviceGuidOculus(
    XrInstance instance,
    char guidBuffer[XR_MAX_AUDIO_DEVICE_STR_SIZE_OCULUS]);
```

### Parameters
- **instance** (XrInstance) - The instance to query.
- **guidBuffer** (char[XR_MAX_AUDIO_DEVICE_STR_SIZE_OCULUS]) - Buffer to receive the GUID string.

### Return Value
- **XrResult** - Result code indicating success or failure.
```

--------------------------------

### XR_EXT_dpad_binding: Creating Dpad Bindings

Source: https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html

Example code demonstrating how to create dpad bindings using the XR_EXT_dpad_binding extension. It shows setting up dpad paths, binding modifiers, suggested bindings, and suggesting them to the runtime.

```APIDOC
## XR_EXT_dpad_binding: Creating Dpad Bindings

### Description
This example demonstrates how to create dpad bindings using the XR_EXT_dpad_binding extension. It shows setting up dpad paths, binding modifiers, suggested bindings, and suggesting them to the runtime.

### Code Example
```cpp
  // Create dpad paths
  XrPath pathThumbstick, pathDpadUp, pathDpadDown;
  xrStringToPath(instance, "/user/hand/left/input/thumbstick", &pathThumbstick);
  xrStringToPath(instance, "/user/hand/left/input/thumbstick/dpad_up", &pathDpadUp);
  xrStringToPath(instance, "/user/hand/left/input/thumbstick/dpad_down", &pathDpadDown);

  // Set dpad binding modifiers
  XrInteractionProfileDpadBindingEXT xrDpadModification {
    .type = XR_TYPE_INTERACTION_PROFILE_DPAD_BINDING_EXT,
    // A gap between these next two members creates hysteresis, to avoid rapid toggling
    .forceThreshold = 0.8f,
    .forceThresholdReleased = 0.2f,
  };

  // Add dpad binding modifiers to binding modifications vector
  std::vector<XrInteractionProfileDpadBindingEXT> vBindingModifs;
  vBindingModifs.push_back( xrDpadModification );

  std::vector<XrBindingModificationBaseHeaderKHR*> vBindingModifsBase;
  for ( XrInteractionProfileDpadBindingEXT &modif : vBindingModifs )
  {
    vBindingModifsBase.push_back(reinterpret_cast<XrBindingModificationBaseHeaderKHR*>(&modif));
  }

  XrBindingModificationsKHR xrBindingModifications {
    .type = XR_TYPE_BINDING_MODIFICATIONS_KHR,
    .bindingModificationCount = static_cast<uint32_t>(vBindingModifsBase.size()),
    .bindingModifications = vBindingModifsBase.data(),
  };

  // Set dpad input path as suggested binding for an action
  XrActionSuggestedBinding xrActionBindingTeleport, xrActionBindingMenu;

  xrActionBindingTeleport.action = xrAction_Teleport;
  xrActionBindingTeleport.binding = pathDpadUp;

  xrActionBindingMenu.action = xrAction_Menu;
  xrActionBindingMenu.binding = pathDpadDown;

  std::vector< XrActionSuggestedBinding > vActionBindings;
  vActionBindings.push_back(xrActionBindingTeleport);
  vActionBindings.push_back(xrActionBindingMenu);

  // Create interaction profile/controller path
  XrPath xrInteractionProfilePath;
  xrStringToPath(instance, "/interaction_profiles/valve/index_controller", &xrInteractionProfilePath);

  // Set suggested binding to interaction profile
  XrInteractionProfileSuggestedBinding xrInteractionProfileSuggestedBinding {
    .type = XR_TYPE_INTERACTION_PROFILE_SUGGESTED_BINDING,
    .interactionProfile = xrInteractionProfilePath,
    .countSuggestedBindings = static_cast<uint32_t>(vActionBindings.size()),
    .suggestedBindings = vActionBindings.data(),
  };

  // Set binding modifications to interaction profile's suggested binding
  xrInteractionProfileSuggestedBinding.next = &xrBindingModifications;

  // Finally, suggest interaction profile bindings to runtime
  xrSuggestInteractionProfileBindings(instance, &xrInteractionProfileSuggestedBinding);
```
```

--------------------------------

### Example usage of xrGetSystem

Source: https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html

Example C++ code showing how to initialize an XrSystemGetInfo structure and call xrGetSystem to obtain an XrSystemId. Includes comments for the session lifecycle.

```C++
XrInstance instance; // previously initialized

XrSystemGetInfo system_get_info {
    .type = XR_TYPE_SYSTEM_GET_INFO,
    .formFactor = XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY,
};

XrSystemId systemId {XR_NULL_SYSTEM_ID};
CHK_XR(xrGetSystem(instance, &system_get_info, &systemId));

// create session
// create swapchains
// begin session

// main loop

// end session
// destroy session

// no access to hardware after this point
```

--------------------------------

### Create Spatial Anchor & Get Its Location

Source: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html

Example code demonstrating how to create a spatial anchor and get its pose every frame.

```APIDOC
## Create Spatial Anchor & Get Its Location

### Description
This example demonstrates how to create a spatial anchor and get its pose every frame.

### Code
```cpp
XrSpatialAnchorCreateInfoEXT createInfo {
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpatialEntityEXT spatialAnchorEntity {XR_NULL_HANDLE};
CHK_XR(xrCreateSpatialAnchorEXT(spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorEntity));

auto updateAnchorLocation = [&](XrTime time) {
  // We want to get updated data for all components of the entities, so skip specifying componentTypes.
  XrSpatialUpdateSnapshotCreateInfoEXT snapshotCreateInfo {
    .type = XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT,
    .entityCount = 1,
    .entities = &spatialAnchorEntity,
    .baseSpace = localSpace,
    .time = time,
  };

  XrSpatialSnapshotEXT snapshot {XR_NULL_HANDLE};
  CHK_XR(xrCreateSpatialUpdateSnapshotEXT(spatialContext, &snapshotCreateInfo, &snapshot));

  // Query for the entities that have the anchor component on them.
  std::array<XrSpatialComponentTypeEXT, 1> componentsToQuery {XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT};
  XrSpatialComponentDataQueryConditionEXT queryCond {
    .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
    .componentTypeCount = componentsToQuery.size(),
    .componentTypes = componentsToQuery.data(),
  };

  XrSpatialComponentDataQueryResultEXT queryResult {
    .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
  };
  CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

  std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
  std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
  queryResult.entityIdCapacityInput = entityIds.size();
  queryResult.entityIds = entityIds.data();
  queryResult.entityStateCapacityInput = entityStates.size();
  queryResult.entityStates = entityStates.data();

  // query for the pose data
  std::vector<XrPosef> locations(queryResult.entityIdCountOutput);
  XrSpatialComponentAnchorListEXT locationList {
    .type = XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT,
    .locationCount = static_cast<uint32_t>(locations.size()),
    .locations = locations.data(),
  };
  queryResult.next = &locationList;

  CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

  for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
      // Pose for entity entityIds[i] is locations[i].
    }
  }

  CHK_XR(xrDestroySpatialSnapshotEXT(snapshot));
};


while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  updateAnchorLocation(time);

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySpatialEntityEXT(spatialAnchorEntity));
```
```

--------------------------------

### Environment Raycaster Creation and Raycast Example

Source: https://registry.khronos.org/OpenXR/specs/1.1/pdf/xrspec.pdf

Complete example showing device support check, asynchronous raycaster creation, future polling, raycast execution with a distance filter, and cleanup. Uses XrInstance, XrSystemId, and XrSession previously initialized, and function pointers obtained via xrGetInstanceProcAddr.

```cpp
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
// The function pointers are previously initialized using xrGetInstanceProcAddr
PFN_xrCreateEnvironmentRaycasterAsyncMETA xrCreateEnvironmentRaycasterAsyncMETA;
PFN_xrCreateEnvironmentRaycasterCompleteMETA xrCreateEnvironmentRaycasterCompleteMETA;
PFN_xrDestroyEnvironmentRaycasterMETA xrDestroyEnvironmentRaycasterMETA;
PFN_xrPerformEnvironmentRaycastMETA xrPerformEnvironmentRaycastMETA;
PFN_xrPollFutureEXT xrPollFutureEXT;
// Check device support
XrSystemEnvironmentRaycastPropertiesMETA environmentRaycastProperties{
.type = XR_TYPE_SYSTEM_ENVIRONMENT_RAYCAST_PROPERTIES_META
};
XrSystemProperties systemProperties{
.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &environmentRaycastProperties,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (environmentRaycastProperties.supportsEnvironmentRaycast == XR_FALSE) {
return;
}
// Create a new environment raycaster
XrFutureEXT createFuture {XR_NULL_HANDLE};
XrEnvironmentRaycasterCreateInfoMETA createInfo = {
.type = XR_TYPE_ENVIRONMENT_RAYCASTER_CREATE_INFO_META,
};
CHK_XR(xrCreateEnvironmentRaycasterAsyncMETA(session, &createInfo, &createFuture));
// Wait for the future to be ready
bool futureReady = false;
while (!futureReady) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = createFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
futureReady = true;
} else {
// sleep(10);
}
}
// Complete future and get creation result
XrEnvironmentRaycasterCreateCompletionMETA completion = {
.type = XR_TYPE_ENVIRONMENT_RAYCASTER_CREATE_COMPLETION_META,
};
CHK_XR(xrCreateEnvironmentRaycasterCompleteMETA(session, createFuture, &completion));
CHK_XR(completion.futureResult); // Return code of the create function
XrEnvironmentRaycasterMETA raycaster = completion.environmentRaycaster;
// these are setup to match the location and time of the ray's origin and direction.

XrSpace localSpace; // previously initialized, e.g. from XR_REFERENCE_SPACE_TYPE_LOCAL
XrTime time; // previously initialized, e.g. from frameState.predictedDisplayTime
XrVector3f rayOrigin; // previously initialized
XrVector3f rayDirection; // previously initialized
// Perform an environment raycast operation
XrEnvironmentRaycastFilterDistanceMETA distanceFilter = {
.type = XR_TYPE_ENVIRONMENT_RAYCAST_FILTER_DISTANCE_META,
.maxDistance = 5.0f,
};
XrEnvironmentRaycastFilterBaseHeaderMETA* filters[] = {
reinterpret_cast<XrEnvironmentRaycastFilterBaseHeaderMETA*>(&distanceFilter)};
XrEnvironmentRaycastHitGetInfoMETA info = {
.type = XR_TYPE_ENVIRONMENT_RAYCAST_HIT_GET_INFO_META,
.baseSpace = localSpace,
.time = time,
.origin = rayOrigin,
.direction = rayDirection,
.filterCount = 1,
.filters = filters,
};
XrEnvironmentRaycastHitMETA hitPoint = {
.type = XR_TYPE_ENVIRONMENT_RAYCAST_HIT_META,
};
CHK_XR(xrPerformEnvironmentRaycastMETA(raycaster, &info, &hitPoint));
if (hitPoint.status == XR_ENVIRONMENT_RAYCAST_HIT_STATUS_HIT_META) {
// Do something with hitPoint, e.g. place a virtual object
}
// Destroy environment raycaster when no longer needed by the app
CHK_XR(xrDestroyEnvironmentRaycasterMETA(raycaster));
```

--------------------------------

### Create Spatial Anchor & Get Its Location

Source: https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html

Example code demonstrating how to create a spatial anchor and get its pose every frame.

```APIDOC
## Create Spatial Anchor & Get Its Location

### Description
Example code demonstrating how to create a spatial anchor and get its pose every frame.

### Code
```cpp
XrSpatialAnchorCreateInfoEXT createInfo {
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpatialEntityEXT spatialAnchorEntity {XR_NULL_HANDLE};
CHK_XR(xrCreateSpatialAnchorEXT(spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorEntity));

auto updateAnchorLocation = [&](XrTime time) {
  // We want to get updated data for all components of the entities, so skip specifying componentTypes.
  XrSpatialUpdateSnapshotCreateInfoEXT snapshotCreateInfo {
    .type = XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT,
    .entityCount = 1,
    .entities = &spatialAnchorEntity,
    .baseSpace = localSpace,
    .time = time,
  };

  XrSpatialSnapshotEXT snapshot {XR_NULL_HANDLE};
  CHK_XR(xrCreateSpatialUpdateSnapshotEXT(spatialContext, &snapshotCreateInfo, &snapshot));

  // Query for the entities that have the anchor component on them.
  std::array<XrSpatialComponentTypeEXT, 1> componentsToQuery {XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT};
  XrSpatialComponentDataQueryConditionEXT queryCond {
    .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
    .componentTypeCount = componentsToQuery.size(),
    .componentTypes = componentsToQuery.data(),
  };

  XrSpatialComponentDataQueryResultEXT queryResult {
    .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
  };
  CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

  std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
  std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
  queryResult.entityIdCapacityInput = entityIds.size();
  queryResult.entityIds = entityIds.data();
  queryResult.entityStateCapacityInput = entityStates.size();
  queryResult.entityStates = entityStates.data();

  // query for the pose data
  std::vector<XrPosef> locations(queryResult.entityIdCountOutput);
  XrSpatialComponentAnchorListEXT locationList {
    .type = XR_TYPE_SPATIAL_COMPONENT_ANCHOR_LIST_EXT,
    .locationCount = static_cast<uint32_t>(locations.size()),
    .locations = locations.data(),
  };
  queryResult.next = &locationList;

  CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

  for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
      // Pose for entity entityIds[i] is locations[i].
    }
  }

  CHK_XR(xrDestroySpatialSnapshotEXT(snapshot));
};


while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  updateAnchorLocation(time);

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySpatialEntityEXT(spatialAnchorEntity));
```
```

--------------------------------

### OpenXR View Configuration and Frame Loop Example

Source: https://registry.khronos.org/OpenXR/specs/1.1-khr/html/xrspec.html

Complete C++ example showing how to enumerate view configurations, select the primary stereo configuration, begin a session, and run a per-frame loop with view locating and layer submission. Uses CHK_XR for error checking and assumes previously initialized instance, system, session, and scene space.

```cpp
XrInstance instance; // previously initialized
XrSystemId system;   // previously initialized
XrSession session;   // previously initialized
XrSpace sceneSpace;  // previously initialized

// Enumerate the view configurations paths.
uint32_t configurationCount;
CHK_XR(xrEnumerateViewConfigurations(instance, system, 0, &configurationCount, nullptr));

std::vector<XrViewConfigurationType> configurationTypes(configurationCount);
CHK_XR(xrEnumerateViewConfigurations(instance, system, configurationCount, &configurationCount, configurationTypes.data()));

bool configFound = false;
XrViewConfigurationType viewConfig = XR_VIEW_CONFIGURATION_TYPE_MAX_ENUM;
for(uint32_t i = 0; i < configurationCount; ++i)
{
    if (configurationTypes[i] == XR_VIEW_CONFIGURATION_TYPE_PRIMARY_STEREO)
    {
        configFound = true;
        viewConfig = configurationTypes[i];
        break;  // Pick the first supported, i.e. preferred, view configuration.
    }
}

if (!configFound)
    return;   // Cannot support any view configuration of this system.

// Get detailed information of each view element.
uint32_t viewCount;
CHK_XR(xrEnumerateViewConfigurationViews(instance, system,
    viewConfig,
    0,
    &viewCount,
    nullptr));

std::vector<XrViewConfigurationView> configViews(viewCount, {
    .type = XR_TYPE_VIEW_CONFIGURATION_VIEW,
});
CHK_XR(xrEnumerateViewConfigurationViews(instance, system,
    viewConfig,
    viewCount,
    &viewCount,
    configViews.data()));

// Set the primary view configuration for the session.
XrSessionBeginInfo beginInfo {
    .type = XR_TYPE_SESSION_BEGIN_INFO,
    .primaryViewConfigurationType = viewConfig,
};
CHK_XR(xrBeginSession(session, &beginInfo));

// Allocate a buffer according to viewCount.
std::vector<XrView> views(viewCount, {
    .type = XR_TYPE_VIEW,
});

// Run a per-frame loop.
while (!quit)
{
    // Wait for a new frame.
    XrFrameWaitInfo frameWaitInfo {
        .type = XR_TYPE_FRAME_WAIT_INFO,
    };
    XrFrameState frameState {
        .type = XR_TYPE_FRAME_STATE,
    };
    CHK_XR(xrWaitFrame(session, &frameWaitInfo, &frameState));

    // Begin frame immediately before GPU work
    XrFrameBeginInfo frameBeginInfo {
        .type = XR_TYPE_FRAME_BEGIN_INFO,
    };
    CHK_XR(xrBeginFrame(session, &frameBeginInfo));

    std::vector<XrCompositionLayerBaseHeader*> layers;
    XrCompositionLayerProjectionView projViews[2] = { /*...*/ };
    XrCompositionLayerProjection layerProj {
        .type = XR_TYPE_COMPOSITION_LAYER_PROJECTION,
    };

    if (frameState.shouldRender) {
        XrViewLocateInfo viewLocateInfo {
            .type = XR_TYPE_VIEW_LOCATE_INFO,
            .viewConfigurationType = viewConfig,
            .displayTime = frameState.predictedDisplayTime,
            .space = sceneSpace,
        };

        XrViewState viewState{
            .type = XR_TYPE_VIEW_STATE,
        };
        XrView views[2] = { {.type = XR_TYPE_VIEW}, {.type = XR_TYPE_VIEW}};
        uint32_t viewCountOutput;
        CHK_XR(xrLocateViews(session, &viewLocateInfo, &viewState, configViews.size(), &viewCountOutput, views));

        // ...
        // Use viewState and frameState for scene render, and fill in projViews[2]
        // ...

        // Assemble composition layers structure
        layerProj.layerFlags = XR_COMPOSITION_LAYER_BLEND_TEXTURE_SOURCE_ALPHA_BIT;
        layerProj.space = sceneSpace;
        layerProj.viewCount = 2;
        layerProj.views = projViews;
        layers.push_back(reinterpret_cast<XrCompositionLayerBaseHeader*>(&layerProj));
    }

    // End frame and submit layers, even if layers is empty due to shouldRender = false
    XrFrameEndInfo frameEndInfo{
        .type = XR_TYPE_FRAME_END_INFO,
        .displayTime = frameState.predictedDisplayTime,
        .environmentBlendMode = XR_ENVIRONMENT_BLEND_MODE_OPAQUE,
        .layerCount = static_cast<uint32_t>(layers.size()),
        .layers = layers.data(),
    };
    CHK_XR(xrEndFrame(session, &frameEndInfo));
}
```
Tokens:
Raw