XR_ANDROID_hand_mesh OpenXR uzantısı

Ad dizesi

XR_ANDROID_hand_mesh

Uzantı Türü

Örnek uzatma

Kayıtlı Uzatma Numarası

704

Düzeltme

1

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

OpenXR 1.0

Son Değiştirilme Tarihi

2024-09-10

IP Durumu

Bilinen IP hak talepleri yok.

Katkıda bulunanlar

Nihav Jain, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Genel Bakış

Bu uzantı, dinamik bir el örgüsü olarak gösterilen el takibini etkinleştirir.

Bu uzantı, kullanıcının ellerinin kişiselleştirilmiş bir temsilinin örgüsü için köşe ve dizin tamponları sağlamak üzere tasarlanmıştır. Gizleme ve görselleştirme için kullanılabilir.

Bu uzantı, diğer el izleme amaçları için kullanılmamalıdır.

El izleme verileri hassas kişisel bilgiler olabilir ve kişisel gizlilik ve bütünlükle yakından ilişkilidir. El izleme verilerini depolayan veya aktaran uygulamaların, bunu yapmak için her zaman kullanıcıdan etkin ve belirli bir onay istemesi önemle tavsiye edilir.

Sistem kapasitesini inceleme

Bir uygulama, xrGetSystemProperties çağrısı sırasında XrSystemHandMeshTrackingPropertiesANDROID yapısını XrSystemProperties ile zincirleyerek sistemin el ağlarını izleyip izleyemediğini kontrol edebilir.

typedef struct XrSystemHandMeshTrackingPropertiesANDROID {
  XrStructureType    type;
  void*              next;
  XrBool32           supportsHandMeshTracking;
  XrBool32           supportsTextureUV;
  XrBool32           supportsVertexNormal;
} XrSystemHandMeshTrackingPropertiesANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • supportsHandMeshTracking, seçili XrSystemId cihazın el örgüsü izlemeyi destekleyip desteklemediğini belirten bir XrBool32 öğesidir.
  • supportsTextureUV, seçili XrSystemId'in örgü köşeleri için doku UV'lerini destekleyip desteklemediğini belirten bir XrBool32 bağımsız değişkenidir.
  • supportsVertexNormal, seçili XrSystemId'in ağ köşeleri için köşe normallerini destekleyip desteklemediğini belirten bir XrBool32 bağımsız değişkenidir.

Sistem el örgüsü takibini desteklemediğinden, supportsHandMeshTracking XR_FALSE olduğunda uygulamanın el örgüsü özelliklerini kullanması uygun değildir. Bu durumda xrCreateHandMeshTrackerANDROID, XR_ERROR_FEATURE_UNSUPPORTED değerini döndürür.

supportsHandMeshTracking XR_TRUE değerini döndürürse sistem el örgüsü takibini destekler. Uygulamalar, her karede xrGetHandMeshANDROID çağrısını yaparken el örgüsü arabelleklerine erişmek ve bunları oluşturma döngülerinde yeniden kullanmak için XrHandMeshANDROID::indexCount ve XrHandMeshANDROID::vertexCount değerlerini kullanmalıdır.

supportsTextureUV XR_FALSE döndürürse sistem, ağ köşeleri için doku UV'lerini desteklemez. Bu nedenle, bir uygulama xrGetHandMeshANDROID'ı çağırdığında XrHandMeshANDROID::textureUVs NULL alır.

supportsVertexNormal XR_FALSE döndürürse sistem, ağ köşeleri için köşe normallerini desteklemez. Bu nedenle, bir uygulama xrGetHandMeshANDROID'ı çağırdığında XrHandMeshANDROID::normals NULL alır.

Geçerli Kullanım (Dolayı)

El örgüsü takip aracı kolu oluşturma

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

XrHandMeshTrackerANDROID kolu, el örgüsü takibi ve ilgili kaynakları yönetmek için bir el örgüsü izleyiciyi temsil eder.

