XR_ANDROID_spatial_discovery_raycast

String de nome

XR_ANDROID_spatial_discovery_raycast

Tipo de extensão

Extensão de instância

Número de extensão registrada

787

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_spatial_entity

Data da última modificação

2025-08-12

Status de IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

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

Visão geral

Essa extensão é baseada em XR_EXT_spatial_entity e oferece funcionalidade de raycast para recursos espaciais atuais, como XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , para descobrir entidades espaciais.

Essa extensão também apresenta um novo recurso espacial para raycasting em relação ao buffer de profundidade.

Permissões

Permissões necessárias dependendo dos recursos usados pelo app Android. Se XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID for usado, o aplicativo precisa ter a permissão android.permission.SCENE_UNDERSTANDING_FINE. Se XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT for usado, o aplicativo precisa ter a permissão android.permission.SCENE_UNDERSTANDING_COARSE. A permissão android.permission.SCENE_UNDERSTANDING_FINE também implica a permissão android.permission.SCENE_UNDERSTANDING_COARSE. Se o aplicativo usar os dois recursos, não será necessário solicitar as duas permissões separadamente.

As permissões android.permission.SCENE_UNDERSTANDING_COARSE e android.permission.SCENE_UNDERSTANDING_FINE são consideradas perigosas.

(nível de proteção: perigoso)

Suporte ao ambiente de execução

Se o ambiente de execução oferecer suporte à descoberta de entidades espaciais por raycasting, ele precisará indicar isso enumerando XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID em xrEnumerateSpatialCapabilityComponentTypesEXT para os recursos que oferecem suporte à descoberta por raycast.

Se o ambiente de execução oferecer suporte a raycasting em relação ao buffer de profundidade, ele precisará enumerar XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID em xrEnumerateSpatialCapabilitiesEXT .

Descobrir entidades espaciais por raycasting

A estrutura XrSpatialRaycastInfoANDROID é definida como:

typedef struct XrSpatialRaycastInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrVector3f         origin;
    XrVector3f         direction;
    float              maxDistance;
} XrSpatialRaycastInfoANDROID;

Descrições de membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• space é o XrSpace em que a pose de XrSpatialRaycastResultDataANDROID será localizada.
• time é um XrTime em que a pose de XrSpatialRaycastResultDataANDROID é definida.
• origin é um XrVector3f que descreve a origem do raio.
• direction é um XrVector3f que descreve a direção do raio.
• maxDistance é a distância em metros que o aplicativo pode especificar opcionalmente para limitar a descoberta de entidades que estão dentro da distância especificada da origin , ao longo da direction .

Um aplicativo pode incluir XrSpatialRaycastInfoANDROID na cadeia XrSpatialDiscoverySnapshotCreateInfoEXT :: next para descobrir entidades espaciais que se cruzam com o raio definido nessa estrutura.

Se um aplicativo usar XrSpatialRaycastInfoANDROID com um XrSpatialContextEXT configurado sem ativar XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID para qualquer recurso, o ambiente de execução precisará retornar XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT de xrCreateSpatialDiscoverySnapshotAsyncEXT ou xrCreateSpatialRaycastSnapshotANDROID .

O ambiente de execução precisará incluir os dados e IDs de componentes apenas dessas entidades espaciais em XrSpatialSnapshotEXT que vêm de recursos que oferecem suporte ao componente XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID.

Se um aplicativo definir maxDistance como um valor positivo, o ambiente de execução não poderá incluir entidades espaciais de acerto no snapshot que estejam a mais de maxDistance de distância do panme:origin ao longo da direction . Se maxDistance for definido como 0 ou um valor negativo, o ambiente de execução precisará considerar o raio ilimitado.

Uso válido (implícito)

• A extensão XR_ANDROID_spatial_discovery_raycast precisa ser ativada antes de usar XrSpatialRaycastInfoANDROID.
• type precisa ser XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• space precisa ser um identificador XrSpace válido.

Componente de resultado de raycast

A estrutura XrSpatialRaycastResultDataANDROID é definida como:

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

Descrições de membros

• hitPose é um XrPosef que define o ponto em que o raio se cruza com a entidade espacial.
• distanceSquared é o quadrado da distância da origem do raio até o ponto de interseção.

O componente XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID só estará presente em um XrSpatialSnapshotEXT criado em xrCreateSpatialDiscoverySnapshotAsyncEXT em que XrSpatialRaycastInfoANDROID está incluído na cadeia XrSpatialDiscoverySnapshotCreateInfoEXT :: next ou em um XrSpatialSnapshotEXT criado em xrCreateSpatialRaycastSnapshotANDROID .

O ambiente de execução não poderá incluir esse componente em nenhum XrSpatialSnapshotEXT criado usando xrCreateSpatialUpdateSnapshotEXT .

