The Android XR SDK is now available in Developer Preview. We want your feedback! Visit our support page to reach out.

Halaman ini diterjemahkan oleh Cloud Translation API.

Ekstensi OpenXR XR_ANDROID_composition_layer_passthrough_mesh

String Nama

XR_ANDROID_composition_layer_passthrough_mesh

Jenis Ekstensi

Ekstensi instance

Registered Extension Number

463

Revisi

Dependensi Ekstensi dan Versi

OpenXR 1.0

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 membuat 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

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.
supportsPassthroughLayer adalah XrBool32, yang menunjukkan apakah sistem saat ini mendukung mesh passthrough lapisan komposisi.
maxMeshIndexCount adalah uint32_t yang menampilkan jumlah maksimum indeks yang akan diterima untuk mesh passthrough.
maxMeshVertexCount adalah uint32_t yang 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_mesh harus diaktifkan sebelum menggunakan XrSystemPassthroughLayerPropertiesANDROID
type harus berupa XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID
next harus berupa NULL atau 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

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.
layerFlags adalah bitmask dari XrCompositionLayerFlags yang menjelaskan flag yang akan diterapkan ke lapisan.
space adalah XrSpace tempat pose mesh lapisan dievaluasi dari waktu ke waktu.
pose adalah XrPosef yang menentukan posisi dan orientasi mesh lapisan dalam frame referensi space.
scale adalah XrVector3f yang menentukan skala mesh lapisan.
opacity adalah float yang menentukan opasitas tekstur passthrough dalam rentang [0, 1].
layer adalah 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_mesh harus diaktifkan sebelum menggunakan XrCompositionLayerPassthroughANDROID
type harus berupa XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
layerFlags harus berupa 0 atau kombinasi yang valid dari nilai XrCompositionLayerFlagBits
space harus berupa nama sebutan XrSpace yang valid
layer harus berupa handle XrPassthroughLayerANDROID yang valid
layer dan space harus 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

session adalah XrSession tempat lapisan passthrough akan dibuat.
createInfo adalah pointer ke struktur XrPassthroughLayerCreateInfoANDROID yang menentukan parameter lapisan passthrough awal. Kolom ini dapat juga dirantai ke struktur XrPassthroughLayerMeshANDROID untuk menetapkan mesh secara bersamaan.
layer adalah pointer ke handle tempat XrPassthroughLayerANDROID yang dibuat ditampilkan.

Aplikasi harus menentukan jumlah indeks mesh passthrough di XrPassthroughLayerCreateInfoANDROID::vertexCapacity dan XrPassthroughLayerCreateInfoANDROID::indexCapacity yang 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_mesh harus diaktifkan sebelum memanggil xrCreatePassthroughLayerANDROID
session harus berupa nama sebutan channel XrSession yang valid
createInfo harus berupa pointer ke struktur XrPassthroughLayerCreateInfoANDROID yang valid
layer harus berupa pointer ke handle XrPassthroughLayerANDROID

Kode Status

Berhasil

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Kegagalan

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

type adalah XrStructureType dari struktur ini.
next adalah 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.
vertexCapacity adalah uint32_t yang mewakili kapasitas maksimum buffer vertex untuk mesh lapisan ini, atau 0 jika tidak ditentukan. Jika ditentukan, XrPassthroughLayerMeshANDROID::vertexCount dari mesh apa pun yang ditetapkan untuk lapisan ini harus kurang dari atau sama dengan vertexCapacity.
indexCapacity adalah uint32_t yang mewakili kapasitas maksimum buffer indeks untuk mesh lapisan ini, atau 0 jika 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_mesh harus diaktifkan sebelum menggunakan XrPassthroughLayerCreateInfoANDROID
type harus berupa XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
next harus berupa NULL atau 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

layer adalah XrPassthroughLayerANDROID yang akan dihancurkan.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_composition_layer_passthrough_mesh harus diaktifkan sebelum memanggil xrDestroyPassthroughLayerANDROID
layer harus berupa handle XrPassthroughLayerANDROID yang valid

Keamanan Thread

Akses ke layer, dan nama sebutan turunan apa pun, harus disinkronkan secara eksternal

Kode Status

Berhasil

XR_SUCCESS

Kegagalan

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

layer adalah handle XrPassthroughLayerANDROID yang akan diperbarui dengan mesh yang diberikan.
- mesh adalah 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_mesh harus diaktifkan sebelum memanggil xrSetPassthroughLayerMeshANDROID
layer harus berupa handle XrPassthroughLayerANDROID yang valid
mesh harus berupa pointer ke struktur XrPassthroughLayerMeshANDROID yang valid

Kode Status

Berhasil

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Kegagalan

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

type adalah XrStructureType dari struktur ini.
next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
windingOrder adalah XrWindingOrderANDROID dari segitiga mesh, yang akan digunakan untuk pemangkasan sisi belakang saat merender mesh.
vertexCount adalah uint32_t yang mewakili jumlah vertex dalam mesh. Jika XrPassthroughLayerCreateInfoANDROID::vertexCapacity ditentukan, vertexCount harus kurang dari atau sama dengan vertexCapacity.
- vertices adalah pointer ke array XrVector3f yang berisi posisi vertex mesh segitiga.
indexCount adalah uint32_t yang mewakili jumlah indeks dalam mesh segitiga. Indeks indexCount % 3 terakhir, jika ada, tidak akan digambar. Jika XrPassthroughLayerCreateInfoANDROID::indexCapacity ditentukan, indexCount harus kurang dari atau sama dengan indexCapacity.
indices adalah pointer ke array uint16_t yang berisi indeks mesh segitiga.

Penggunaan yang Valid (Implisit)

Ekstensi XR_ANDROID_composition_layer_passthrough_mesh harus diaktifkan sebelum menggunakan XrPassthroughLayerMeshANDROID
type harus berupa XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
windingOrder harus berupa nilai XrWindingOrderANDROID yang valid
Jika vertexCount bukan 0, vertices, harus berupa pointer ke array struktur XrVector3f vertexCount
Jika indexCount bukan 0, indices, harus berupa pointer ke array nilai indexCount 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));