XR_ANDROID_spatial_annotation_tracking
Name String
XR_ANDROID_spatial_annotation_tracking
Erweiterungstyp
Instanzerweiterung
Registrierte Durchwahl
795
Revision
1
Ratification Status
Nicht ratifiziert
Erweiterungs- und Versionsabhängigkeiten
XR_EXT_spatial_entity
und
XR_EXT_spatial_image_tracking
Datum der letzten Änderung
2026-01-12
IP-Status
Keine bekannten Ansprüche auf geistiges Eigentum.
Mitwirkende
Levana Chen, Google
Christopher Feil, Google
Martin Sundermeyer, Google
David Joseph Tan, Google
Jared Finder, Google
Nihav Jain, Google
Übersicht
Diese Erweiterung bietet die Möglichkeit, Annotationen für die Erweiterung XR_EXT_spatial_entity zu verfolgen, um verschiedene Annotationen in der Szene zu verfolgen. Damit können Anwendungen Overlays auf physische oder virtuelle Objekte legen, die durch Laufzeitreferenzen definiert sind.
Diese Erweiterung bietet den grundlegenden Annotationstyp „Quad“, ein Polygon mit genau vier Seiten, d.h. ein konvexes Viereck, das einen verallgemeinerten 2D-Begrenzungsrahmen innerhalb einer Laufzeitreferenz darstellt. Eine getrackte Quad-Annotation wird als räumliche Entität mit den folgenden Komponenten dargestellt:
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Anwendungen können die Erweiterung für das Tracking räumlicher Annotationen in der Regel in den folgenden Mustern verwenden:
- Eine Anwendung erstellt zuerst ein Handle von XrSpatialReferenceCacheANDROID, das mit der Aufzeichnung von Laufzeitreferenzen aus der angegebenen Quelle beginnt.
- Die Anwendung erfasst dann eine Laufzeitreferenz von XrSpatialReferenceImageEXT und definiert eine gewünschte Annotation innerhalb der Referenz während der Zeitspanne des Referenz-Cache.
- Die Anwendung erstellt dann ein XrSpatialContextEXT-Handle basierend auf dem XrSpatialReferenceImageEXT, das von XrSpatialCapabilityConfigurationAnnotationTrackingANDROID bereitgestellt wird.
- Die Anwendung kann das XrSpatialReferenceCacheANDROID-Handle löschen, um die Aufzeichnung von Laufzeitreferenzen zu beenden und die Speichernutzung zu reduzieren, oder auf das
XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID-Ereignis warten, um das Initialisierungsergebnis zu bestätigen. - Die Anwendung ruft dann das Ereignis
XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDab, um das Initialisierungsergebnis der Annotation zu bestätigen. - Wenn die Initialisierung erfolgreich ist, kann die Anwendung das Ereignis
XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXTabrufen, um die Annotation zu verfolgen. - Wenn die Initialisierung fehlschlägt, kann die Anwendung den im Ereignis zurückgegebenen Fehlercode verwenden, um die Ursache des Fehlers zu ermitteln, und das vorhandene XrSpatialContextEXT-Handle löschen, um eine neue Annotation zu starten.
- Unabhängig vom Initialisierungsergebnis kann die Anwendung den Bildpuffer freigeben, um die Speichernutzung nach dem Empfang des Ereignisses zu reduzieren.
- Die Anwendung erkennt und fragt Annotationen gemäß den Zugriffsmustern für räumliche Entitäten ab.
- Die Anwendung kann ein zusätzliches XrSpatialContextEXT-Handle erstellen, um Annotationen innerhalb einer neuen Referenz während der Gültigkeitsdauer eines gültigen XrSpatialReferenceCacheANDROID zu verfolgen.
- Die Anwendung kann XrSpatialContextEXT-Handles löschen, um die Anzahl der erkennbaren und verfolgbaren Annotationen dynamisch zur Laufzeit zu reduzieren.
Laufzeitunterstützung
Eine Laufzeit muss die Unterstützung für die Funktion zum Tracking von Annotationen über xrEnumerateSpatialCapabilitiesEXT angeben, indem sie die folgende Funktion auflistet:
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
Wenn die Laufzeit die Funktion zum Tracking von Annotationen unterstützt:
- Es muss mindestens eine Annotationskomponente unterstützen, indem die unterstützten Annotationskomponenten über xrEnumerateSpatialCapabilityComponentTypesEXT aufgelistet werden.
- Es muss mindestens eines der XrSpatialReferenceImageFormatEXT-Formate unterstützen, indem die unterstützten Referenzformate über xrEnumerateSpatialReferenceImageFormatsEXT mit
capabilityaufXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROIDaufgelistet werden. - Sie MÜSSEN mindestens eine der XrSpatialAnnotationReferenceSourceANDROID-Quellen unterstützen, indem sie die unterstützten Referenzquellen über xrEnumerateSpatialAnnotationReferenceSourcesANDROID auflisten, wobei
capabilityaufXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROIDgesetzt ist.
Die Funktion xrEnumerateSpatialAnnotationReferenceSourcesANDROID ist so definiert:
XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
XrInstance instance,
XrSystemId systemId,
XrSpatialCapabilityEXT capability,
uint32_t sourceCapacityInput,
uint32_t* sourceCountOutput,
XrSpatialAnnotationReferenceSourceANDROID* sources);
Parameterbeschreibungen
instanceist ein Handle für eine XrInstance .systemIdist dieXrSystemId, deren Referenzquellen aufgezählt werden.capabilityist die XrSpatialCapabilityEXT, für die die Referenzquellen aufgezählt werden.sourceCapacityInputist die Kapazität dessources-Arrays oder 0, um eine Anfrage zum Abrufen der erforderlichen Kapazität anzugeben.sourceCountOutputist die Anzahl der Quellen oder die erforderliche Kapazität, fallssourceCapacityInputnicht ausreicht.sourcesist ein Array von XrSpatialAnnotationReferenceSourceANDROID . Er kannNULLsein, wennsourceCapacityInput0 ist.- Eine detaillierte Beschreibung zum Abrufen der erforderlichen
sources-Größe finden Sie im Abschnitt Parameter für die Puffergröße.
Die Anwendung kann die Liste der Referenzquellen, die von einem bestimmten XrSystemId unterstützt werden, mit xrEnumerateSpatialAnnotationReferenceSourcesANDROID aufzählen.
Die Laufzeit darf die Referenzquellen, deren Erweiterung nicht für instance aktiviert ist, nicht auflisten.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert werden, bevor xrEnumerateSpatialAnnotationReferenceSourcesANDROID aufgerufen wird. -
instancemuss ein gültiges XrInstance-Handle sein -
capabilitymuss ein gültiger XrSpatialCapabilityEXT-Wert sein -
sourceCountOutputmuss ein Zeiger auf einenuint32_t-Wert sein - Wenn
sourceCapacityInputnicht0ist, musssourcesein Zeiger auf ein Array vonsourceCapacityInputXrSpatialAnnotationReferenceSourceANDROID-Werten sein.
Rückgabecodes
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SIZE_INSUFFICIENTXR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXTXR_ERROR_SYSTEM_INVALIDXR_ERROR_VALIDATION_FAILURE
typedef enum XrSpatialAnnotationReferenceSourceANDROID {
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;
Die Aufzählung XrSpatialAnnotationReferenceSourceANDROID beschreibt die Quelle der Referenz, die die Metadaten für eine Annotation bereitstellt.
Die Enums haben die folgenden Bedeutungen:
Enum-Beschreibung
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID
Das Referenzbild ist ein nicht zugeschnittenes Bild, das von einer Android-Kamera-API ausgegeben wird, z.B. ein Bild von einem ImageReader, der mit einem Camera2-CameraDevice verknüpft ist, oder ein ImageProxy von einer ImageAnalysis, die mit CameraX verknüpft ist. In der Regel ist dies eine der nach vorn gerichteten RGB-Kameras.
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID
Das Referenzbild ist ein nicht zugeschnittenes Bild, das von der Android MediaProjection API ausgegeben wird, z.B. ein Bild von einem ImageReader, der mit einem virtuellen MediaProjection-Display verknüpft ist. Sie kann virtuelle und reale Inhalte umfassen.
Die Struktur XrSystemSpatialAnnotationPropertiesANDROID ist so definiert:
typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
XrStructureType type;
void* next;
uint32_t referenceCacheTimespan;
uint32_t maxReferencePixelWidth;
uint32_t maxReferencePixelHeight;
uint32_t maxReferenceCount;
uint32_t maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette.referenceCacheTimespangibt die Zeitspanne in Sekunden an, für die ein XrSpatialReferenceCacheANDROID-Handle gültig ist.maxReferencePixelWidthgibt die maximale Breite des Randes von Referenzbildern in Pixeln an.maxReferencePixelHeightgibt die maximale Höhe der Kante von Referenzbildern in Pixeln an.maxReferenceCountgibt die maximale Anzahl von Referenzbildern an, die gleichzeitig zugewiesen werden können.maxAnnotationCountgibt die maximale Anzahl von Annotationen an, die gleichzeitig verfolgt werden können.
Wenn die Laufzeit die Funktion zum Tracking von Annotationen unterstützt, kann eine Anwendung relevante Systemeigenschaften prüfen, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemSpatialAnnotationPropertiesANDROID-Struktur mit den XrSystemProperties verknüpft.
Wenn XrSpatialReferenceImageEXT :: width von XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference den Wert maxReferencePixelWidth überschreitet, muss die Laufzeit beim Aufruf von xrCreateSpatialContextAsyncEXT den Wert XR_ERROR_VALIDATION_FAILURE zurückgeben.
Wenn XrSpatialReferenceImageEXT :: height von XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference den Wert maxReferencePixelHeight überschreitet, muss die Laufzeit beim Aufruf von xrCreateSpatialContextAsyncEXT den Wert XR_ERROR_VALIDATION_FAILURE zurückgeben.
Wenn XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time außerhalb der Zeitspanne von XrSpatialReferenceCacheANDROID :: cache liegt, muss die Laufzeit beim Aufruf von xrCreateSpatialContextAsyncEXT XR_ERROR_TIME_INVALID zurückgeben. Die Anwendung kann das XrSpatialContextEXT-Handle mit einer neuen Referenz während der Zeitspanne des XrSpatialReferenceCacheANDROID neu erstellen.
Wenn die Anzahl der zugewiesenen Referenzbilder maxReferenceCount überschreitet, muss die Laufzeit XR_ERROR_LIMIT_REACHED zurückgeben und den Initialisierungsfehler über XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult angeben. Die Anwendung kann das XrSpatialContextEXT-Handle löschen und es noch einmal versuchen, nachdem die ausstehende Initialisierung abgeschlossen ist.
Wenn die Anzahl der aktiven Annotationen maxAnnotationCount überschreitet, muss die Laufzeit beim Aufrufen von xrCreateSpatialContextAsyncEXT XR_ERROR_VALIDATION_FAILURE zurückgeben.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert sein, bevor XrSystemSpatialAnnotationPropertiesANDROID verwendet werden kann. -
typemussXR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
Laufzeitreferenz-Cache
XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)
Das XrSpatialReferenceCacheANDROID-Handle stellt einen Cache mit Laufzeitreferenzen dar, die von einer bestimmten Quelle aufgezeichnet wurden.
Die Funktion xrCreateSpatialReferenceCacheAsyncANDROID ist so definiert:
XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
XrSession session,
const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Parameterbeschreibungen
sessionist eine XrSession, in der der Referenz-Cache aktiv ist.createInfoist ein Zeiger auf ein XrSpatialReferenceCacheCreateInfoANDROID, mit dem die Parameter für den Referenz-Cache angegeben werden.futureist ein Zeiger auf das Ausgabe-Handle einesXrFutureEXT.
Die Anwendung kann ein XrSpatialReferenceCacheANDROID-Handle erstellen, indem sie xrCreateSpatialReferenceCacheAsyncANDROID aufruft. Die Laufzeit benötigt möglicherweise einige Zeit, um die Tracking-Dienste zu initialisieren. Die Anwendung kann dann wiederholt xrCreateSpatialReferenceCacheCompleteANDROID aufrufen, um den Abschluss dieses asynchronen Vorgangs zu prüfen.
Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT zurückgeben, wenn XrSpatialReferenceCacheCreateInfoANDROID :: capability nicht von xrEnumerateSpatialCapabilitiesEXT aufgeführt wird.
Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED zurückgeben, wenn XrSpatialReferenceCacheCreateInfoANDROID :: source nicht von xrEnumerateSpatialAnnotationReferenceSourcesANDROID für die angegebene Funktion aufgeführt wird.
Die Anwendung kann nur ein Handle pro Quelle für eine bestimmte Funktion erstellen. Andernfalls muss die Laufzeit XR_ERROR_LIMIT_REACHED zurückgeben.
Die Anwendung kann dann Laufzeitreferenzen während der Zeitspanne des XrSpatialReferenceCacheANDROID-Handles erfassen, um ein neues XrSpatialContextEXT-Handle zu konfigurieren.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert werden, bevor xrCreateSpatialReferenceCacheAsyncANDROID aufgerufen wird. -
sessionmuss ein gültiges XrSession-Handle sein -
createInfomuss ein Zeiger auf eine gültige XrSpatialReferenceCacheCreateInfoANDROID-Struktur sein. -
futuremuss ein Zeiger auf einenXrFutureEXT-Wert sein
Rückgabecodes
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXTXR_ERROR_VALIDATION_FAILURE
Die Struktur XrSpatialReferenceCacheCreateInfoANDROID ist so definiert:
typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
XrStructureType type;
const void* next;
XrSpatialCapabilityEXT capability;
XrSpatialAnnotationReferenceSourceANDROID source;
} XrSpatialReferenceCacheCreateInfoANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.capabilityist eine XrSpatialCapabilityEXT, die beschreibt, für welche Funktion der Referenz-Cache erstellt wird.sourceist eine XrSpatialAnnotationReferenceSourceANDROID, die die Quelle des Referenz-Cache beschreibt.
Die Struktur XrSpatialReferenceCacheCreateInfoANDROID beschreibt die Informationen zum Erstellen eines XrSpatialReferenceCacheANDROID-Handles.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert werden, bevor XrSpatialReferenceCacheCreateInfoANDROID verwendet werden kann. -
typemussXR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
capabilitymuss ein gültiger XrSpatialCapabilityEXT-Wert sein -
sourcemuss ein gültiger XrSpatialAnnotationReferenceSourceANDROID-Wert sein
Die Funktion xrCreateSpatialReferenceCacheCompleteANDROID ist so definiert:
XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateSpatialReferenceCacheCompletionANDROID* completion);
Parameterbeschreibungen
sessionist die XrSession, die zuvor an xrCreateSpatialReferenceCacheAsyncANDROID ::sessionübergeben wurde.futureist derXrFutureEXT, der von xrCreateSpatialReferenceCacheAsyncANDROID ::futureempfangen wurde.completionist ein Zeiger auf ein XrCreateSpatialReferenceCacheCompletionANDROID .
Die Anwendung kann xrCreateSpatialReferenceCacheCompleteANDROID aufrufen, um auf den Abschluss des asynchronen Vorgangs zu warten, der von xrCreateSpatialReferenceCacheAsyncANDROID gestartet wurde.
Die Laufzeit muss XR_ERROR_FUTURE_PENDING_EXT zurückgeben, wenn future nicht im Status „Bereit“ ist. Die Laufzeit muss XR_ERROR_FUTURE_INVALID_EXT zurückgeben, wenn future bereits abgeschlossen oder abgebrochen wurde.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert werden, bevor xrCreateSpatialReferenceCacheCompleteANDROID aufgerufen wird. -
sessionmuss ein gültiges XrSession-Handle sein -
completionmuss ein Zeiger auf eine XrCreateSpatialReferenceCacheCompletionANDROID-Struktur sein.
Rückgabecodes
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Die Struktur XrCreateSpatialReferenceCacheCompletionANDROID ist so definiert:
typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrSpatialReferenceCacheANDROID referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind weder in OpenXR noch in dieser Erweiterung definiert.futureResultist das XrResult des Vorgangs zum Erstellen des Referenz-Cache.referenceCacheist das XrSpatialReferenceCacheANDROID-Handle, wenn der Vorgang erfolgreich ist.
Zukünftige Rückgabecodes
futureResult-Werte:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Wenn futureResult ein Erfolgscode ist, muss die Laufzeit ein gültiges referenceCache-Handle zurückgeben. Wenn referenceCache gültig ist, bleibt es nur innerhalb der Lebensdauer von xrCreateSpatialReferenceCacheAsyncANDROID :: session oder bis die Anwendung das Handle mit xrDestroySpatialReferenceCacheANDROID zerstört, je nachdem, was zuerst eintritt.
Wenn referenceCache gültig ist, werden Caches in XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan aufgezeichnet.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert werden, bevor XrCreateSpatialReferenceCacheCompletionANDROID verwendet werden kann. -
typemussXR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
futureResultmuss ein gültiger XrResult-Wert sein. -
referenceCachemuss ein gültiges XrSpatialReferenceCacheANDROID-Handle sein
Die Funktion xrDestroySpatialReferenceCacheANDROID ist so definiert:
XrResult xrDestroySpatialReferenceCacheANDROID(
XrSpatialReferenceCacheANDROID cacheHandle);
Parameterbeschreibungen
cacheHandleist ein XrSpatialReferenceCacheANDROID, der zuvor von xrCreateSpatialReferenceCacheAsyncANDROID erstellt wurde.
Die Anwendung kann die Funktion xrDestroySpatialReferenceCacheANDROID aufrufen, um das Handle cacheHandle und die zugrunde liegenden Ressourcen freizugeben, wenn die Erstellung des räumlichen Kontexts abgeschlossen ist.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert sein, bevor xrDestroySpatialReferenceCacheANDROID aufgerufen wird. -
cacheHandlemuss ein gültiges XrSpatialReferenceCacheANDROID-Handle sein
Threadsicherheit
- Der Zugriff auf
cacheHandleund alle untergeordneten Handles muss extern synchronisiert werden.
Rückgabecodes
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
Konfiguration
Die Struktur XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ist so definiert:
typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
XrStructureType type;
const void* next;
XrSpatialCapabilityEXT capability;
uint32_t enabledComponentCount;
const XrSpatialComponentTypeEXT* enabledComponents;
XrSpatialReferenceCacheANDROID cache;
XrTime time;
XrSpatialReferenceImageEXT reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette.capabilityist ein XrSpatialCapabilityEXT und mussXR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROIDsein.enabledComponentCountist einuint32_t, der die Anzahl der Elemente im ArrayenabledComponentsbeschreibt.enabledComponentsist ein Zeiger auf ein Array von XrSpatialComponentTypeEXT .cacheist ein XrSpatialReferenceCacheANDROID, der zuvor erstellt wurde, um Laufzeitreferenzen für diereference-Konfiguration aufzuzeichnen.timeist dieXrTime, bei der diereferenceerfasst wird.referenceist ein XrSpatialReferenceImageEXT mit Annotationen, die mit dem nächsten Zeiger verkettet sind.
Anwendungen können die räumliche Funktion XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID aktivieren, indem sie einen Zeiger auf die Struktur XrSpatialCapabilityConfigurationAnnotationTrackingANDROID in XrSpatialContextCreateInfoEXT :: capabilityConfigs hinzufügen.
Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE zurückgeben, wenn capability nicht XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID ist.
Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT zurückgeben, wenn reference keine Annotationen enthält.
Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT zurückgeben, wenn die Annotationskomponente in enabledComponents aufgeführt ist, aber keine entsprechenden Annotationen mit reference verknüpft sind.
Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE zurückgeben, wenn cache nicht derselben XrSession gehört, die an xrCreateSpatialContextAsyncEXT übergeben wird.
Die Laufzeit muss XR_ERROR_TIME_INVALID zurückgeben, wenn time außerhalb der Zeitspanne von cache liegt.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert sein, bevor XrSpatialCapabilityConfigurationAnnotationTrackingANDROID verwendet werden kann. -
typemussXR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
capabilitymuss ein gültiger XrSpatialCapabilityEXT-Wert sein -
enabledComponentsmuss ein Zeiger auf ein Array mitenabledComponentCountgültigen XrSpatialComponentTypeEXT-Werten sein. -
cachemuss ein gültiges XrSpatialReferenceCacheANDROID-Handle sein -
referencemuss eine gültige XrSpatialReferenceImageEXT-Struktur sein - Der Parameter
enabledComponentCountmuss größer als0sein.
Tracking-Ereignisse für Annotationen
Die Struktur XrEventDataSpatialAnnotationTrackingANDROID ist so definiert:
typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
XrStructureType type;
const void* next;
XrSpatialContextEXT spatialContext;
uint32_t annotationIndex;
XrResult initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette.spatialContextist der XrSpatialContextEXT, für den das Annotations-Tracking aktiviert wurde.annotationIndexwird dem Index aus dem Annotationsarray zugeordnet, das mit XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ::referenceverknüpft ist.initializationResultgibt das Initialisierungsergebnis der Annotation an. Wenn der Wert nichtXR_SUCCESSist, kann die Anwendung das XrSpatialContextEXT-Handle löschen und neu erstellen, um die Annotation neu zu initialisieren, oder dasspatialContextweiterhin verwenden, um andere Annotationen zu verfolgen.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert sein, bevor XrEventDataSpatialAnnotationTrackingANDROID verwendet werden kann. -
typemussXR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
Die Laufzeit muss für jede Annotation XrEventDataSpatialAnnotationTrackingANDROID ausfüllen, um den Abschluss der Initialisierung anzugeben. Unabhängig vom Initialisierungsergebnis kann die Anwendung den Bildpuffer freigeben, um die Speichernutzung nach dem Empfang des Ereignisses zu reduzieren.
Die Laufzeit muss initializationResult mit XR_SUCCESS füllen, wenn die Annotation erfolgreich initialisiert wurde. Die Anwendung kann dann das Ereignis XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT abrufen, um die Annotation zu verfolgen.
Andernfalls muss die Laufzeit initializationResult mit einem entsprechenden Fehlercode füllen, um die Fehlerursache anzugeben. Die Anwendung kann das XrSpatialContextEXT-Handle löschen, um eine neue Annotation zu starten, oder weiterhin spatialContext verwenden, um andere Annotationen zu verfolgen.
Quad-Annotation
Eine Laufzeit muss ihre Unterstützung für Quad-Anmerkungen mit xrEnumerateSpatialCapabilityComponentTypesEXT angeben, indem sie den folgenden Komponententyp auflistet:
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Quad-Referenz
Die Struktur XrSpatialAnnotationQuadReferenceANDROID ist so definiert:
typedef struct XrSpatialAnnotationQuadReferenceANDROID {
XrStructureType type;
const void* next;
uint32_t quadCount;
const XrSpatialAnnotationQuadANDROID* quads;
} XrSpatialAnnotationQuadReferenceANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette.quadCountist einuint32_t, der die Anzahl der Elemente im Arrayquadsbeschreibt.quadsist der Zeiger auf ein Array von XrSpatialAnnotationQuadANDROID .
Wenn die Laufzeit Quad-Annotationen unterstützt, kann eine Anwendung Annotationen konfigurieren, indem sie eine XrSpatialAnnotationQuadReferenceANDROID-Struktur mit der XrSpatialReferenceImageEXT :: next verkettet und die Referenz in XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference festlegt, wenn das XrSpatialContextEXT-Handle erstellt wird.
Die Laufzeit muss XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT von xrCreateSpatialContextAsyncEXT zurückgeben, wenn quadCount 0 ist.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert sein, bevor XrSpatialAnnotationQuadReferenceANDROID verwendet werden kann. -
typemussXR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
quadsmuss ein Zeiger auf ein Array vonquadCountgültigen XrSpatialAnnotationQuadANDROID-Strukturen sein - Der Parameter
quadCountmuss größer als0sein.
Die Struktur XrSpatialAnnotationQuadANDROID ist so definiert:
typedef struct XrSpatialAnnotationQuadANDROID {
XrSpatialAnnotationQuadAlignmentANDROID alignment;
XrVector2f upperLeft;
XrVector2f upperRight;
XrVector2f lowerRight;
XrVector2f lowerLeft;
} XrSpatialAnnotationQuadANDROID;
Mitgliederbeschreibungen
alignmentist die XrSpatialAnnotationQuadAlignmentANDROID des Quads.upperLeftist ein XrVector2f, der die Koordinate der oberen linken Ecke des Vierecks relativ zum Ursprung beschreibt.upperRightist ein XrVector2f, der die Koordinate der oberen rechten Ecke des Vierecks relativ zum Ursprung beschreibt.lowerRightist ein XrVector2f, der die Koordinate der unteren rechten Ecke des Vierecks relativ zum Ursprung beschreibt.lowerLeftist ein XrVector2f, der die Koordinate der unteren linken Ecke des Vierecks im Verhältnis zum Ursprung beschreibt.
Ein Quad in einem 2D-Bereich ist ein konvexes Viereck im Uhrzeigersinn. Der Wert der vier Ecken bezieht sich auf den Ursprung (0, 0), dem das Viereck zugeordnet ist.
- Wenn es mit einem XrSpatialReferenceImageEXT verknüpft ist, ist der Ursprung die obere linke Ecke des Bildes, wobei X dem Pixel auf der Breite und Y dem Pixel auf der Höhe entspricht.
- Wenn sie mit XrSpatialAnnotationQuadDataANDROID verknüpft ist, wird der Ursprung durch XrSpaceLocationData ::
posevon XrSpatialAnnotationQuadDataANDROID ::originangegeben.
Gültige Verwendung (implizit)
- Die
XR_ANDROID_spatial_annotation_tracking-Erweiterung muss aktiviert sein, bevor XrSpatialAnnotationQuadANDROID verwendet werden kann. -
alignmentmuss ein gültiger XrSpatialAnnotationQuadAlignmentANDROID-Wert sein
typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID = 2,
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;
Die Aufzählung XrSpatialAnnotationQuadAlignmentANDROID beschreibt die Ausrichtung der Quad-Annotation.
Die Enums haben die folgenden Bedeutungen:
Enum-Beschreibung
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID
Das Anmerkungsquadrat ist parallel zur Bildschirmebene, während die Drehung in der Ebene an die Schwerkraft der Welt gebunden bleibt. Die Ausgabe wird als normaler, aufrechter Begrenzungsrahmen angezeigt.
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID
Das Annotationsquadrat ist direkt am Objekt verankert und entspricht der im Referenzbild definierten Ausrichtung. Die Ausgabe ist ein konvexes Viereck, dessen Form an die Perspektive des Objekts angepasst wird.
XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID
Das Annotationsquadrat ist koplanar mit der Oberfläche des zugrunde liegenden Objekts, vorausgesetzt, das verfolgte Ziel ist ein planares Objekt oder eine planare Oberfläche. Die Ausgabe wird nahtlos an die physische Geometrie des Objekts angepasst und die Perspektive so geändert, dass sie flach auf der jeweiligen Oberfläche liegt.
Quad-Komponenten
Die Struktur XrSpatialAnnotationQuadDataANDROID ist so definiert:
typedef struct XrSpatialAnnotationQuadDataANDROID {
uint32_t annotationIndex;
XrSpaceLocationData origin;
XrSpatialAnnotationQuadANDROID quad;
} XrSpatialAnnotationQuadDataANDROID;
Mitgliederbeschreibungen
annotationIndexist der Index, der dem Array XrSpatialAnnotationQuadReferenceANDROID ::quadszugeordnet ist, das mit der Referenz verknüpft ist, die von XrSpatialCapabilityConfigurationAnnotationTrackingANDROID ::referenceübergeben wurde.originist ein XrSpaceLocationData-Objekt, das den Ursprung einer 2D-Ebene beschreibt, auf der das Quad verankert ist. Die Laufzeit muss XrSpaceLocationData ::locationFlagsfestlegen, um die gültigen Bits der Ursprungspose anzugeben.quadist ein XrSpatialAnnotationQuadANDROID, das das Quad im lokalen Raum darstellt. Verwenden Sieorigin, um das Viereck in den Pose-Space zu transformieren.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert sein, bevor XrSpatialAnnotationQuadDataANDROID verwendet werden kann. -
originmuss eine gültige XrSpaceLocationData-Struktur sein -
quadmuss eine gültige XrSpatialAnnotationQuadANDROID-Struktur sein.
Die Struktur XrSpatialComponentAnnotationQuadListANDROID ist so definiert:
typedef struct XrSpatialComponentAnnotationQuadListANDROID {
XrStructureType type;
void* next;
uint32_t quadCount;
XrSpatialAnnotationQuadDataANDROID* quads;
} XrSpatialComponentAnnotationQuadListANDROID;
Mitgliederbeschreibungen
typeist der XrStructureType dieser Struktur.nextistNULLoder ein Zeiger auf die nächste Struktur in einer Strukturkette.quadCountist einuint32_t, der die Anzahl der Elemente im Arrayquadsbeschreibt.quadsist ein Array von XrSpatialAnnotationQuadDataANDROID .
Die Anwendung kann die Quad-Annotationskomponente der räumlichen Entitäten in einem XrSpatialSnapshotEXT abfragen, indem sie XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID in XrSpatialComponentDataQueryConditionEXT :: componentTypes und XrSpatialComponentAnnotationQuadListANDROID zur nächsten Zeigerkette von XrSpatialComponentDataQueryResultEXT hinzufügt.
Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE von xrQuerySpatialComponentDataEXT zurückgeben, wenn XrSpatialComponentAnnotationQuadListANDROID in der nächsten Kette von XrSpatialComponentDataQueryResultEXT :: next enthalten ist, aber XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID nicht in XrSpatialComponentDataQueryConditionEXT :: componentTypes enthalten ist.
Die Laufzeit muss XR_ERROR_SIZE_INSUFFICIENT von xrQuerySpatialComponentDataEXT zurückgeben, wenn quadCount kleiner als XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput ist.
Gültige Verwendung (implizit)
- Die Erweiterung
XR_ANDROID_spatial_annotation_trackingmuss aktiviert sein, bevor XrSpatialComponentAnnotationQuadListANDROID verwendet werden kann. -
typemussXR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROIDsein -
nextmussNULLoder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein. -
quadsmuss ein Zeiger auf ein Array vonquadCountXrSpatialAnnotationQuadDataANDROID-Strukturen sein. - Der Parameter
quadCountmuss größer als0sein.
Beispiel-Code
Laufzeitunterstützung prüfen
Der folgende Beispielcode zeigt, wie Sie prüfen, ob die Laufzeit die Funktion zum Verfolgen von Annotationen unterstützt.
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;
// Check spatial annotation tracking capability
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_ANNOTATION_TRACKING_ANDROID) ==
capabilities.end()) {
// System does not support spatial annotation tracking.
return;
}
// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &annotationSystemProperties,
.systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
// System does not support any active annotations.
return;
}
// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
// The desired source is not supported.
return;
}
// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
&formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
// The desired format is not supported
return;
}
// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
&capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
&capabilityComponentTypes));
// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
XrSpatialComponentTypeEXT component) {
return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
// The desired annotation is not supported.
return;
}
Quad-Annotation konfigurieren
Der folgende Beispielcode zeigt, wie Sie die Quad-Annotation konfigurieren.
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);
XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;
// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
.type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
.next = nullptr,
.capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
.source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));
waitUntilReady(cacheFuture);
XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
&cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
// Error, reference cache creation failed
return;
}
referenceCache = cacheCompletion.referenceCache;
// Create the reference image with quad annotations
// YUV 4:2:0 Planar:
// ----------------------
// | Y |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;
XrSpatialAnnotationQuadANDROID
quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};
XrSpatialAnnotationQuadReferenceANDROID quadReference{
XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;
// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
desiredComponent,
};
// Configure annotation tracking
XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
annotationConfig.capability =
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
annotationConfig.enabledComponentCount = enabledComponents.size();
annotationConfig.enabledComponents = enabledComponents.data();
annotationConfig.cache = referenceCache;
annotationConfig.time; // The time when this reference image is captured.
annotationConfig.reference = referenceImage;
std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT *>
capabilityConfigs;
capabilityConfigs.push_back(
reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT *>(
&annotationConfig));
XrSpatialContextCreateInfoEXT spatialContextCreateInfo{
XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo,
&createContextFuture));
waitUntilReady(createContextFuture);
XrCreateSpatialContextCompletionEXT completion{
XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture,
&completion));
if (completion.futureResult != XR_SUCCESS) {
// Error, spatial context creation failed
return;
}
spatialContext = completion.spatialContext;
CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}
Aktive Anmerkungen entdecken
Der folgende Beispielcode zeigt, wie Sie Annotationen finden und abfragen.
XrInstance instance; // previously initialized
XrSession session; // previously initialized
XrSpace localSpace; // previously initialized, e.g. from
// XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created
PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);
XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
XrSpace baseSpace) {
std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
snapshotCreateInfo.componentTypes = snapshotComponents.data();
XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(
spatialContext, &snapshotCreateInfo, &discoveryFuture));
waitUntilReady(discoveryFuture);
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{
XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
completionInfo.baseSpace = baseSpace;
completionInfo.time = time;
completionInfo.future = discoveryFuture;
XrCreateSpatialDiscoverySnapshotCompletionEXT completion{
XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
spatialContext, &completionInfo, &completion));
if (completion.futureResult == XR_SUCCESS) {
// Query for desired annotation data, e.g. quad.
XrSpatialComponentTypeEXT componentsToQuery[] = {
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
XrSpatialComponentDataQueryConditionEXT queryCond{
XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = componentsToQuery;
XrSpatialComponentDataQueryResultEXT queryResult{
XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond,
&queryResult));
std::vector<XrSpatialEntityIdEXT> entityIds(
queryResult.entityIdCountOutput);
std::vector<XrSpatialEntityTrackingStateEXT> entityStates(
queryResult.entityStateCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();
queryResult.entityStateCapacityInput = entityStates.size();
queryResult.entityStates = entityStates.data();
std::vector<XrSpatialAnnotationQuadDataANDROID> quads(
queryResult.entityIdCountOutput);
XrSpatialComponentAnnotationQuadListANDROID quadList{
XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
quadList.quadCount = quads.size();
quadList.quads = quads.data();
queryResult.next = &quadList;
CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond,
&queryResult));
for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
const XrSpatialAnnotationQuadDataANDROID ¤tQuad = quads[i];
// Rendering quad in the view.
}
}
CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
}
};
while (1) {
// For every frame in frame loop
XrSpace space; // Application's play space.
XrFrameState frameState; // Previously returned from xrWaitFrame
const XrTime time = frameState.predictedDisplayTime;
// Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID: {
const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
*reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
&event);
if (eventdata.initializationResult != XR_SUCCESS) {
// handle initialization failure.
// e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
}
break;
}
case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
const XrEventDataSpatialDiscoveryRecommendedEXT &eventdata =
*reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT *>(
&event);
// Discover spatial entities for the context that we received the
// "discovery recommended" event for.
//discoverSpatialEntities(eventdata.spatialContext, time, space);
break;
}
}
}
// Finish frame loop
}
CHK_XR(xrDestroySpatialContextEXT(spatialContext));
Neue Objekttypen
Neue Befehle
- xrCreateSpatialReferenceCacheAsyncANDROID
- xrCreateSpatialReferenceCacheCompleteANDROID
- xrDestroySpatialReferenceCacheANDROID
- xrEnumerateSpatialAnnotationReferenceSourcesANDROID
Neue Gebäude
- XrCreateSpatialReferenceCacheCompletionANDROID
- XrEventDataSpatialAnnotationTrackingANDROID
- XrSpatialAnnotationQuadANDROID
- XrSpatialAnnotationQuadDataANDROID
- XrSpatialCapabilityConfigurationAnnotationTrackingANDROID
- XrSpatialReferenceCacheCreateInfoANDROID
Erweiterung von XrSpatialComponentDataQueryResultEXT :
Erweiterung von XrSpatialReferenceImageEXT :
Erweiterung von XrSystemProperties :
Neue Enums
Neue Enum-Konstanten
XR_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAMEXR_ANDROID_spatial_annotation_tracking_SPEC_VERSIONErweiterung von XrObjectType :
XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID
Erweiterung von XrSpatialCapabilityEXT :
XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID
Erweiterung von XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID
Erweiterung von XrStructureType :
XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROIDXR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROIDXR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROIDXR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROIDXR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROIDXR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID
Probleme
Versionsverlauf
Version 1, 17.09.2025 (Levana Chen)
- Erste Beschreibung der Erweiterung.