XR_ANDROID_spatial_discovery_raycast

Chaîne de nom

XR_ANDROID_spatial_discovery_raycast

Type d'extension

Extension d'instance

Numéro d'extension enregistré

787

Révision

1

État de ratification

Non ratifié

Dépendances d'extension et de version

XR_EXT_spatial_entity

Date de dernière modification

2025-08-12

État de la propriété intellectuelle

Aucune réclamation connue concernant la propriété intellectuelle.

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 lancer de rayons 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 lancer de rayons par rapport au 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 considérées comme dangereuses.

(niveau de protection : dangereux)

Compatibilité des environnements d'exécution

Si l'environnement d'exécution est compatible avec la découverte d'entités spatiales via le lancer de rayons, il doit l'indiquer en énumérant XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID dans xrEnumerateSpatialCapabilityComponentTypesEXT pour les fonctionnalités qui prennent en charge la découverte par lancer de rayons.

Si l'environnement d'exécution est compatible avec le lancer de rayons par rapport au 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 correspond au XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• space correspond au XrSpace dans lequel se trouvera la pose de XrSpatialRaycastResultDataANDROID.
• time correspond à un XrTime auquel la pose de XrSpatialRaycastResultDataANDROID est définie.
• origin correspond à un XrVector3f qui décrit l'origine du rayon.
• direction correspond à un XrVector3f qui décrit la direction du rayon.
• maxDistance correspond à la distance en mètres que l'application peut spécifier de manière facultative pour limiter la découverte d'entités qui se trouvent à la distance spécifiée de l'origin , le long de la 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 et les ID de composant uniquement pour les 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 d'entités spatiales touchées dans l'instantané qui se trouvent à plus de 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 illimité.

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 descripteur XrSpace valide.

Composant de résultat du lancer de rayons

La structure XrSpatialRaycastResultDataANDROID est définie comme suit :

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

Descriptions des membres

• hitPose correspond à un XrPosef définissant le point où le rayon croise l'entité spatiale.
• distanceSquared correspond au carré de la distance entre l'origine du rayon et le point d'intersection.

Le XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID composant n'est 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 un XrSpatialSnapshotEXT créé à 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 ne doit inclure que les entités spatiales fournies par ces fonctionnalités dans l'instantané. Par exemple, si un objet et un plan s'alignent 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écouvert.

Le hitPose de XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID se trouvera dans XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace à XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time . L'axe Z positif est la normale de la surface touchée, 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 liste de 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 correspond au XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• raycastResultCount correspond à un uint32_t décrivant le nombre d'éléments dans le tableau raycastResults.
• raycastResults correspond à un tableau de XrSpatialRaycastResultDataANDROID .

Pour interroger le composant de résultat du lancer de rayons 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 raycastResultCount structures 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 enum 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.

Fonctionnalité spatiale de lancer de rayons en profondeur

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 correspond au XrStructureType de cette structure.
• next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
• capability correspond à un XrSpatialCapabilityEXT et doit être XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .
• enabledComponentCount correspond à un uint32_t décrivant le nombre d'éléments dans le tableau enabledComponents. Il doit être supérieur à 0.
• enabledComponents correspond à 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 descripteur 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 enabledComponentCount valeurs XrSpatialComponentTypeEXT valides.
• 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 être compatible avec 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

Lancer de rayons synchrone

La fonction xrCreateSpatialRaycastSnapshotANDROID est définie comme suit :

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

Descriptions des paramètres

• spatialContext correspond à un XrSpatialContextEXT créé précédemment à l'aide de xrCreateSpatialContextAsyncEXT .
• createInfo correspond à un pointeur vers un XrSpatialRaycastSnapshotCreateInfoANDROID .
• snapshot correspond à 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 lancer de rayons instantanés. xrCreateSpatialRaycastSnapshotANDROID lance un lancer de rayons synchrone pour créer un instantané, ce qui permet aux applications de commencer à interroger immédiatement les résultats du lancer de rayons.

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 dans l'instantané qui comportent l'ensemble de composants énumérés dans XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents pour les fonctionnalités compatibles avec le lancer de rayons 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 lancer de rayons 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 descripteur XrSpatialContextEXT valide.
• createInfo doit être un pointeur vers une structure XrSpatialRaycastSnapshotCreateInfoANDROID valide.
• snapshot doit être un pointeur vers un descripteur 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 correspond au 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 le noyau OpenXR ni dans cette extension.
• componentTypeCount correspond à un uint32_t décrivant le nombre d'éléments dans le tableau componentTypes.
• componentTypes correspond à un tableau de XrSpatialComponentTypeEXT .
• raycastInfo correspond à 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 componentTypeCount valeurs XrSpatialComponentTypeEXT valides.
• raycastInfo doit être un pointeur vers une structure XrSpatialRaycastInfoANDROID valide.

Exemple de code

Configurer la fonctionnalité de lancer de rayons en 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 lancer de rayons. Pour 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 des entités spatiales et interroger les données de composant

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 comment interroger ses données de composant.

// 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é de lancer de rayons

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 XrSpatialDiscoverySnapshotSnapshotCreateInfoEXT :

  • XrSpatialRaycastInfoANDROID

Nouvelles constantes enum

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