XR_ANDROID_scene_meshing

String Nama

XR_ANDROID_scene_meshing

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

719

Revisi

3

Status Ratifikasi

Belum diratifikasi

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2025-05-15

Status IP

Tidak ada klaim kekayaan intelektual yang diketahui.

Kontributor

Spencer Quin, Google
Jared Finder, Google
Antonio Fontan, Google
Cairn Overturf, Google
Nihav Jain, Google
Salar Khan, Google
Sebastian Klose, Google
Jürgen Sturm, Google
Vinny DaSilva, Google
Ricardo Campbell, Google

Ringkasan

Ekstensi ini dimaksudkan untuk menyediakan mesh yang kurang lebih mewakili objek fisik di lingkungan pengguna.

Aplikasi dapat menggunakan ekstensi ini untuk memvisualisasikan tampilan dan memungkinkan objek virtual berinteraksi dengan objek fisik seperti tabrakan.

Data mesh tampilan dihasilkan oleh runtime dan dibagikan ke aplikasi menggunakan XrSceneMeshingTrackerANDROID dan XrSceneMeshSnapshotANDROID . Aplikasi dapat mengakses nilai dalam informasi submesh scene melalui XrSceneSubmeshStateANDROID yang ditampilkan dari xrGetAllSubmeshStatesANDROID . Aplikasi dapat mengakses nilai dalam data submesh scene melalui XrSceneSubmeshDataANDROID yang ditampilkan dari xrGetSubmeshDataANDROID .

Data meshing tampilan adalah informasi pribadi yang sensitif dan terkait erat dengan privasi dan integritas pribadi. Sangat disarankan agar aplikasi yang menyimpan atau mentransfer data mesh scene selalu meminta persetujuan aktif dan spesifik dari pengguna untuk melakukannya.

Izin

Aplikasi Android harus memiliki izin android.permission.SCENE_UNDERSTANDING_FINE yang tercantum dalam manifesnya. Izin android.permission.SCENE_UNDERSTANDING_FINE dianggap sebagai izin sensitif karena memungkinkan runtime mempelajari lingkungan pengguna.

Aplikasi harus meminta izin saat runtime untuk menggunakan fungsi berikut:

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemSceneMeshingPropertiesANDROID didefinisikan sebagai:

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • supportsSceneMeshing adalah XrBool32 , yang menunjukkan apakah sistem mendukung mesh scene.

Aplikasi dapat memeriksa apakah sistem mampu melakukan meshing scene dengan merantai struktur XrSystemSceneMeshingPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties .

Jika runtime menampilkan XR_FALSE untuk supportsSceneMeshing , sistem tidak mendukung pembuatan mesh scene, sehingga harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateSceneMeshingTrackerANDROID . Aplikasi sebaiknya menghindari penggunaan fungsi mesh scene saat supportsSceneMeshing adalah XR_FALSE .

Jika runtime menampilkan XR_TRUE untuk supportsSceneMeshing , sistem akan mendukung pembuatan mesh tampilan.

Penggunaan yang Valid (Implisit)

Enumerasi XrSceneMeshSemanticLabelSetANDROID menjelaskan set label semantik untuk mesh scene. Setiap nilai dalam enum ini mewakili enum lain yang berisi label semantik. Misalnya, nilai XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID mewakili set XrSceneMeshSemanticLabelANDROID .

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID = 1000801000,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

Nilai enumerasi memiliki arti berikut:

Deskripsi Enum

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

Set label semantik ini menunjukkan tidak adanya label semantik.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

Set label semantik ini mewakili XrSceneMeshSemanticLabelANDROID.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

Set label semantik ini mewakili XrSceneMeshSemanticLabel2ANDROID. (Ditambahkan oleh ekstensi XR_ANDROID_scene_meshing_semantic_label2)

Fungsi xrEnumerateSupportedSemanticLabelSetsANDROID didefinisikan sebagai:

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

