XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Typ rozszerzenia

Rozszerzenie instancji

Zarejestrowany numer wewnętrzny

708

Wersja

1

Stan ratyfikacji

Nie ratyfikowano

Zależności rozszerzeń i wersji

XR_ANDROID_trackables

Stan wycofania

  • Wycofane przez rozszerzenie XR_EXT_spatial_marker_tracking

Data ostatniej modyfikacji

2025-07-23

Stan IP

Brak znanych roszczeń dotyczących własności intelektualnej.

Twórcy

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 znaczników fizycznych i pozwala aplikacjom na efektywne dołączanie treści XR do znaczników fizycznych.

Rozszerzenie obsługuje znane typy znaczników, w szczególności ArUco i AprilTag. Umożliwia środowiskom wykonawczym opcjonalną obsługę szacowania rozmiaru znacznika.

Uprawnienia

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

(poziom ochrony: niebezpieczne)

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 członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie OpenXR ani w tym rozszerzeniu nie zdefiniowano takich struktur. Więcej informacji o łańcuchu struktur znajdziesz w rozszerzanej strukturze ( XrSystemProperties).
  • supportsMarkerTracking to XrBool32 wskazujący, czy bieżący system zapewnia możliwość śledzenia znaczników.
  • supportsMarkerSizeEstimation to XrBool32 wskazujący, czy bieżący system umożliwia oszacowanie rozmiaru znacznika.
  • maxMarkerCount to maksymalna liczba znaczników, które środowisko wykonawcze może śledzić jednocześnie.

Aplikacja może sprawdzić, czy system jest w stanie śledzić znaczniki, rozszerzając XrSystemProperties o strukturę XrSystemMarkerTrackingPropertiesANDROID podczas wywoływania xrGetSystemProperties . Środowisko wykonawcze musi zwracać XR_ERROR_FEATURE_UNSUPPORTED w przypadku tworzenia modułu śledzenia znaczników tylko wtedy, gdy supportsMarkerTracking to XR_FALSE .

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

Prawidłowe użycie (pośrednie)

Znaczniki śledzenia

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 obiektu możliwego do ś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 to XR_TRACKABLE_TYPE_MARKER_ANDROID, a XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking zwraca XR_FALSE przez 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 członkó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żda zawiera znaczniki z danego słownika, które mają być śledzone.

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 . Jeśli typ modułu śledzącego jest ustawiony jak powyżej, ale struktura konfiguracji nie jest obecna lub jest nieprawidłowa, środowisko wykonawcze musi zwrócić błąd 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 zwrócić XR_ERROR_VALIDATION_FAILURE .

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

Prawidłowe użycie (pośrednie)

Typ wyliczeniowy 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 zapewnia 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 członków

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

Prawidłowe użycie (pośrednie)

Typ wyliczeniowy 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 słownika.

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

Opisy członków

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

Prawidłowe użycie (pośrednie)

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 (pośrednie)

Kody zwrotu

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 członków

  • type to XrStructureType tej struktury.
  • next to NULL lub wskaźnik do następnej struktury w łańcuchu struktur. W podstawowym interfejsie 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 leży na płaszczyźnie XZ, przy czym oś X wskazuje prawą stronę znacznika, oś Z – jego dół, a oś Y – prostopadłą do znacznika.
  • extents to wymiary XrExtent2Df znacznika. Granica ramki ograniczającej znajduje się w punktach: centerPose +/- ( extents / 2).

Prawidłowe użycie (pośrednie)

Przykładowy kod do pobierania znaczników możliwych do śledzenia

Poniższy przykładowy kod pokazuje, jak uzyskać znaczniki możliwe do śledzenia.

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 domy

Nowe wartości w polu enum

Nowe stałe typu wyliczeniowego

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

    • Początkowy opis rozszerzenia.