XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

708

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_ANDROID_trackables

Einstellungsstatus

  • Eingestellt durch die Erweiterung XR_EXT_spatial_marker_tracking

Datum der letzten Änderung

23.07.2025

IP-Status

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

Christopher Doer, Google
Diego Tipaldi, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

Übersicht

Diese Erweiterung ermöglicht das Tracking physischer Markierungen und erlaubt es Anwendungen, XR-Inhalte effizient an physische Markierungen anzuhängen.

Die Erweiterung unterstützt bekannte Markertypen, insbesondere ArUco- und April-Tags. Damit können Laufzeiten optional die Schätzung der Markierungsgröße unterstützen.

Berechtigungen

Android-Apps müssen die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ in ihrem Manifest enthalten, da diese Erweiterung von XR_ANDROID_trackables abhängt und die Geometrie der Umgebung offenlegt. Die Berechtigung „android.permission.SCENE_UNDERSTANDING_COARSE“ gilt als gefährliche Berechtigung, d.h. Apps müssen die Berechtigung explizit anfordern.

(Schutzebene: gefährlich)

Systemkapazität prüfen

Die Struktur XrSystemMarkerTrackingPropertiesANDROID ist so definiert:

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

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. Weitere Informationen zur Strukturkette finden Sie in der erweiterten Struktur ( XrSystemProperties).
  • supportsMarkerTracking ist ein XrBool32, der angibt, ob das aktuelle System die Möglichkeit bietet, Markierungen zu verfolgen.
  • supportsMarkerSizeEstimation ist ein XrBool32, der angibt, ob das aktuelle System eine Schätzung der Markierungsgröße bietet.
  • maxMarkerCount ist die maximale Anzahl von Markierungen, die die Laufzeit gleichzeitig verfolgen kann.

Eine Anwendung kann prüfen, ob das System Marker-Tracking unterstützt, indem sie die XrSystemProperties beim Aufruf von xrGetSystemProperties um die Struktur XrSystemMarkerTrackingPropertiesANDROID erweitert. Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED für die Erstellung des Markertrackers zurückgeben, wenn und nur wenn supportsMarkerTracking XR_FALSE ist.

Wenn eine Laufzeit das Marker-Tracking unterstützt, muss maxMarkerCount mindestens 1 sein.

Gültige Verwendung (implizit)

Tracking-Markierungen

Diese Erweiterung fügt XR_TRACKABLE_TYPE_MARKER_ANDROID zu XrTrackableTypeANDROID hinzu.

Die Anwendung erstellt einen XrTrackableTrackerANDROID, indem sie xrCreateTrackableTrackerANDROID aufruft und XR_TRACKABLE_TYPE_MARKER_ANDROID als trackbaren Typ in XrTrackableTrackerCreateInfoANDROID :: trackableType angibt. Außerdem wird eine gültige Konfiguration festgelegt, indem der nächsten Kette von XrTrackableTrackerCreateInfoANDROID ein XrTrackableMarkerConfigurationANDROID hinzugefügt wird.

Die Laufzeit muss XR_ERROR_FEATURE_UNSUPPORTED zurückgeben, wenn XrTrackableTrackerCreateInfoANDROID :: trackableType XR_TRACKABLE_TYPE_MARKER_ANDROID ist und XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking über xrGetSystemProperties XR_FALSE zurückgibt.

Die Struktur XrTrackableMarkerConfigurationANDROID ist so definiert:

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • trackingMode ist ein XrTrackableMarkerTrackingModeANDROID, der den gewünschten Tracking-Modus angibt.
  • databaseCount ist ein uint32_t, der die Anzahl der Elemente im Array databases beschreibt.
  • databases ist ein Zeiger auf ein Array von XrTrackableMarkerDatabaseANDROID, die jeweils die gewünschten Markierungen aus einem bestimmten Wörterbuch enthalten, die erfasst werden sollen.

Die Anwendung muss eine gültige Konfiguration festlegen, indem sie der XrTrackableTrackerCreateInfoANDROID :: next-Kette eine XrTrackableMarkerConfigurationANDROID hinzufügt, wenn xrCreateTrackableTrackerANDROID mit XrTrackableTrackerCreateInfoANDROID :: trackableType auf XR_TRACKABLE_TYPE_MARKER_ANDROID gesetzt aufgerufen wird. Wenn der Tracker-Typ wie oben festgelegt ist, die Konfigurationsstruktur aber nicht vorhanden oder ungültig ist, muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