Deskripsi Parameter

  • instance adalah XrInstance yang dibuat oleh aplikasi.
  • systemId adalah XrSystemId yang dicoba ulang dari xrGetSystem .
  • supportedSemanticLabelSetsInputCapacity adalah kapasitas supportedSemanticLabelSets , atau 0 untuk mengambil kapasitas yang diperlukan.
  • supportedSemanticLabelSetsOutputCount adalah pointer ke jumlah supportedSemanticLabelSets yang ditulis, atau pointer ke kapasitas yang diperlukan jika supportedSemanticLabelSetsInputCapacity tidak mencukupi.
  • supportedSemanticLabelSets adalah pointer ke array XrSceneMeshSemanticLabelSetANDROID . Nilainya bisa NULL jika supportedSemanticLabelSetsInputCapacity adalah 0.
  • Lihat bab Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang cara mengambil ukuran supportedSemanticLabelSets yang diperlukan.

Aplikasi dapat menghitung set label semantik yang didukung oleh sistem menggunakan fungsi xrEnumerateSupportedSemanticLabelSetsANDROID.

Setiap sistem harus setidaknya mendukung XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID karena nilai enum ini tidak mewakili kumpulan label semantik dan dapat digunakan jika aplikasi tidak memerlukan semantik verteks.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Membuat handle pelacak mesh scene

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Handle XrSceneMeshingTrackerANDROID mewakili pelacak meshing scene untuk meshing scene dan mengelola resource terkait.

Handle ini dapat digunakan untuk membuat snapshot mesh scene menggunakan xrCreateSceneMeshSnapshotANDROID di ekstensi ini.

Fungsi xrCreateSceneMeshingTrackerANDROID didefinisikan sebagai:

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

Deskripsi Parameter

Aplikasi dapat membuat handle XrSceneMeshingTrackerANDROID menggunakan fungsi xrCreateSceneMeshingTrackerANDROID.

Jika sistem tidak mendukung pembuatan mesh scene, runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateSceneMeshingTrackerANDROID . Dalam hal ini, runtime harus menampilkan XR_FALSE untuk XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing saat fungsi xrGetSystemProperties dipanggil, sehingga aplikasi dapat menghindari pembuatan pelacak mesh scene.

Aplikasi harus hanya menggunakan set label semantik yang didukung oleh sistem di XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet saat membuat pelacak meshing scene. Jika aplikasi menggunakan kumpulan label semantik verteks mesh scene yang tidak didukung, runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateSceneMeshingTrackerANDROID .

Aplikasi dapat menghitung daftar set label semantik yang didukung dengan fungsi xrEnumerateSupportedSemanticLabelSetsANDROID.

Handle xrCreateSceneMeshingTrackerANDROID memiliki semua resource untuk pembuatan mesh scene. Setelah selesai dengan pengalaman mesh scene, aplikasi harus menghancurkan handle melalui fungsi xrDestroySceneMeshingTrackerANDROID.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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

Struktur XrSceneMeshingTrackerCreateInfoANDROID didefinisikan sebagai:

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • semanticLabelSet adalah XrSceneMeshSemanticLabelSetANDROID yang digunakan untuk menentukan set label semantik yang akan digunakan untuk meshing scene. Jika ini ditetapkan ke XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , runtime akan mengabaikan kolom buffer XrSceneSubmeshDataANDROID :: vertexSemantics.
  • enableNormals adalah XrBool32 yang digunakan untuk menentukan apakah akan menyertakan normal verteks untuk verteks mesh di buffer mesh tampilan saat mendapatkan data mesh tampilan.

Struktur XrSceneMeshingTrackerCreateInfoANDROID menjelaskan informasi untuk membuat handle XrSceneMeshingTrackerANDROID.

Penggunaan yang Valid (Implisit)

Fungsi xrDestroySceneMeshingTrackerANDROID didefinisikan sebagai:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Deskripsi Parameter

