XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

708

Düzeltme

1

Onay Durumu

Onaylanmadı

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

XR_ANDROID_trackables

Desteği Sonlandı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 bir fikri mülkiyet 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 takibini etkinleştirir ve uygulamaların XR içeriğini fiziksel işaretçilere verimli bir şekilde eklemesine olanak tanır.

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

İzinler

Android uygulamalarının manifest dosyasında android.permission.SCENE_UNDERSTANDING_COARSE izni bulunmalıdır. Bu uzantı, XR_ANDROID_trackables uzantısına bağlıdır ve ortamın geometrisini gösterir. android.permission.SCENE_UNDERSTANDING_COARSE izni tehlikeli bir izin olarak kabul edilir. Bu nedenle uygulamaların bu izni açıkça istemesi gerekir.

(koruma düzeyi: tehlikeli)

Sistem özelliğini 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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da 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 sağlayıp sağlamadığını gösteren bir XrBool32 değeridir.
  • supportsMarkerSizeEstimation, mevcut sistemin işaretçi boyutu tahmini sağlayıp sağlamadığını gösteren bir XrBool32 değeridir.
  • maxMarkerCount, çalışma zamanının aynı anda izleyebileceği maksimum işaretçi sayısıdır.

Uygulamalar, xrGetSystemProperties çağrısı yaparken XrSystemProperties'i XrSystemMarkerTrackingPropertiesANDROID yapısıyla genişleterek sistemin işaretçi takibi yapıp yapamayacağını kontrol edebilir. Çalışma zamanı, yalnızca supportsMarkerTracking, XR_FALSE ise işaretçi izleyici oluşturma için XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir.

Ç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'ye XR_TRACKABLE_TYPE_MARKER_ANDROID ekler.

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

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

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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir.
  • trackingMode, istenen izleme modunu belirten bir XrTrackableMarkerTrackingModeANDROID değeridir.
  • databaseCount, databases dizisindeki öğe sayısını açıklayan bir uint32_t değeridir.
  • databases, her biri belirli bir sözlükten izlenecek istenen işaretçileri içeren bir XrTrackableMarkerDatabaseANDROID dizisine işaretçidir.

Uygulama, XrTrackableTrackerCreateInfoANDROID :: trackableType, XR_TRACKABLE_TYPE_MARKER_ANDROID olarak ayarlanmış şekilde xrCreateTrackableTrackerANDROID'i çağırırken XrTrackableTrackerCreateInfoANDROID :: next zincirine bir XrTrackableMarkerConfigurationANDROID ekleyerek geçerli bir yapılandırma ayarlamalıdır (must). 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 (must).

Ç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ı, trackingMode ve XrTrackableMarkerDatabaseEntryANDROID :: edgeSize ile eşleşmesi için xrGetAllTrackablesANDROID çıkışını filtrelemelidir (must).

Geçerli Kullanım (Dolaylı)

XrTrackableMarkerTrackingModeANDROID enum, 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ırma 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şaretleyicilerde çalışır ancak aynı zamanda en yüksek güç tüketimine sahiptir.
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID: Statik işaretçileri izleme. Bu mod, öncelikle statik olduğu bilinen işaretçiler için kullanışlıdır. Bu sayede, dinamik moda kıyasla daha az güç tüketimi sağlanır.

XrTrackableMarkerDatabaseANDROID yapısı, bir sözlük ve takip edilecek 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'dir. Uygulama, dictionary içindeki tüm işaretçileri izlemek için entryCount 0 değerini ayarlayabilir.
  • entries, her biri izlenecek bir işaretçinin yapılandırmasını içeren bir XrTrackableMarkerDatabaseEntryANDROID dizisine işaret eder.

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 temsil eder. Ç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 ayarlanmışsa ancak çalışma zamanı, işaretçi boyutu tahminini desteklemiyorsa çalışma zamanı 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ı

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 çalışma zamanı 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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • trackingState, işaretçinin 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şaretçinin XrPosef değeridir. İşaretçi, XZ düzleminde yer alır. X, işaretçinin sağını, Z ise altını gösterir. Y ise 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 Enum Veri Türleri

Yeni Enum Sabitleri

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • XrStructureType'ı genişletme:

    • 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ı.