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 ramal registrado

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 do IP

Nenhuma reivindicação de PI 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 se baseia em XR_EXT_spatial_entity e oferece a funcionalidade de raycast para recursos espaciais, como XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , para descobrir entidades espaciais.

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

Permissões

Permissões necessárias dependendo dos recursos que o app Android usa. 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 precisa 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 for compatível com raycasting no buffer de profundidade, ele precisa 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 dos 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 para limitar a descoberta de entidades que estão dentro da distância especificada do origin , ao longo de direction .

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

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

O ambiente de execução precisa incluir os dados e os IDs de componentes apenas das entidades espaciais em XrSpatialSnapshotEXT que vêm de recursos compatíveis com o componente XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID.

Se um aplicativo definir maxDistance como um valor positivo, o ambiente de execução não pode incluir no snapshot nenhuma entidade espacial atingida que esteja a mais de maxDistance de distância de panme:origin ao longo de direction . Se maxDistance for definido como 0 ou um valor negativo, o ambiente de execução precisará considerar o raio como 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 do Raycast

A estrutura XrSpatialRaycastResultDataANDROID é definida como:

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

Descrições dos 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ó vai estar presente em um XrSpatialSnapshotEXT criado de xrCreateSpatialDiscoverySnapshotAsyncEXT em que XrSpatialRaycastInfoANDROID está incluído na cadeia XrSpatialDiscoverySnapshotCreateInfoEXT :: next ou em um XrSpatialSnapshotEXT criado de xrCreateSpatialRaycastSnapshotANDROID .

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

O ambiente de execução precisa 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 as entidades espaciais fornecidas por esses recursos no snapshot. Por exemplo, se um objeto e um plano estiverem alinhados na mesma direção e XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID estiver ativado apenas para XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , somente o plano será descoberto.

O hitPose do XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID vai estar localizado em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace em XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time . O eixo Z positivo é o normal da superfície de colisão, 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 dos 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 do 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 precisa 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 precisa 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 estruturas raycastResultCount 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 do tipo enumerado na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Esse componente não requer nenhuma configuração especial para ser incluído na próxima cadeia de XrSpatialCapabilityConfigurationBaseHeaderEXT .

O ambiente de execução precisa 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 dos 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 precisa 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. 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 valores enabledComponentCount válidos de XrSpatialComponentTypeEXT
• O parâmetro enabledComponentCount precisa ser maior que 0.

Componentes garantidos

Um ambiente de execução compatível com 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 dos 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. O xrCreateSpatialRaycastSnapshotANDROID inicia um raycast síncrono para criar um snapshot, o que permite que os aplicativos comecem a consultar os resultados do raycast imediatamente.

O ambiente de execução precisa 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 tenham o conjunto de componentes enumerados em XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents para recursos compatíveis com raycast configurados para spatialContext . O ambiente de execução precisa incluir os dados de todos os componentes ativados dos recursos compatíveis com 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 dos membros

• type é o XrStructureType dessa estrutura.
• next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta 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 componentTypeCount válidos de XrSpatialComponentTypeEXT.
• 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 tipo enumerado

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