O ambiente de execução precisará retornar XR_ERROR_VALIDATION_FAILURE de xrCreateSpatialUpdateSnapshotEXT se o aplicativo incluir XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID em XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

Se XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID estiver ativado apenas para determinados recursos, o ambiente de execução precisará incluir apenas entidades espaciais fornecidas por esses recursos no snapshot. Por exemplo, se um objeto e uma linha de plano estiverem na mesma direção e XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID estiver ativado apenas para XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , apenas o plano será descoberto.

O hitPose do XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID estará localizado em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time . O eixo Z positivo é a normal da superfície de acerto, e o eixo Y negativo aponta aproximadamente para a origem do raio.

Uso válido (implícito)

• A extensão XR_ANDROID_spatial_discovery_raycast precisa ser ativada antes de usar XrSpatialRaycastResultDataANDROID

Estrutura da lista de componentes para consultar dados

A estrutura XrSpatialComponentRaycastResultListANDROID é definida como:

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

Descrições de membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• raycastResultCount é um uint32_t que descreve a contagem de elementos na matriz raycastResults.
• raycastResults é uma matriz de XrSpatialRaycastResultDataANDROID .

Para consultar o componente de resultado de raycast das entidades espaciais em um XrSpatialSnapshotEXT , inclua XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID em XrSpatialComponentDataQueryConditionEXT :: componentTypes e adicione XrSpatialComponentRaycastResultListANDROID à cadeia XrSpatialComponentDataQueryResultEXT :: next.

O ambiente de execução precisará retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentRaycastResultListANDROID estiver na cadeia XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisará retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se raycastResultCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Os raycastResults retornados não estão ordenados. Um aplicativo pode usar XrSpatialRaycastResultDataANDROID :: distanceSquared para classificar os resultados por distância.

Uso válido (implícito)

• A extensão XR_ANDROID_spatial_discovery_raycast precisa ser ativada antes de usar XrSpatialComponentRaycastResultListANDROID
• type precisa ser XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• raycastResults precisa ser um ponteiro para uma matriz de raycastResultCount estruturas XrSpatialRaycastResultDataANDROID
• O parâmetro raycastResultCount precisa ser maior que 0

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, o aplicativo poderá ativá-lo incluindo o valor de enumeração na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Esse componente não exige nenhuma configuração especial para ser incluído na próxima cadeia de XrSpatialCapabilityConfigurationBaseHeaderEXT .

O ambiente de execução precisará retornar XR_ERROR_VALIDATION_FAILURE de xrCreateSpatialUpdateSnapshotEXT se o aplicativo incluir XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID em XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Esse componente é específico para snapshots de descoberta.

Recurso espacial de raycast de profundidade

Configuração

A estrutura XrSpatialCapabilityConfigurationDepthRaycastANDROID é definida como:

typedef struct XrSpatialCapabilityConfigurationDepthRaycastANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationDepthRaycastANDROID;

Descrições de membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
• capability é um XrSpatialCapabilityEXT e precisa ser XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .
• enabledComponentCount é um uint32_t que descreve a contagem de elementos na matriz enabledComponents. Ele precisa ser maior que 0.
• enabledComponents é um ponteiro para uma matriz de XrSpatialComponentTypeEXT .

Os aplicativos podem ativar o recurso espacial XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID incluindo um ponteiro para uma estrutura XrSpatialCapabilityConfigurationDepthRaycastANDROID em XrSpatialContextCreateInfoEXT :: capabilityConfigs .

O ambiente de execução precisará retornar XR_ERROR_VALIDATION_FAILURE se capability não for XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .

O ID das entidades descobertas por esse recurso é sempre XR_NULL_SPATIAL_ENTITY_ID_EXT . Isso também significa que o aplicativo não pode criar um identificador XrSpatialEntityEXT para essas entidades e, portanto, elas não podem ser incluídas em XrSpatialUpdateSnapshotCreateInfoEXT :: entities para criar um snapshot de atualização.

Uso válido (implícito)

• A extensão XR_ANDROID_spatial_discovery_raycast precisa ser ativada antes de usar XrSpatialCapabilityConfigurationDepthRaycastANDROID.
• type precisa ser XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• capability precisa ser um valor XrSpatialCapabilityEXT válido
• enabledComponents precisa ser um ponteiro para uma matriz de enabledComponentCount valores XrSpatialComponentTypeEXT válidos
• O parâmetro enabledComponentCount precisa ser maior que 0

Componentes garantidos

Um ambiente de execução que oferece suporte a XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID , precisa oferecer suporte aos seguintes componentes espaciais como componentes garantidos das entidades descobertas por esse recurso e precisa enumerá-los em xrEnumerateSpatialCapabilityComponentTypesEXT -

• XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Raycast síncrono

A função xrCreateSpatialRaycastSnapshotANDROID é definida como:

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

Descrições de parâmetros

• spatialContext é um XrSpatialContextEXT criado anteriormente usando xrCreateSpatialContextAsyncEXT .
• createInfo é um ponteiro para um XrSpatialRaycastSnapshotCreateInfoANDROID .
• snapshot é um ponteiro para um XrSpatialSnapshotEXT .

Embora xrCreateSpatialDiscoverySnapshotAsyncEXT seja suficiente para a maioria dos casos de uso, ele é considerado lento para aplicativos que exigem resultados instantâneos de raycast. xrCreateSpatialRaycastSnapshotANDROID inicia um raycasting síncrono para criar um snapshot, o que permite que os aplicativos comecem a consultar os resultados de raycast imediatamente.

O ambiente de execução precisará retornar XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT se algum dos XrSpatialComponentTypeEXT em XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes não estiver ativado para os recursos espaciais transmitidos para XrSpatialContextCreateInfoEXT :: capabilityConfigs ao criar spatialContext .

Se o aplicativo não fornecer uma lista de tipos de componentes espaciais em XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes , o ambiente de execução precisará incluir todas as entidades espaciais no snapshot que têm o conjunto de componentes enumerados em XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents para recursos com suporte a raycast configurados para spatialContext . O ambiente de execução precisará incluir os dados de todos os componentes ativados dos recursos com suporte a raycast configurados para spatialContext .

Uso válido (implícito)

• A extensão XR_ANDROID_spatial_discovery_raycast precisa ser ativada antes de chamar xrCreateSpatialRaycastSnapshotANDROID.
• spatialContext precisa ser um identificador XrSpatialContextEXT válido.
• createInfo precisa ser um ponteiro para uma estrutura XrSpatialRaycastSnapshotCreateInfoANDROID válida.
• snapshot precisa ser um ponteiro para um identificador XrSpatialSnapshotEXT.

Códigos de retorno

Sucesso

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Falha

• 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

A estrutura XrSpatialRaycastSnapshotCreateInfoANDROID é definida como:

typedef struct XrSpatialRaycastSnapshotCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    uint32_t                              componentTypeCount;
    const XrSpatialComponentTypeEXT*      componentTypes;
    const XrSpatialRaycastInfoANDROID*    raycastInfo;
} XrSpatialRaycastSnapshotCreateInfoANDROID;

Descrições de membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no OpenXR principal ou nessa extensão.
• componentTypeCount é um uint32_t que descreve a contagem de elementos na matriz componentTypes.
• componentTypes é uma matriz de XrSpatialComponentTypeEXT .
• raycastInfo é a estrutura XrSpatialRaycastInfoANDROID que descreve as informações de um raio.

Uso válido (implícito)

• A extensão XR_ANDROID_spatial_discovery_raycast precisa ser ativada antes de usar XrSpatialRaycastSnapshotCreateInfoANDROID.
• type precisa ser XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID
• next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
• Se componentTypeCount não for 0 , componentTypes precisa ser um ponteiro para uma matriz de valores XrSpatialComponentTypeEXT válidos componentTypeCount.
• raycastInfo precisa ser um ponteiro para uma estrutura XrSpatialRaycastInfoANDROID válida.

Exemplo de código

Configurar o recurso de raycast de profundidade e rastreamento de plano

O exemplo de código a seguir demonstra como criar um contexto espacial com recursos que oferecem suporte à funcionalidade de raycast. Neste exemplo, XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID e XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT são usados.

// 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))

Descobrir entidades espaciais e consultar dados de componentes

O exemplo de código a seguir demonstra como descobrir entidades espaciais para um contexto configurado com XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID e XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT e consultar os dados do componente.

// 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);

Criar snapshot de raycast

O exemplo de código a seguir demonstra como criar um snapshot de raycast síncrono.

// 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);

Novos comandos

• xrCreateSpatialRaycastSnapshotANDROID

Novas estruturas

• XrSpatialCapabilityConfigurationDepthRaycastANDROID
• XrSpatialRaycastResultDataANDROID
• XrSpatialRaycastSnapshotCreateInfoANDROID

• Estendendo XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentRaycastResultListANDROID

• Estendendo XrSpatialDiscoverySnapshotCreateInfoEXT :

  • XrSpatialRaycastInfoANDROID

Novas constantes de enumeração

• XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAME
• XR_ANDROID_spatial_discovery_raycast_SPEC_VERSION

• Estendendo XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

• Estendendo XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

• Estendendo 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

Problemas

Histórico de versões

• Revisão 1, 15/07/2025 (Brian Chen)

  • Descrição inicial da extensão.