String Nama
XR_ANDROID_composition_layer_passthrough_mesh
Jenis Ekstensi
Perpanjangan instance
Registered Extension Number
463
Revisi
1
Dependensi Ekstensi dan Versi
Tanggal Terakhir Diubah
2024-09-18
Status IP
Tidak ada klaim IP yang diketahui.
Kontributor
Grant Yoshida, Google
Kevin Moule, Google
Vasiliy Baranov, Google
Peter Chen, Google
Levana Chen, Google
Ringkasan
Untuk perangkat yang mendukung beberapa mode perpaduan lingkungan, sistem dapat menyediakan konfigurasi passthrough untuk menampilkan lingkungan fisik kepada pengguna dari tampilan imersif.
Ekstensi ini memungkinkan aplikasi memproyeksikan tekstur passthrough ke geometri arbitrer melalui lapisan komposisi tambahan XrCompositionLayerPassthroughANDROID.
Karakteristik lapisan passthrough ditentukan oleh parameter berikut, dengan proyeksi diwakili oleh XrPassthroughLayerANDROID.
  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
Untuk passthrough layar penuh, aplikasi dapat menggunakan Mode Gabungan Lingkungan.
Memeriksa kemampuan sistem
Aplikasi dapat memeriksa apakah sistem mampu melakukan mesh passthrough lapisan komposisi dengan mengaitkan struktur XrSystemPassthroughLayerPropertiesANDROID ke XrSystemProperties saat memanggil xrGetSystemProperties.
typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;
Deskripsi Anggota
- typeadalah XrStructureType dari struktur ini.
- nextadalah- NULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
- supportsPassthroughLayeradalah- XrBool32, yang menunjukkan apakah sistem saat ini mendukung mesh passthrough lapisan komposisi.
- maxMeshIndexCountadalah- uint32_tyang menampilkan jumlah maksimum indeks yang akan diterima untuk mesh passthrough.
- maxMeshVertexCountadalah- uint32_tyang menampilkan jumlah maksimum vertex yang akan diterima untuk mesh passthrough.
Jika supportsPassthroughLayer menampilkan XR_FALSE, sistem
tidak mendukung mesh passthrough lapisan komposisi, sehingga akan menerima
XR_ERROR_FEATURE_UNSUPPORTED dari xrCreatePassthroughLayerANDROID. Aplikasi
harus menghindari penggunaan mesh passthrough lapisan komposisi saat
supportsPassthroughLayer adalah XR_FALSE.
Jika supportsPassthroughLayer menampilkan XR_TRUE, sistem
akan mendukung mesh passthrough lapisan komposisi. Dalam hal ini,
maxMeshIndexCount dan maxMeshVertexCount akan menampilkan angka selain nol. Aplikasi
harus menggunakan maxMeshIndexCount dan maxMeshVertexCount sebagai
nilai maksimum untuk menetapkan mesh passthrough saat memanggil
xrCreatePassthroughLayerANDROID dan
xrSetPassthroughLayerMeshANDROID. Jika tidak, XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID dapat ditampilkan
untuk menunjukkan bahwa data mesh melebihi
batas yang didukung.
Penggunaan yang Valid (Implisit)
- Ekstensi XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum menggunakan XrSystemPassthroughLayerPropertiesANDROID
- typeharus berupa- XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID
- nextharus berupa- NULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur
Komposisi Lapisan Passthrough
XrCompositionLayerPassthroughANDROID berisi informasi yang diperlukan untuk merender tekstur passthrough ke mesh segitiga saat memanggil xrEndFrame. XrCompositionLayerPassthroughANDROID adalah jenis alias untuk struct dasar XrCompositionLayerBaseHeader yang digunakan di XrFrameEndInfo.
typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;
Deskripsi Anggota
- typeadalah XrStructureType dari struktur ini.
- nextadalah- NULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.
- layerFlagsadalah bitmask dari XrCompositionLayerFlags yang menjelaskan flag yang akan diterapkan ke lapisan.
- spaceadalah XrSpace tempat- posemesh lapisan dievaluasi dari waktu ke waktu.
- poseadalah- XrPosefyang menentukan posisi dan orientasi mesh lapisan dalam frame referensi- space.
- scaleadalah- XrVector3fyang menentukan skala mesh lapisan.
- opacityadalah- floatyang menentukan opasitas tekstur passthrough dalam rentang [0, 1].
- layeradalah XrPassthroughLayerANDROID yang sebelumnya dibuat oleh xrCreatePassthroughLayerANDROID.
Aplikasi dapat membuat struktur XrCompositionLayerPassthroughANDROID
dengan layer yang dibuat dan mesh yang sesuai yang disediakan oleh
XrPassthroughLayerMeshANDROID.
Pointer ke XrCompositionLayerPassthroughANDROID dapat dikirim dalam xrEndFrame sebagai pointer ke struktur dasar XrCompositionLayerBaseHeader, dalam urutan lapisan yang dipilih, untuk meminta runtime agar menggabungkan lapisan passthrough ke dalam output frame akhir.
Penggunaan yang Valid (Implisit)
- Ekstensi XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum menggunakan XrCompositionLayerPassthroughANDROID
- typeharus berupa- XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
- nextharus berupa- NULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur
- layerFlagsharus berupa- 0atau kombinasi yang valid dari nilai XrCompositionLayerFlagBits
- spaceharus berupa nama sebutan XrSpace yang valid
- layerharus berupa handle XrPassthroughLayerANDROID yang valid
- layerdan- spaceharus telah dibuat, dialokasikan, atau diambil dari XrSession yang sama
Membuat handle lapisan passthrough
Handle XrPassthroughLayerANDROID mewakili lapisan passthrough yang menentukan perilaku XrCompositionLayerPassthroughANDROID.
XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)
Aplikasi dapat membuat handle XrPassthroughLayerANDROID dengan memanggil xrCreatePassthroughLayerANDROID. Handle XrPassthroughLayerANDROID yang ditampilkan dapat digunakan dalam panggilan API.
XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);
Deskripsi Parameter
- sessionadalah XrSession tempat lapisan passthrough akan dibuat.
- createInfoadalah pointer ke struktur XrPassthroughLayerCreateInfoANDROID yang menentukan parameter lapisan passthrough awal. Kolom ini dapat juga dirantai ke struktur XrPassthroughLayerMeshANDROID untuk menetapkan mesh secara bersamaan.
- layeradalah pointer ke handle tempat XrPassthroughLayerANDROID yang dibuat ditampilkan.
Aplikasi harus menentukan jumlah indeks mesh passthrough di
XrPassthroughLayerCreateInfoANDROID::vertexCapacity dan
XrPassthroughLayerCreateInfoANDROID::indexCapacity kurang dari atau sama dengan
nilai maksimum yang ditampilkan oleh
XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount dan
XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount saat memanggil
xrGetSystemProperties. xrCreatePassthroughLayerANDROID akan menampilkan
error XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID jika jumlah indeks mesh
yang ditentukan olehcreateInfo lebih besar dari nilai maksimum.
Pegangan XrPassthroughLayerANDROID harus pada akhirnya dibebaskan menggunakan
fungsi xrDestroyPassthroughLayerANDROID.
Penggunaan yang Valid (Implisit)
- Ekstensi XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum memanggil xrCreatePassthroughLayerANDROID
- sessionharus berupa nama sebutan channel XrSession yang valid
- createInfoharus berupa pointer ke struktur XrPassthroughLayerCreateInfoANDROID yang valid
- layerharus berupa pointer ke handle XrPassthroughLayerANDROID
Kode Status
- XR_SUCCESS
- XR_SESSION_LOSS_PENDING
- XR_ERROR_FUNCTION_UNSUPPORTED
- XR_ERROR_VALIDATION_FAILURE
- XR_ERROR_RUNTIME_FAILURE
- XR_ERROR_HANDLE_INVALID
- XR_ERROR_INSTANCE_LOST
- XR_ERROR_SESSION_LOST
- XR_ERROR_OUT_OF_MEMORY
- XR_ERROR_LIMIT_REACHED
- XR_ERROR_SIZE_INSUFFICIENT
- XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID
Struktur XrPassthroughLayerCreateInfoANDROID ditentukan sebagai:
typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;
Deskripsi Anggota
- typeadalah XrStructureType dari struktur ini.
- nextadalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. XrPassthroughLayerMeshANDROID dapat disediakan di rantai berikutnya untuk menentukan mesh awal untuk lapisan passthrough saat memanggil xrCreatePassthroughLayerANDROID.
- vertexCapacityadalah- uint32_tyang mewakili kapasitas maksimum buffer vertex untuk mesh lapisan ini, atau- 0jika tidak ditentukan. Jika ditentukan, XrPassthroughLayerMeshANDROID::vertexCount dari mesh apa pun yang ditetapkan untuk lapisan ini harus kurang dari atau sama dengan- vertexCapacity.
- indexCapacityadalah- uint32_tyang mewakili kapasitas maksimum buffer indeks untuk mesh lapisan ini, atau- 0jika tidak ditentukan. Jika ditentukan, XrPassthroughLayerMeshANDROID::indexCount dari mesh apa pun yang ditetapkan untuk lapisan ini harus kurang dari atau sama dengan- indexCapacity.
Penggunaan yang Valid (Implisit)
- Ekstensi XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum menggunakan XrPassthroughLayerCreateInfoANDROID
- typeharus berupa- XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
- nextharus berupa- NULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur. Lihat juga: XrPassthroughLayerMeshANDROID
Aplikasi dapat menggunakan fungsi xrDestroyPassthroughLayerANDROID untuk
merilis lapisan passthrough dan resource yang mendasarinya.
XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);
Deskripsi Parameter
- layeradalah XrPassthroughLayerANDROID yang akan dihancurkan.
Penggunaan yang Valid (Implisit)
- Ekstensi XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum memanggilxrDestroyPassthroughLayerANDROID
- layerharus berupa handle XrPassthroughLayerANDROID yang valid
Keamanan Thread
- Akses ke layer, dan setiap nama sebutan turunan, harus disinkronkan secara eksternal
Kode Status
- XR_SUCCESS
- XR_ERROR_FUNCTION_UNSUPPORTED
- XR_ERROR_RUNTIME_FAILURE
- XR_ERROR_HANDLE_INVALID
Menetapkan mesh lapisan passthrough
Aplikasi dapat menggunakan fungsi xrSetPassthroughLayerMeshANDROID untuk menetapkan mesh untuk lapisan passthrough.
XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);
Deskripsi Parameter
- layeradalah handle XrPassthroughLayerANDROID yang akan diperbarui dengan- meshyang diberikan.- meshadalah pointer ke struktur XrPassthroughLayerMeshANDROID yang menentukan informasi mesh.
 
