XR_ANDROID_scene_meshing

String Nama

XR_ANDROID_scene_meshing

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

719

Revisi

3

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

OpenXR 1.0

Tanggal Terakhir Diubah

2025-05-15

Status IP

Tidak ada klaim IP 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 secara kasar merepresentasikan objek fisik di lingkungan pengguna.

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

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

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

Izin

Aplikasi Android harus mencantumkan izin android.permission.SCENE_UNDERSTANDING_FINE 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 ini:

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemSceneMeshingPropertiesANDROID ditentukan 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 penyatuan adegan.

Aplikasi dapat memeriksa apakah sistem mampu melakukan penyambungan adegan dengan merangkai struktur XrSystemSceneMeshingPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties .

Jika runtime menampilkan XR_FALSE untuk supportsSceneMeshing , sistem tidak mendukung pembuatan mesh adegan, dan oleh karena itu harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED dari xrCreateSceneMeshingTrackerANDROID . Aplikasi harus menghindari penggunaan fungsi penyusunan jaring adegan saat supportsSceneMeshing adalah XR_FALSE .

Jika runtime menampilkan XR_TRUE untuk supportsSceneMeshing , sistem mendukung penyatuan adegan.

Penggunaan yang Valid (Implisit)

Enumerasi XrSceneMeshSemanticLabelSetANDROID menjelaskan set label semantik untuk pembuatan mesh adegan. Setiap nilai dalam enum ini merepresentasikan 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_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

Kumpulan label semantik ini merepresentasikan XrSceneMeshSemanticLabelANDROID.

Fungsi xrEnumerateSupportedSemanticLabelSetsANDROID ditentukan 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 lagi 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 dapat berupa NULL jika supportedSemanticLabelSetsInputCapacity adalah 0.
  • Lihat bab Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran supportedSemanticLabelSets yang diperlukan.

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

Setiap sistem harus mendukung XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID karena nilai enum ini tidak merepresentasikan set 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 penggabungan adegan

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

Handle XrSceneMeshingTrackerANDROID merepresentasikan pelacak pemeshan adegan untuk pemeshan adegan dan mengelola resource terkait.

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

Fungsi xrCreateSceneMeshingTrackerANDROID ditentukan sebagai:

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

Deskripsi Parameter

Aplikasi dapat membuat handle XrSceneMeshingTrackerANDROID menggunakan fungsi xrCreateSceneMeshingTrackerANDROID.

Jika sistem tidak mendukung penyatuan adegan, 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 pemeshan adegan.

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

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

Handler xrCreateSceneMeshingTrackerANDROID memiliki semua resource untuk pemetaan mesh adegan. Setelah selesai menggunakan pengalaman pemetaan adegan, 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 ditentukan 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 pembuatan mesh adegan. Jika disetel 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 dalam buffer mesh adegan saat mendapatkan data mesh adegan.

Struktur XrSceneMeshingTrackerCreateInfoANDROID menjelaskan informasi untuk membuat handle XrSceneMeshingTrackerANDROID.

Penggunaan yang Valid (Implisit)

Fungsi xrDestroySceneMeshingTrackerANDROID ditentukan sebagai:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

Deskripsi Parameter

Fungsi xrDestroySceneMeshingTrackerANDROID melepaskan tracker dan resource pokok saat selesai menggunakan pengalaman pemetaan mesh adegan.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke tracker , dan semua handle turunan, 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 adegan

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

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

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

Fungsi xrCreateSceneMeshSnapshotANDROID ditentukan sebagai:

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

Deskripsi Parameter

Aplikasi dapat menggunakan fungsi xrCreateSceneMeshSnapshotANDROID untuk membuat snapshot mesh adegan dari pelacak mesh adegan. Fungsi ini menampilkan handle XrSceneMeshSnapshotANDROID bersama dengan XrSceneMeshTrackingStateANDROID yang di-wrap dalam struktur XrSceneMeshSnapshotCreationResultANDROID. Secara teknis, handle adalah snapshot data mesh adegan pada saat pembuatan. Handle dapat digunakan untuk mengkueri info dan data mesh adegan 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 ditentukan 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 yang di dalamnya info pose submesh adegan direpresentasikan.
  • time adalah XrTime yang menjelaskan waktu saat mesh adegan akan diproses atau ditampilkan, biasanya XrFrameState :: predictedDisplayTime .
  • boundingBox adalah XrBoxf yang menjelaskan kotak pembatas tempat untuk mendapatkan mesh adegan.

Struktur XrSceneMeshSnapshotCreateInfoANDROID menjelaskan informasi untuk membuat handle XrSceneMeshSnapshotANDROID

Penggunaan yang Valid (Implisit)

Struktur XrSceneMeshSnapshotCreationResultANDROID ditentukan 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 pemetaan visualisasi adegan pada saat pembuatan snapshot.

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

Penggunaan yang Valid (Implisit)

Enumerasi XrSceneMeshTrackingStateANDROID menjelaskan status pelacakan untuk pelacak pemeshan adegan. Setiap nilai dalam enum ini mewakili status pelacak pemaduan mesh adegan.

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 untuk menyediakan 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 dari snapshot tersebut, 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 adegan dari snapshot mesh adegan

Fungsi xrGetAllSubmeshStatesANDROID ditentukan 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 menampilkan status semua submesh dalam mesh adegan. Nilainya dapat berupa NULL jika submeshStateCapacityInput adalah 0.
  • Lihat bab Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran submeshStates yang diperlukan.

Aplikasi dapat menggunakan fungsi xrGetAllSubmeshStatesANDROID untuk mendapatkan status semua submesh dalam mesh adegan. 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 ditentukan 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 adegan. 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 adegan.

Runtime berupaya sebaik mungkin 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 diwajibkan untuk menggunakan kembali UUID yang sama untuk mesh yang sama dalam instance aplikasi berikutnya.

Penggunaan yang Valid (Implisit)

Fungsi xrGetSubmeshDataANDROID ditentukan 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 yang ditetapkan ke ID submesh masing-masing 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, maka 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 .

Dapat digunakan dalam idiom 2 panggilan untuk mengkueri jumlah indeks dan verteks 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 ditentukan 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 menampilkan normalitas 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 verteks 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 digunakan runtime untuk menampilkan indeks submesh.
  • Lihat bab Parameter Ukuran Buffer untuk deskripsi mendetail tentang pengambilan 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. Kumpulan 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 merepresentasikan 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 merepresentasikan 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 adegan

Fungsi xrDestroySceneMeshSnapshotANDROID ditentukan sebagai:

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

Deskripsi Parameter

Aplikasi dapat menggunakan fungsi xrDestroySceneMeshSnapshotANDROID untuk menghancurkan snapshot mesh adegan. 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 adegan.

Penggunaan yang Valid (Implisit)

Keamanan Thread

  • Akses ke snapshot , dan semua handle turunan, 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 pemaduan adegan

Contoh kode berikut menunjukkan cara mengakses data mesh adegan 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