XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

787

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_EXT_spatial_entity

Datum der letzten Änderung

12.08.2025

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

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 baut auf XR_EXT_spatial_entity auf und bietet Raycast-Funktionen für vorhandene räumliche Funktionen wie XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, um räumliche Entitäten zu erkennen.

Mit dieser Erweiterung wird auch eine neue räumliche Funktion für Raycasting gegen den Tiefenpuffer eingeführt.

Berechtigungen

Erforderliche Berechtigungen, je nachdem, welche Funktionen 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.

(Schutzebene: 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 aufzählt, die die Erkennung per Raycast unterstützen.

Wenn die Laufzeitumgebung Raycasting für 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, an 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 die Entfernung in Metern, die die Anwendung optional angeben kann, um die Suche nach Entitäten einzuschränken, die sich innerhalb der angegebenen Entfernung vom origin entlang direction befinden.

Eine Anwendung kann XrSpatialRaycastInfoANDROID in die XrSpatialDiscoverySnapshotCreateInfoEXT :: next-Kette einfügen, um räumliche Entitäten zu finden, 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 die Komponentendaten und IDs nur der räumlichen Entitäten in XrSpatialSnapshotEXT enthalten, die von Funktionen stammen, die die Komponente XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID unterstützen.

Wenn eine Anwendung maxDistance auf einen positiven Wert setzt, darf die Laufzeit keine räumlichen Entitäten in den Snapshot aufnehmen, die entlang direction mehr als maxDistance von panme:origin 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 der Strahl die räumliche Entität schneidet.
  • distanceSquared ist das Quadrat der Entfernung vom Ursprung des Strahls zum Schnittpunkt.

Die Komponente XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID 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 XrSpatialSnapshotEXT-Objekten enthalten, die mit xrCreateSpatialUpdateSnapshotEXT erstellt wurden.

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrCreateSpatialUpdateSnapshotEXT zurückgeben, wenn die Anwendung XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes enthält.

Wenn XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID nur für bestimmte Funktionen aktiviert ist, darf die Laufzeit nur räumliche Entitäten, die von diesen Funktionen bereitgestellt werden, in den Snapshot aufnehmen. 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.

Der hitPose des 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 Strahlursprungs.

Gültige Verwendung (implizit)

Komponentenlistenstruktur 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 sich XrSpatialComponentRaycastResultListANDROID in der XrSpatialComponentDataQueryResultEXT :: next-Kette befindet, 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 ungeordnet. 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 bestimmte Funktion aufgeführt ist, kann die Anwendung sie aktivieren, indem sie den Enum-Wert in die Liste XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents aufnimmt. Für diese Komponente ist keine spezielle Konfiguration erforderlich, um in die nächste Kette von XrSpatialCapabilityConfigurationBaseHeaderEXT aufgenommen zu werden.

Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrCreateSpatialUpdateSnapshotEXT zurückgeben, wenn die Anwendung XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes enthält. Diese Komponente ist spezifisch für Discovery-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 räumliche Funktion XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID 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 über diese Funktion erkannt werden, ist immer XR_NULL_SPATIAL_ENTITY_ID_EXT . Das bedeutet auch, dass die Anwendung für diese Entitäten kein XrSpatialEntityEXT-Handle erstellen kann und sie daher nicht in XrSpatialUpdateSnapshotCreateInfoEXT :: entities aufgenommen werden können, um einen Aktualisierungs-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 von dieser Funktion erkannten Entitäten unterstützen und muss sie in xrEnumerateSpatialCapabilityComponentTypesEXT aufzählen:

  • 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

xrCreateSpatialDiscoverySnapshotAsyncEXT ist für die meisten Anwendungsfälle ausreichend, wird aber für Anwendungen, die sofortige Raycast-Ergebnisse erfordern, als langsam angesehen. xrCreateSpatialRaycastSnapshotANDROID startet ein synchrones Raycasting, um einen Snapshot zu erstellen, sodass Anwendungen sofort mit der Abfrage von Raycast-Ergebnissen beginnen können.

Die Laufzeit muss XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT zurückgeben, wenn einer der XrSpatialComponentTypeEXT-Werte 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 in XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes keine Liste von räumlichen Komponententypen bereitstellt, muss die Laufzeit alle räumlichen Entitäten in den Snapshot aufnehmen, die die in XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents für Raycast-unterstützte Funktionen, die für spatialContext konfiguriert sind, aufgeführten Komponenten enthalten. Die Laufzeit muss die Daten für alle aktivierten Komponenten der unterstützten Raycast-Funktionen enthalten, 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 weder in OpenXR noch in dieser Erweiterung 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

Depth Raycast und Plane Tracking konfigurieren

Der folgende Beispielcode zeigt, wie Sie einen räumlichen Kontext mit Funktionen erstellen, 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 entdecken und Komponentendaten abfragen

Im folgenden Beispielcode wird gezeigt, wie Sie räumliche Entitäten für einen mit XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID und XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT konfigurierten Kontext ermitteln und die zugehörigen Komponentendaten abfragen.

// 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 Sie einen synchronen Raycast-Snapshot erstellen.

// 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 Gebäude

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

  • Version 1, 15.07.2025 (Brian Chen)

    • Erste Beschreibung der Erweiterung.