XR_ANDROID_trackables_image

Name String

XR_ANDROID_trackables_image

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

710

Düzeltme

1

Onay durumu

Onaylanmadı

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

XR_EXT_future
ve
XR_ANDROID_trackables

Son Değiştirilme Tarihi

2025-04-08

IP Durumu

Bilinen IP hak talebi yok.

Katkıda bulunanlar

Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm

Genel Bakış

Bu uzantı, giriş referans resim kümeleriyle belirtildiği şekilde düzlem resimlerin izlenmesini 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.

(koruma düzeyi: tehlikeli)

Sistem kapasitesini inceleme

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

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

Ü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.
  • supportsImageTracking, mevcut sistemin görüntü izleme özelliği sağlayıp sağlamadığını gösteren bir XrBool32'dir.
  • supportsPhysicalSizeEstimation, mevcut sistemin resim boyutu tahmini sağlayıp sağlamadığını belirten bir XrBool32.
  • maxTrackedImageCount, aynı anda izlenebilecek toplam maksimum resim sayısıdır.
  • maxLoadedImageCount, tüm veritabanlarında yüklenebilecek referans resimlerin toplam maksimum sayısıdır.

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

Bir çalışma zamanı, resim izlemeyi destekliyorsa herhangi bir zamanda maxTrackedImageCount izlenen resmi desteklemesi gerekir.

Bir çalışma zamanı, görüntü izlemeyi destekliyorsa herhangi bir zamanda maxLoadedImageCount yüklü görüntüyü desteklemesi gerekir.

Bir çalışma zamanı, resim boyutu tahminini destekliyorsa uygulama, boyut tahmininin kullanımını belirtmek için XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 değerini ayarlayabilir. Aksi takdirde, uygulama XrTrackableImageDatabaseEntryANDROID :: physicalWidth değerini pozitif bir değere ayarlamalıdır. Aksi takdirde XR_ERROR_VALIDATION_FAILURE döndürülür.

Geçerli Kullanım (Dolaylı)

Veritabanı oluşturma

Uygulama, bir veya daha fazla XrTrackableImageDatabaseEntryANDROID yapısı oluşturup bunları XrTrackableImageDatabaseCreateInfoANDROID yapısı aracılığıyla xrCreateTrackableImageDatabaseAsyncANDROID işlevine ileterek XrTrackableImageDatabaseANDROID tutacağı oluşturabilir.

Uygulama, XrTrackableImageDatabaseANDROID tutacağı oluştururken en az bir XrTrackableImageDatabaseEntryANDROID sağlamalıdır.

XrTrackableImageDatabaseANDROID, ortamda keşfedilebilen ve izlenebilen bir dizi işlenmiş referans görüntüyü temsil eden bir tutamaktır.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

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

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

Ü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.
  • trackingMode, izleme için istenen modu belirten bir XrTrackableImageTrackingModeANDROID'dir.
  • physicalWidth, resmin metre cinsinden genişliğini gösterir. Sıfırsa resim boyutu online olarak tahmin edilir.
  • imageWidth, resmin piksel cinsinden genişliğini gösterir.
  • imageHeight, resmin piksel cinsinden yüksekliğini gösterir.
  • format, buffer içindeki görüntü verilerinin biçimini gösteren bir XrTrackableImageFormatANDROID'dir .
  • bufferSize, buffer öğesinin bayt uzunluğunu gösterir .
  • buffer, referans görsel piksel verilerini içeren uint8_t arabelleğidir. buffer içeriği, xrCreateTrackableImageDatabaseAsyncANDROID ile başlatılan ve xrCreateTrackableImageDatabaseCompleteANDROID ile tamamlanan veritabanı oluşturma eş zamansız işlemi süresince geçerli olmalıdır .

XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation değeri XR_TRUE ise uygulama, online boyut tahmini istemek için physicalWidth değerini 0 olarak ayarlayabilir.

Çalışma zamanı, bufferSize, girişin imageWidth, imageHeight ve format değerlerine göre beklenen boyuta uymuyorsa xrCreateTrackableImageDatabaseAsyncANDROID işlevinden XR_ERROR_VALIDATION_FAILURE değerini döndürebilir .

Geçerli Kullanım (Dolaylı)

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

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

Ü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.
  • entryCount, entries dizisindeki öğelerin sayısını belirten bir uint32_t değeridir.
  • entries, XrTrackableImageDatabaseEntryANDROID yapılarının bir dizisidir.

Geçerli Kullanım (Dolaylı)

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

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

Ü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.
  • futureResult, eşzamansız işlemin XrResult'ıdır.
  • database, oluşturulan XrTrackableImageDatabaseANDROID tutma yeridir.

Gelecekteki İade Kodları

futureResult değerleri:

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Geçerli Kullanım (Dolaylı)

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

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

Parametre Açıklamaları

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

Parametre Açıklamaları

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

Parametre Açıklamaları

Geçerli Kullanım (Dolaylı)

İş Parçacığı Güvenliği (Thread Safety)

  • database ve tüm alt tutma yerlerine erişim, harici olarak senkronize edilmelidir.

Dönüş Kodları

Başarılı

  • XR_SUCCESS

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

İzleme resimleri

Bu uzantı, XrTrackableTypeANDROID öğesine XR_TRACKABLE_TYPE_IMAGE_ANDROID ekler .

Uygulama, xrCreateTrackableTrackerANDROID işlevini çağırıp XrTrackableTrackerCreateInfoANDROID :: trackableType içinde izlenebilir tür olarak XR_TRACKABLE_TYPE_IMAGE_ANDROID değerini belirterek görüntüleri izlemek için XrTrackableTrackerANDROID oluşturabilir.

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

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

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

