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 来指示网格数据超出支持的限制。

有效用法（隐式）

• 必须先启用 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 中指定的透视网格索引数量小于或等于调用 xrGetSystemProperties 时由 XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount 和 XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount 返回的最大值。如果由 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 为 NULL 或指向结构链中下一个结构的指针。在调用 xrCreatePassthroughLayerANDROID 时，可以在下一个链中提供 XrPassthroughLayerMeshANDROID，以指定透视层的初始网格。
• 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 中的透视网格索引数量，该数量应小于或等于调用 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_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 年 9 月 11 日（Levana Chen）
  • 初始扩展程序说明