Aplikasi harus menentukan jumlah indeks mesh passthrough di
XrPassthroughLayerMeshANDROID::vertexCount dan
XrPassthroughLayerMeshANDROID::indexCount kurang dari atau sama dengan
nilai maksimum yang ditampilkan oleh
XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount dan
XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount saat memanggil
xrGetSystemProperties. Jika jumlah indeks mesh yang diberikan oleh mesh dari
xrSetPassthroughLayerMeshANDROID lebih besar dari nilai maksimum, XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID akan ditampilkan.
Jika kapasitas buffer mesh ditentukan oleh
XrPassthroughLayerCreateInfoANDROID::vertexCapacity dan
XrPassthroughLayerCreateInfoANDROID::indexCapacity saat membuat
layer menggunakan xrCreatePassthroughLayerANDROID, error
XR_ERROR_SIZE_INSUFFICIENT akan ditampilkan di
xrSetPassthroughLayerMeshANDROID jika
jumlah indeks mesh yang ditentukan oleh mesh lebih besar dari kapasitas.
Penggunaan yang Valid (Implisit)
- Ekstensi XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum memanggil xrSetPassthroughLayerMeshANDROID
- layerharus berupa handle XrPassthroughLayerANDROID yang valid
- meshharus berupa pointer ke struktur XrPassthroughLayerMeshANDROID yang valid
Kode Status
- XR_SUCCESS
- XR_SESSION_LOSS_PENDING
- XR_ERROR_FUNCTION_UNSUPPORTED
- XR_ERROR_VALIDATION_FAILURE
- XR_ERROR_RUNTIME_FAILURE
- XR_ERROR_HANDLE_INVALID
- XR_ERROR_INSTANCE_LOST
- XR_ERROR_SESSION_LOST
- XR_ERROR_OUT_OF_MEMORY
- XR_ERROR_LIMIT_REACHED
- XR_ERROR_SIZE_INSUFFICIENT
- XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID
Struktur XrPassthroughLayerMeshANDROID ditentukan sebagai:
typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;
Deskripsi Anggota
- typeadalah XrStructureType dari struktur ini.
- nextadalah- NULLatau pointer ke struktur berikutnya dalam rantai struktur.
- windingOrderadalah XrWindingOrderANDROID dari segitiga mesh, yang akan digunakan untuk pemangkasan sisi belakang saat merender mesh.
- vertexCountadalah- uint32_tyang mewakili jumlah vertex dalam mesh. Jika XrPassthroughLayerCreateInfoANDROID::vertexCapacity ditentukan,- vertexCountharus kurang dari atau sama dengan- vertexCapacity.- verticesadalah pointer ke array- XrVector3fyang berisi posisi vertex mesh segitiga.
 