Fungsi xrDestroySceneMeshingTrackerANDROID merilis tracker dan resource yang mendasarinya setelah selesai dengan pengalaman pembuatan mesh tampilan.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke tracker , dan handle turunan apa pun, harus disinkronkan secara eksternal

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Membuat handle snapshot mesh scene

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

Handle XrSceneMeshSnapshotANDROID mewakili snapshot mesh scene. Snapshot ini dibuat menggunakan xrCreateSceneMeshSnapshotANDROID yang mengambil snapshot data mesh scene pada saat panggilan fungsi.

Handle ini dapat digunakan untuk mengambil informasi dan data submesh menggunakan xrGetAllSubmeshStatesANDROID dan xrGetSubmeshDataANDROID .

Fungsi xrCreateSceneMeshSnapshotANDROID didefinisikan sebagai:

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

Deskripsi Parameter

Aplikasi dapat menggunakan fungsi xrCreateSceneMeshSnapshotANDROID untuk membuat snapshot mesh scene dari pelacak mesh scene. Fungsi ini menampilkan handle XrSceneMeshSnapshotANDROID beserta XrSceneMeshTrackingStateANDROID yang digabungkan dalam struktur XrSceneMeshSnapshotCreationResultANDROID. Handle secara teknis adalah snapshot data mesh scene pada saat pembuatan. Handle ini dapat digunakan untuk mengkueri info dan data mesh scene menggunakan xrGetAllSubmeshStatesANDROID dan xrGetSubmeshDataANDROID.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

Struktur XrSceneMeshSnapshotCreateInfoANDROID didefinisikan sebagai:

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • baseSpace adalah XrSpace tempat info pose submesh scene direpresentasikan.
  • time adalah XrTime yang menjelaskan waktu saat mesh tampilan akan diproses atau ditampilkan, biasanya XrFrameState :: predictedDisplayTime .
  • boundingBox adalah XrBoxf yang menjelaskan kotak pembatas tempat mesh tampilan diperoleh.

Struktur XrSceneMeshSnapshotCreateInfoANDROID menjelaskan informasi untuk membuat handle XrSceneMeshSnapshotANDROID

Penggunaan yang Valid (Implisit)

Struktur XrSceneMeshSnapshotCreationResultANDROID didefinisikan sebagai:

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • snapshot adalah handle XrSceneMeshSnapshotANDROID yang dibuat oleh runtime.
  • trackingState adalah XrSceneMeshTrackingStateANDROID yang menjelaskan status pelacak mesh scene pada saat pembuatan snapshot.

Struktur XrSceneMeshSnapshotCreationResultANDROID menyimpan hasil pembuatan snapshot mesh scene yang ditampilkan dari xrCreateSceneMeshSnapshotANDROID .

Penggunaan yang Valid (Implisit)

Enumerasi XrSceneMeshTrackingStateANDROID menjelaskan status pelacakan untuk pelacak mesh scene. Setiap nilai dalam enum ini mewakili status pelacak mesh tampilan.

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

Nilai enumerasi memiliki arti berikut:

Deskripsi Enum

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

Pelacak belum siap memberikan data mesh.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

Pelacak sedang aktif melacak.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

Pelacak sedang menunggu pengukuran yang valid untuk diintegrasikan sejak update mesh terakhir.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

Pelacak belum menerima pengukuran yang valid untuk beberapa siklus dan berada dalam status error.

Status ini hanya berfungsi sebagai informasi tambahan untuk aplikasi. Jika tidak ada sumber error lain, runtime harus terus mengizinkan aplikasi membuat snapshot dan mengambil data darinya, terlepas dari XrSceneMeshTrackingStateANDROID pelacak saat ini. Jika statusnya bukan XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID , snapshot mungkin tidak terbaru atau kosong.

Mendapatkan data mesh scene dari snapshot mesh scene

Fungsi xrGetAllSubmeshStatesANDROID didefinisikan sebagai:

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

