XR_ANDROID_trackables_marker

String Nama

XR_ANDROID_trackables_marker

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

708

Revisi

1

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

XR_ANDROID_trackables

Status Penghentian Penggunaan

  • Tidak digunakan lagi oleh ekstensi XR_EXT_spatial_marker_tracking

Tanggal Terakhir Diubah

2025-07-23

Status IP

Tidak ada klaim kekayaan intelektual yang diketahui.

Kontributor

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

Ringkasan

Ekstensi ini memungkinkan pelacakan penanda fisik, dan memungkinkan aplikasi melampirkan konten XR ke penanda fisik secara efisien.

Ekstensi ini mendukung jenis penanda yang terkenal, khususnya ArUco dan April Tag. Hal ini memungkinkan runtime untuk secara opsional mendukung estimasi ukuran penanda.

Izin

Aplikasi Android harus memiliki izin android.permission.SCENE_UNDERSTANDING_COARSE yang tercantum dalam manifesnya karena ekstensi ini bergantung pada XR_ANDROID_trackables dan mengekspos geometri lingkungan. Izin android.permission.SCENE_UNDERSTANDING_COARSE dianggap sebagai izin berbahaya, yaitu aplikasi harus meminta izin secara eksplisit.

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemMarkerTrackingPropertiesANDROID didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini. Untuk mengetahui detail selengkapnya tentang rantai struktur, lihat struktur yang diperluas ( XrSystemProperties ).
  • supportsMarkerTracking adalah XrBool32 yang menunjukkan apakah sistem saat ini menyediakan kemampuan pelacakan penanda.
  • supportsMarkerSizeEstimation adalah XrBool32 yang menunjukkan apakah sistem saat ini menyediakan estimasi ukuran penanda.
  • maxMarkerCount adalah jumlah maksimum penanda yang dapat dilacak runtime secara bersamaan.

Aplikasi dapat memeriksa apakah sistem mampu melakukan pelacakan penanda dengan memperluas XrSystemProperties dengan struktur XrSystemMarkerTrackingPropertiesANDROID saat memanggil xrGetSystemProperties . Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED untuk pembuatan pelacak penanda jika dan hanya jika supportsMarkerTracking adalah XR_FALSE .

Jika runtime mendukung pelacakan penanda, maxMarkerCount harus minimal 1.

Penggunaan yang Valid (Implisit)

Penanda pelacakan

Ekstensi ini menambahkan XR_TRACKABLE_TYPE_MARKER_ANDROID ke XrTrackableTypeANDROID .

Aplikasi membuat XrTrackableTrackerANDROID dengan memanggil xrCreateTrackableTrackerANDROID dan menentukan XR_TRACKABLE_TYPE_MARKER_ANDROID sebagai jenis yang dapat dilacak di XrTrackableTrackerCreateInfoANDROID :: trackableType serta menetapkan konfigurasi yang valid dengan menambahkan XrTrackableMarkerConfigurationANDROID ke rantai XrTrackableTrackerCreateInfoANDROID berikutnya.

Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED jika XrTrackableTrackerCreateInfoANDROID :: trackableType adalah XR_TRACKABLE_TYPE_MARKER_ANDROID dan XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking menampilkan XR_FALSE melalui xrGetSystemProperties .

Struktur XrTrackableMarkerConfigurationANDROID didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • trackingMode adalah XrTrackableMarkerTrackingModeANDROID yang menunjukkan mode yang diinginkan untuk pelacakan.
  • databaseCount adalah uint32_t yang menjelaskan jumlah elemen dalam array databases.
  • databases adalah pointer ke array XrTrackableMarkerDatabaseANDROID , yang masing-masing berisi penanda yang diinginkan dari kamus tertentu untuk dilacak.

Aplikasi harus menetapkan konfigurasi yang valid dengan menambahkan XrTrackableMarkerConfigurationANDROID ke rantai XrTrackableTrackerCreateInfoANDROID :: next saat memanggil xrCreateTrackableTrackerANDROID dengan XrTrackableTrackerCreateInfoANDROID :: trackableType ditetapkan ke XR_TRACKABLE_TYPE_MARKER_ANDROID . Jika tidak, jika jenis pelacak ditetapkan seperti di atas, tetapi struktur konfigurasi tidak ada atau tidak valid, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