Bu herkese açık kullanıcı adı, bu uzantıdaki diğer işlevleri kullanarak el örgüsü arabelleklerine erişmek için kullanılabilinir.

Bir uygulama, xrCreateHandMeshTrackerANDROID işlevini kullanarak XrHandMeshTrackerANDROID işleyicisi oluşturabilir. 

XrResult xrCreateHandMeshTrackerANDROID(
    XrSession                                   session,
    const XrHandMeshTrackerCreateInfoANDROID*   createInfo,
    XrHandMeshTrackerANDROID*                   handMeshTracker);

Parametre Açıklamaları

Sistem el örgüsü takibini desteklemiyorsa xrCreateHandMeshTrackerANDROID XR_ERROR_FEATURE_UNSUPPORTED değerini döndürür.

XrHandMeshTrackerANDROID herkese açık kullanıcı adı, el örgüsü izlemeyle ilgili tüm kaynaklara sahiptir. Uygulama, el örgüsü izleme deneyimlerini tamamladıktan sonra xrDestroyHandMeshTrackerANDROID işlevini kullanarak kullanıcının elini yok etmelidir.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

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

XrHandMeshTrackerCreateInfoANDROID yapısı, XrHandMeshTrackerANDROID işleyicisi oluşturmak için gereken bilgileri açıklar. 

typedef struct XrHandMeshTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrHandMeshTrackerCreateInfoANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.

Geçerli Kullanım (Dolayı)

xrDestroyHandMeshTrackerANDROID işlevi, el örgüsü izleme deneyimleri sona erdiğinde handMeshTracker ve temel kaynakları serbest bırakır. 

XrResult xrDestroyHandMeshTrackerANDROID(
    XrHandMeshTrackerANDROID handMeshTracker);

Parametre Açıklamaları

Geçerli Kullanım (Dolayı)

Thread Güvenliği

  • handMeshTracker ve alt herkese açık kimliklere erişim, harici olarak senkronize edilmelidir.

İade Kodları

Başarılı

  • XR_SUCCESS

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

El ağlarını bulma

Uygulama, belirli bir zaman damgasındaki el örgüsünü almak için xrGetHandMeshANDROID işlevini kullanabilir. El örgüsünün köşe noktalarının konumu ve normal değeri, xrGetHandMeshANDROID çağrılırken XrHandMeshGetInfoANDROID::baseSpace tarafından belirtilen alanda temsil edilir.

XrResult xrGetHandMeshANDROID(
    XrHandMeshTrackerANDROID                    handMeshTracker,
    const XrHandMeshGetInfoANDROID*             getInfo,
    XrHandTrackingMeshesANDROID*                handMeshes);

Parametre Açıklamaları

Uygulama, çalışma zamanı tarafından oluşturulan el örgüsü arabelleklerine erişmek için xrGetHandMeshANDROID işlevini kullanabilir.

Uygulama, xrGetHandMeshANDROID çağrısından önce oturum sırasında en az bir kez xrBeginFrame çağrısı etmelidir.

Uygulamalar, her karede xrGetHandMeshANDROID çağrısı yaparken el örgüsü arabelleklerine erişmek ve bunları oluşturma döngülerinde yeniden kullanmak için XrHandMeshANDROID::indexCount ve XrHandMeshANDROID::vertexCount değerlerini kullanmalıdır.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID

XrHandMeshGetInfoANDROID, el örgüsü verilerini almak için gereken bilgileri açıklar. 

typedef struct XrHandMeshGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
} XrHandMeshGetInfoANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • baseSpace, time'daki köşe noktalarının dönüştürme işleminin bulunacağı referans uzayı tanımlayan bir XrSpace bağımsız değişkenidir.
  • time, uygulamanın el örgüsünü sorgulamak istediği zamanı açıklayan XrTime bağımsız değişkenidir.

