XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

Erweiterungstyp

Instanzerweiterung

Registrierte Erweiterungsnummer

787

Revision

1

Ratifizierungsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

XR_EXT_spatial_entity

Datum der letzten Änderung

12.08.2025

IP-Status

Keine bekannten IP-Ansprüche.

Mitwirkende

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

Übersicht

Diese Erweiterung basiert auf XR_EXT_spatial_entity und bietet Raycast-Funktionen für vorhandene räumliche Funktionen wie XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , um räumliche Entitäten zu erkennen.

Diese Erweiterung führt auch eine neue räumliche Funktion für Raycasting gegen den Tiefenpuffer ein.

Berechtigungen

Erforderliche Berechtigungen je nach den Funktionen, die die Android-App verwendet. Wenn XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID verwendet wird, muss die Anwendung die Berechtigung android.permission.SCENE_UNDERSTANDING_FINE haben. Wenn XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT verwendet wird, muss die Anwendung die Berechtigung android.permission.SCENE_UNDERSTANDING_COARSE haben. Die Berechtigung android.permission.SCENE_UNDERSTANDING_FINE impliziert auch die Berechtigung android.permission.SCENE_UNDERSTANDING_COARSE. Wenn die Anwendung beide Funktionen verwendet, muss sie nicht beide Berechtigungen separat anfordern.

Sowohl android.permission.SCENE_UNDERSTANDING_COARSE als auch android.permission.SCENE_UNDERSTANDING_FINE gelten als gefährliche Berechtigungen.

(Schutzstufe: gefährlich)

Laufzeitunterstützung

Wenn die Laufzeit die Erkennung räumlicher Entitäten per Raycasting unterstützt, muss sie dies angeben, indem sie XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID in xrEnumerateSpatialCapabilityComponentTypesEXT für die Funktionen auflistet, die die Erkennung per Raycast unterstützen.

Wenn die Laufzeit Raycasting gegen den Tiefenpuffer unterstützt, muss sie XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID in xrEnumerateSpatialCapabilitiesEXT auflisten .

Räumliche Entitäten per Raycasting erkennen

Die Struktur XrSpatialRaycastInfoANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • space ist der XrSpace, in dem sich die Pose von XrSpatialRaycastResultDataANDROID befindet.
  • time ist ein XrTime, zu dem die Pose von XrSpatialRaycastResultDataANDROID definiert ist.
  • origin ist ein XrVector3f, der den Ursprung des Strahls beschreibt.
  • direction ist ein XrVector3f, der die Richtung des Strahls beschreibt.
  • maxDistance ist der Abstand in Metern, den die Anwendung optional angeben kann , um die Erkennung von Entitäten zu beschränken, die sich innerhalb des angegebenen Abstands vom origin entlang der direction befinden .

Eine Anwendung kann XrSpatialRaycastInfoANDROID in die Kette XrSpatialDiscoverySnapshotCreateInfoEXT :: next einfügen, um räumliche Entitäten zu erkennen, die sich mit dem in dieser Struktur definierten Strahl schneiden.

Wenn eine Anwendung XrSpatialRaycastInfoANDROID mit einem XrSpatialContextEXT verwendet, der ohne Aktivierung von XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID für eine Funktion konfiguriert wurde, muss die Laufzeit XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT von xrCreateSpatialDiscoverySnapshotAsyncEXT oder xrCreateSpatialRaycastSnapshotANDROID zurückgeben .

Die Laufzeit muss nur die Komponentendaten und IDs der räumlichen Entitäten in XrSpatialSnapshotEXT einfügen, die von Funktionen stammen, die die Komponente XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID unterstützen.

Wenn eine Anwendung maxDistance auf einen positiven Wert festlegt, darf die Laufzeit keine räumlichen Entitäten in den Snapshot einfügen, die mehr als maxDistance vom Ursprung entlang der direction entfernt sind . Wenn maxDistance auf 0 oder einen negativen Wert festgelegt ist, muss die Laufzeit den Strahl als unbegrenzt betrachten.

Gültige Verwendung (implizit)

Raycast-Ergebniskomponente

Die Struktur XrSpatialRaycastResultDataANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • hitPose ist ein XrPosef, der den Punkt definiert, an dem sich der Strahl mit der räumlichen Entität schneidet.
  • distanceSquared ist das Quadrat des Abstands vom Ursprung des Strahls zum Schnittpunkt.

Die XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID Komponente ist nur in einem XrSpatialSnapshotEXT vorhanden, der aus xrCreateSpatialDiscoverySnapshotAsyncEXT erstellt wurde, wobei XrSpatialRaycastInfoANDROID in der Kette XrSpatialDiscoverySnapshotCreateInfoEXT :: next enthalten ist, oder in einem XrSpatialSnapshotEXT, der aus xrCreateSpatialRaycastSnapshotANDROID erstellt wurde .

Die Laufzeit darf diese Komponente nicht in einen XrSpatialSnapshotEXT einfügen, der mit xrCreateSpatialUpdateSnapshotEXT erstellt wurde .

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrCreateSpatialUpdateSnapshotEXT zurückgeben, wenn die Anwendung XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes einfügt .

