XR_ANDROID_composition_layer_passthrough_mesh OpenXR 擴充功能

名稱字串

XR_ANDROID_composition_layer_passthrough_mesh

擴充功能類型

執行個體擴充功能

已註冊的擴充號碼

463

修訂版本

1

擴充功能和版本依附元件

OpenXR 1.0

上次修改日期

2024-09-18

IP 狀態

沒有已知的 IP 版權聲明。

著作人

Google 的 Grant Yoshida

Kevin Moule，Google

Vasiliy Baranov，Google

Google 的 Peter Chen

Levana Chen，Google

總覽

如果裝置支援多種環境混合模式，系統可能會提供透視設定，讓使用者在沉浸式檢視畫面中看到自己的實體環境。

這個擴充功能可讓應用程式透過額外的組合層 XrCompositionLayerPassthroughANDROID，將透視紋理投射到任意幾何圖形。

透視層特性由下列參數指定，其中投影由 XrPassthroughLayerANDROID 代表。

  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;

如要全螢幕傳送，應用程式可以使用環境混合模式。

檢查系統能力

應用程式可以在呼叫 xrGetSystemProperties 時，將 XrSystemPassthroughLayerPropertiesANDROID 結構體連結至 XrSystemProperties，藉此檢查系統是否能夠組合轉送網格。

typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL 或結構鏈結中下一個結構的指標。核心 OpenXR 或這個擴充功能中並未定義這類結構。
• supportsPassthroughLayer 是 XrBool32，用於指出目前系統是否支援組合圖層傳遞透視網格。
• maxMeshIndexCount 是 uint32_t，會傳回可接受的傳送網格索引數量上限。
• maxMeshVertexCount 是 uint32_t，會傳回可接受的通過式網格頂點數量上限。

如果 supportsPassthroughLayer 傳回 XR_FALSE，系統就不會支援合成圖層傳輸網格，因此會從 xrCreatePassthroughLayerANDROID 接收 XR_ERROR_FEATURE_UNSUPPORTED。當 supportsPassthroughLayer 為 XR_FALSE 時，應用程式應避免使用組合圖層傳遞網格。

如果 supportsPassthroughLayer 傳回 XR_TRUE，系統就會支援組合圖層傳輸網格。在這種情況下，maxMeshIndexCount 和 maxMeshVertexCount 會傳回非零值。應用程式應在呼叫 xrCreatePassthroughLayerANDROID 和 xrSetPassthroughLayerMeshANDROID 時，使用 maxMeshIndexCount 和 maxMeshVertexCount 做為最大值，以設定穿透網格，否則可能會傳回 XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID，表示網格資料超出支援的限制。

有效用法 (隱含)

• 您必須先啟用 XR_ANDROID_composition_layer_passthrough_mesh 擴充功能，才能使用 XrSystemPassthroughLayerPropertiesANDROID
• type 必須為 XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID
• next 必須為 NULL，或指向結構體鏈結中下一個結構體的有效指標

直通圖層組合

XrCompositionLayerPassthroughANDROID 包含在呼叫 xrEndFrame 時，將轉送紋理算繪至三角形網格所需的資訊。XrCompositionLayerPassthroughANDROID 是 XrFrameEndInfo 中使用的基礎結構體 XrCompositionLayerBaseHeader 的別名類型。

typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL 或結構鏈結中下一個結構的指標。核心 OpenXR 或這個擴充功能中並未定義這類結構。
• layerFlags 是 XrCompositionLayerFlags 的位元遮罩，用於說明要套用至圖層的標記。
• space 是 XrSpace，其中會隨著時間評估圖層網格的 pose。
• pose 是 XrPosef，定義圖層網格在 space 參考架構中的位置和方向。
• scale 是 XrVector3f，定義圖層網格比例。
• opacity 是 float，定義傳送紋理的不透明度範圍 [0, 1]。
• layer 是先前由 xrCreatePassthroughLayerANDROID 建立的 XrPassthroughLayerANDROID。

應用程式可以使用已建立的 layer 和 XrPassthroughLayerMeshANDROID 提供的相應網格，建立 XrCompositionLayerPassthroughANDROID 結構。

在 xrEndFrame 中，可以將指向 XrCompositionLayerPassthroughANDROID 的指標，做為指向基本結構 XrCompositionLayerBaseHeader 的指標，並以所選圖層順序提交，要求執行階段將傳送層合成至最終影格輸出。

有效用法 (隱含)

