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;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是結構鏈中下一個結構的指標。space是 XrSpace,用於存放 XrSpatialRaycastResultDataANDROID 的姿態。time是定義 XrSpatialRaycastResultDataANDROID 姿勢的XrTime。origin是 XrVector3f,用於說明光線的來源。direction是 XrVector3f,用於說明光線的方向。maxDistance是應用程式可選擇指定的距離 (以公尺為單位),用於限制探索origin指定距離內的實體 (沿direction)。
應用程式可以在 XrSpatialDiscoverySnapshotCreateInfoEXT :: next 鏈結中加入 XrSpatialRaycastInfoANDROID,以探索與這個結構體中定義的光線相交的空間實體。
如果應用程式使用 XrSpatialRaycastInfoANDROID,且 XrSpatialContextEXT 的設定未啟用任何功能,則執行階段必須從 xrCreateSpatialDiscoverySnapshotAsyncEXT 或 xrCreateSpatialRaycastSnapshotANDROID 傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。XR_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;
成員說明
hitPose是 XrPosef,用於定義光線與空間實體相交的點。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,系統只會探索平面。
hitPose 的 XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 會位於 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace,位於 XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time。正 Z 軸是擊中表面的法線,負 Y 軸大致指向射線原點。
有效使用 (隱含)
- 必須先啟用
XR_ANDROID_spatial_discovery_raycast擴充功能,才能使用 XrSpatialRaycastResultDataANDROID
元件清單結構體,用於查詢資料
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_ANDROID_spatial_discovery_raycast擴充功能,才能使用 XrSpatialComponentRaycastResultListANDROID -
type必須為XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 -
raycastResults必須是指向raycastResultCountXrSpatialRaycastResultDataANDROID 結構體陣列的指標 -
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。next是NULL,或是結構鏈中下一個結構的指標。capability是 XrSpatialCapabilityEXT,且必須為XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID。enabledComponentCount是uint32_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);
參數說明
spatialContext是先前使用 xrCreateSpatialContextAsyncEXT 建立的 XrSpatialContextEXT。createInfo是 XrSpatialRaycastSnapshotCreateInfoANDROID 的指標。- 是指向 XrSpatialSnapshotEXT 的指標。
snapshot
雖然 xrCreateSpatialDiscoverySnapshotAsyncEXT 足以應付大多數用途,但對於需要即時光線追蹤結果的應用程式來說,這項函式速度較慢。xrCreateSpatialRaycastSnapshotANDROID 會啟動同步光線追蹤來建立快照,讓應用程式立即開始查詢光線追蹤結果。
如果傳遞至 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空間功能未啟用 XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes 中的任何 XrSpatialComponentTypeEXT,執行階段「必須」傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT (建立 spatialContext 時)。
如果應用程式未在 XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes 中提供空間元件類型清單,執行階段必須在快照中納入所有空間實體,這些實體具有 XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents 中列舉的元件組合,適用於為 spatialContext 設定的光線投射支援功能。執行階段必須包含 spatialContext 設定的射線輪播支援功能中,所有已啟用元件的資料。
有效使用 (隱含)
- 必須先啟用
XR_ANDROID_spatial_discovery_raycast擴充功能,才能呼叫 xrCreateSpatialRaycastSnapshotANDROID -
spatialContext必須是有效的 XrSpatialContextEXT 控制代碼 -
createInfo必須是指向有效 XrSpatialRaycastSnapshotCreateInfoANDROID 結構體的指標 -
snapshot必須是指向 XrSpatialSnapshotEXT 控制代碼的指標
傳回代碼
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXTXR_ERROR_TIME_INVALIDXR_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 結構,說明光線的資訊。
有效使用 (隱含)
- 使用 XrSpatialRaycastSnapshotCreateInfoANDROID 前,
XR_ANDROID_spatial_discovery_raycast擴充功能必須啟用 -
type必須為XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID -
next必須是NULL,或是結構體鏈結中下一個結構體的有效指標 - 如果
componentTypeCount不是0,componentTypes必須是指向componentTypeCount個有效 XrSpatialComponentTypeEXT 值的陣列指標 -
raycastInfomust 是有效 XrSpatialRaycastInfoANDROID 結構體的指標
範例程式碼
設定深度光線投射和平面追蹤功能
以下範例程式碼示範如何建立空間環境,並支援光線投射功能。本範例使用 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);
新指令
新結構
- XrSpatialCapabilityConfigurationDepthRaycastANDROID
- XrSpatialRaycastResultDataANDROID
- XrSpatialRaycastSnapshotCreateInfoANDROID
新增列舉常數
XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAMEXR_ANDROID_spatial_discovery_raycast_SPEC_VERSION-
XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID
正在擴充 XrSpatialComponentTypeEXT:
XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
擴充 XrStructureType:
XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROIDXR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROIDXR_TYPE_SPATIAL_RAYCAST_INFO_ANDROIDXR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID
問題
版本記錄
修訂版本 1,2025-07-15 (Brian Chen)
- 擴充功能說明。