XR_ANDROID_composition_layer_passthrough_mesh OpenXR 扩展

名称字符串

XR_ANDROID_composition_layer_passthrough_mesh

扩展程序类型

实例扩展

已注册的扩展号码

463

修订版本

1

扩展程序和版本依赖项

OpenXR 1.0

上次修改日期

2024-09-18

IP 状态

没有已知的 IP 版权主张。

创作贡献者

Grant Yoshida，Google

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 中指定的透视网格索引数量小于或等于调用 xrGetSystemProperties 时由 XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount 和 XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount 返回的最大值。如果由 createInfo 定义的网格索引数量大于最大值，xrCreatePassthroughLayerANDROID 将返回 XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID 错误。

最终必须使用 xrDestroyPassthroughLayerANDROID 函数释放 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;

成员说明

有效用法（隐式）

应用可以使用 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 中的透视网格索引数量，该数量应小于或等于调用 xrGetSystemProperties 时 XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount 和 XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount 返回的最大值。如果 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 年 9 月 11 日（Levana Chen）
    • 初始扩展程序说明