C Specification

The xrComputeNewSceneMSFT function begins the compute of a new scene and the runtime must return quickly without waiting for the compute to complete. The application should use xrGetSceneComputeStateMSFT to inspect the compute status.

The application can control the compute features by passing a list of XrSceneComputeFeatureMSFT via XrNewSceneComputeInfoMSFT::requestedFeatures.

  • If XR_SCENE_COMPUTE_FEATURE_PLANE_MSFT is passed, but XR_SCENE_COMPUTE_FEATURE_PLANE_MESH_MSFT is not passed, then:

    • The application may be able to read XR_SCENE_COMPONENT_TYPE_PLANE_MSFT and XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT scene components from the resulting XrSceneMSFT handle.

    • XrScenePlaneMSFT::meshBufferId must be zero to indicate that the plane scene component does not have a mesh buffer available to read.

  • If XR_SCENE_COMPUTE_FEATURE_PLANE_MSFT and XR_SCENE_COMPUTE_FEATURE_PLANE_MESH_MSFT are passed, then:

    • the application may be able to read XR_SCENE_COMPONENT_TYPE_PLANE_MSFT and XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT scene components from the resulting XrSceneMSFT handle

    • XrScenePlaneMSFT::meshBufferId may contain a non-zero mesh buffer identifier to indicate that the plane scene component has a mesh buffer available to read.

  • If XR_SCENE_COMPUTE_FEATURE_VISUAL_MESH_MSFT is passed then:

    • the application may be able to read XR_SCENE_COMPONENT_TYPE_VISUAL_MESH_MSFT and XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT scene components from the resulting XrSceneMSFT handle.

  • If XR_SCENE_COMPUTE_FEATURE_COLLIDER_MESH_MSFT is passed then:

    • the application may be able to read XR_SCENE_COMPONENT_TYPE_COLLIDER_MESH_MSFT and XR_SCENE_COMPONENT_TYPE_OBJECT_MSFT scene components from the resulting XrSceneMSFT handle.

// Provided by XR_MSFT_scene_understanding
XrResult xrComputeNewSceneMSFT(
    XrSceneObserverMSFT                         sceneObserver,
    const XrNewSceneComputeInfoMSFT*            computeInfo);

Parameters

Parameter Descriptions

Description

The runtime must return XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT if incompatible features were passed or no compatible features were passed.

The runtime must return XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT if XR_SCENE_COMPUTE_FEATURE_PLANE_MESH_MSFT was passed but XR_SCENE_COMPUTE_FEATURE_PLANE_MSFT was not passed.

The runtime must return XR_ERROR_COMPUTE_NEW_SCENE_NOT_COMPLETED_MSFT if xrComputeNewSceneMSFT is called while the scene computation is in progress.

An application that wishes to use XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT must create an XrSceneObserverMSFT handle that passes neither XR_SCENE_COMPUTE_CONSISTENCY_SNAPSHOT_COMPLETE_MSFT nor XR_SCENE_COMPUTE_CONSISTENCY_SNAPSHOT_INCOMPLETE_FAST_MSFT to xrComputeNewSceneMSFT for the lifetime of that XrSceneObserverMSFT handle. This allows the runtime to return occlusion mesh at a different cadence than non-occlusion mesh or planes.

  • The runtime must return XR_ERROR_SCENE_COMPUTE_CONSISTENCY_MISMATCH_MSFT if:

  • The runtime must return XR_ERROR_SCENE_COMPUTE_CONSISTENCY_MISMATCH_MSFT if:

  • The runtime must return XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT if:

    • XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT is passed to xrComputeNewSceneMSFT and

    • neither XR_SCENE_COMPUTE_FEATURE_VISUAL_MESH_MSFT nor XR_SCENE_COMPUTE_FEATURE_COLLIDER_MESH_MSFT are also passed.

  • The runtime must return XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT if:

    • XR_SCENE_COMPUTE_CONSISTENCY_OCCLUSION_OPTIMIZED_MSFT is passed to xrComputeNewSceneMSFT and

    • at least one of XR_SCENE_COMPUTE_FEATURE_SERIALIZE_SCENE_MSFT, XR_SCENE_COMPUTE_FEATURE_PLANE_MSFT, XR_SCENE_COMPUTE_FEATURE_PLANE_MESH_MSFT, or XR_SCENE_COMPUTE_FEATURE_SERIALIZE_SCENE_MSFT are also passed.

Valid Usage (Implicit)
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_TIME_INVALID

  • XR_ERROR_SCENE_COMPUTE_FEATURE_INCOMPATIBLE_MSFT

  • XR_ERROR_SCENE_COMPUTE_CONSISTENCY_MISMATCH_MSFT

  • XR_ERROR_POSE_INVALID

  • XR_ERROR_COMPUTE_NEW_SCENE_NOT_COMPLETED_MSFT

See Also

XR_MSFT_scene_understanding, XrNewSceneComputeInfoMSFT, XrSceneObserverMSFT, xrEnumerateSceneComputeFeaturesMSFT

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

Copyright 2014-2024, The Khronos Group Inc.

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