Deskripsi Parameter

  • snapshot adalah handle XrSceneMeshSnapshotANDROID yang sebelumnya dibuat dengan xrCreateSceneMeshSnapshotANDROID .
  • submeshStateCapacityInput adalah kapasitas submeshStates , atau 0 untuk mengambil kapasitas yang diperlukan.
  • submeshStateCountOutput adalah pointer ke jumlah submeshStates yang ditulis, atau pointer ke kapasitas yang diperlukan jika submeshStateCapacityInput tidak mencukupi.
  • submeshStates adalah pointer ke array struktur XrSceneSubmeshStateANDROID yang akan digunakan runtime untuk menghasilkan status semua submesh dalam mesh scene. Nilainya bisa NULL jika submeshStateCapacityInput adalah 0.
  • Lihat bab Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang cara mengambil ukuran submeshStates yang diperlukan.

Aplikasi dapat menggunakan fungsi xrGetAllSubmeshStatesANDROID untuk mendapatkan status semua submesh dalam mesh scene. Ini berisi informasi dasar untuk memungkinkan aplikasi memilih submesh yang datanya diinginkan oleh aplikasi.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSceneSubmeshStateANDROID didefinisikan sebagai:

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • submeshId adalah XrUuid yang mengidentifikasi submesh.
  • lastUpdatedTime adalah XrTime yang menunjukkan waktu saat submesh terakhir diperbarui.
  • submeshPoseInBaseSpace adalah XrPosef yang merepresentasikan pose submesh di ruang dasar yang digunakan untuk membuat snapshot mesh scene. Pose juga merupakan pusat kotak pembatas submesh.
  • bounds adalah XrExtent3Df yang menjelaskan dimensi kotak pembatas yang mengapit submesh. Batas ini ditentukan dalam ruang dasar yang digunakan untuk membuat handle mesh scene.

Runtime melakukan upaya terbaik untuk memetakan submeshId dengan region ruang fisik yang ditempati oleh submesh. Runtime dapat kehilangan pemetaan ini kapan saja dan menetapkan UUID baru ke subset submesh yang terdeteksi. Secara khusus, runtime tidak diperlukan untuk menggunakan kembali UUID yang sama untuk mesh yang sama dalam instance aplikasi berikutnya.

Penggunaan yang Valid (Implisit)

Fungsi xrGetSubmeshDataANDROID didefinisikan sebagai:

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

Deskripsi Parameter

Aplikasi dapat menggunakan fungsi xrGetSubmeshDataANDROID untuk mendapatkan batch submesh, atau semua submesh sekaligus, dengan meneruskan daftar XrSceneSubmeshDataANDROID dengan setiap XrSceneSubmeshDataANDROID :: submeshId ditetapkan ke ID masing-masing submesh yang akan diambil.

XrSceneSubmeshDataANDROID :: submeshId harus unik untuk setiap elemen di inoutSubmeshData dan dapat diambil oleh xrGetAllSubmeshStatesANDROID untuk snapshot yang sama. Jika ID submesh tidak valid atau lebih dari satu elemen di inoutSubmeshData memiliki ID submesh yang sama, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

submeshDataCount harus sama dengan atau kurang dari nilai yang ditampilkan oleh xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput , jika tidak, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

Ini dapat digunakan dalam idiom 2 panggilan untuk mengkueri jumlah verteks dan indeks untuk semua submesh yang dipilih.

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

