XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

787

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_EXT_spatial_entity

上次修改日期

2025-08-12

IP 狀態

沒有已知的智慧財產權聲明。

著作人

Brian Chen, Google
Levana Chen, Google
Kyle Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance

總覽

這項擴充功能以 XR_EXT_spatial_entity 為基礎,為現有的空間功能 (例如 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT) 提供光線投射功能,以便探索空間實體。

這項擴充功能也推出新的空間功能,可針對深度緩衝區進行光線投射。

權限

視 Android 應用程式使用的功能而定,可能需要特定權限。如果使用 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID,應用程式必須具備 android.permission.SCENE_UNDERSTANDING_FINE 權限。如果使用 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT,應用程式必須具備 android.permission.SCENE_UNDERSTANDING_COARSE 權限。android.permission.SCENE_UNDERSTANDING_FINE 也包含 android.permission.SCENE_UNDERSTANDING_COARSE 權限,如果應用程式同時使用這兩項功能,則不必分別要求這兩項權限。

android.permission.SCENE_UNDERSTANDING_COARSE 和 android.permission.SCENE_UNDERSTANDING_FINE 均視為危險權限。

(防護等級:危險)

執行階段支援

如果執行階段支援透過光線投射探索空間實體,則必須在 xrEnumerateSpatialCapabilityComponentTypesEXT 中列舉 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID,指出支援透過光線投射探索的功能。

如果執行階段支援對深度緩衝區進行光線投射,則必須在 xrEnumerateSpatialCapabilitiesEXT 中列舉 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID。

透過光線投射探索空間實體

XrSpatialRaycastInfoANDROID 結構定義如下:

typedef struct XrSpatialRaycastInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrVector3f         origin;
    XrVector3f         direction;
    float              maxDistance;
} XrSpatialRaycastInfoANDROID;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL,或指向結構鏈中下一個結構的指標。
  • space 是 XrSpace,XrSpatialRaycastResultDataANDROID 的姿勢會位於其中。
  • time 是 XrTime,用於定義 XrSpatialRaycastResultDataANDROID 的姿勢。
  • origin 是 XrVector3f,用於描述光線的原點。
  • direction 是 XrVector3f,用於描述光線方向。
  • maxDistance 是應用程式可選擇指定的距離 (以公尺為單位),用於限制探索與 origin 的距離在指定範圍內,且沿著 direction 的實體。

應用程式可以在 XrSpatialDiscoverySnapshotCreateInfoEXT :: next 鏈結中加入 XrSpatialRaycastInfoANDROID,探索與這個結構中定義的射線相交的空間實體。

如果應用程式使用 XrSpatialRaycastInfoANDROID,且 XrSpatialContextEXT 設定時未啟用任何功能的 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID,則執行階段必須從 xrCreateSpatialDiscoverySnapshotAsyncEXT 或 xrCreateSpatialRaycastSnapshotANDROID 傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。

執行階段必須包含 XrSpatialSnapshotEXT 中空間實體的元件資料和 ID,且這些實體必須來自支援 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 元件的功能。

如果應用程式將 maxDistance 設為正值,執行階段不得在快照中包含任何命中空間實體,這些實體沿著 direction 距離 panme:origin 超過 maxDistance。如果 maxDistance 設為 0 或負值,執行階段「必須」將光線視為無界限。

有效用途 (隱含)

Raycast 結果元件

XrSpatialRaycastResultDataANDROID 結構定義如下:

typedef struct XrSpatialRaycastResultDataANDROID {
    XrPosef    hitPose;
    float      distanceSquared;
} XrSpatialRaycastResultDataANDROID;

成員說明

  • hitPose 是 XrPosef,用於定義光線與空間實體相交的點。
  • distanceSquared 是從光線原點到交點的距離平方。

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 元件只會出現在 XrSpatialSnapshotEXT 中,該元件是由 xrCreateSpatialDiscoverySnapshotAsyncEXT 建立,其中 XrSpatialRaycastInfoANDROID 包含在 XrSpatialDiscoverySnapshotCreateInfoEXT :: next 鏈結中,或由 xrCreateSpatialRaycastSnapshotANDROID 建立的 XrSpatialSnapshotEXT 中。

