XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

708

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_ANDROID_trackables

Stato di ritiro

  • Ritirata dall'estensione XR_EXT_spatial_marker_tracking

Data ultima modifica

23/07/2025

Stato IP

Nessuna rivendicazione di PI 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 marker fisici e permette alle applicazioni di collegare i contenuti XR ai marker fisici in modo efficiente.

L'estensione supporta tipi di marker noti, in particolare ArUco e AprilTag. Consente ai runtime di supportare facoltativamente la stima delle dimensioni dei marker.

Autorizzazioni

Le app per 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 richiederla esplicitamente.

(livello di protezione: pericoloso)

Ispeziona la funzionalità del sistema

La struttura XrSystemMarkerTrackingPropertiesANDROID è definita come:

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 struttura di questo tipo è definita in OpenXR di base o in questa estensione. Per maggiori dettagli sulla catena di strutture, consulta la struttura che viene estesa ( XrSystemProperties).
  • supportsMarkerTracking è un XrBool32 che indica se il sistema attuale fornisce la funzionalità di monitoraggio dei marker.
  • supportsMarkerSizeEstimation è un XrBool32 che indica se il sistema attuale fornisce la stima delle dimensioni del marker.
  • maxMarkerCount è il numero massimo di indicatori che il runtime è in grado di monitorare contemporaneamente.

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

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

Utilizzo valido (implicito)

Indicatori di monitoraggio

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 elemento tracciabile 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:

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 marker 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 marker, 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 o 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 supportate dei marker.

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 marker dinamici. Questa modalità offre la massima precisione e funziona con indicatori in movimento e statici, ma ha anche il consumo energetico più elevato.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID: monitoraggio degli indicatori statici. Questa modalità è utile principalmente per i marker che sono 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 marker corrispondenti da monitorare.

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

Descrizioni dei membri

  • dictionary è l'oggetto XrTrackableMarkerDictionaryANDROID a cui appartengono tutti gli oggetti entries.
  • entryCount è un uint32_t che descrive il numero di elementi nell'array entries. L'applicazione può impostare entryCount 0 per monitorare tutti gli indicatori in dictionary .
  • entries è un puntatore a un array di XrTrackableMarkerDatabaseEntryANDROID , ognuno dei quali contiene la configurazione di un indicatore da monitorare.

Utilizzo valido (implicito)

L'enum XrTrackableMarkerDictionaryANDROID descrive i dizionari di indicatori 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 indicatore di un dizionario.

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

Descrizioni dei membri

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

Utilizzo valido (implicito)

Recupera indicatori

La funzione xrGetTrackableMarkerANDROID è definita come:

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 tracciabile di XrTrackableANDROID non è XR_TRACKABLE_TYPE_MARKER_ANDROID o se il tipo tracciabile di XrTrackableTrackerANDROID non è XR_TRACKABLE_TYPE_MARKER_ANDROID .

Utilizzo valido (implicito)

Codici di risposta

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:

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 struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • trackingState è l'XrTrackingStateANDROID del marker.
  • lastUpdatedTime è l'XrTime dell'ultimo aggiornamento dell'indicatore.
  • dictionary è l'oggetto XrTrackableMarkerDictionaryANDROID del marker.
  • markerId è l'ID dell'indicatore fornito nel dizionario.
  • centerPose è l'XrPosef del marker che si trova in XrTrackableGetInfoANDROID :: baseSpace . L'indicatore si trova nel piano XZ con X che punta a destra dell'indicatore, Z che punta verso il basso e Y che esce dall'indicatore come normale.
  • extents sono le dimensioni XrExtent2Df dell'indicatore. Il confine del riquadro di delimitazione si trova nei punti: centerPose +/- ( extents / 2).

Utilizzo valido (implicito)

Codice di esempio per ottenere indicatori tracciabili

Il seguente codice di esempio mostra come ottenere indicatori 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.