• 您必須先啟用 XR_ANDROID_composition_layer_passthrough_mesh 擴充功能，才能使用 XrCompositionLayerPassthroughANDROID
• type 必須為 XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
• next 必須為 NULL，或指向結構體鏈結中下一個結構體的有效指標
• layerFlags 必須為 0，或 XrCompositionLayerFlagBits 值的有效組合
• space 必須是有效的 XrSpace 句柄
• layer 必須是有效的 XrPassthroughLayerANDROID 句柄
• layer 和 space 必須已建立、分配或從相同的 XrSession 擷取

建立傳遞層句柄

XrPassthroughLayerANDROID 句柄代表傳遞層，可定義 XrCompositionLayerPassthroughANDROID 的行為。

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

應用程式可以透過呼叫 xrCreatePassthroughLayerANDROID 建立 XrPassthroughLayerANDROID 句柄。系統會傳回的 XrPassthroughLayerANDROID 句柄可在後續的 API 呼叫中使用。

XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);

參數說明

• session 是 XrSession，其中會建立傳送層。
• createInfo 是指向 XrPassthroughLayerCreateInfoANDROID 結構體的指標，用於指定初始傳送層參數。這個欄位可以連結至 XrPassthroughLayerMeshANDROID 結構，以便同時設定網格。
• layer 是指向句柄的指標，其中會傳回已建立的 XrPassthroughLayerANDROID。

應用程式應在 XrPassthroughLayerCreateInfoANDROID::vertexCapacity 和 XrPassthroughLayerCreateInfoANDROID::indexCapacity 中指定的傳送網格索引數量，應小於或等於 XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount 和 XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount 在呼叫 xrGetSystemProperties 時傳回的最大值。如果 createInfo 定義的網格索引數量大於最大值，xrCreatePassthroughLayerANDROID 會傳回 XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID 錯誤。

XrPassthroughLayerANDROID 句柄必須最終使用 xrDestroyPassthroughLayerANDROID 函式釋放。

有效用法 (隱含)

• 您必須先啟用 XR_ANDROID_composition_layer_passthrough_mesh 擴充功能，才能呼叫 xrCreatePassthroughLayerANDROID
• session 必須是有效的 XrSession 句柄
• createInfo 必須是指向有效 XrPassthroughLayerCreateInfoANDROID 結構體的指標
• layer 必須是 XrPassthroughLayerANDROID 句柄的指標

傳回代碼

成功

• 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

XrPassthroughLayerCreateInfoANDROID 結構的定義如下：

typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 為空值或結構鏈結中下一個結構的指標。XrPassthroughLayerMeshANDROID 可在下一個鏈結中提供，以便在呼叫 xrCreatePassthroughLayerANDROID 時，為傳送層指定初始網格。
• vertexCapacity 是 uint32_t，代表此圖層網格的頂點緩衝區的最大容量，如果未指定，則為 0。如果指定，則為此圖層設定的任何網格集合的 XrPassthroughLayerMeshANDROID::vertexCount 必須小於或等於 vertexCapacity。
• indexCapacity 是 uint32_t，代表此圖層網格的索引緩衝區的最大容量，如果未指定，則為 0。如果指定，則為此圖層設定的任何網格集合的 XrPassthroughLayerMeshANDROID::indexCount 必須小於或等於 indexCapacity。

有效用法 (隱含)

• 您必須先啟用 XR_ANDROID_composition_layer_passthrough_mesh 擴充功能，才能使用 XrPassthroughLayerCreateInfoANDROID
• type 必須為 XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
• next 必須為 NULL，或指向結構體鏈中的下一個結構體的有效指標。另請參閱：XrPassthroughLayerMeshANDROID

應用程式可以使用 xrDestroyPassthroughLayerANDROID 函式釋放傳輸層和基礎資源。

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

參數說明

• layer 是將要銷毀的 XrPassthroughLayerANDROID。

有效用法 (隱含)

• 必須先啟用 XR_ANDROID_composition_layer_passthrough_mesh 擴充功能，才能呼叫 xrDestroyPassthroughLayerANDROID
• layer 必須是有效的 XrPassthroughLayerANDROID 句柄

執行緒安全性

• layer 和任何子系句柄的存取權必須在外部同步

傳回代碼

成功

• XR_SUCCESS

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID

設定穿透圖層網格

應用程式可以使用 xrSetPassthroughLayerMeshANDROID 函式，為傳輸層設定網格。

XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);

參數說明