Geçerli Kullanım (Dolayı)

  • XrHandMeshGetInfoANDROID işlevi kullanılmadan önce XR_ANDROID_hand_mesh uzantısı etkinleştirilmelidir.
  • type XR_TYPE_HAND_MESH_GET_INFO_ANDROID olmalıdır
  • next NULL veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır.
  • baseSpace geçerli bir XrSpace herkese açık kullanıcı adı olmalıdır.

XrHandTrackingMeshesANDROID yapısı, her iki elin de ağ verilerini içerir. 

typedef struct XrHandTrackingMeshesANDROID {
    XrStructureType      type;
    void*                next;
    XrHandMeshANDROID    leftHandMesh;
    XrHandMeshANDROID    rightHandMesh;
} XrHandTrackingMeshesANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • leftHandMesh, sol el için XrHandMeshANDROID öğesidir.
  • rightHandMesh, sağ el için XrHandMeshANDROID öğesidir.

Geçerli Kullanım (Dolayı)

XrHandMeshANDROID yapısı, bir el için xrGetHandMeshANDROID işlevinden el örgüsü izleme verilerini almak üzere veriler ve arabellekler içerir.

typedef struct XrHandMeshANDROID {
    XrBool32             isActive;
    XrTime               dynamicLastUpdateTime;
    uint32_t             indexCount;
    uint32_t             vertexCount;
    const uint32_t*      indices;
    const XrVector2f*    textureUVs;
    const XrVector3f*    positions;
    const XrVector3f*    normals;
    XrPosef              baseSpaceFromVertexSpace;
} XrHandMeshANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • isActive, mevcut el örgüsü izleyicinin etkin olup olmadığını ve örgülü verilerin geçerli olup olmadığını belirten bir XrBool32 değeridir.
  • dynamicLastUpdateTime, dinamik arabelleklerin son güncellenme zamanını belirten XrTime bağımsız değişkenidir.
  • indexCount, el örgüsünün indices sayısı olarak hizmet veren bir uint32_t bağımsız değişkenidir.
  • vertexCount, el örgüsündeki positions sayısı olarak hizmet veren bir uint32_t bağımsız değişkenidir. Sistem tarafından desteklendiğinde textureUVs veya normals için de kullanılabilir.
  • indices, saat yönünün tersine sarma sırasına göre üçgenlerin ızgara dizelerini temsil eden bir uint32_t dizisidir. İşaretlenen değerlerin sayısı indexCount.
  • textureUVs, NULL veya köşe doku koordinatlarını temsil eden bir XrVector2f dizisidir. İşaretlenen değerlerin sayısı vertexCount'tür.
  • positions, baseSpaceFromVertexSpace içindeki köşe konumlarını temsil eden bir XrVector3f dizisidir. İşaretlenen değerlerin sayısı vertexCount'tür.
  • normals, baseSpaceFromVertexSpace'daki köşe normallerini temsil eden bir NULL veya XrVector3f dizisidir. İşaretlenen değerlerin sayısı vertexCount'tür.
  • baseSpaceFromVertexSpace, xrGetHandMeshANDROID çağrılırken XrHandMeshGetInfoANDROID::baseSpace içinde bulunan XrSpace köşesidir. Uygulamalar, oluşturma sırasında ağ köşe noktalarının ve normallerinin koordinat alanını dönüştürmek için bunu kullanabilir.

El örgüsü, üçgen listeleriyle temsil edilir ve her üçgenin tepe noktaları, elin dışından bakıldığında saat yönünün tersine sırayladır.

Döndürülen isActive değeri XR_FALSE olduğunda, elin etkin bir şekilde izlenmediğini gösterir. Örneğin, el sensörün aralığının dışındadır, giriş odağı uygulamadan kaldırılmıştır veya uygulamanın el izleme verilerine erişme izni yoktur.

Döndürülen isActive değeri XR_TRUE olduğunda, sistem tarafından destekleniyorsa textureUVs ve normals dahil olmak üzere indices ve positions'de temsil edilen el izleme örgüsü, xrGetHandMeshANDROID işlevine verilen XrHandMeshGetInfoANDROID::time değerinin en son verileriyle güncellenir.