執行階段不得在任何使用 xrCreateSpatialUpdateSnapshotEXT 建立的 XrSpatialSnapshotEXT 中加入這個元件。

如果應用程式在 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中包含 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID,執行階段必須從 xrCreateSpatialUpdateSnapshotEXT 傳回 XR_ERROR_VALIDATION_FAILURE。

如果只為特定功能啟用 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID,執行階段必須在快照中只納入這些功能提供的空間實體。舉例來說,如果物件和平面朝向相同方向,且 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 僅針對 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 啟用,則系統只會偵測到平面。

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 的 hitPose 位於 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace 的 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time。正 Z 軸是命中表面的法線,負 Y 軸則大致指向光線原點。

有效用途 (隱含)

用於查詢資料的元件清單結構

XrSpatialComponentRaycastResultListANDROID 結構定義如下:

typedef struct XrSpatialComponentRaycastResultListANDROID {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              raycastResultCount;
    XrSpatialRaycastResultDataANDROID*    raycastResults;
} XrSpatialComponentRaycastResultListANDROID;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL,或指向結構鏈中下一個結構的指標。
  • raycastResultCount 是 uint32_t,用於描述 raycastResults 陣列中的元素數量。
  • raycastResults 是 XrSpatialRaycastResultDataANDROID 的陣列。

如要查詢 XrSpatialSnapshotEXT 中空間實體的光線投射結果元件,請在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中加入 XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID,並將 XrSpatialComponentRaycastResultListANDROID 新增至 XrSpatialComponentDataQueryResultEXT :: next 鏈結。

如果 XrSpatialComponentRaycastResultListANDROID 位於 XrSpatialComponentDataQueryResultEXT :: next 鏈結中,但 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_VALIDATION_FAILURE。

如果 raycastResultCount 小於 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput,執行階段必須從 xrQuerySpatialComponentDataEXT 傳回 XR_ERROR_SIZE_INSUFFICIENT。

傳回的 raycastResults 沒有順序。應用程式可以使用 XrSpatialRaycastResultDataANDROID :: distanceSquared,依距離排序結果。

有效用途 (隱含)

設定

如果 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 列舉在 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中,代表某項功能,應用程式可以在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉值,啟用該功能。這個元件不需要任何特殊設定,即可納入 XrSpatialCapabilityConfigurationBaseHeaderEXT 的下一個鏈結。

如果應用程式在 XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes 中包含 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID,執行階段必須從 xrCreateSpatialUpdateSnapshotEXT 傳回 XR_ERROR_VALIDATION_FAILURE。這個元件僅適用於探索快照。

深度光線投射空間功能

設定

XrSpatialCapabilityConfigurationDepthRaycastANDROID 結構定義如下:

typedef struct XrSpatialCapabilityConfigurationDepthRaycastANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationDepthRaycastANDROID;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL,或指向結構鏈中下一個結構的指標。
  • capability 是 XrSpatialCapabilityEXT,且「必須」為 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID。
  • enabledComponentCount 是 uint32_t,用於描述 enabledComponents 陣列中的元素數量。必須大於 0。
  • enabledComponents 是指向 XrSpatialComponentTypeEXT 陣列的指標。

應用程式可以啟用 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID 空間功能,方法是在 XrSpatialContextCreateInfoEXT :: capabilityConfigs 中加入指向 XrSpatialCapabilityConfigurationDepthRaycastANDROID 結構的指標。

如果 capability 不是 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID,執行階段「必須」傳回 XR_ERROR_VALIDATION_FAILURE。

透過這項功能偵測到的實體 ID 一律為 XR_NULL_SPATIAL_ENTITY_ID_EXT。這也表示應用程式無法為這些實體建立 XrSpatialEntityEXT 控制代碼,因此無法將這些實體納入 XrSpatialUpdateSnapshotCreateInfoEXT :: entities 來建立更新快照

有效用途 (隱含)

保證元件

支援 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID 的執行階段必須支援下列空間元件,做為這項功能偵測到的實體保證元件,且必須在 xrEnumerateSpatialCapabilityComponentTypesEXT 中列舉這些元件 -

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

同步 Raycast

xrCreateSpatialRaycastSnapshotANDROID 函式的定義如下:

