XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

708

Düzeltme

1

Onay durumu

Onaylanmadı

Uzantı ve Sürüm Bağımlılıkları

XR_ANDROID_trackables

Kullanımdan Kaldırma Durumu

  • XR_EXT_spatial_marker_tracking uzantısı tarafından kullanımdan kaldırıldı

Son Değiştirilme Tarihi

2025-07-23

IP Durumu

Bilinen IP hak talebi yok.

Katkıda bulunanlar

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

Genel Bakış

Bu uzantı, fiziksel işaretçi izlemeyi etkinleştirir ve uygulamaların XR içeriğini fiziksel işaretçilere verimli bir şekilde eklemesini sağlar.

Uzantı, iyi bilinen işaretleyici türlerini (özellikle ArUco ve April etiketleri) destekler. Çalışma zamanlarının, işaretçi boyutu tahminini isteğe bağlı olarak desteklemesini sağlar.

İzinler

Bu uzantı XR_ANDROID_trackables'ya bağlı olduğundan ve ortamın geometrisini ortaya çıkardığından Android uygulamalarının manifest dosyalarında android.permission.SCENE_UNDERSTANDING_COARSE izninin listelenmesi gerekir. android.permission.SCENE_UNDERSTANDING_COARSE izni tehlikeli bir izin olarak kabul edilir. Yani uygulamaların bu izni açıkça istemesi gerekir.

(koruma düzeyi: tehlikeli)

Sistem kapasitesini inceleme

XrSystemMarkerTrackingPropertiesANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır. Yapı zinciri hakkında daha fazla bilgi için genişletilen yapıya ( XrSystemProperties ) bakın.
  • supportsMarkerTracking, mevcut sistemin işaretçi izleme özelliği sunup sunmadığını belirten bir XrBool32'dir.
  • supportsMarkerSizeEstimation, mevcut sistemin işaretçi boyutu tahmini sağlayıp sağlamadığını belirten bir XrBool32.
  • maxMarkerCount, çalışma zamanının aynı anda izleyebileceği maksimum işaretçi sayısıdır.

Bir uygulama, xrGetSystemProperties çağrılırken XrSystemProperties'i XrSystemMarkerTrackingPropertiesANDROID yapısıyla genişleterek sistemin işaretçi izleme özelliğine sahip olup olmadığını kontrol edebilir . Çalışma zamanı, işaretçi izleyici oluşturma için supportsMarkerTracking değeri XR_FALSE ise kesinlikle XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir .

Bir çalışma zamanı işaretçi izlemeyi destekliyorsa maxMarkerCount en az 1 olmalıdır.

Geçerli Kullanım (Dolaylı)

İzleme işaretçileri

Bu uzantı, XrTrackableTypeANDROID öğesine XR_TRACKABLE_TYPE_MARKER_ANDROID ekler .

Uygulama, xrCreateTrackableTrackerANDROID'i çağırıp XrTrackableTrackerCreateInfoANDROID :: trackableType içinde izlenebilir tür olarak XR_TRACKABLE_TYPE_MARKER_ANDROID'i belirterek ve XrTrackableTrackerCreateInfoANDROID'in sonraki zincirine bir XrTrackableMarkerConfigurationANDROID ekleyerek geçerli bir yapılandırma ayarlayarak XrTrackableTrackerANDROID oluşturur .

Çalışma zamanı, XrTrackableTrackerCreateInfoANDROID :: trackableType XR_TRACKABLE_TYPE_MARKER_ANDROID ise ve XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking xrGetSystemProperties aracılığıyla XR_FALSE değerini döndürüyorsa XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir.

XrTrackableMarkerConfigurationANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • trackingMode, izleme için istenen modu belirten bir XrTrackableMarkerTrackingModeANDROID'dir.
  • databaseCount, databases dizisindeki öğelerin sayısını açıklayan bir uint32_t'dir.
  • databases , izlenecek belirli bir sözlükteki istenen işaretçileri içeren XrTrackableMarkerDatabaseANDROID dizisine yönelik bir işaretçidir.

Uygulama, XrTrackableTrackerCreateInfoANDROID :: trackableType XR_TRACKABLE_TYPE_MARKER_ANDROID olarak ayarlanmışken xrCreateTrackableTrackerANDROID çağrılırken XrTrackableTrackerCreateInfoANDROID :: next zincirine XrTrackableMarkerConfigurationANDROID ekleyerek geçerli bir yapılandırma ayarlamalıdır . Aksi takdirde, izleyici türü yukarıdaki gibi ayarlanmışsa ancak yapılandırma yapısı mevcut değilse veya geçerli değilse çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