• layer 是 XrPassthroughLayerANDROID 的句柄，可用於使用指定的 mesh 進行更新。
  • mesh 是指向 XrPassthroughLayerMeshANDROID 結構體的指標，可指定網格資訊。

應用程式應在 XrPassthroughLayerMeshANDROID::vertexCount 和 XrPassthroughLayerMeshANDROID::indexCount 中指定的傳送網格索引數量，應小於或等於 XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount 和 XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount 在呼叫 xrGetSystemProperties 時傳回的最大值。如果 xrSetPassthroughLayerMeshANDROID 的 mesh 所提供的網格索引數量大於上限值，系統會傳回 XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID。

如果使用 xrCreatePassthroughLayerANDROID 建立 layer 時，XrPassthroughLayerCreateInfoANDROID::vertexCapacity 和 XrPassthroughLayerCreateInfoANDROID::indexCapacity 會指定網格緩衝區容量，如果 mesh 定義的網格索引數量大於容量，則 xrSetPassthroughLayerMeshANDROID 會傳回 XR_ERROR_SIZE_INSUFFICIENT 錯誤。

有效用法 (隱含)

• 必須先啟用 XR_ANDROID_composition_layer_passthrough_mesh 擴充功能，才能呼叫 xrSetPassthroughLayerMeshANDROID
• layer 必須是有效的 XrPassthroughLayerANDROID 句柄
• mesh 必須是指向有效 XrPassthroughLayerMeshANDROID 結構體的指標

傳回代碼

成功

• 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

XrPassthroughLayerMeshANDROID 結構的定義如下：

typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;

成員說明

• type 是這個結構的 XrStructureType。
• next 是 NULL，或結構鏈結中指向下一個結構的指標。
• windingOrder 是網格三角形的 XrWindingOrderANDROID，會在算繪網格時用於背面剔除。
• vertexCount 是 uint32_t，代表網格中的頂點數。指定 XrPassthroughLayerCreateInfoANDROID::vertexCapacity 時，vertexCount 必須小於或等於 vertexCapacity。
  • vertices 是指向 XrVector3f 陣列的指標，其中包含三角形網格的頂點位置。
• indexCount 是 uint32_t，代表三角形網格中的索引數量。不會繪製最後的 indexCount % 3 索引 (如有)。指定 XrPassthroughLayerCreateInfoANDROID::indexCapacity 時，indexCount 必須小於或等於 indexCapacity。
• indices 是指向 uint16_t 陣列的指標，其中包含三角形網格的索引。

有效用法 (隱含)

• 您必須先啟用 XR_ANDROID_composition_layer_passthrough_mesh 擴充功能，才能使用 XrPassthroughLayerMeshANDROID
• type 必須為 XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
• next 必須為 NULL，或指向結構體鏈結中下一個結構體的有效指標
• windingOrder 必須為有效的 XrWindingOrderANDROID 值
• 如果 vertexCount 不是 0, vertices，則必須是 vertexCount XrVector3f 結構體陣列的指標
• 如果 indexCount 不是 0, indices，則必須是指向 indexCount uint16_t 值陣列的指標

XrWindingOrderANDROID 列舉會指出網格三角形的迴轉順序，在轉送層的網格算繪時，這個順序會由執行階段用於背面剔除。

typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;

列舉說明

• XR_WINDING_ORDER_UNKNOWN_ANDROID  -- 未知網格三角形的纏繞順序。
• XR_WINDING_ORDER_CW_ANDROID  — 網格的三角形順時針方向排列順序。
• XR_WINDING_ORDER_CCW_ANDROID  — 網格的三角形排列順序為逆時針。

透過層級組合傳遞的程式碼範例

以下程式碼範例說明如何建立傳送層，並在合成中使用該層。

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));

新物件類型

• XrPassthroughLayerANDROID

新列舉常數

XrObjectType 列舉已擴充以下項目：

• XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

XrStructureType 列舉已擴充以下項目：

• 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

XrResult 列舉已擴充以下項目：

• XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

新列舉項目

• XrWindingOrderANDROID

新結構體

• XrPassthroughLayerCreateInfoANDROID
• XrPassthroughLayerMeshANDROID
• XrCompositionLayerPassthroughANDROID
• XrSystemPassthroughLayerPropertiesANDROID

新函式

• xrCreatePassthroughLayerANDROID
• xrDestroyPassthroughLayerANDROID
• xrSetPassthroughLayerMeshANDROID

問題

版本記錄

• 修訂版本 1，2024-09-11 (Levana Chen)
  • 初始擴充功能說明