Jika runtime mendukung estimasi ukuran penanda, aplikasi dapat menetapkan XrTrackableMarkerDatabaseEntryANDROID :: edgeSize ke 0 di XrTrackableMarkerDatabaseANDROID :: entries untuk menunjukkan penggunaan estimasi ukuran. Jika tidak, aplikasi harus menetapkan XrTrackableMarkerDatabaseEntryANDROID :: edgeSize ke nilai positif atau runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

Runtime harus memfilter output dari xrGetAllTrackablesANDROID agar cocok dengan trackingMode dan XrTrackableMarkerDatabaseEntryANDROID :: edgeSize .

Penggunaan yang Valid (Implisit)

Enum XrTrackableMarkerTrackingModeANDROID menjelaskan mode pelacakan penanda yang didukung.

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;

Deskripsi Enumeran

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID — Melacak penanda dinamis. Mode ini memiliki akurasi tertinggi dan berfungsi pada penanda bergerak dan statis, tetapi juga memiliki konsumsi daya tertinggi.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID — Melacak penanda statis. Mode ini terutama berguna untuk penanda yang diketahui bersifat statis, sehingga menghasilkan konsumsi daya yang lebih rendah dibandingkan dengan mode dinamis.

Struktur XrTrackableMarkerDatabaseANDROID menentukan kamus dan ID penanda yang sesuai untuk dilacak.

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

Deskripsi Anggota

  • dictionary adalah XrTrackableMarkerDictionaryANDROID yang menjadi tempat semua entries berada.
  • entryCount adalah uint32_t yang menjelaskan jumlah elemen dalam array entries. Aplikasi dapat menetapkan entryCount 0 untuk melacak semua penanda di dictionary .
  • entries adalah pointer ke array XrTrackableMarkerDatabaseEntryANDROID , yang masing-masing berisi konfigurasi penanda yang akan dilacak.

Penggunaan yang Valid (Implisit)

Enum XrTrackableMarkerDictionaryANDROID menjelaskan kamus penanda yang didukung.

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;

Struktur XrTrackableMarkerDatabaseEntryANDROID mengonfigurasi satu ID penanda kamus.

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

Deskripsi Anggota

  • id adalah ID penanda seperti yang diberikan dalam kamus.
  • edgeSize mewakili ukuran tepi penanda dalam meter. Jika runtime mendukung estimasi ukuran penanda, aplikasi dapat menetapkan nilai ini ke nol dan ukuran penanda akan diperkirakan secara online. Jika ini ditetapkan ke nol, tetapi runtime tidak mendukung estimasi ukuran penanda, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

Penggunaan yang Valid (Implisit)

Mendapatkan penanda

Fungsi xrGetTrackableMarkerANDROID didefinisikan sebagai:

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

Deskripsi Parameter

Runtime harus menampilkan XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID jika jenis yang dapat dilacak dari XrTrackableANDROID bukan XR_TRACKABLE_TYPE_MARKER_ANDROID , atau jika jenis yang dapat dilacak dari XrTrackableTrackerANDROID bukan XR_TRACKABLE_TYPE_MARKER_ANDROID .

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • 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

Struktur XrTrackableMarkerANDROID didefinisikan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • trackingState adalah XrTrackingStateANDROID penanda.
  • lastUpdatedTime adalah XrTime dari update terakhir penanda.
  • dictionary adalah XrTrackableMarkerDictionaryANDROID penanda.
  • markerId adalah ID penanda seperti yang diberikan dalam kamus.
  • centerPose adalah XrPosef penanda yang terletak di XrTrackableGetInfoANDROID :: baseSpace . Penanda terletak di bidang XZ dengan X mengarah ke kanan penanda dan Z mengarah ke bawahnya dan Y keluar dari penanda sebagai normal.
  • extents adalah dimensi XrExtent2Df penanda. Batas kotak pembatas berada di titik: centerPose +/- ( extents / 2).

Penggunaan yang Valid (Implisit)

Contoh kode untuk mendapatkan penanda yang dapat dilacak

Kode contoh berikut menunjukkan cara mendapatkan penanda yang dapat dilacak.

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

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • Memperluas XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • Memperluas XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Masalah

Riwayat Versi

  • Revisi 1, 23-07-2025 (Levana Chen)

    • Deskripsi ekstensi awal.