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，表示網格資料超出支援的限制。

有效用法 (隱含)

直通圖層組合

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 基本結構的指標，並以所選圖層順序，要求執行階段將傳輸層合成至最終影格輸出。

有效用法 (隱含)

建立傳遞層句柄

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

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

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

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

參數說明

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

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

有效用法 (隱含)

傳回代碼

成功

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

成員說明

有效用法 (隱含)

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

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

參數說明

有效用法 (隱含)

執行緒安全性

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

傳回代碼

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

設定穿透圖層網格

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

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

參數說明

應用程式應在 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_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 陣列的指標，其中包含三角形網格的索引。

有效用法 (隱含)

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

新物件類型

新列舉常數

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

新列舉項目

新結構體

新函式

問題

版本記錄

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