XR_ANDROID_spatial_discovery_raycast
名称字符串
XR_ANDROID_spatial_discovery_raycast
扩展类型
实例扩展程序
已注册的扩展程序编号
787
修订版本
1
批准状态
未获批准
扩展程序和版本依赖项
XR_EXT_spatial_entity
上次修改日期
2025-08-12
IP 状态
没有已知的 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是 XrSpatialRaycastResultDataANDROID 的姿态所在的 XrSpace。time是一个XrTime,用于定义 XrSpatialRaycastResultDataANDROID 的姿势。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 设置为正值,则运行时不得在快照中包含沿 direction 距离 panme:origin 超过 maxDistance 的任何命中空间实体。如果 maxDistance 设置为 0 或负值,运行时必须将光线视为无界。
有效使用情况(隐式)
- 必须先启用
XR_ANDROID_spatial_discovery_raycast扩展程序,然后才能使用 XrSpatialRaycastInfoANDROID -
type必须为XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID -
next必须是NULL或指向结构链中下一个结构的有效指针 -
space必须是有效的 XrSpace 句柄
Raycast Result 组件
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,则系统只会发现该平面。
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必须是指向raycastResultCount个 XrSpatialRaycastResultDataANDROID 结构的数组的指针 -
raycastResultCount参数必须大于0
配置
如果 XrSpatialCapabilityComponentTypesEXT :: componentTypes 中列举了某个功能,应用可以通过在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中包含相应枚举值来启用该功能。XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID此组件不需要任何特殊配置即可包含在下一个 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 的指针。snapshot是指向 XrSpatialSnapshotEXT 的指针。
虽然 xrCreateSpatialDiscoverySnapshotAsyncEXT 足以满足大多数使用情形,但对于需要即时光线投射结果的应用来说,它被认为速度较慢。xrCreateSpatialRaycastSnapshotANDROID 会启动同步光线投射来创建快照,从而使应用能够立即开始查询光线投射结果。
如果创建 spatialContext 时,传递给 XrSpatialContextCreateInfoEXT :: capabilityConfigs 的空间功能未启用 XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes 中的任何 XrSpatialComponentTypeEXT,运行时必须返回 XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT。
如果应用未在 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 结构,用于描述光线的信息。
有效使用情况(隐式)
-
XR_ANDROID_spatial_discovery_raycast扩展程序必须先启用,然后才能使用 XrSpatialRaycastSnapshotCreateInfoANDROID -
type必须为XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID -
next必须是NULL或指向结构链中下一个结构的有效指针 - 如果
componentTypeCount不为0,则componentTypes必须是指向包含componentTypeCount个有效 XrSpatialComponentTypeEXT 值的数组的指针 -
raycastInfo必须是指向有效 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
-
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)
- 初始扩展程序说明。