XrResult xrCreateSpatialRaycastSnapshotANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialRaycastSnapshotCreateInfoANDROID* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

參數說明

雖然 xrCreateSpatialDiscoverySnapshotAsyncEXT 足以應付大多數用途,但對於需要即時光線投射結果的應用程式來說,速度可能不夠快。xrCreateSpatialRaycastSnapshotANDROID 會啟動同步光線投射來建立快照,讓應用程式能立即開始查詢光線投射結果。

建立 spatialContext 時,如果 XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes 中的任何 XrSpatialComponentTypeEXT 未針對傳遞至 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空間功能啟用,執行階段必須傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。

如果應用程式未在 XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes 中提供空間元件類型清單,執行階段必須在快照中納入所有空間實體,這些實體必須具備 XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents 中列舉的元件組合,用於為 spatialContext 設定的光線投射支援功能。執行階段必須包含 spatialContext 設定的 Raycast 支援功能中,所有已啟用元件的資料。

有效用途 (隱含)

傳回代碼

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialRaycastSnapshotCreateInfoANDROID 結構定義如下:

typedef struct XrSpatialRaycastSnapshotCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    uint32_t                              componentTypeCount;
    const XrSpatialComponentTypeEXT*      componentTypes;
    const XrSpatialRaycastInfoANDROID*    raycastInfo;
} XrSpatialRaycastSnapshotCreateInfoANDROID;

成員說明

  • type 是這個結構的 XrStructureType。
  • next 是 NULL,或指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • componentTypeCount 是 uint32_t,用於描述 componentTypes 陣列中的元素數量。
  • componentTypes 是 XrSpatialComponentTypeEXT 的陣列。
  • raycastInfo 是 XrSpatialRaycastInfoANDROID 結構,用於描述光線資訊。

有效用途 (隱含)

範例程式碼

設定深度 Raycast 和平面追蹤功能

以下程式碼範例示範如何建立空間情境,並加入支援光線投射功能的能力。本範例使用的是 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID 和 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT。

// Check runtime supported capabilities
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID) == capabilities.end()) {
  return;
}

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Create capability config for depth raycasting
std::vector<XrSpatialComponentTypeEXT> depthRaycastComponents {
  XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
};

// Create capability config for depth raycasting
XrSpatialCapabilityConfigurationDepthRaycastANDROID depthRaycastConfig {
  .type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID,
  .enabledComponentCount = (uint32_t)depthRaycastComponents.size(),
  .enabledComponents = depthRaycastComponents.data(),
};

// Enumerate runtime supported components for plane tracking capability
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes {
  XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
};

bool isRaycastSupportedViaPlaneTracking;
std::vector<XrSpatialComponentTypeEXT> planeTrackingComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};

CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId,
       XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &capabilityComponentTypes));

planeTrackingComponents.resize(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = (uint32_t)planeTrackingComponents.size();
capabilityComponentTypes.componentTypes = planeTrackingComponents.data();

CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId,
       XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &capabilityComponentTypes));

// Check if raycast is supported by plane tracking
isRaycastSupportedViaPlaneTracking = std::find(planeTrackingComponents.begin(),
planeTrackingComponents.end(), XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID)
!= planeTrackingComponents.end();

// Create capability config for plane tracking
XrSpatialCapabilityConfigurationPlaneTrackingEXT planeTrackingConfig {
  .type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT,
  .enabledComponentCount = (uint32_t)planeTrackingComponents.size(),
  .enabledComponents = planeTrackingComponents.data(),
};

// Create spatial context
// Types of raycast is determined by configs included in XrSpatialContextCreateInfoEXT
// For this example, both plane raycast & depth raycast are performed
std::vector<const XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
capabilityConfigs.push_back(reinterpret_cast<const XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&depthRaycastConfig));
if(isRaycastSupportedViaPlaneTracking) capabilityConfigs.push_back(reinterpret_cast<const XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&planeTrackingConfig));

XrSpatialContextCreateInfoEXT contextCreateInfo {
  .type = XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT,
  .next = nullptr,
  .capabilityConfigCount = (uint32_t)capabilityConfigs.size(),
  .capabilityConfigs = capabilityConfigs.data(),
};