Ü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.
  • databaseCount, databases içindeki öğe sayısını belirten bir uint32_t değeridir.
  • databases, takip cihazını oluşturmak için kullanılacak veritabanlarını belirten bir XrTrackableImageDatabaseANDROID dizisidir.

Uygulama, XrTrackableTrackerCreateInfoANDROID next zincirine XrTrackableImageConfigurationANDROID ekleyerek geçerli bir yapılandırma ayarlamalıdır . Aksi takdirde, çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

Uygulama, izleyiciyi oluşturmak için en az bir XrTrackableImageDatabaseANDROID yapısı sağlamalıdır.

Geçerli Kullanım (Dolaylı)

XrTrackableImageTrackingModeANDROID numaralandırması, resimlerin desteklenen izleme modlarını açıklar.

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

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

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID: Bu mod en yüksek doğruluğa sahiptir ve hareketli görüntülerin düşük gecikmeli olarak izlenmesine olanak tanır. Ayrıca en yüksek güç tüketimine de sahiptir.
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID: Bu mod, statik veya yarı statik olduğu bilinen resimler için kullanılmalıdır. Bu mod, dinamik moda kıyasla daha az güç tüketir. Statik bir görüntü taşınıyorsa dinamik mod kullanmaya kıyasla çok daha yüksek bir gecikmeyle güncellenir.

XrTrackableImageFormatANDROID numaralandırması, desteklenen resim biçimlerini açıklar.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

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

  • XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: Kanal başına 8 bit renk ve şeffaflık verisi içeren RGBA görüntü biçimi.

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

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Parametre Açıklamaları

Bir izleyiciye XrTrackableImageDatabaseANDROID eklendiğinde, bu veritabanının referans resimleri, izleyici ilk oluşturulurken xrAddTrackableImageDatabaseANDROID ile veya XrTrackableImageConfigurationANDROID yapısı aracılığıyla daha önce eklenmiş olan diğer veritabanlarının yanı sıra algılama ve izleme için dikkate alınmalıdır.

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_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

Parametre Açıklamaları

Bir XrTrackableImageDatabaseANDROID , XrTrackableTrackerANDROID öğesinden kaldırıldığında bu veritabanının XrTrackableImageDatabaseEntryANDROID yapıları artık algılama ve izleme için dikkate alınmamalıdır. Bu veritabanının etkin olarak izlenen girişleri artık bildirilmemelidir. Kaldırılan XrTrackableImageDatabaseANDROID tutacağı, bu işlem kapsamında dolaylı olarak yok edilmemelidir.

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Resimleri alma

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

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

Parametre Açıklamaları

Çalışma zamanı , XrTrackableANDROID öğesinin izlenebilir türü XR_TRACKABLE_TYPE_IMAGE_ANDROID değilse veya XrTrackableTrackerANDROID öğesinin izlenebilir türü XR_TRACKABLE_TYPE_IMAGE_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_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

Ü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, resmin XrTrackingStateANDROID değeridir.
  • lastUpdatedTime, resmin son güncellemesinin XrTime değeridir.
  • database, bu görüntünün izlendiği XrTrackableImageDatabaseANDROID tutma yeridir.
  • databaseEntryIndex, XrTrackableImageDatabaseCreateInfoANDROID :: entries dizisine eşlenen database dizinidir .
  • centerPose, XrTrackableGetInfoANDROID :: baseSpace konumundaki resmin XrPosef değeridir . Resim, XZ düzleminde yer alır. X, resmin sağını, Z ise altını gösterir.
  • extents, resmin XrExtent2Df boyutlarıdır. Sınırlayıcı kutunun sınırı şu noktalardadır: centerPose +/- ( extents / 2).

Geçerli Kullanım (Dolaylı)

Hataları işleme

Uygulama, xrPollEvent kullanarak XrEventDataImageTrackingLostANDROID etkinliğini sorgulamalıdır ve bu etkinliği yoksaymamalıdır.

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

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

Ü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.
  • time XrTime

XrEventDataImageTrackingLostANDROID etkinliğinin alınması, görüntü izlemenin başarısız olduğunu ve mevcut kaynakların geçersiz kılınmasına neden olan dahili bir hata oluştuğunu gösterir. Uygulama, görüntü izlemeye devam etmek istiyorsa tüm XrTrackableImageDatabaseANDROID tanıtıcılarını kaldırmalı ve bunları yeniden oluşturmalıdır. Uygulama, görüntü izlemeye devam etmek istiyorsa görüntü izlemeyle ilgili tüm XrTrackableTrackerANDROID tanıtıcılarını da kaldırmalı ve yeniden oluşturmalıdır.

Geçerli Kullanım (Dolaylı)

İzlenebilir resimleri alma için örnek kod

Aşağıdaki örnek kodda, izlenebilir resimlerin nasıl alınacağı gösterilmektedir.

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // 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
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

Çalışma zamanında resim veritabanlarını yönetmeye yönelik örnek kod

Aşağıdaki örnek kod, izlenen resim grubunun nasıl değiştirileceğini gösterir.

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

Resim izleme hatalarına tepki verme ile ilgili örnek kod

Aşağıdaki örnek kodda, XrEventDataImageTrackingLostANDROID etkinliği için yoklama yaparak hatanın nasıl ele alınacağı gösterilmektedir.

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

Yeni Nesne Türleri

Yeni Komutlar

Yeni Yapılar

Yeni Sıralamalar

Yeni Enum Sabitleri

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • XrObjectType'i genişletme :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • XrResult'ı genişletme :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XrStructureType uzatma :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • XrTrackableTypeANDROID'i genişletme :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

Sayılar

Sürüm Geçmişi

  • 1. sürüm, 2025-04-08 (Daniel Guttenberg)

    • İlk uzantı açıklaması.