XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

787

Revision

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 считаются опасными.

(уровень защиты: опасный)

Поддержка среды выполнения

Если среда выполнения поддерживает обнаружение пространственных объектов с помощью трассировки лучей, она должна указывать это, перечисляя XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID в xrEnumerateSpatialCapabilityComponentTypesEXT для возможностей, поддерживающих обнаружение с помощью трассировки лучей.

Если среда выполнения поддерживает трассировку лучей в буфере глубины, она должна перечислять XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID в xrEnumerateSpatialCapabilitiesEXT .

Обнаружение пространственных объектов с помощью трассировки лучей

Структура 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 .

Приложение может включать XrSpatialRaycastInfoANDROID в цепочку XrSpatialDiscoverySnapshotCreateInfoEXT :: next, чтобы обнаруживать пространственные объекты, пересекающиеся с лучом, определенным в этой структуре.

Если приложение использует XrSpatialRaycastInfoANDROID с XrSpatialContextEXT, настроенным без включения XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID для любой функции, среда выполнения должна возвращать XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT из xrCreateSpatialDiscoverySnapshotAsyncEXT или xrCreateSpatialRaycastSnapshotANDROID .

Среда выполнения должна включать данные компонентов и идентификаторы только тех пространственных объектов в XrSpatialSnapshotEXT, которые получены от возможностей, поддерживающих компонент XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID.

Если приложение задает для maxDistance положительное значение, среда выполнения не должна включать в снимок пространственные объекты, которые находятся дальше от panme:origin вдоль direction, чем 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, или в XrSpatialSnapshotEXT, созданном из xrCreateSpatialRaycastSnapshotANDROID .

Среда выполнения не должна включать этот компонент ни в один объект XrSpatialSnapshotEXT, созданный с помощью xrCreateSpatialUpdateSnapshotEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrCreateSpatialUpdateSnapshotEXT, если приложение включает XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID в XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

Если XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID включено только для определенных возможностей, среда выполнения должна включать в снимок только пространственные объекты, предоставляемые этими возможностями. Например, если объект и плоскость выровнены в одном направлении и XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID включен только для XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , будет обнаружена только плоскость.

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 , включите XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавьте XrSpatialComponentRaycastResultListANDROID в цепочку XrSpatialComponentDataQueryResultEXT :: next.

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrQuerySpatialComponentDataEXT, если XrSpatialComponentRaycastResultListANDROID находится в цепочке XrSpatialComponentDataQueryResultEXT :: next, но XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID не включен в XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если raycastResultCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Возвращенные значения 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 .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrCreateSpatialUpdateSnapshotEXT, если приложение включает XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID в XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Этот компонент относится только к статистике по рекомендациям.

Пространственная возможность Depth Raycast

Конфигурация

Структура 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. Значение должно быть больше нуля.
• enabledComponents – указатель на массив XrSpatialComponentTypeEXT .

Приложения могут включить пространственную функцию XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID, добавив указатель на структуру XrSpatialCapabilityConfigurationDepthRaycastANDROID в XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если capability не равно XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .

Идентификатор объектов, обнаруженных с помощью этой функции, всегда равен 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 – это XrSpatialContextEXT, ранее созданный с помощью xrCreateSpatialContextAsyncEXT .
• createInfo – указатель на XrSpatialRaycastSnapshotCreateInfoANDROID .
• snapshot – указатель на XrSpatialSnapshotEXT .

Хотя xrCreateSpatialDiscoverySnapshotAsyncEXT подходит для большинства случаев, он считается медленным для приложений, которым требуются мгновенные результаты трассировки лучей. xrCreateSpatialRaycastSnapshotANDROID запускает синхронную трассировку лучей для создания снимка, что позволяет приложениям немедленно начать запрашивать результаты трассировки лучей.

Среда выполнения должна возвращать XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT, если какие-либо из XrSpatialComponentTypeEXT в XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes не включены для пространственных возможностей, переданных в XrSpatialContextCreateInfoEXT :: capabilityConfigs при создании spatialContext .

Если приложение не предоставляет список типов пространственных компонентов в XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes, среда выполнения должна включить в снимок все пространственные объекты, у которых есть набор компонентов, перечисленных в XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents для поддерживаемых возможностей raycast, настроенных для spatialContext . Среда выполнения должна включать данные для всех включенных компонентов поддерживаемых возможностей raycast, настроенных для spatialContext .

Допустимое использование (неявное)

• Расширение XR_ANDROID_spatial_discovery_raycast должно быть включено до вызова xrCreateSpatialRaycastSnapshotANDROID.
• spatialContext должен быть действительным дескриптором XrSpatialContextEXT.
• createInfo должен быть указателем на действительную структуру XrSpatialRaycastSnapshotCreateInfoANDROID.
• snapshot должен быть указателем на дескриптор XrSpatialSnapshotEXT.

Коды возврата

Выполнено

• 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, описывающая информацию о луче.

Допустимое использование (неявное)

• Перед использованием XrSpatialRaycastSnapshotCreateInfoANDROID необходимо включить расширение XR_ANDROID_spatial_discovery_raycast.
• type должно быть XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• Если componentTypeCount не равно 0 , componentTypes должен быть указателем на массив допустимых значений componentTypeCount XrSpatialComponentTypeEXT.
• raycastInfo должен быть указателем на действительную структуру XrSpatialRaycastInfoANDROID.

Пример кода

Настройте функцию Depth Raycast и отслеживание плоскостей

В примере кода ниже показано, как создать пространственный контекст с возможностями, поддерживающими функцию 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);

Новые команды

• xrCreateSpatialRaycastSnapshotANDROID

Новые структуры

• XrSpatialCapabilityConfigurationDepthRaycastANDROID
• XrSpatialRaycastResultDataANDROID
• XrSpatialRaycastSnapshotCreateInfoANDROID

• Расширение XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentRaycastResultListANDROID

• Расширение XrSpatialDiscoverySnapshotCreateInfoEXT :

  • XrSpatialRaycastInfoANDROID

Новые константы перечисления

• 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, 15 июля 2025 г. (Брайан Чен)

  • Начальное описание расширения.