Ekstensi OpenXR XR_ANDROID_hand_mesh

String Nama

XR_ANDROID_hand_mesh

Jenis Ekstensi

Ekstensi instance

Registered Extension Number

704

Revisi

1

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2024-09-10

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Nihav Jain, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Ringkasan

Ekstensi ini memungkinkan pelacakan tangan yang direpresentasikan sebagai mesh tangan dinamis.

Ekstensi ini dimaksudkan untuk menyediakan buffering vertex dan indeks untuk mesh representasi tangan pengguna yang dipersonalisasi. Fitur ini dapat digunakan untuk oklusi dan visualisasi.

Ekstensi ini tidak boleh digunakan untuk tujuan pelacakan tangan lainnya.

Data pelacakan tangan dapat berupa informasi pribadi yang sensitif dan terkait erat dengan privasi dan integritas pribadi. Sebaiknya aplikasi yang menyimpan atau mentransfer data pelacakan tangan selalu meminta persetujuan aktif dan tertentu dari pengguna untuk melakukannya.

Memeriksa kemampuan sistem

Aplikasi dapat memeriksa apakah sistem mampu melacak mesh tangan dengan mengaitkan struktur XrSystemHandMeshTrackingPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties.

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
  • supportsHandMeshTracking adalah XrBool32, yang menunjukkan apakah XrSystemId yang dipilih mendukung pelacakan mesh tangan.
  • supportsTextureUV adalah XrBool32, yang menunjukkan apakah XrSystemId yang dipilih mendukung UV tekstur untuk vertex mesh.
  • supportsVertexNormal adalah XrBool32, yang menunjukkan apakah XrSystemId yang dipilih mendukung normal vertex untuk vertex mesh.

Aplikasi harus menghindari penggunaan kemampuan mesh tangan saat supportsHandMeshTracking adalah XR_FALSE, karena ini berarti sistem tidak mendukung pelacakan mesh tangan. Dalam hal ini, xrCreateHandMeshTrackerANDROID akan menampilkan XR_ERROR_FEATURE_UNSUPPORTED.

Jika supportsHandMeshTracking menampilkan XR_TRUE, sistem akan mendukung pelacakan mesh tangan. Aplikasi harus menggunakan XrHandMeshANDROID::indexCount dan XrHandMeshANDROID::vertexCount untuk mengakses buffering mesh tangan dan menggunakannya kembali dalam loop render saat memanggil xrGetHandMeshANDROID setiap frame.

Jika supportsTextureUV menampilkan XR_FALSE, sistem tidak mendukung UV tekstur untuk vertex mesh, sehingga aplikasi akan menerima XrHandMeshANDROID::textureUVs NULL saat memanggil xrGetHandMeshANDROID.

Jika supportsVertexNormal menampilkan XR_FALSE, sistem tidak mendukung normal vertex untuk vertex mesh, sehingga aplikasi akan menerima XrHandMeshANDROID::normals NULL saat memanggil xrGetHandMeshANDROID.

Penggunaan yang Valid (Implisit)

Membuat nama sebutan channel pelacak mesh tangan

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

Handle XrHandMeshTrackerANDROID mewakili pelacak mesh tangan untuk pelacakan mesh tangan dan mengelola resource terkait.

ID ini dapat digunakan untuk mengakses buffering mesh tangan menggunakan fungsi lain dalam ekstensi ini.

Aplikasi dapat membuat handle XrHandMeshTrackerANDROID menggunakan fungsi xrCreateHandMeshTrackerANDROID. 

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

Deskripsi Parameter

Jika sistem tidak mendukung pelacakan mesh tangan, xrCreateHandMeshTrackerANDROID akan menampilkan XR_ERROR_FEATURE_UNSUPPORTED.

Nama sebutan channel XrHandMeshTrackerANDROID memiliki semua resource untuk pelacakan mesh tangan. Setelah menyelesaikan pengalaman pelacakan mesh tangan, aplikasi harus menghancurkan handle menggunakan fungsi xrDestroyHandMeshTrackerANDROID.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • 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

Struktur XrHandMeshTrackerCreateInfoANDROID menjelaskan informasi untuk membuat handle XrHandMeshTrackerANDROID. 

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.

Penggunaan yang Valid (Implisit)

Fungsi xrDestroyHandMeshTrackerANDROID merilis handMeshTracker dan resource yang mendasarinya setelah selesai dengan pengalaman pelacakan mesh tangan. 

XrResult xrDestroyHandMeshTrackerANDROID(
    XrHandMeshTrackerANDROID handMeshTracker);

Deskripsi Parameter

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke handMeshTracker, dan setiap nama sebutan turunan, harus disinkronkan secara eksternal

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Menemukan mesh tangan

Aplikasi dapat menggunakan fungsi xrGetHandMeshANDROID untuk mengambil mesh tangan pada stempel waktu tertentu. Posisi dan normal vertex mesh tangan direpresentasikan dalam ruang yang ditentukan oleh XrHandMeshGetInfoANDROID::baseSpace saat memanggil xrGetHandMeshANDROID.

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

Deskripsi Parameter

Aplikasi dapat menggunakan fungsi xrGetHandMeshANDROID untuk mengakses buffer mesh tangan yang dihasilkan oleh runtime.

Aplikasi harus memanggil xrBeginFrame setidaknya satu kali selama sesi sebelum panggilan pertama ke xrGetHandMeshANDROID.

