XR_ANDROID_trackables_marker

Stringa del nome

XR_ANDROID_trackables_marker

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

708

Revisione

1

Stato di ratifica

Non ratificata

Dipendenze di estensione e versione

XR_ANDROID_trackables

Stato di ritiro

  • Obsoleta dall'estensione XR_EXT_spatial_marker_tracking

Data ultima modifica

23/07/2025

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

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

Panoramica

Questa estensione consente il monitoraggio dei marcatori fisici e consente alle applicazioni di collegare in modo efficiente i contenuti XR ai marcatori fisici.

L'estensione supporta i tipi di marcatori più noti, in particolare ArUco e April Tags. Consente ai runtime di supportare facoltativamente la stima delle dimensioni dei marcatori.

Autorizzazioni

Le applicazioni Android devono disporre dell'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE elencata nel loro manifest, in quanto questa estensione dipende da XR_ANDROID_trackables ed espone la geometria dell'ambiente. L'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE è considerata un'autorizzazione pericolosa, ovvero le applicazioni devono richiedere esplicitamente l'autorizzazione.

(livello di protezione: pericoloso)

Esaminare la funzionalità del sistema

La struttura XrSystemMarkerTrackingPropertiesANDROID è definita come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna di queste strutture è definita in OpenXR di base o in questa estensione. Per ulteriori dettagli sulla catena di strutture, consulta la struttura in fase di estensione ( XrSystemProperties ).
  • supportsMarkerTracking è un XrBool32 che indica se il sistema corrente fornisce la funzionalità di monitoraggio dei marcatori.
  • supportsMarkerSizeEstimation è un XrBool32 che indica se il sistema corrente fornisce la stima delle dimensioni dei marcatori.
  • maxMarkerCount è il numero massimo di marcatori che il runtime è in grado di monitorare contemporaneamente.

Un'applicazione può verificare se il sistema è in grado di monitorare i marcatori estendendo XrSystemProperties con la struttura XrSystemMarkerTrackingPropertiesANDROID quando chiama xrGetSystemProperties . Il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED per la creazione del tracker dei marcatori se e solo se supportsMarkerTracking è XR_FALSE .

Se un runtime supporta il monitoraggio dei marcatori, maxMarkerCount deve essere almeno 1.

Utilizzo valido (implicito)

Monitorare i marcatori

Questa estensione aggiunge XR_TRACKABLE_TYPE_MARKER_ANDROID a XrTrackableTypeANDROID .

L'applicazione crea un XrTrackableTrackerANDROID chiamando xrCreateTrackableTrackerANDROID e specificando XR_TRACKABLE_TYPE_MARKER_ANDROID come tipo di tracciamento in XrTrackableTrackerCreateInfoANDROID :: trackableType , nonché impostando una configurazione valida aggiungendo un XrTrackableMarkerConfigurationANDROID alla catena successiva di XrTrackableTrackerCreateInfoANDROID .

Il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED se XrTrackableTrackerCreateInfoANDROID :: trackableType è XR_TRACKABLE_TYPE_MARKER_ANDROID e XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking restituisce XR_FALSE tramite xrGetSystemProperties .

La struttura XrTrackableMarkerConfigurationANDROID è definita come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • trackingMode è un XrTrackableMarkerTrackingModeANDROID che indica la modalità di monitoraggio desiderata.
  • databaseCount è un uint32_t che descrive il conteggio degli elementi nell'array databases.
  • databases è un puntatore a un array di XrTrackableMarkerDatabaseANDROID , ognuno dei quali contiene i marcatori desiderati di un determinato dizionario da monitorare.

L'applicazione deve impostare una configurazione valida aggiungendo un XrTrackableMarkerConfigurationANDROID alla catena XrTrackableTrackerCreateInfoANDROID :: next quando chiama xrCreateTrackableTrackerANDROID con XrTrackableTrackerCreateInfoANDROID :: trackableType impostato su XR_TRACKABLE_TYPE_MARKER_ANDROID . In caso contrario, se il tipo di tracker è impostato come sopra, ma la struttura di configurazione non è presente o non è valida, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Se un runtime supporta la stima delle dimensioni dei marcatori, l'applicazione può impostare XrTrackableMarkerDatabaseEntryANDROID :: edgeSize su 0 in XrTrackableMarkerDatabaseANDROID :: entries per indicare l'utilizzo della stima delle dimensioni. In caso contrario, l'applicazione deve impostare XrTrackableMarkerDatabaseEntryANDROID :: edgeSize su un valore positivo oppure il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Il runtime deve filtrare l'output di xrGetAllTrackablesANDROID in modo che corrisponda a trackingMode e XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