Wenn XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID nur für bestimmte Funktionen aktiviert ist, muss die Laufzeit nur räumliche Entitäten aus diesen Funktionen in den Snapshot einfügen. Wenn beispielsweise ein Objekt und eine Ebene in derselben Richtung ausgerichtet sind und XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID nur für XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT aktiviert ist, wird nur die Ebene erkannt.

Die hitPose von XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID befindet sich in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace bei XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time . Die positive Z-Achse ist die Normale der Trefferoberfläche und die negative Y-Achse zeigt ungefähr in Richtung des Ursprungs des Strahls.

Gültige Verwendung (implizit)

Struktur der Komponentenliste zum Abfragen von Daten

Die Struktur XrSpatialComponentRaycastResultListANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • raycastResultCount ist ein uint32_t, der die Anzahl der Elemente im Array raycastResults beschreibt.
  • raycastResults ist ein Array von XrSpatialRaycastResultDataANDROID .

Wenn Sie die Raycast-Ergebniskomponente der räumlichen Entitäten in einem XrSpatialSnapshotEXT abfragen möchten , fügen Sie XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID in XrSpatialComponentDataQueryConditionEXT :: componentTypes ein und fügen Sie XrSpatialComponentRaycastResultListANDROID zur Kette XrSpatialComponentDataQueryResultEXT :: next hinzu.

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrQuerySpatialComponentDataEXT zurückgeben, wenn XrSpatialComponentRaycastResultListANDROID in der Kette XrSpatialComponentDataQueryResultEXT :: next enthalten ist, aber XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID nicht in XrSpatialComponentDataQueryConditionEXT :: componentTypes enthalten ist .

Die Laufzeit muss XR_ERROR_SIZE_INSUFFICIENT von xrQuerySpatialComponentDataEXT zurückgeben, wenn raycastResultCount kleiner als XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput ist .

Die zurückgegebenen raycastResults sind nicht sortiert. Eine Anwendung kann XrSpatialRaycastResultDataANDROID :: distanceSquared verwenden, um die Ergebnisse nach Entfernung zu sortieren.

Gültige Verwendung (implizit)

Konfiguration

Wenn XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID in XrSpatialCapabilityComponentTypesEXT :: componentTypes für eine Funktion aufgelistet ist, kann die Anwendung sie aktivieren, indem sie den Enum-Wert in die Liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents einfügt. Für diese Komponente ist keine spezielle Konfiguration erforderlich, um sie in die nächste Kette von XrSpatialCapabilityConfigurationBaseHeaderEXT einzufügen .

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrCreateSpatialUpdateSnapshotEXT zurückgeben, wenn die Anwendung XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes einfügt . Diese Komponente ist spezifisch für Erkennungs-Snapshots.

Räumliche Funktion für Tiefen-Raycast

Konfiguration

Die Struktur XrSpatialCapabilityConfigurationDepthRaycastANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • capability ist ein XrSpatialCapabilityEXT und muss XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID sein .
  • enabledComponentCount ist ein uint32_t, der die Anzahl der Elemente im Array enabledComponents beschreibt. Er muss größer als 0 sein.
  • enabledComponents ist ein Zeiger auf ein Array von XrSpatialComponentTypeEXT .

Anwendungen können die XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID räumliche Funktion aktivieren, indem sie einen Zeiger auf eine XrSpatialCapabilityConfigurationDepthRaycastANDROID-Struktur in XrSpatialContextCreateInfoEXT :: capabilityConfigs einfügen .

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE zurückgeben, wenn capability nicht XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID ist .

Die ID von Entitäten, die mit dieser Funktion erkannt wurden, ist immer XR_NULL_SPATIAL_ENTITY_ID_EXT . Das bedeutet auch, dass Anwendungen keinen XrSpatialEntityEXT-Handle für diese Entitäten erstellen können und sie daher nicht in XrSpatialUpdateSnapshotCreateInfoEXT :: entities eingefügt werden können , um einen Update-Snapshot zu erstellen.

Gültige Verwendung (implizit)

Garantierte Komponenten

Eine Laufzeit, die XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID unterstützt, muss die folgenden räumlichen Komponenten als garantierte Komponenten der mit dieser Funktion erkannten Entitäten unterstützen und sie in xrEnumerateSpatialCapabilityComponentTypesEXT auflisten:

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Synchroner Raycast

Die Funktion xrCreateSpatialRaycastSnapshotANDROID ist so definiert:

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

Parameterbeschreibungen

Während xrCreateSpatialDiscoverySnapshotAsyncEXT für die meisten Anwendungsfälle ausreicht, gilt es für Anwendungen, die sofortige Raycast-Ergebnisse benötigen, als langsam. xrCreateSpatialRaycastSnapshotANDROID startet einen synchronen Raycast, um einen Snapshot zu erstellen, sodass Anwendungen sofort Raycast-Ergebnisse abfragen können.