Bir çalışma zamanı, işaretçi boyutu tahminini destekliyorsa uygulama, boyut tahmininin kullanımını belirtmek için XrTrackableMarkerDatabaseANDROID :: entries içinde XrTrackableMarkerDatabaseEntryANDROID :: edgeSize değerini 0 olarak ayarlayabilir. Aksi takdirde, uygulama XrTrackableMarkerDatabaseEntryANDROID :: edgeSize değerini pozitif bir değere ayarlamalı veya çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

Çalışma zamanı, xrGetAllTrackablesANDROID çıkışını trackingMode ve XrTrackableMarkerDatabaseEntryANDROID :: edgeSize ile eşleşecek şekilde filtrelemelidir .

Geçerli Kullanım (Dolaylı)

XrTrackableMarkerTrackingModeANDROID numaralandırılmış türü, işaretçilerin desteklenen izleme modlarını açıklar.

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;

Numaralandırılmış Değer Açıklamaları

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID: Dinamik işaretçileri izleme. Bu mod en yüksek doğruluğa sahiptir ve hareketli ve statik işaretçilerde çalışır ancak en yüksek güç tüketimine de sahiptir.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID — Statik işaretçileri izleme. Bu mod, öncelikli olarak statik olduğu bilinen işaretçiler için kullanışlıdır. Bu sayede, dinamik moda kıyasla daha az güç tüketilir.

XrTrackableMarkerDatabaseANDROID yapısı, izlenecek bir sözlük ve ilgili işaretçi kimliklerini tanımlar.

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

Üye Açıklamaları

  • dictionary, tüm entries öğelerinin ait olduğu XrTrackableMarkerDictionaryANDROID'dir.
  • entryCount, entries dizisindeki öğelerin sayısını açıklayan bir uint32_t değeridir. Uygulama, dictionary içindeki tüm işaretçileri izlemek için entryCount 0 değerini ayarlayabilir .
  • entries , izlenecek bir işaretçinin yapılandırmasını içeren XrTrackableMarkerDatabaseEntryANDROID dizisine yönelik bir işaretçidir.

Geçerli Kullanım (Dolaylı)

XrTrackableMarkerDictionaryANDROID enum'u, desteklenen işaretçi sözlüklerini açıklar.

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;

XrTrackableMarkerDatabaseEntryANDROID yapısı, bir sözlüğün tek bir işaretçi kimliğini yapılandırır.

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

Üye Açıklamaları

  • id, sözlükte verilen işaretçi kimliğidir.
  • edgeSize, işaretçi kenarının metre cinsinden boyutunu gösterir. Çalışma zamanı, işaretçi boyutu tahminini destekliyorsa uygulama bunu sıfır olarak ayarlayabilir ve işaretçi boyutu online olarak tahmin edilir. Bu değer sıfır olarak ayarlanırsa ancak çalışma zamanı işaretçi boyutu tahminini desteklemiyorsa çalışma zamanı mutlaka XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir .

Geçerli Kullanım (Dolaylı)

İşaretçileri alma

xrGetTrackableMarkerANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

Çalışma zamanı , XrTrackableANDROID öğesinin izlenebilir türü XR_TRACKABLE_TYPE_MARKER_ANDROID değilse veya XrTrackableTrackerANDROID öğesinin izlenebilir türü XR_TRACKABLE_TYPE_MARKER_ANDROID değilse XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID değerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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

XrTrackableMarkerANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • trackingState, işaretleyicinin XrTrackingStateANDROID değeridir.
  • lastUpdatedTime, işaretçinin son güncellemesinin XrTime değeridir.
  • dictionary, işaretçinin XrTrackableMarkerDictionaryANDROID değeridir.
  • markerId, sözlükte verilen işaretçi kimliğidir.
  • centerPose, XrTrackableGetInfoANDROID :: baseSpace içinde bulunan işaretleyicinin XrPosef değeridir . İşaretçi, XZ düzleminde yer alır. X, işaretçinin sağını, Z ise altını gösterir. Y, işaretçiden normal olarak çıkar.
  • extents, işaretçinin XrExtent2Df boyutlarıdır. Sınırlayıcı kutunun sınırı şu noktalardadır: centerPose +/- ( extents / 2).

Geçerli Kullanım (Dolaylı)

İzlenebilir işaretçileri alma için örnek kod

Aşağıdaki örnek kodda, izlenebilir işaretçilerin nasıl alınacağı gösterilmektedir.

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

Yeni Komutlar

Yeni Yapılar

Yeni Sıralamalar

Yeni Enum Sabitleri

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • XrStructureType uzatma :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • XrTrackableTypeANDROID'i genişletme :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

Sayılar

Sürüm Geçmişi

  • Düzeltme 1, 23.07.2025 (Levana Chen)

    • İlk uzantı açıklaması.