XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

Type d'extension

Extension d'instance

Numéro d'extension enregistré

787

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_EXT_spatial_entity

Date de dernière modification

2025-08-12

État de l'adresse IP

Aucune réclamation de propriété intellectuelle connue.

Participants

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

Présentation

Cette extension s'appuie sur XR_EXT_spatial_entity et fournit une fonctionnalité de raycast pour les fonctionnalités spatiales existantes, telles que XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , afin de découvrir des entités spatiales.

Cette extension introduit également une nouvelle fonctionnalité spatiale pour le raycasting sur le tampon de profondeur.

Autorisations

Autorisations requises en fonction des fonctionnalités utilisées par l'application Android. Si XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID est utilisé, l'application doit disposer de l'autorisation android.permission.SCENE_UNDERSTANDING_FINE. Si XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT est utilisé, l'application doit disposer de l'autorisation android.permission.SCENE_UNDERSTANDING_COARSE. L'autorisation android.permission.SCENE_UNDERSTANDING_FINE implique également l'autorisation android.permission.SCENE_UNDERSTANDING_COARSE. Si l'application utilise les deux fonctionnalités, elle n'a pas besoin de demander les deux autorisations séparément.

Les autorisations android.permission.SCENE_UNDERSTANDING_COARSE et android.permission.SCENE_UNDERSTANDING_FINE sont toutes deux considérées comme dangereuses.

(niveau de protection : dangereux)

Compatibilité des environnements d'exécution

Si l'environnement d'exécution accepte la découverte d'entités spatiales via le raycasting, il doit l'indiquer en énumérant XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID dans xrEnumerateSpatialCapabilityComponentTypesEXT pour les fonctionnalités qui acceptent la découverte par raycast.

Si l'environnement d'exécution est compatible avec le raycasting sur le tampon de profondeur, il doit énumérer XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID dans xrEnumerateSpatialCapabilitiesEXT .

Découvrir des entités spatiales par lancer de rayons

La structure XrSpatialRaycastInfoANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• space est l'XrSpace dans lequel se trouvera la pose de XrSpatialRaycastResultDataANDROID.
• time est un XrTime auquel la position de XrSpatialRaycastResultDataANDROID est définie.
• origin est un XrVector3f qui décrit l'origine du rayon.
• direction est un XrVector3f qui décrit la direction du rayon.
• maxDistance est la distance en mètres que l'application peut éventuellement spécifier pour limiter la découverte d'entités se trouvant à la distance spécifiée du origin , le long de direction .

Une application peut inclure XrSpatialRaycastInfoANDROID dans la chaîne XrSpatialDiscoverySnapshotCreateInfoEXT :: next pour découvrir les entités spatiales qui croisent le rayon défini dans cette structure.

Si une application utilise XrSpatialRaycastInfoANDROID avec un XrSpatialContextEXT configuré sans activer XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID pour une fonctionnalité, l'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT à partir de xrCreateSpatialDiscoverySnapshotAsyncEXT ou xrCreateSpatialRaycastSnapshotANDROID .

L'environnement d'exécution doit inclure les données de composant et les ID des entités spatiales dans XrSpatialSnapshotEXT qui proviennent de fonctionnalités compatibles avec le composant XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID.

Si une application définit maxDistance sur une valeur positive, l'environnement d'exécution ne doit pas inclure dans l'instantané d'entités spatiales touchées qui se trouvent à une distance supérieure à maxDistance de panme:origin le long de direction . Si maxDistance est défini sur 0 ou sur une valeur négative, l'environnement d'exécution doit considérer le rayon comme non limité.

Utilisation valide (implicite)

• L'extension XR_ANDROID_spatial_discovery_raycast doit être activée avant d'utiliser XrSpatialRaycastInfoANDROID.
• type doit être XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures
• space doit être un handle XrSpace valide

Composant de résultat de raycast

La structure XrSpatialRaycastResultDataANDROID est définie comme suit :

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

Descriptions des membres

• hitPose est un XrPosef définissant le point d'intersection du rayon avec l'entité spatiale.
• distanceSquared est le carré de la distance entre l'origine du rayon et le point d'intersection.

Le composant XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID ne sera présent que dans un XrSpatialSnapshotEXT créé à partir de xrCreateSpatialDiscoverySnapshotAsyncEXT où XrSpatialRaycastInfoANDROID est inclus dans la chaîne XrSpatialDiscoverySnapshotCreateInfoEXT :: next ou dans un XrSpatialSnapshotEXT créé à partir de xrCreateSpatialRaycastSnapshotANDROID .

L'environnement d'exécution ne doit pas inclure ce composant dans les XrSpatialSnapshotEXT créés à l'aide de xrCreateSpatialUpdateSnapshotEXT .

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrCreateSpatialUpdateSnapshotEXT si l'application inclut XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID dans XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