Die Laufzeit muss XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT zurückgeben, wenn eine der XrSpatialComponentTypeEXT-Komponenten in XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes nicht für die räumlichen Funktionen aktiviert ist, die beim Erstellen von spatialContext an XrSpatialContextCreateInfoEXT :: capabilityConfigs übergeben wurden .

Wenn die Anwendung keine Liste von räumlichen Komponententypen in XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes bereitstellt, muss die Laufzeit alle räumlichen Entitäten in den Snapshot einfügen, die die Gruppe von Komponenten haben, die in XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents für Raycast-fähige Funktionen aufgelistet sind, die für spatialContext konfiguriert sind . Die Laufzeit muss die Daten für alle aktivierten Komponenten der Raycast-fähigen Funktionen einfügen, die für spatialContext konfiguriert sind .

Gültige Verwendung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • 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

Die Struktur XrSpatialRaycastSnapshotCreateInfoANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR Core oder dieser Erweiterung nicht definiert.
  • componentTypeCount ist ein uint32_t, der die Anzahl der Elemente im Array componentTypes beschreibt.
  • componentTypes ist ein Array von XrSpatialComponentTypeEXT .
  • raycastInfo ist die XrSpatialRaycastInfoANDROID-Struktur, die die Informationen eines Strahls beschreibt.

Gültige Verwendung (implizit)

Beispielcode

Funktion für Tiefen-Raycast und Ebenenverfolgung konfigurieren

Der folgende Beispielcode zeigt, wie ein räumlicher Kontext mit Funktionen erstellt wird, die Raycast-Funktionen unterstützen. In diesem Beispiel werden XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID und XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT verwendet.

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

Räumliche Entitäten erkennen und Komponentendaten abfragen

Der folgende Beispielcode zeigt, wie räumliche Entitäten für einen Kontext erkannt werden, der mit XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID und XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT konfiguriert wurde, und wie die zugehörigen Komponentendaten abgefragt werden.

// Fill in the raycast info.
XrSpatialRaycastInfoANDROID raycastInfo {
  .type        = XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID,
  .next        = nullptr,
  .space       = viewSpace,
  .time        = updateTime,
  .origin      = {0.0f, 0.0f, 0.0f},
  .direction   = {0.0f, 0.0f,-1.0f},
  .maxDistance = 0.0f  // ray is unbounded
};

// Next pointing to the raycast info.
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = &raycastInfo
};

// Create snapshot
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT (
spatialContext, &discoverySnapshotCreateInfo, &future));

waitUntilReady(future);

// Complete async operation.
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
  createSnapshotCompletionInfo {
    .type      = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
    .baseSpace = viewSpace,
    .time      = updateTime,
    .future    = future,
  };

XrCreateSpatialDiscoverySnapshotCompletionEXT completion {
  XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
           spatialContext, &createSnapshotCompletionInfo,
           &completion));

if(completion.futureResult != XR_SUCCESS) return;

// Query hit result components
std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
};

XrSpatialComponentDataQueryConditionEXT queryCond {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
  .componentTypeCount = 1,
  .componentTypes     = enabledComponents.data(),
};

XrSpatialComponentDataQueryResultEXT queryResult {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};

XrResult result = xrQuerySpatialComponentDataEXT(
           completion.snapshot, &queryCond, &queryResult);

// Check query result.
if(result != XR_SUCCESS) return;

// Query again for the hit result list.
std::vector<XrSpatialRaycastResultDataANDROID> raycastResults;
raycastResults.resize(queryResult.entityIdCountOutput);
XrSpatialComponentRaycastResultListANDROID raycastResultList {
  .type               = XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID,
  .raycastResultCount = (uint32_t)raycastResults.size(),
  .raycastResults     = raycastResults.data(),
};

queryResult.next = &raycastResultList;
result = xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult);

// Check query result again.
if(result != XR_SUCCESS) return;

std::vector<XrSpatialEntityEXT> hitEntities;
std::vector<XrPosef> depthHitPoses;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    // access raycastResults[i] for id & pose
    XrSpatialEntityIdEXT   id   = queryResult.entityIds[i];
    XrPosef                pose = raycastResults[i].hitPose;

    if (id != XR_NULL_SPATIAL_ENTITY_ID_EXT) {
        // hit entities (e.g. planes)
    // get entity handle via entity id
    XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
      .type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
      .entityId = id,
    };

    XrSpatialEntityEXT entity = XR_NULL_HANDLE;
    xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);

    hitEntities.push_back(entity);
  } else {
    // hit depth
    depthHitPoses.push_back(pose);
  }
}

// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);

Raycast-Snapshot erstellen

Der folgende Beispielcode zeigt, wie ein synchroner Raycast-Snapshot erstellt wird.

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

Neue Befehle

Neue Strukturen

Neue Enum-Konstanten

  • XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_raycast_SPEC_VERSION

  • Erweiterung von XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

  • Erweiterung von XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

  • Erweiterung von 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

Probleme

Versionsverlauf

  • Revision 1, 15.07.2025 (Brian Chen)

    • Erste Beschreibung der Erweiterung.