Utilizzo valido (implicito)

L'enum XrTrackableMarkerTrackingModeANDROID descrive le modalità di monitoraggio dei marcatori supportate.

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;

Descrizioni degli enumeranti

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID : monitoraggio dei marcatori dinamici. Questa modalità ha la massima precisione e funziona su marcatori statici e in movimento, ma ha anche il consumo energetico più elevato.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID : monitoraggio dei marcatori statici. Questa modalità è utile principalmente per i marcatori noti per essere statici, il che comporta un consumo energetico inferiore rispetto alla modalità dinamica.

La struttura XrTrackableMarkerDatabaseANDROID definisce un dizionario e gli ID dei marcatori corrispondenti da monitorare.

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

Descrizioni dei membri

  • dictionary è l'XrTrackableMarkerDictionaryANDROID a cui appartengono tutte le entries.
  • entryCount è un uint32_t che descrive il conteggio degli elementi nell'array entries. L'applicazione può impostare entryCount 0 per monitorare tutti i marcatori nel dictionary .
  • entries è un puntatore a un array di XrTrackableMarkerDatabaseEntryANDROID , ognuno dei quali contiene la configurazione di un marcatore da monitorare.

Utilizzo valido (implicito)

L'enum XrTrackableMarkerDictionaryANDROID descrive i dizionari di marcatori supportati.

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;

La struttura XrTrackableMarkerDatabaseEntryANDROID configura un singolo ID di marcatore di un dizionario.

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

Descrizioni dei membri

  • id è l'ID del marcatore indicato nel dizionario.
  • edgeSize rappresenta le dimensioni del bordo del marcatore in metri. Se il runtime supporta la stima delle dimensioni dei marcatori, l'applicazione può impostare questo valore su zero e le dimensioni del marcatore verranno stimate online. Se questo valore è impostato su zero, ma il runtime non supporta la stima delle dimensioni dei marcatori, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Utilizzo valido (implicito)

Recuperare i marcatori

La funzione xrGetTrackableMarkerANDROID è definita come segue:

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

Descrizioni dei parametri

Il runtime deve restituire XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID se il tipo di tracciamento di XrTrackableANDROID non è XR_TRACKABLE_TYPE_MARKER_ANDROID o se il tipo di tracciamento di XrTrackableTrackerANDROID non è XR_TRACKABLE_TYPE_MARKER_ANDROID .

Utilizzo valido (implicito)

Codici restituiti

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrTrackableMarkerANDROID è definita come segue:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna di queste strutture è definita in OpenXR di base o in questa estensione.
  • trackingState è lo XrTrackingStateANDROID del marcatore.
  • lastUpdatedTime è l'XrTime dell'ultimo aggiornamento dell'indicatore.
  • dictionary è l'XrTrackableMarkerDictionaryANDROID dell'indicatore.
  • markerId è l'ID del marcatore indicato nel dizionario.
  • centerPose è l'XrPosef dell'indicatore che si trova in XrTrackableGetInfoANDROID :: baseSpace . L'indicatore si trova nel piano XZ con X che punta a destra dell'indicatore e Z che punta verso il basso e Y che esce dall'indicatore come normale.
  • extents sono le dimensioni XrExtent2Df del marcatore. Il limite del riquadro di delimitazione si trova nei punti: centerPose +/- ( extents / 2).

Utilizzo valido (implicito)

Esempio di codice per recuperare i marcatori tracciabili

Il seguente esempio di codice mostra come recuperare i marcatori tracciabili.

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

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Estensione di XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Estensione di XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Problemi

Cronologia delle versioni

  • Revisione 1, 23/07/2025 (Levana Chen)

    • Descrizione iniziale dell'estensione.