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

Peter Chen, Google

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 将返回非零数字。应用程序应将 maxMeshIndexCount 和 maxMeshVertexCount 用作设置透视网格时的最大值，以调用 xrCreatePassthroughLayerANDROID 和 xrSetPassthroughLayerMeshANDROID，否则可能会返回 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 结构。

指向 XrCompositionLayerPassthroughANDROID 的指针可以在 xrEndFrame 中作为指向基础结构 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 返回的最大值。xrCreatePassthroughLayerANDROID 将返回 XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID 错误，如果由 createInfo 定义的网格索引数量大于最大值。

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 中指定的透视网格索引数量小于或等于调用 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-09-11 (Levana Chen)
    • 初始扩展描述

OpenXR™ 和 OpenXR 徽标是 The Khronos Group Inc. 拥有的商标，并在中国、欧盟、日本和英国注册为商标。