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.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur semacam itu yang ditentukan di OpenXR inti atau ekstensi ini.supportsPassthroughLayeradalahXrBool32, yang menunjukkan apakah sistem saat ini mendukung mesh passthrough lapisan komposisi.maxMeshIndexCountadalahuint32_tyang menampilkan jumlah maksimum indeks yang akan diterima untuk mesh passthrough.maxMeshVertexCountadalahuint32_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 berupaXR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROIDnextharus berupaNULLatau 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.nextadalahNULLatau 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 tempatposemesh lapisan dievaluasi dari waktu ke waktu.poseadalahXrPosefyang menentukan posisi dan orientasi mesh lapisan dalam frame referensispace.scaleadalahXrVector3fyang menentukan skala mesh lapisan.opacityadalahfloatyang 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 berupaXR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROIDnextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai strukturlayerFlagsharus berupa0atau kombinasi yang valid dari nilai XrCompositionLayerFlagBitsspaceharus berupa nama sebutan XrSpace yang validlayerharus berupa handle XrPassthroughLayerANDROID yang validlayerdanspaceharus 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 validcreateInfoharus berupa pointer ke struktur XrPassthroughLayerCreateInfoANDROID yang validlayerharus berupa pointer ke handle XrPassthroughLayerANDROID
Kode Status
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_RUNTIME_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHEDXR_ERROR_SIZE_INSUFFICIENTXR_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.vertexCapacityadalahuint32_tyang mewakili kapasitas maksimum buffer vertex untuk mesh lapisan ini, atau0jika tidak ditentukan. Jika ditentukan, XrPassthroughLayerMeshANDROID::vertexCount dari mesh apa pun yang ditetapkan untuk lapisan ini harus kurang dari atau sama denganvertexCapacity.indexCapacityadalahuint32_tyang mewakili kapasitas maksimum buffer indeks untuk mesh lapisan ini, atau0jika tidak ditentukan. Jika ditentukan, XrPassthroughLayerMeshANDROID::indexCount dari mesh apa pun yang ditetapkan untuk lapisan ini harus kurang dari atau sama denganindexCapacity.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum menggunakan XrPassthroughLayerCreateInfoANDROID typeharus berupaXR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROIDnextharus berupaNULLatau 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_UNSUPPORTEDXR_ERROR_RUNTIME_FAILUREXR_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 denganmeshyang 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 validmeshharus berupa pointer ke struktur XrPassthroughLayerMeshANDROID yang valid
Kode Status
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_VALIDATION_FAILUREXR_ERROR_RUNTIME_FAILUREXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHEDXR_ERROR_SIZE_INSUFFICIENTXR_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.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur.windingOrderadalah XrWindingOrderANDROID dari segitiga mesh, yang akan digunakan untuk pemangkasan sisi belakang saat merender mesh.vertexCountadalahuint32_tyang mewakili jumlah vertex dalam mesh. Jika XrPassthroughLayerCreateInfoANDROID::vertexCapacity ditentukan,vertexCountharus kurang dari atau sama denganvertexCapacity.verticesadalah pointer ke arrayXrVector3fyang berisi posisi vertex mesh segitiga.
indexCountadalahuint32_tyang mewakili jumlah indeks dalam mesh segitiga. IndeksindexCount % 3terakhir, jika ada, tidak akan digambar. Jika XrPassthroughLayerCreateInfoANDROID::indexCapacity ditentukan,indexCountharus kurang dari atau sama denganindexCapacity.indicesadalah pointer ke arrayuint16_tyang berisi indeks mesh segitiga.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_composition_layer_passthrough_meshharus diaktifkan sebelum menggunakan XrPassthroughLayerMeshANDROID typeharus berupaXR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROIDnextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai strukturwindingOrderharus 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_ANDROIDXR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROIDXR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROIDXR_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.