XR_ANDROID_trackables_image
Name String
XR_ANDROID_trackables_image
Uzantı Türü
Örnek uzantısı
Kayıtlı Dahili Numara
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 bir fikri mülkiyet 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 görseli grupları tarafından belirtilen düzlemsel görsellerin izlenmesini 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.
(koruma düzeyi: tehlikeli)
Sistem özelliğini 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 değeridir.next,NULLveya 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.supportsImageTracking, mevcut sistemin görüntü izleme özelliği sağlayıp sağlamadığını gösteren birXrBool32değeridir.supportsPhysicalSizeEstimation, mevcut sistemin resim boyutu tahmini sağlayıp sağlamadığını gösteren birXrBool32değeridir.maxTrackedImageCount, aynı anda takip edilebilecek maksimum toplam resim sayısıdır.maxLoadedImageCount, tüm veritabanlarına yüklenebilecek maksimum referans görsel sayısıdır.
Uygulamalar, xrGetSystemProperties işlevini çağırı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, 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 desteklemelidir.
Bir çalışma zamanı, resim izlemeyi destekliyorsa herhangi bir zamanda maxLoadedImageCount yüklü resmi desteklemesi gerekir.
Ç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. XR_ERROR_VALIDATION_FAILURE döndürülür.
Geçerli Kullanım (Dolaylı)
- XrSystemImageTrackingPropertiesANDROID kullanılmadan önce
XR_ANDROID_trackables_imageuzantısı etkinleştirilmiş olmalıdır. -
typeXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDolmalıdır -
next,NULLveya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır.
Veritabanı oluşturma
Uygulama, bir veya daha fazla XrTrackableImageDatabaseEntryANDROID yapısı oluşturup bunları bir XrTrackableImageDatabaseCreateInfoANDROID yapısı aracılığıyla xrCreateTrackableImageDatabaseAsyncANDROID işlevine ileterek XrTrackableImageDatabaseANDROID herkese açık kullanıcı adı oluşturabilir.
Uygulama, XrTrackableImageDatabaseANDROID herkese açık kullanıcı adı oluştururken en az bir XrTrackableImageDatabaseEntryANDROID sağlamalıdır.
XrTrackableImageDatabaseANDROID, ortamda keşfedilip takip edilebilecek işlenmiş referans görsellerden oluşan bir grubu temsil eden bir tanıtıcıdı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 değeridir.next,NULLveya 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.trackingMode, izleme için istenen modu belirten bir XrTrackableImageTrackingModeANDROID'dir.physicalWidth, resmin metre cinsinden genişliğini gösterir. Sıfır ise 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,bufferiçindeki resim verilerinin biçimini belirten bir XrTrackableImageFormatANDROID'dir.bufferSize,bufferdeğerinin bayt uzunluğunu gösterir.buffer, referans görsel piksel verilerini içerenuint8_tarabelleğidir.bufferiçeriği, xrCreateTrackableImageDatabaseAsyncANDROID tarafından başlatılan ve xrCreateTrackableImageDatabaseCompleteANDROID tarafından tamamlanan veritabanı oluşturma eş zamansız işlemi süresince geçerli olmalıdır.
XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation, XR_TRUE ise uygulama, online boyut tahmini istemek için physicalWidth değerini 0 olarak ayarlayabilir.
bufferSize, girişin imageWidth, imageHeight ve format değerlerine göre beklenen boyutla eşleşmiyorsa çalışma zamanı, xrCreateTrackableImageDatabaseAsyncANDROID'den XR_ERROR_VALIDATION_FAILURE değerini döndürebilir.
Geçerli Kullanım (Dolaylı)
- XrTrackableImageDatabaseEntryANDROID kullanılmadan önce
XR_ANDROID_trackables_imageuzantısı etkinleştirilmelidir. -
typeXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROIDolmalıdır -
next,NULLveya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır. -
trackingMode, geçerli bir XrTrackableImageTrackingModeANDROID değeri olmalıdır. -
formatgeçerli bir XrTrackableImageFormatANDROID değeri olmalıdır -
buffer,bufferSizeuint8_tdeğerlerinden oluşan bir dizinin işaretçisi olmalıdır -
bufferSizeparametresi0değerinden büyük olmalıdır.
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 değeridir.next,NULLveya 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.entryCount,entriesdizisindeki öğe sayısını belirten biruint32_tdeğeridir.entries, XrTrackableImageDatabaseEntryANDROID yapılarından oluşan bir dizidir.
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_trackables_imageuzantısı, XrTrackableImageDatabaseCreateInfoANDROID kullanılmadan önce etkinleştirilmelidir -
typeXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDolmalıdır -
next,NULLveya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır. -
entries,entryCountgeçerli XrTrackableImageDatabaseEntryANDROID yapısından oluşan bir diziye işaretçi olmalıdır. -
entryCountparametresi0değerinden büyük olmalıdır.
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 değeridir.next,NULLveya 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.futureResult, eşzamansız işlemin XrResult değeridir.database, oluşturulan XrTrackableImageDatabaseANDROID herkese açık adıdır.
Gelecekteki İade Kodları
futureResult değer:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_trackables_imageuzantısı, XrCreateTrackableImageDatabaseCompletionANDROID kullanılmadan önce etkinleştirilmelidir. -
typeXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDolmalıdır -
next,NULLveya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır. -
futureResultgeçerli bir XrResult değeri olmalıdır -
databasegeçerli bir XrTrackableImageDatabaseANDROID tanıtıcısı olmalıdır.
xrCreateTrackableImageDatabaseAsyncANDROID işlevi şu şekilde tanımlanır:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Parametre Açıklamaları
session, daha önce xrCreateSession ile oluşturulmuş bir XrSession için tanıtıcıdır.createInfo, XrTrackableImageDatabaseCreateInfoANDROID yapısına işaret eden bir göstergedir.future, oluşturulanXrFutureEXTiçin bir işaretçidir.
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_trackables_imageuzantısı, xrCreateTrackableImageDatabaseAsyncANDROID çağrılmadan önce etkinleştirilmelidir. -
sessiongeçerli bir XrSession herkese açık kullanıcı adı olmalıdır -
createInfo, geçerli bir XrTrackableImageDatabaseCreateInfoANDROID yapısına işaret eden bir işaretçi olmalıdır. -
future, birXrFutureEXTdeğerine işaretçi olmalıdır
Dönüş Kodları
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrCreateTrackableImageDatabaseCompleteANDROID işlevi şu şekilde tanımlanır:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Parametre Açıklamaları
session, daha önce xrCreateSession ile oluşturulmuş bir XrSession'ın herkese açık kullanıcı adıdır.future, gelecekte tamamlanacakXrFutureEXT.completion, işlemin sonucunu içeren bir XrCreateTrackableImageDatabaseCompletionANDROID yapısına işaret eder.
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_trackables_imageuzantısı, xrCreateTrackableImageDatabaseCompleteANDROID çağrılmadan önce etkinleştirilmelidir. -
sessiongeçerli bir XrSession herkese açık kullanıcı adı olmalıdır -
completion, bir XrCreateTrackableImageDatabaseCompletionANDROID yapısına işaretçi olmalıdır.
Dönüş Kodları
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrDestroyTrackableImageDatabaseANDROID işlevi şu şekilde tanımlanır:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Parametre Açıklamaları
database, yok edilecek XrTrackableImageDatabaseANDROID herkese açık anahtarıdır.
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_trackables_imageuzantısı, xrDestroyTrackableImageDatabaseANDROID çağrılmadan önce etkinleştirilmelidir. -
databasegeçerli bir XrTrackableImageDatabaseANDROID tanıtıcısı olmalıdır.
İleti Dizisi Güvenliği
databaseve tüm alt herkese açık kullanıcı adlarına erişim harici olarak senkronize edilmelidir.
Dönüş Kodları
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
İzleme resimleri
Bu uzantı, XrTrackableTypeANDROID'ye XR_TRACKABLE_TYPE_IMAGE_ANDROID ekler.
Uygulama, xrCreateTrackableTrackerANDROID işlevini çağırarak ve XrTrackableTrackerCreateInfoANDROID :: trackableType içinde izlenebilir tür olarak XR_TRACKABLE_TYPE_IMAGE_ANDROID değerini belirterek XrTrackableTrackerANDROID oluşturabilir.
XrTrackableTrackerCreateInfoANDROID :: trackableType, XR_TRACKABLE_TYPE_IMAGE_ANDROID ise ve XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking, 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).
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 değeridir.next,NULLveya 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.databaseCount,databasesiçindeki öğe sayısını belirten biruint32_tdeğeridir.databases, takipçinin oluşturulacağı veritabanlarını belirten bir XrTrackableImageDatabaseANDROID dizisidir.
Uygulama, XrTrackableTrackerCreateInfoANDROID'nin next zincirine XrTrackableImageConfigurationANDROID ekleyerek geçerli bir yapılandırma ayarlamalıdır (must). Aksi takdirde çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir (must).
Uygulama, izleyiciyi oluşturmak için en az bir XrTrackableImageDatabaseANDROID yapısı sağlamalıdır.
Geçerli Kullanım (Dolaylı)
- XrTrackableImageConfigurationANDROID kullanılmadan önce
XR_ANDROID_trackables_imageuzantısı etkinleştirilmelidir. -
typeXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDolmalıdır -
next,NULLveya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır. -
databases,databaseCountgeçerli XrTrackableImageDatabaseANDROID herkese açık hesaplarından oluşan bir diziye işaretçi olmalıdır. -
databaseCountparametresi0değerinden büyük olmalıdır.
XrTrackableImageTrackingModeANDROID enum, 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ırma 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 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üketimi sağlar. Statik bir resim taşınıyorsa dinamik modun kullanılmasına kıyasla çok daha yüksek bir gecikmeyle güncellenir.
XrTrackableImageFormatANDROID enum, 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ırma Açıklamaları
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: Kanal rengi ve şeffaflık verileri için 8 bit içeren RGBA resim biçimi.
xrAddTrackableImageDatabaseANDROID işlevi şu şekilde tanımlanır:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Parametre Açıklamaları
tracker,databaseöğesinin ekleneceği XrTrackableTrackerANDROID herkese açık tanıtıcısıdır.database,trackeröğesine eklenecek XrTrackableImageDatabaseANDROID herkese açık anahtarıdır.
Bir izleyiciye XrTrackableImageDatabaseANDROID eklendiğinde, bu veritabanının referans görselleri, daha önce xrAddTrackableImageDatabaseANDROID ile veya izleyiciyi ilk oluştururken XrTrackableImageConfigurationANDROID yapısı aracılığıyla eklenen diğer veritabanlarına ek olarak algılama ve izleme için dikkate alınmalıdır.
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_trackables_imageuzantısı, xrAddTrackableImageDatabaseANDROID çağrılmadan önce etkinleştirilmelidir. -
trackergeçerli bir XrTrackableTrackerANDROID herkese açık kullanıcı adı olmalıdır -
databasegeçerli bir XrTrackableImageDatabaseANDROID tanıtıcısı olmalıdır. -
databasevetracker, aynı XrSession'dan oluşturulmuş, tahsis edilmiş veya alınmış olmalıdır.
Dönüş Kodları
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
xrRemoveTrackableImageDatabaseANDROID işlevi şu şekilde tanımlanır:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Parametre Açıklamaları
tracker,databaseöğesinin kaldırılacağı XrTrackableTrackerANDROID herkese açık adıdır.database,trackeröğesinden kaldırılacak XrTrackableImageDatabaseANDROID herkese açık anahtarıdır.
Bir XrTrackableImageDatabaseANDROID, XrTrackableTrackerANDROID'den kaldırıldığında, söz konusu 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 herkese açık kullanıcı adı, bu işlem kapsamında dolaylı olarak yok edilmemelidir.
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_trackables_imageuzantısı, xrRemoveTrackableImageDatabaseANDROID çağrılmadan önce etkinleştirilmelidir. -
trackergeçerli bir XrTrackableTrackerANDROID herkese açık kullanıcı adı olmalıdır -
databasegeçerli bir XrTrackableImageDatabaseANDROID tanıtıcısı olmalıdır. -
databasevetracker, aynı XrSession'dan oluşturulmuş, tahsis edilmiş veya alınmış olmalıdır.
Dönüş Kodları
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Resimler alınıyor
xrGetTrackableImageANDROID işlevi şu şekilde tanımlanır:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Parametre Açıklamaları
tracker, sorgulanacak XrTrackableTrackerANDROID'dir.getInfo, izlenebilir QR kodunu almak için kullanılan bilgileri içeren XrTrackableGetInfoANDROID'dir.trackable, izlenebilir görüntünün döndürüldüğü XrTrackableImageANDROID yapısına işaret eden bir göstergedir.
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 çalışma zamanı XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID değerini döndürmelidir.
Geçerli Kullanım (Dolaylı)
-
XR_ANDROID_trackables_imageuzantısı, xrGetTrackableImageANDROID çağrılmadan önce etkinleştirilmelidir. -
trackergeçerli bir XrTrackableTrackerANDROID herkese açık kullanıcı adı olmalıdır -
getInfo, geçerli bir XrTrackableGetInfoANDROID yapısına işaret eden bir işaretçi olmalıdır. -
trackable, bir XrTrackableImageANDROID yapısına işaretçi olmalıdır.
Dönüş Kodları
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_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 değeridir.next,NULLveya 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, resmin XrTrackingStateANDROID değeridir.lastUpdatedTime, resmin son güncellemeXrTimedeğeridir.database, bu görüntünün izlendiği XrTrackableImageDatabaseANDROID herkese açık adıdır.databaseEntryIndex, XrTrackableImageDatabaseCreateInfoANDROID ::entriesdatabasedizisiyle eşlenen dizindir.centerPose, XrTrackableGetInfoANDROID ::baseSpaceiçinde bulunan 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ı)
-
XR_ANDROID_trackables_imageuzantısı, XrTrackableImageANDROID kullanılmadan önce etkinleştirilmelidir -
typeXR_TYPE_TRACKABLE_IMAGE_ANDROIDolmalıdır -
next,NULLveya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır. -
trackingStategeçerli bir XrTrackingStateANDROID değeri olmalıdır -
databasegeçerli bir XrTrackableImageDatabaseANDROID tanıtıcısı olmalıdır.
Hataları ele alma
Uygulama, xrPollEvent kullanarak XrEventDataImageTrackingLostANDROID etkinliğini sorgulamalı ve bunu 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 değeridir.next,NULLveya 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.timeXrTime
XrEventDataImageTrackingLostANDROID etkinliğinin alınması, görüntü izlemenin dahili bir hataya maruz kaldığını ve mevcut kaynakların geçersiz kılındığını gösterir. Uygulama, tüm XrTrackableImageDatabaseANDROID tanıtıcılarını yok etmeli ve görüntü izlemeye devam etmek istiyorsa bunları yeniden oluşturmalıdır. Uygulama ayrıca görüntü izlemeyle ilgili tüm XrTrackableTrackerANDROID tanıtıcılarını yok etmeli ve görüntü izlemeye devam etmek istiyorsa bunları yeniden oluşturmalıdır.
Geçerli Kullanım (Dolaylı)
- XrEventDataImageTrackingLostANDROID kullanılmadan önce
XR_ANDROID_trackables_imageuzantısı etkinleştirilmiş olmalıdır. -
typeXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDolmalıdır -
next,NULLveya yapı zincirindeki bir sonraki yapıya geçerli bir işaretçi olmalıdır.
İ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 görüntü veritabanlarını yönetmek için örnek kod
Aşağıdaki örnek kodda, izlenen resim grubunun nasıl değiştirileceği gösterilmektedir.
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.
Görüntü izleme hatalarına tepki vermek için örnek kod
Aşağıdaki örnek kodda, XrEventDataImageTrackingLostANDROID etkinliği için sorgulama yaparak hatanın nasıl işleneceği 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
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Yeni Yapılar
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
XrSystemProperties'i genişletme:
Yeni Enum Veri Türleri
Yeni Enum Sabitleri
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONXrObjectType'i genişletme:
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
XrResult'ı genişletme:
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
XrStructureType'ı genişletme:
XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
XrTrackableTypeANDROID'i genişletme:
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Sayılar
Sürüm Geçmişi
Düzeltme 1, 08.04.2025 (Daniel Guttenberg)
- İlk uzantı açıklaması.