Aplikasi harus menggunakan XrHandMeshANDROID::indexCount dan XrHandMeshANDROID::vertexCount untuk mengakses buffering mesh tangan dan menggunakannya kembali dalam loop render saat memanggil xrGetHandMeshANDROID setiap frame.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • 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 menjelaskan informasi yang diperlukan untuk mendapatkan data mesh tangan. 

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
  • baseSpace adalah XrSpace yang menentukan ruang referensi tempat menemukan transformasi untuk vertex di time.
  • time adalah XrTime yang menjelaskan waktu saat aplikasi ingin membuat kueri mesh tangan.

Penggunaan yang Valid (Implisit)

Struktur XrHandTrackingMeshesANDROID berisi data mesh untuk kedua tangan. 

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
  • leftHandMesh adalah XrHandMeshANDROID untuk tangan kiri.
  • rightHandMesh adalah XrHandMeshANDROID untuk tangan kanan.

Penggunaan yang Valid (Implisit)

Struktur XrHandMeshANDROID berisi data dan buffering untuk menerima data pelacakan mesh tangan dari fungsi xrGetHandMeshANDROID untuk satu tangan.

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;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
  • isActive adalah XrBool32 yang menunjukkan apakah pelacak mesh tangan saat ini aktif dan data mesh valid.
  • dynamicLastUpdateTime adalah XrTime yang menentukan waktu saat buffer dinamis terakhir diperbarui.
  • indexCount adalah uint32_t yang berfungsi sebagai jumlah indices dari mesh tangan.
  • vertexCount adalah uint32_t yang berfungsi sebagai jumlah positions jaringan tangan. Ini dapat juga digunakan untuk textureUVs atau normals jika didukung oleh sistem.
  • indices adalah array uint32_t yang mewakili indeks mesh untuk segitiga dalam urutan penggulung berlawanan arah jarum jam. Jumlah nilai yang ditunjuk adalah indexCount.
  • textureUVs adalah NULL atau array XrVector2f yang mewakili koordinat tekstur vertex. Jumlah nilai yang ditunjuk adalah vertexCount.
  • positions adalah array XrVector3f yang mewakili posisi vertex di baseSpaceFromVertexSpace. Jumlah nilai yang ditunjuk adalah vertexCount.
  • normals adalah NULL atau array XrVector3f yang mewakili normal vertex di baseSpaceFromVertexSpace. Jumlah nilai yang ditunjuk adalah vertexCount.
  • baseSpaceFromVertexSpace adalah XrSpace vertex yang terletak di XrHandMeshGetInfoANDROID::baseSpace saat memanggil xrGetHandMeshANDROID. Aplikasi dapat menggunakannya untuk mengubah ruang koordinat vertex dan normal mesh selama rendering.

Mesh tangan direpresentasikan dalam daftar segitiga dan setiap vertex segitiga berada dalam urutan berlawanan dengan arah jarum jam saat dilihat dari luar tangan.

Jika nilai isActive yang ditampilkan adalah XR_FALSE, ini menunjukkan bahwa tangan tidak dilacak secara aktif; misalnya, tangan berada di luar rentang sensor, fokus input diambil dari aplikasi, atau aplikasi tidak memiliki izin untuk mengakses data pelacakan tangan.

Jika nilai isActive yang ditampilkan adalah XR_TRUE, mesh pelacakan tangan yang direpresentasikan dalam indices dan positions, termasuk textureUVs dan normals jika didukung oleh sistem, akan diperbarui ke data terbaru dari XrHandMeshGetInfoANDROID::time yang diberikan ke fungsi xrGetHandMeshANDROID.

Memori yang ditunjuk oleh buffer mesh tangan yang ditampilkan di XrHandMeshANDROID dimiliki oleh runtime dan dibagikan dengan aplikasi. Memori aman untuk diakses dari thread mana pun hingga panggilan berikutnya ke xrBeginFrame saat ID XrHandMeshTrackerANDROID valid.

  • Nilai yang ditunjuk oleh indices dan textureUVs tidak dinamis
  • Pointer dan nilai yang ditunjuk oleh positions dan normals bersifat dinamis yang dapat berubah di antara panggilan ke xrBeginFrame. Aplikasi dapat menggunakan dynamicLastUpdateTime untuk memeriksa apakah nilai telah berubah sejak frame terakhir dan menghindari pemrosesan data yang tidak perlu jika tidak ada perubahan.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_hand_mesh harus diaktifkan sebelum menggunakan XrHandMeshANDROID
  • indices harus berupa pointer ke nilai uint32_t yang valid
  • textureUVs harus berupa pointer ke struktur XrVector2f yang valid
  • positions harus berupa pointer ke struktur XrVector3f yang valid
  • normals harus berupa pointer ke struktur XrVector3f yang valid

Contoh kode untuk pelacakan mesh tangan

Kode contoh berikut menunjukkan cara mengakses buffering mesh tangan untuk rendering.

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

Jenis Objek Baru

Konstanta Enum Baru

Enumerasi XrObjectType diperluas dengan:

  • XR_OBJECT_TYPE_HAND_MESH_TRACKER_ANDROID

Enumerasi XrStructureType diperluas dengan:

  • 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

Enum Baru

Struktur Baru

Fungsi Baru

Masalah

Histori Versi

  • Revisi 1, 10-09-2024 (Levana Chen)
    • Deskripsi ekstensi awal