Struktur XrSceneSubmeshDataANDROID didefinisikan sebagai:

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • submeshId adalah XrUuid yang mengidentifikasi submesh.
  • vertexCapacityInput adalah kapasitas vertexPositions , vertexNormals dan vertexSemantics , atau 0 untuk mengambil kapasitas yang diperlukan.
  • vertexCountOutput adalah pointer ke jumlah vertexPositions , vertexNormals , dan vertexSemantics yang ditulis, atau pointer ke kapasitas yang diperlukan jika vertexCapacityInput tidak mencukupi.
  • vertexPositions adalah array XrVector3f yang akan digunakan runtime untuk menghasilkan posisi verteks submesh.
  • vertexNormals adalah array XrVector3f yang akan digunakan runtime untuk menghasilkan output normal verteks submesh. Kolom ini dapat dibiarkan NULL jika aplikasi membuat pelacak dengan normal dinonaktifkan.
  • vertexSemantics adalah array uint8_t yang akan digunakan runtime untuk menghasilkan semantik vertex submesh. Kolom ini dapat dibiarkan NULL jika aplikasi membuat pelacak dengan set label semantik XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • indexCapacityInput adalah kapasitas indices , atau 0 untuk mengambil kapasitas yang diperlukan.
  • indexCountOutput adalah pointer ke jumlah indices yang ditulis, atau pointer ke kapasitas yang diperlukan jika vertexCapacityInput tidak mencukupi.
  • indices adalah array uint32_t yang akan menjadi output indeks submesh dari runtime.
  • Lihat bab Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang cara mengambil ukuran vertexPositions , vertexNormals , vertexSemantics , dan indices yang diperlukan.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_scene_meshing harus diaktifkan sebelum menggunakan XrSceneSubmeshDataANDROID
  • type harus berupa XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
  • Jika vertexCapacityInput bukan 0 , vertexPositions harus berupa pointer ke array struktur vertexCapacityInput XrVector3f
  • Jika vertexCapacityInput bukan 0 , vertexNormals harus berupa pointer ke array struktur vertexCapacityInput XrVector3f
  • Jika vertexCapacityInput bukan 0 , vertexSemantics harus berupa pointer ke array nilai vertexCapacityInput uint8_t
  • Jika indexCapacityInput bukan 0 , indices harus berupa pointer ke array nilai indexCapacityInput uint32_t

Enumerasi XrSceneMeshSemanticLabelANDROID adalah kumpulan label semantik default yang dapat digunakan untuk memberi label pada verteks mesh guna mendeskripsikan permukaan lingkungan fisik tempat verteks mesh berada. Set enum ini diwakili oleh nilai XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID di XrSceneMeshSemanticLabelSetANDROID .

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

Enum memiliki arti berikut:

Deskripsi Enum

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

Label semantik ini menunjukkan bahwa elemen mesh yang sesuai mewakili objek yang tidak diketahui.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

Label semantik ini menunjukkan bahwa elemen mesh yang sesuai merepresentasikan lantai.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

Label semantik ini menunjukkan bahwa elemen mesh yang sesuai mewakili langit-langit.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

Label semantik ini menunjukkan bahwa elemen mesh yang sesuai merepresentasikan dinding.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

Label semantik ini menunjukkan bahwa elemen mesh yang sesuai merepresentasikan tabel.

Menghancurkan snapshot mesh scene

Fungsi xrDestroySceneMeshSnapshotANDROID didefinisikan sebagai:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Deskripsi Parameter

Aplikasi dapat menggunakan fungsi xrDestroySceneMeshSnapshotANDROID untuk menghancurkan snapshot mesh scene. Setelah handle dihancurkan, aplikasi tidak dapat lagi menggunakannya untuk mendapatkan info atau data submesh. Handle akan otomatis dihancurkan saat pelacak dihancurkan karena handle pelacak adalah induk dari handle snapshot mesh tampilan.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke snapshot , dan handle turunan apa pun, harus disinkronkan secara eksternal

Kode Status

Berhasil

  • XR_SUCCESS

Kegagalan

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Contoh kode untuk pembuatan mesh tampilan

Kode contoh berikut menunjukkan cara mengakses data mesh scene 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_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

Jenis Objek Baru

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • Memperluas XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • Memperluas XrStructureType :

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

Masalah

Riwayat Versi

  • Revisi 3, 15-05-2025 (Salar Khan)

    • Deskripsi ekstensi awal