Wenn eine Laufzeit die Schätzung der Markierungsgröße unterstützt, kann die Anwendung XrTrackableMarkerDatabaseEntryANDROID :: edgeSize in XrTrackableMarkerDatabaseANDROID :: entries auf 0 setzen, um die Verwendung der Größenschätzung anzugeben. Andernfalls muss die Anwendung XrTrackableMarkerDatabaseEntryANDROID :: edgeSize auf einen positiven Wert setzen oder die Laufzeit muss XR_ERROR_VALIDATION_FAILURE zurückgeben.

Die Laufzeit muss die Ausgabe von xrGetAllTrackablesANDROID filtern, damit sie mit trackingMode und XrTrackableMarkerDatabaseEntryANDROID :: edgeSize übereinstimmt.

Gültige Verwendung (implizit)

Das Enum XrTrackableMarkerTrackingModeANDROID beschreibt die unterstützten Tracking-Modi von Markern.

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

Beschreibungen der Enumeranten

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID: Dynamische Markierungen werden verfolgt. Dieser Modus bietet die höchste Genauigkeit und funktioniert sowohl bei beweglichen als auch bei statischen Markierungen, hat aber auch den höchsten Stromverbrauch.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID: Statische Markierungen werden erfasst. Dieser Modus ist vor allem für statische Markierungen nützlich und verbraucht im Vergleich zum dynamischen Modus weniger Strom.

Die Struktur XrTrackableMarkerDatabaseANDROID definiert ein Wörterbuch und die entsprechenden zu verfolgenden Markierungs-IDs.

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

Mitgliederbeschreibungen

  • dictionary ist das XrTrackableMarkerDictionaryANDROID, zu dem alle entries gehören.
  • entryCount ist ein uint32_t, der die Anzahl der Elemente im entries-Array beschreibt. Die Anwendung kann entryCount 0 festlegen, um alle Markierungen im dictionary zu verfolgen.
  • entries ist ein Zeiger auf ein Array von XrTrackableMarkerDatabaseEntryANDROID , die jeweils die Konfiguration eines zu verfolgenden Markers enthalten.

Gültige Verwendung (implizit)

Das Enum XrTrackableMarkerDictionaryANDROID beschreibt die unterstützten Markierungswörterbücher.

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

Mit der Struktur XrTrackableMarkerDatabaseEntryANDROID wird eine einzelne Markierungs-ID eines Wörterbuchs konfiguriert.

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

Mitgliederbeschreibungen

  • id ist die Markierungs-ID, wie im Wörterbuch angegeben.
  • edgeSize steht für die Größe des Markierungsrands in Metern. Wenn die Laufzeit die Schätzung der Markierungsgröße unterstützt, kann die Anwendung diesen Wert auf null setzen und die Markierungsgröße wird online geschätzt. Wenn dieser Wert auf null gesetzt ist, die Laufzeit aber keine Schätzung der Markierungsgröße unterstützt, muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.

Gültige Verwendung (implizit)

Markierungen abrufen

Die Funktion xrGetTrackableMarkerANDROID ist so definiert:

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

Parameterbeschreibungen

Die Laufzeit muss XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID zurückgeben, wenn der trackbare Typ von XrTrackableANDROID nicht XR_TRACKABLE_TYPE_MARKER_ANDROID ist oder wenn der trackbare Typ von XrTrackableTrackerANDROID nicht XR_TRACKABLE_TYPE_MARKER_ANDROID ist.

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_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrTrackableMarkerANDROID ist so definiert:

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

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.
  • trackingState ist der XrTrackingStateANDROID des Markers.
  • lastUpdatedTime ist der XrTime der letzten Aktualisierung der Markierung.
  • dictionary ist das XrTrackableMarkerDictionaryANDROID der Markierung.
  • markerId ist die Markierungs-ID, wie im Wörterbuch angegeben.
  • centerPose ist die XrPosef des Markers in XrTrackableGetInfoANDROID :: baseSpace . Die Markierung liegt in der XZ-Ebene, wobei X nach rechts und Z nach unten zeigt. Y ist die Normale, die aus der Markierung herausragt.
  • extents sind die XrExtent2Df-Abmessungen des Markers. Die Grenze des Begrenzungsrahmens liegt bei den Punkten: centerPose +/– (extents / 2).

Gültige Verwendung (implizit)

Beispielcode zum Abrufen von trackbaren Markierungen

Der folgende Beispielcode zeigt, wie Sie trackbare Markierungen abrufen.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session;   // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // previously initialized
PFN_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

Neue Befehle

Neue Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Erweiterung von XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Erweiterung von XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Probleme

Versionsverlauf

  • Version 1, 23.07.2025 (Levana Chen)

    • Erste Beschreibung der Erweiterung.