XR_ANDROID_spatial_discovery_raycast

名稱字串

XR_ANDROID_spatial_discovery_raycast

擴充功能類型

執行個體擴充功能

擴充功能註冊編號

787

修訂版本

1

批准狀態

未批准

擴充功能和版本依附元件

XR_EXT_spatial_entity

上次修改日期

2025-08-12

IP 狀態

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

著作人

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

總覽

這項擴充功能以 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;

成員說明

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

如果應用程式使用 XrSpatialRaycastInfoANDROID,且 XrSpatialContextEXT 的設定未啟用任何功能,則執行階段必須xrCreateSpatialDiscoverySnapshotAsyncEXTxrCreateSpatialRaycastSnapshotANDROID 傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXTXR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

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

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

有效使用 (隱含)

  • 使用 XrSpatialRaycastInfoANDROID 前,XR_ANDROID_spatial_discovery_raycast 擴充功能必須啟用
  • type 必須XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • space 必須是有效的 XrSpace 控制代碼

光線投射結果元件

XrSpatialRaycastResultDataANDROID 結構體的定義如下:

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

成員說明

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

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 元件只會出現在從 xrCreateSpatialDiscoverySnapshotAsyncEXT 建立的 XrSpatialSnapshotEXT 中,其中 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_CAPABILITY_PLANE_TRACKING_EXT 啟用 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID,系統只會探索平面。

hitPoseXR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 會位於 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace,位於 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time。正 Z 軸是擊中表面的法線,負 Y 軸大致指向射線原點。

有效使用 (隱含)

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

XrSpatialComponentRaycastResultListANDROID 結構體的定義如下:

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

成員說明

  • type 是這個結構的 XrStructureType
  • nextNULL,或是結構鏈中下一個結構的指標。
  • raycastResultCountuint32_t,說明 raycastResults 陣列中的元素數量。
  • raycastResultsXrSpatialRaycastResultDataANDROID 的陣列。

如要查詢 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_ANDROID_spatial_discovery_raycast 擴充功能,才能使用 XrSpatialComponentRaycastResultListANDROID
  • type 必須XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • raycastResults 必須是指向 raycastResultCount XrSpatialRaycastResultDataANDROID 結構體陣列的指標
  • raycastResultCount 參數必須大於 0

設定

如果 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
  • nextNULL,或是結構鏈中下一個結構的指標。
  • capabilityXrSpatialCapabilityEXT,且必須XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID
  • enabledComponentCountuint32_t,說明 enabledComponents 陣列中的元素數量。必須大於 0。
  • enabledComponents 是指向 XrSpatialComponentTypeEXT 陣列的指標。

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

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

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

有效使用 (隱含)

  • XR_ANDROID_spatial_discovery_raycast 擴充功能必須先啟用,才能使用 XrSpatialCapabilityConfigurationDepthRaycastANDROID
  • type 必須XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • capability 必須是有效的 XrSpatialCapabilityEXT
  • enabledComponents 必須是指向 enabledComponentCount 個有效 XrSpatialComponentTypeEXT 值的陣列的指標
  • enabledComponentCount 參數必須大於 0

保證元件

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

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

同步光線投射

xrCreateSpatialRaycastSnapshotANDROID 函式定義如下:

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

參數說明

雖然 xrCreateSpatialDiscoverySnapshotAsyncEXT 足以應付大多數用途,但對於需要即時光線追蹤結果的應用程式來說,這項函式速度較慢。xrCreateSpatialRaycastSnapshotANDROID 會啟動同步光線追蹤來建立快照,讓應用程式立即開始查詢光線追蹤結果。

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

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

有效使用 (隱含)

傳回代碼

成功

  • 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
  • nextNULL,或是指向結構鏈中下一個結構的指標。核心 OpenXR 或這個擴充功能中未定義這類結構。
  • componentTypeCountuint32_t,說明 componentTypes 陣列中的元素數量。
  • componentTypesXrSpatialComponentTypeEXT 的陣列。
  • raycastInfoXrSpatialRaycastInfoANDROID 結構,說明光線的資訊。

有效使用 (隱含)

  • 使用 XrSpatialRaycastSnapshotCreateInfoANDROID 前,XR_ANDROID_spatial_discovery_raycast 擴充功能必須啟用
  • type 必須XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID
  • next 必須NULL,或是結構體鏈結中下一個結構體的有效指標
  • 如果 componentTypeCount 不是 0componentTypes 必須是指向 componentTypeCount 個有效 XrSpatialComponentTypeEXT 值的陣列指標
  • raycastInfo must 是有效 XrSpatialRaycastInfoANDROID 結構體的指標

範例程式碼

設定深度光線投射和平面追蹤功能

以下範例程式碼示範如何建立空間環境,並支援光線投射功能。本範例使用 XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROIDXR_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_ANDROIDXR_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)

    • 擴充功能說明。