XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Extension Type

Instance extension

Registered Extension Number

708

Revision

1

Ratification Status

Not ratified

Extension and Version Dependencies

XR_ANDROID_trackables

Deprecation State

  • Deprecated by XR_EXT_spatial_marker_tracking extension

Last Modified Date

2025-07-23

IP Status

No known IP claims.

Contributors

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

Przegląd

To rozszerzenie umożliwia śledzenie fizycznych znaczników i pozwala aplikacjom efektywnie dołączać treści XR do fizycznych znaczników.

Rozszerzenie obsługuje dobrze znane typy znaczników, w szczególności ArUco i April Tags. Umożliwia ono środowiskom wykonawczym opcjonalne obsługiwanie szacowania rozmiaru znacznika.

Uprawnienia

Aplikacje na Androida muszą mieć w pliku manifestu uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE, ponieważ to rozszerzenie zależy od rozszerzenia XR_ANDROID_trackables i udostępnia geometrię otoczenia. Uprawnienie android.permission.SCENE_UNDERSTANDING_COARSE jest uważane za niebezpieczne, co oznacza, że aplikacje muszą wyraźnie o nie poprosić.

(poziom ochrony: niebezpieczny)

Sprawdzanie możliwości systemu

Struktura XrSystemMarkerTrackingPropertiesANDROID jest zdefiniowana w ten sposób:

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

Opisy elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej wersji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur. Więcej informacji o łańcuchu struktur znajdziesz w strukturze, która jest rozszerzana ( XrSystemProperties).
  • supportsMarkerTracking to XrBool32 wskazujący, czy bieżący system obsługuje śledzenie znaczników.
  • supportsMarkerSizeEstimation to XrBool32 wskazujący, czy bieżący system obsługuje szacowanie rozmiaru znacznika.
  • maxMarkerCount to maksymalna liczba znaczników, które środowisko wykonawcze może śledzić jednocześnie.

Aplikacja może sprawdzić, czy system obsługuje śledzenie znaczników, rozszerzając XrSystemProperties o strukturę XrSystemMarkerTrackingPropertiesANDROID podczas wywoływania xrGetSystemProperties . Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED w przypadku tworzenia narzędzia do śledzenia znaczników tylko wtedy, gdy supportsMarkerTracking ma wartość XR_FALSE .

Jeśli środowisko wykonawcze obsługuje śledzenie znaczników, maxMarkerCount musi mieć wartość co najmniej 1.

Prawidłowe użycie (niejawne)

Śledzenie znaczników

To rozszerzenie dodaje XR_TRACKABLE_TYPE_MARKER_ANDROID do XrTrackableTypeANDROID .

Aplikacja tworzy XrTrackableTrackerANDROID, wywołując xrCreateTrackableTrackerANDROID i określając XR_TRACKABLE_TYPE_MARKER_ANDROID jako typ śledzenia w XrTrackableTrackerCreateInfoANDROID :: trackableType, a także ustawiając prawidłową konfigurację przez dodanie XrTrackableMarkerConfigurationANDROID do następnego łańcucha XrTrackableTrackerCreateInfoANDROID .

Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED jeśli XrTrackableTrackerCreateInfoANDROID :: trackableType ma wartość XR_TRACKABLE_TYPE_MARKER_ANDROID a XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking zwraca XR_FALSE za pomocą xrGetSystemProperties .

Struktura XrTrackableMarkerConfigurationANDROID jest zdefiniowana w ten sposób:

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

Opisy elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur.
  • trackingMode to XrTrackableMarkerTrackingModeANDROID wskazujący żądany tryb śledzenia.
  • databaseCount to uint32_t opisujący liczbę elementów w tablicy databases.
  • databases to wskaźnik do tablicy XrTrackableMarkerDatabaseANDROID , z których każdy zawiera żądane znaczniki z danego słownika do śledzenia.

Aplikacja musi ustawić prawidłową konfigurację, dodając XrTrackableMarkerConfigurationANDROID do łańcucha XrTrackableTrackerCreateInfoANDROID :: next podczas wywoływania xrCreateTrackableTrackerANDROID z XrTrackableTrackerCreateInfoANDROID :: trackableType ustawionym na XR_TRACKABLE_TYPE_MARKER_ANDROID . W przeciwnym razie, jeśli typ narzędzia do śledzenia jest ustawiony jak powyżej, ale struktura konfiguracji jest nieobecna lub nieprawidłowa, środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE .

Jeśli środowisko wykonawcze obsługuje szacowanie rozmiaru znacznika, aplikacja może ustawić XrTrackableMarkerDatabaseEntryANDROID :: edgeSize na 0 w XrTrackableMarkerDatabaseANDROID :: entries, aby wskazać użycie szacowania rozmiaru. W przeciwnym razie aplikacja musi ustawić XrTrackableMarkerDatabaseEntryANDROID :: edgeSize na wartość dodatnią lub środowisko wykonawcze musi zwracać XR_ERROR_VALIDATION_FAILURE .

Środowisko wykonawcze musi filtrować dane wyjściowe z xrGetAllTrackablesANDROID, aby pasowały do trackingMode i XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

Prawidłowe użycie (niejawne)

Wyliczenie XrTrackableMarkerTrackingModeANDROID opisuje obsługiwane tryby śledzenia znaczników.

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;

Opisy elementów wyliczenia

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID – śledzenie znaczników dynamicznych. Ten tryb ma najwyższą dokładność i działa w przypadku znaczników ruchomych i statycznych, ale też zużywa najwięcej energii.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID – śledzenie znaczników statycznych. Ten tryb jest przydatny głównie w przypadku znaczników, które są statyczne, co prowadzi do mniejszego zużycia energii w porównaniu z trybem dynamicznym.

Struktura XrTrackableMarkerDatabaseANDROID definiuje słownik i odpowiadające mu identyfikatory znaczników do śledzenia.

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

Opisy elementów

  • dictionary to XrTrackableMarkerDictionaryANDROID, do którego należą wszystkie entries.
  • entryCount to uint32_t opisujący liczbę elementów w tablicy entries. Aplikacja może ustawić entryCount na 0, aby śledzić wszystkie znaczniki w dictionary .
  • entries to wskaźnik do tablicy XrTrackableMarkerDatabaseEntryANDROID , z których każdy zawiera konfigurację znacznika do śledzenia.

Prawidłowe użycie (niejawne)

Wyliczenie XrTrackableMarkerDictionaryANDROID opisuje obsługiwane słowniki znaczników.

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;

Struktura XrTrackableMarkerDatabaseEntryANDROID konfiguruje pojedynczy identyfikator znacznika w słowniku.

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

Opisy elementów

  • id to identyfikator znacznika podany w słowniku.
  • edgeSize to rozmiar krawędzi znacznika w metrach. Jeśli środowisko wykonawcze obsługuje szacowanie rozmiaru znacznika, aplikacja może ustawić tę wartość na zero, a rozmiar znacznika zostanie oszacowany online. Jeśli ta wartość jest ustawiona na zero, ale środowisko wykonawcze nie obsługuje szacowania rozmiaru znacznika, musi zwracać XR_ERROR_VALIDATION_FAILURE .

Prawidłowe użycie (niejawne)

Pobieranie znaczników

Funkcja xrGetTrackableMarkerANDROID jest zdefiniowana w ten sposób:

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

Opisy parametrów

Środowisko wykonawcze musi zwracać XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID , jeśli typ śledzenia XrTrackableANDROID nie jest XR_TRACKABLE_TYPE_MARKER_ANDROID lub jeśli typ śledzenia XrTrackableTrackerANDROID nie jest XR_TRACKABLE_TYPE_MARKER_ANDROID .

Prawidłowe użycie (niejawne)

Kody powrotu

Sukces

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Błąd

  • 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

Struktura XrTrackableMarkerANDROID jest zdefiniowana w ten sposób:

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

Opisy elementów

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowej wersji OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur.
  • trackingState to XrTrackingStateANDROID znacznika.
  • lastUpdatedTime to XrTime ostatniej aktualizacji znacznika.
  • dictionary to XrTrackableMarkerDictionaryANDROID znacznika.
  • markerId to identyfikator znacznika podany w słowniku.
  • centerPose to XrPosef znacznika znajdującego się w XrTrackableGetInfoANDROID :: baseSpace . Znacznik znajduje się w płaszczyźnie XZ, gdzie oś X wskazuje na prawo od znacznika, oś Z na jego dół, a oś Y wychodzi ze znacznika jako normalna.
  • extents to wymiary znacznika XrExtent2Df. Granica ramki ograniczającej znajduje się w punktach: centerPose +/- ( extents / 2).

Prawidłowe użycie (niejawne)

Przykładowy kod do pobierania śledzonych znaczników

Poniższy przykładowy kod pokazuje, jak pobierać śledzone znaczniki.

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

Nowe polecenia

Nowe struktury

Nowe wyliczenia

Nowe stałe wyliczenia

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Rozszerzanie XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Rozszerzanie XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Problemy

Historia zmian

  • Wersja 1, 23 lipca 2025 r. (Levana Chen)

    • Pierwszy opis rozszerzenia.