Si XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID n'est activé que pour certaines fonctionnalités, l'environnement d'exécution doit inclure uniquement les entités spatiales fournies par ces fonctionnalités dans l'instantané. Par exemple, si un objet et un plan sont alignés dans la même direction et que XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID n'est activé que pour XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , seul le plan sera détecté.

Le hitPose de XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID se trouvera dans XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace à l'emplacement XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time . L'axe Z positif est la normale de la surface d'impact, et l'axe Y négatif pointe approximativement vers l'origine du rayon.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_spatial_discovery_raycast doit être activée avant d'utiliser XrSpatialRaycastResultDataANDROID.

Structure de la liste des composants pour interroger les données

La structure XrSpatialComponentRaycastResultListANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• raycastResultCount est un uint32_t décrivant le nombre d'éléments dans le tableau raycastResults.
• raycastResults est un tableau de XrSpatialRaycastResultDataANDROID .

Pour interroger le composant de résultat du raycast des entités spatiales dans un XrSpatialSnapshotEXT , incluez XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID dans XrSpatialComponentDataQueryConditionEXT :: componentTypes et ajoutez XrSpatialComponentRaycastResultListANDROID à la chaîne XrSpatialComponentDataQueryResultEXT :: next.

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrQuerySpatialComponentDataEXT si XrSpatialComponentRaycastResultListANDROID se trouve dans la chaîne XrSpatialComponentDataQueryResultEXT :: next, mais que XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID n'est pas inclus dans XrSpatialComponentDataQueryConditionEXT :: componentTypes .

L'environnement d'exécution doit renvoyer XR_ERROR_SIZE_INSUFFICIENT à partir de xrQuerySpatialComponentDataEXT si raycastResultCount est inférieur à XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Les raycastResults renvoyés ne sont pas ordonnés. Une application peut utiliser XrSpatialRaycastResultDataANDROID :: distanceSquared pour trier les résultats par distance.

Utilisation valide (implicite)

•  L'extension XR_ANDROID_spatial_discovery_raycast doit être activée avant d'utiliser XrSpatialComponentRaycastResultListANDROID.
• type doit être XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures
• raycastResults doit être un pointeur vers un tableau de structures raycastResultCount XrSpatialRaycastResultDataANDROID
• Le paramètre raycastResultCount doit être supérieur à 0.

Configuration

Si XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID est énuméré dans XrSpatialCapabilityComponentTypesEXT :: componentTypes pour une fonctionnalité, l'application peut l'activer en incluant la valeur d'énumération dans la liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Ce composant ne nécessite aucune configuration spéciale pour être inclus dans la chaîne suivante de XrSpatialCapabilityConfigurationBaseHeaderEXT .

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE à partir de xrCreateSpatialUpdateSnapshotEXT si l'application inclut XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID dans XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Ce composant est spécifique aux instantanés de découverte.

Capacité spatiale Depth Raycast

Configuration

La structure XrSpatialCapabilityConfigurationDepthRaycastANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• capability est un XrSpatialCapabilityEXT et doit être XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .
• enabledComponentCount est un uint32_t décrivant le nombre d'éléments dans le tableau enabledComponents. Il doit être supérieur à 0.
• enabledComponents est un pointeur vers un tableau de XrSpatialComponentTypeEXT .

Les applications peuvent activer la fonctionnalité spatiale XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID en incluant un pointeur vers une structure XrSpatialCapabilityConfigurationDepthRaycastANDROID dans XrSpatialContextCreateInfoEXT :: capabilityConfigs .

L'environnement d'exécution doit renvoyer XR_ERROR_VALIDATION_FAILURE si capability n'est pas XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .

L'ID des entités découvertes via cette fonctionnalité est toujours XR_NULL_SPATIAL_ENTITY_ID_EXT . Cela signifie également que l'application ne peut pas créer de handle XrSpatialEntityEXT pour ces entités. Par conséquent, elles ne peuvent pas être incluses dans XrSpatialUpdateSnapshotCreateInfoEXT :: entities pour créer un instantané de mise à jour.

Utilisation valide (implicite)

• L'extension XR_ANDROID_spatial_discovery_raycast doit être activée avant d'utiliser XrSpatialCapabilityConfigurationDepthRaycastANDROID.
• type doit être XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures
• capability doit être une valeur XrSpatialCapabilityEXT valide
• enabledComponents doit être un pointeur vers un tableau de valeurs XrSpatialComponentTypeEXT valides enabledComponentCount
• Le paramètre enabledComponentCount doit être supérieur à 0.

Composants garantis

Un environnement d'exécution compatible avec XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID doit prendre en charge les composants spatiaux suivants en tant que composants garantis des entités découvertes par cette fonctionnalité et doit les énumérer dans xrEnumerateSpatialCapabilityComponentTypesEXT :

• XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Raycast synchrone

La fonction xrCreateSpatialRaycastSnapshotANDROID est définie comme suit :

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

Description des paramètres

• spatialContext est un XrSpatialContextEXT précédemment créé à l'aide de xrCreateSpatialContextAsyncEXT .
• createInfo est un pointeur vers un XrSpatialRaycastSnapshotCreateInfoANDROID .
• snapshot est un pointeur vers un XrSpatialSnapshotEXT .

Bien que xrCreateSpatialDiscoverySnapshotAsyncEXT soit suffisant pour la plupart des cas d'utilisation, il est considéré comme lent pour les applications qui nécessitent des résultats de raycast instantanés. xrCreateSpatialRaycastSnapshotANDROID lance un raycast synchrone pour créer un instantané, ce qui permet aux applications de commencer à interroger les résultats du raycast immédiatement.

L'environnement d'exécution doit renvoyer XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT si l'un des XrSpatialComponentTypeEXT dans XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes n'est pas activé pour les fonctionnalités spatiales transmises à XrSpatialContextCreateInfoEXT :: capabilityConfigs lors de la création de spatialContext .

Si l'application ne fournit pas de liste de types de composants spatiaux dans XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes , l'environnement d'exécution doit inclure toutes les entités spatiales de l'instantané qui possèdent l'ensemble de composants énumérés dans XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents pour les fonctionnalités compatibles avec le raycast configurées pour spatialContext . L'environnement d'exécution doit inclure les données de tous les composants activés des fonctionnalités compatibles avec le raycast configurées pour spatialContext .

Utilisation valide (implicite)

• L'extension XR_ANDROID_spatial_discovery_raycast doit être activée avant d'appeler xrCreateSpatialRaycastSnapshotANDROID.
• spatialContext doit être un handle XrSpatialContextEXT valide
• createInfo doit être un pointeur vers une structure XrSpatialRaycastSnapshotCreateInfoANDROID valide
• snapshot doit être un pointeur vers un handle XrSpatialSnapshotEXT

Codes renvoyés

Opération réussie

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Échec

• 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

La structure XrSpatialRaycastSnapshotCreateInfoANDROID est définie comme suit :

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

Descriptions des membres

• type est le XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures. Aucune structure de ce type n'est définie dans OpenXR de base ou dans cette extension.
• componentTypeCount est un uint32_t décrivant le nombre d'éléments dans le tableau componentTypes.
• componentTypes est un tableau de XrSpatialComponentTypeEXT .
• raycastInfo est la structure XrSpatialRaycastInfoANDROID décrivant les informations d'un rayon.

Utilisation valide (implicite)

• L'extension XR_ANDROID_spatial_discovery_raycast doit être activée avant d'utiliser XrSpatialRaycastSnapshotCreateInfoANDROID.
• type doit être XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID
• next doit être NULL ou un pointeur valide vers la structure suivante dans une chaîne de structures
• Si componentTypeCount n'est pas 0 , componentTypes doit être un pointeur vers un tableau de valeurs XrSpatialComponentTypeEXT valides componentTypeCount
• raycastInfo doit être un pointeur vers une structure XrSpatialRaycastInfoANDROID valide.

Exemple de code

Configurer la fonctionnalité de raycast de profondeur et de suivi de plan

L'exemple de code suivant montre comment créer un contexte spatial avec des fonctionnalités compatibles avec le raycasting. Dans cet exemple, XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID et XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT sont utilisés.

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

Découvrir les entités spatiales et interroger les données des composants

L'exemple de code suivant montre comment découvrir des entités spatiales pour un contexte configuré avec XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID et XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, et interroger les données de ses composants.

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

Créer un instantané Raycast

L'exemple de code suivant montre comment créer un instantané de lancer de rayons synchrone.

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

Nouvelles commandes

• xrCreateSpatialRaycastSnapshotANDROID

Nouvelles structures

• XrSpatialCapabilityConfigurationDepthRaycastANDROID
• XrSpatialRaycastResultDataANDROID
• XrSpatialRaycastSnapshotCreateInfoANDROID

• Extension de XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentRaycastResultListANDROID

• Extension de XrSpatialDiscoverySnapshotCreateInfoEXT :

  • XrSpatialRaycastInfoANDROID

Nouvelles constantes d'énumération

• XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAME
• XR_ANDROID_spatial_discovery_raycast_SPEC_VERSION

• Extension de XrSpatialCapabilityEXT :

  • XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

• Extension de XrSpatialComponentTypeEXT :

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

• Extension de 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

Problèmes

Historique des versions

• Révision 1, 15/07/2025 (Brian Chen)

  • Description initiale de l'extension.