- indexCountadalah- uint32_tyang mewakili jumlah indeks dalam mesh segitiga. Indeks- indexCount % 3terakhir, jika ada, tidak akan digambar. Jika XrPassthroughLayerCreateInfoANDROID::indexCapacity ditentukan,- indexCountharus kurang dari atau sama dengan- indexCapacity.
- indicesadalah pointer ke array- uint16_tyang berisi indeks mesh segitiga.
Penggunaan yang Valid (Implisit)
- Ekstensi XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum menggunakan XrPassthroughLayerMeshANDROID
- typeharus berupa- XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
- nextharus berupa- NULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur
- windingOrderharus berupa nilai XrWindingOrderANDROID yang valid
- Jika vertexCountbukan0, vertices, harus berupa pointer ke array struktur XrVector3fvertexCount
- Jika indexCountbukan0, indices, harus berupa pointer ke array nilaiindexCount uint16_t
Enumerasi XrWindingOrderANDROID mengidentifikasi urutan winding segitiga mesh, yang digunakan oleh runtime untuk pembuangan backface saat merender mesh lapisan passthrough.
typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;
Deskripsi Enumerant
- XR_WINDING_ORDER_UNKNOWN_ANDROID— Urutan winding segitiga mesh tidak diketahui.
- XR_WINDING_ORDER_CW_ANDROID— Urutan winding segitiga mesh adalah searah jarum jam.
- XR_WINDING_ORDER_CCW_ANDROID— Urutan winding segitiga mesh adalah berlawanan arah jarum jam.
Contoh kode untuk komposisi lapisan passthrough
Contoh kode berikut menunjukkan cara membuat lapisan passthrough dan menggunakannya dalam komposisi.
XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace space; // previously initialized
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreatePassthroughLayerANDROID xrCreatePassthroughLayerANDROID; // previously initialized
PFN_xrDestroyPassthroughLayerANDROID xrDestroyPassthroughLayerANDROID; // previously initialized
PFN_xrSetPassthroughLayerMeshANDROID xrSetPassthroughLayerMeshANDROID; // previously initialized
// Inspect passthrough mesh system properties
XrSystemPassthroughLayerPropertiesANDROID passthroughLayerSystemProperties{
  XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{
  XR_TYPE_SYSTEM_PROPERTIES, &passthroughLayerSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!passthroughLayerSystemProperties.supportsPassthroughLayer) {
    // the system does not support composite layer passthrough mesh.
    return;
}
// The initial mesh for the layer.
XrPassthroughLayerMeshANDROID mesh = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID,
  .windingOrder = XR_WINDING_ORDER_CW_ANDROID,
  .vertexCount = 4,
  .vertices = {
    { 0, 0, 0 }, { 0, 1, 0 }, { 1, 1, 0 }, { 1, 0, 0 }
  },
  .indexCount = 6,
  .indices = {
    0, 1, 2,
    0, 2, 3
  },
};
// Create the layer. Layers are expected to persist across frames.
XrPassthroughLayerCreateInfoANDROID create_info = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID,
  .next = &mesh,
  .vertexCapacity = 0,
  .indexCapacity = 0,
};
XrPassthroughLayerANDROID layer;
CHK_XR(xrCreatePassthroughLayerANDROID(session, &create_info, &layer));
// Create a composition layer. Composition layers are submitted per frame.
XrCompositionLayerPassthroughANDROID passthrough_layer = {
  .type = XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID,
  .next = nullptr,
  .layerFlags = 0,
  .space = space,
  .pose = {
    .orientation = { 0.0f, 0.0f, 0.0f, 1.0f }
    .position = { 0.0f, 0.0f, 0.0f }
  },
  .scale = { 1.0f, 1.0f, 1.0f },
  .opacity = 1.0f,
  .layer = layer
};
while (1) {
    // ...
    // For every frame in frame loop
    // ...
    // Submit composition layer in xrEndFrame.
    std::vector<XrCompositionLayerBaseHeader*> layers = {
        ...,
        &passthrough_layer,
        ...,
    };
    XrFrameEndInfo end_frame_info = { XR_TYPE_FRAME_END_INFO, nullptr };
    end_frame_info.layerCount = (uint32_t)layers.size();
    end_frame_info.layers = layers.data();
    CHK_XR(xrEndFrame(session, &end_frame_info));
    // Update the layer. Results can be seen the next time a passthrough composition
    // layer is submitted.
    mesh.indexCount = 9;
    const uint16_t new_index_buffer[] = {
        0, 1, 2,
        0, 2, 3,
        0, 1, 2
    };
    mesh.indexBuffer = &new_index_buffer[0];
    CHK_XR(xrSetPassthroughLayerMeshANDROID(&layer, &mesh));
    // ...
    // Finish frame loop
    // ...
}
// Clean up.
CHK_XR(xrDestroyPassthroughLayerANDROID(layer));
Jenis Objek Baru
Konstanta Enum Baru
Enumerasi XrObjectType diperluas dengan:
- XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID
Enumerasi XrStructureType diperluas dengan:
- XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
- XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
- XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
- XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID
Enumerasi XrResult diperluas dengan:
- XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID
Enum Baru
Struktur Baru
- XrPassthroughLayerCreateInfoANDROID
- XrPassthroughLayerMeshANDROID
- XrCompositionLayerPassthroughANDROID
- XrSystemPassthroughLayerPropertiesANDROID
Fungsi Baru
- xrCreatePassthroughLayerANDROID
- xrDestroyPassthroughLayerANDROID
- xrSetPassthroughLayerMeshANDROID
Masalah
Histori Versi
- Revisi 1, 11-09-2024 (Levana Chen)
- Deskripsi ekstensi awal
 
OpenXR™ dan logo OpenXR adalah merek dagang yang dimiliki oleh The Khronos Group Inc. dan terdaftar sebagai merek dagang di China, Uni Eropa, Jepang, dan Inggris Raya.
