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 或負值,執行階段「必須」將光線視為無界限。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_spatial_discovery_raycast擴充功能,才能使用 XrSpatialRaycastInfoANDROID -
type「必須」為XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 -
space「必須」是有效的 XrSpace 帳號代碼
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 軸則大致指向光線原點。
有效用途 (隱含)
- 必須先啟用
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 陣列的指標。
應用程式可以啟用 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_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
同步 Raycast
xrCreateSpatialRaycastSnapshotANDROID 函式的定義如下:
XrResult xrCreateSpatialRaycastSnapshotANDROID(
XrSpatialContextEXT spatialContext,
const XrSpatialRaycastSnapshotCreateInfoANDROID* createInfo,
XrSpatialSnapshotEXT* snapshot);
參數說明
spatialContext是先前使用 xrCreateSpatialContextAsyncEXT 建立的 XrSpatialContextEXT。createInfo是指向 XrSpatialRaycastSnapshotCreateInfoANDROID 的指標。snapshot是指向 XrSpatialSnapshotEXT 的指標。
雖然 xrCreateSpatialDiscoverySnapshotAsyncEXT 足以應付大多數用途,但對於需要即時光線投射結果的應用程式來說,速度可能不夠快。xrCreateSpatialRaycastSnapshotANDROID 會啟動同步光線投射來建立快照,讓應用程式能立即開始查詢光線投射結果。
建立 spatialContext 時,如果 XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes 中的任何 XrSpatialComponentTypeEXT 未針對傳遞至 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空間功能啟用,執行階段必須傳回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。
如果應用程式未在 XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes 中提供空間元件類型清單,執行階段必須在快照中納入所有空間實體,這些實體必須具備 XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents 中列舉的元件組合,用於為 spatialContext 設定的光線投射支援功能。執行階段必須包含 spatialContext 設定的 Raycast 支援功能中,所有已啟用元件的資料。
有效用途 (隱含)
- 必須先啟用
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 結構,用於描述光線資訊。
有效用途 (隱含)
- 必須先啟用
XR_ANDROID_spatial_discovery_raycast擴充功能,才能使用 XrSpatialRaycastSnapshotCreateInfoANDROID -
type「必須」為XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID -
next「必須」為NULL,或指向結構鏈中下一個結構的有效指標 - 如果
componentTypeCount不是0,componentTypes必須是指向componentTypeCount個有效 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);
新指令
新結構
- XrSpatialCapabilityConfigurationDepthRaycastANDROID
- XrSpatialRaycastResultDataANDROID
- XrSpatialRaycastSnapshotCreateInfoANDROID
新列舉常數
XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAMEXR_ANDROID_spatial_discovery_raycast_SPEC_VERSION-
XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID
-
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)
- 初始擴充功能說明。