XrHandMeshANDROID işlevinde döndürülen el örgüsü arabelleklerinin işaret ettiği bellek, çalışma zamanından alınır ve uygulamayla paylaşılır. XrHandMeshTrackerANDROID işleyicisi geçerliyken xrBeginFrame çağrısı yapılana kadar belleğe herhangi bir mesaj dizisinden erişilebilir.

  • indices ve textureUVs tarafından işaretlenen değerler dinamik değildir.
  • İşaretçi ve positions ile normals tarafından işaretlenen değerler xrBeginFrame çağrıları arasında dinamik olarak değişebilir. Uygulama, değerlerin son çerçeveden bu yana değişip değişmediğini kontrol etmek ve değişiklik olmadığında gereksiz veri işlemeyi önlemek için dynamicLastUpdateTime'yi kullanabilir.

Geçerli Kullanım (Dolayı)

  • XrHandMeshANDROID özelliğini kullanmadan önce XR_ANDROID_hand_mesh uzantısı etkinleştirilmelidir.
  • indices geçerli bir uint32_t değerine işaret eden bir işaretçi olmalıdır.
  • textureUVs, geçerli bir XrVector2f yapısının işaretçisi olmalıdır.
  • positions, geçerli bir XrVector3f yapısının işaretçisi olmalıdır.
  • normals, geçerli bir XrVector3f yapısının işaretçisi olmalıdır.

El örgüsü izleme için örnek kod

Aşağıdaki örnek kodda, oluşturma için el ağ geçitlerine nasıl erişileceği gösterilmektedir.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup.
XrSpace appPlaySpace; // Created at app startup.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateHandMeshTrackerANDROID xrCreateHandMeshTrackerANDROID; // previously initialized
PFN_xrDestroyHandMeshTrackerANDROID xrDestroyHandMeshTrackerANDROID; // previously initialized
PFN_xrGetHandMeshANDROID xrGetHandMeshANDROID; // previously initialized

// Inspect system capability
XrSystemHandMeshTrackingPropertiesANDROID handMeshTrackingProps = {
  .type = XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &handMeshTrackingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!handMeshTrackingProps.supportsHandMeshTracking) {
  // hand mesh tracking is not supported.
  return;
}

XrHandMeshTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
};
XrHandMeshTrackerANDROID handMeshTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateHandMeshTrackerANDROID(
    session, &trackerCreateInfo, &handMeshTracker));
// app update loop
while (true) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;

    // ...
    XrHandMeshGetInfoANDROID getInfo = {
        .type = XR_TYPE_HAND_MESH_GET_INFO_ANDROID,
        .baseSpace = appPlaySpace,
        .time = time,
    };
    XrHandTrackingMeshesANDROID handMeshes = {
        .type = XR_TYPE_HAND_TRACKING_MESHES_ANDROID
    };
    CHK_XR(xrGetHandMeshANDROID(handMeshTracker, &getInfo, &handMeshes));

    if (handMeshes.leftHandMesh.isActive) {
        // access vertex/index buffers for rendering.
    }

    // ...
    // Finish frame loop
    // ...
}

CHECK_XR(xrDestroyHandMeshTracker(handMeshTracker));

Yeni Nesne Türleri

Yeni Enum Constants

XrObjectType dizini aşağıdakilerle genişletildi:

  • XR_OBJECT_TYPE_HAND_MESH_TRACKER_ANDROID

XrStructureType dizini aşağıdakilerle genişletildi:

  • XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_HAND_MESH_GET_INFO_ANDROID
  • XR_TYPE_HAND_TRACKING_MESHES_ANDROID

Yeni Sıralamalar

Yeni Yapılar

Yeni İşlevler

Sorunlar

Sürüm Geçmişi

  • Düzeltme 1, 10.09.2024 (Levana Chen)
    • İlk uzantı açıklaması