CHK_XR(xrCreateSpatialContextAsyncEXT(session, &contextCreateInfo, &future))

// Completes creating spatial context
XrCreateSpatialContextCompletionEXT contextCompletion{
XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialContextCompleteEXT(session, future, &contextCompletion))

探索空間實體和查詢元件資料

以下程式碼範例說明如何為設定 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID 和 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 的情境探索空間實體,並查詢其元件資料。

// Fill in the raycast info.
XrSpatialRaycastInfoANDROID raycastInfo {
  .type        = XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID,
  .next        = nullptr,
  .space       = viewSpace,
  .time        = updateTime,
  .origin      = {0.0f, 0.0f, 0.0f},
  .direction   = {0.0f, 0.0f,-1.0f},
  .maxDistance = 0.0f  // ray is unbounded
};

// Next pointing to the raycast info.
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = &raycastInfo
};

// Create snapshot
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT (
spatialContext, &discoverySnapshotCreateInfo, &future));

waitUntilReady(future);

// Complete async operation.
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
  createSnapshotCompletionInfo {
    .type      = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
    .baseSpace = viewSpace,
    .time      = updateTime,
    .future    = future,
  };

XrCreateSpatialDiscoverySnapshotCompletionEXT completion {
  XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
           spatialContext, &createSnapshotCompletionInfo,
           &completion));

if(completion.futureResult != XR_SUCCESS) return;

// Query hit result components
std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
};

XrSpatialComponentDataQueryConditionEXT queryCond {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
  .componentTypeCount = 1,
  .componentTypes     = enabledComponents.data(),
};

XrSpatialComponentDataQueryResultEXT queryResult {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};

XrResult result = xrQuerySpatialComponentDataEXT(
           completion.snapshot, &queryCond, &queryResult);

// Check query result.
if(result != XR_SUCCESS) return;

// Query again for the hit result list.
std::vector<XrSpatialRaycastResultDataANDROID> raycastResults;
raycastResults.resize(queryResult.entityIdCountOutput);
XrSpatialComponentRaycastResultListANDROID raycastResultList {
  .type               = XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID,
  .raycastResultCount = (uint32_t)raycastResults.size(),
  .raycastResults     = raycastResults.data(),
};

queryResult.next = &raycastResultList;
result = xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult);

// Check query result again.
if(result != XR_SUCCESS) return;

std::vector<XrSpatialEntityEXT> hitEntities;
std::vector<XrPosef> depthHitPoses;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    // access raycastResults[i] for id & pose
    XrSpatialEntityIdEXT   id   = queryResult.entityIds[i];
    XrPosef                pose = raycastResults[i].hitPose;

    if (id != XR_NULL_SPATIAL_ENTITY_ID_EXT) {
        // hit entities (e.g. planes)
    // get entity handle via entity id
    XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
      .type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
      .entityId = id,
    };

    XrSpatialEntityEXT entity = XR_NULL_HANDLE;
    xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);

    hitEntities.push_back(entity);
  } else {
    // hit depth
    depthHitPoses.push_back(pose);
  }
}

// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);

建立 Raycast 快照

以下程式碼範例說明如何建立同步光線投射快照。

// fill in create info
XrSpatialRaycastSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID,
  .componentTypeCount = 0,   // include all hit spatial entities
  .componentTypes = nullptr,
  .raycastInfo = &raycastInfo
};

// create raycast snapshot
XrSpatialSnapshotEXT raycastSnapshot = XR_NULL_HANDLE;
CHK_XR(xrCreateSpatialRaycastSnapshotANDROID(
  spatialContext, &createInfo, &raycastSnapshot));

// ...
// query component data as previous example
// ...

// Cleanup
xrDestroySpatialSnapshotEXT(raycastSnapshot);

新指令

新結構

新列舉常數

  • XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_raycast_SPEC_VERSION
  • 擴充 XrSpatialCapabilityEXT:

    • XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID
  • 擴充 XrSpatialComponentTypeEXT:

    • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
  • 擴充 XrStructureType:

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID
    • XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID
    • XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID
    • XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID

問題

版本記錄

  • 修訂版本 1,2025-07-15 (Brian Chen)

    • 初始擴充功能說明。