Tiện ích OpenXR XR_ANDROID_composition_layer_passthrough_mesh

Chuỗi tên

XR_ANDROID_composition_layer_passthrough_mesh

Loại phần mở rộng

Tiện ích thực thể

Số điện thoại mở rộng đã đăng ký

463

Bản sửa đổi

1

Phần mở rộng và phần phụ thuộc phiên bản

OpenXR 1.0

Ngày sửa đổi gần đây nhất

2024-09-18

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu đối với tài sản trí tuệ nào.

Cộng tác viên

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

Tổng quan

Đối với các thiết bị hỗ trợ nhiều chế độ kết hợp môi trường, hệ thống có thể cung cấp cấu hình truyền tải để hiển thị cho người dùng môi trường thực của họ từ chế độ xem sống động.

Tiện ích này cho phép các ứng dụng chiếu hoạ tiết truyền qua lên hình học tuỳ ý thông qua một lớp kết hợp bổ sung XrCompositionLayerPassthroughANDROID.

Các đặc điểm của lớp truyền tải được chỉ định bằng các tham số sau, trong đó phép chiếu được biểu thị bằng XrPassthroughLayerANDROID.

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

Đối với tính năng truyền toàn màn hình, các ứng dụng có thể sử dụng Chế độ kết hợp môi trường.

Kiểm tra chức năng của hệ thống

Ứng dụng có thể kiểm tra xem hệ thống có thể truyền lưới lớp thành phần hay không bằng cách nối chuỗi cấu trúc XrSystemPassthroughLayerPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties.

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • supportsPassthroughLayer là XrBool32, cho biết liệu hệ thống hiện tại có hỗ trợ lưới truyền qua lớp thành phần hay không.
  • maxMeshIndexCount là một uint32_t trả về số lượng chỉ mục tối đa sẽ được chấp nhận cho một lưới truyền qua.
  • maxMeshVertexCount là một uint32_t trả về số lượng đỉnh tối đa sẽ được chấp nhận cho một lưới truyền qua.

Nếu supportsPassthroughLayer trả về XR_FALSE, thì hệ thống sẽ không hỗ trợ lưới truyền qua lớp thành phần, do đó sẽ nhận được XR_ERROR_FEATURE_UNSUPPORTED từ xrCreatePassthroughLayerANDROID. Ứng dụng nên tránh sử dụng lưới truyền qua lớp thành phần khi supportsPassthroughLayer là XR_FALSE.

Nếu supportsPassthroughLayer trả về XR_TRUE, thì hệ thống sẽ hỗ trợ lưới truyền qua lớp thành phần. Trong trường hợp này, maxMeshIndexCount và maxMeshVertexCount sẽ trả về một số khác 0. Ứng dụng nên sử dụng maxMeshIndexCount và maxMeshVertexCount làm giá trị tối đa để đặt lưới truyền dẫn khi gọi xrCreatePassthroughLayerANDROID và xrSetPassthroughLayerMeshANDROID, nếu không, XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID có thể được trả về để cho biết dữ liệu lưới vượt quá giới hạn được hỗ trợ.

Cách sử dụng hợp lệ (ngầm ẩn)

Cấu trúc lớp truyền qua

XrCompositionLayerPassthroughANDROID chứa thông tin cần thiết để kết xuất hoạ tiết truyền qua trên lưới tam giác khi gọi xrEndFrame. XrCompositionLayerPassthroughANDROID là một loại bí danh cho cấu trúc cơ sở XrCompositionLayerBaseHeader dùng trong XrFrameEndInfo.

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • layerFlags là mặt nạ bit của XrCompositionLayerFlags mô tả các cờ áp dụng cho lớp.
  • space là XrSpace, trong đó pose của lưới lớp được đánh giá theo thời gian.
  • pose là một XrPosef xác định vị trí và hướng của lưới lớp trong khung tham chiếu của space.
  • scale là một XrVector3f xác định tỷ lệ của lưới lớp.
  • opacity là float xác định độ mờ của hoạ tiết truyền trong phạm vi [0, 1].
  • layer là XrPassthroughLayerANDROID do xrCreatePassthroughLayerANDROID tạo trước đó.

Ứng dụng có thể tạo cấu trúc XrCompositionLayerPassthroughANDROID bằng layer đã tạo và các lưới tương ứng do XrPassthroughLayerMeshANDROID cung cấp.

Bạn có thể gửi con trỏ đến XrCompositionLayerPassthroughANDROID trong xrEndFrame dưới dạng con trỏ đến cấu trúc cơ sở XrCompositionLayerBaseHeader, theo thứ tự lớp đã chọn, để yêu cầu thời gian chạy kết hợp một lớp truyền tải vào đầu ra khung cuối cùng.

Cách sử dụng hợp lệ (ngầm ẩn)

Tạo tay cầm lớp truyền qua

Tay điều khiển XrPassthroughLayerANDROID đại diện cho một lớp truyền tải xác định hành vi của XrCompositionLayerPassthroughANDROID.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Ứng dụng có thể tạo một tay điều khiển XrPassthroughLayerANDROID bằng cách gọi xrCreatePassthroughLayerANDROID. Bạn có thể sử dụng tay điều khiển XrPassthroughLayerANDROID được trả về trong các lệnh gọi API. 

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

Nội dung mô tả thông số

Ứng dụng phải chỉ định số lượng chỉ mục lưới truyền qua trong XrPassthroughLayerCreateInfoANDROID::vertexCapacity và XrPassthroughLayerCreateInfoANDROID::indexCapacity nhỏ hơn hoặc bằng các giá trị tối đa do XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount và XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount trả về khi gọi xrGetSystemProperties. xrCreatePassthroughLayerANDROID sẽ trả về lỗi XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID nếu số lượng chỉ mục lưới do createInfo xác định lớn hơn các giá trị tối đa.

Cuối cùng, bạn phải giải phóng tay điều khiển XrPassthroughLayerANDROID bằng cách sử dụng hàm xrDestroyPassthroughLayerANDROID.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Cấu trúc XrPassthroughLayerCreateInfoANDROID được xác định là: 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Bạn có thể cung cấp XrPassthroughLayerMeshANDROID trong chuỗi tiếp theo để chỉ định lưới ban đầu cho lớp truyền tải khi gọi xrCreatePassthroughLayerANDROID.
  • vertexCapacity là uint32_t biểu thị dung lượng tối đa của vùng đệm đỉnh cho lưới của lớp này hoặc 0 nếu không được chỉ định. Nếu được chỉ định, XrPassthroughLayerMeshANDROID::vertexCount của bất kỳ lưới nào được đặt cho lớp này phải nhỏ hơn hoặc bằng vertexCapacity.
  • indexCapacity là uint32_t biểu thị dung lượng tối đa của vùng đệm chỉ mục cho lưới của lớp này hoặc 0 nếu không được chỉ định. Nếu được chỉ định, XrPassthroughLayerMeshANDROID::indexCount của bất kỳ lưới nào được đặt cho lớp này phải nhỏ hơn hoặc bằng indexCapacity.

Cách sử dụng hợp lệ (ngầm ẩn)

Ứng dụng có thể sử dụng hàm xrDestroyPassthroughLayerANDROID để giải phóng lớp truyền tải và các tài nguyên cơ bản.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Nội dung mô tả thông số

Cách sử dụng hợp lệ (ngầm ẩn)

Độ an toàn cho luồng

  • Quyền truy cập vào layer và mọi tay điều khiển con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

Đặt lưới lớp truyền tải

Ứng dụng có thể sử dụng hàm xrSetPassthroughLayerMeshANDROID để đặt lưới cho lớp truyền tải.

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

Nội dung mô tả thông số

Ứng dụng phải chỉ định số lượng chỉ mục lưới truyền qua trong XrPassthroughLayerMeshANDROID::vertexCount và XrPassthroughLayerMeshANDROID::indexCount nhỏ hơn hoặc bằng các giá trị tối đa do XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount và XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount trả về khi gọi xrGetSystemProperties. Nếu số lượng chỉ mục lưới do mesh cung cấp từ xrSetPassthroughLayerMeshANDROID lớn hơn các giá trị tối đa, thì XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID sẽ được trả về.

Nếu dung lượng vùng đệm lưới được chỉ định bởi XrPassthroughLayerCreateInfoANDROID::vertexCapacity và XrPassthroughLayerCreateInfoANDROID::indexCapacity khi tạo layer bằng xrCreatePassthroughLayerANDROID, thì lỗi XR_ERROR_SIZE_INSUFFICIENT sẽ được trả về trên xrSetPassthroughLayerMeshANDROID nếu số lượng chỉ mục lưới do mesh xác định lớn hơn dung lượng.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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

Cấu trúc XrPassthroughLayerMeshANDROID được xác định là: 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • windingOrder là XrWindingOrderANDROID của các tam giác lưới, sẽ được dùng để loại bỏ mặt sau khi kết xuất lưới.
  • vertexCount là uint32_t biểu thị số đỉnh trong lưới. Khi XrPassthroughLayerCreateInfoANDROID::vertexCapacity được chỉ định, vertexCount phải nhỏ hơn hoặc bằng vertexCapacity.
    • vertices là con trỏ trỏ đến một mảng XrVector3f chứa các vị trí đỉnh của lưới tam giác.
  • indexCount là uint32_t biểu thị số lượng chỉ mục trong lưới tam giác. Các chỉ mục indexCount % 3 cuối cùng (nếu có) sẽ không được vẽ. Khi chỉ định XrPassthroughLayerCreateInfoANDROID::indexCapacity, indexCount phải nhỏ hơn hoặc bằng indexCapacity.
  • indices là con trỏ trỏ đến một mảng uint16_t chứa các chỉ mục của lưới tam giác.

Cách sử dụng hợp lệ (ngầm ẩn)

Biến liệt kê XrWindingOrderANDROID xác định thứ tự xoắn của các tam giác của lưới, được thời gian chạy sử dụng để loại bỏ mặt sau khi kết xuất lưới của lớp truyền qua. 

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

Mô tả enumerant

  • XR_WINDING_ORDER_UNKNOWN_ANDROID  — Không xác định được thứ tự xoắn của các tam giác của lưới.
  • XR_WINDING_ORDER_CW_ANDROID  — Thứ tự cuộn của các tam giác của lưới là theo chiều kim đồng hồ.
  • XR_WINDING_ORDER_CCW_ANDROID  — Thứ tự cuộn của các tam giác của lưới là ngược chiều kim đồng hồ.

Mã ví dụ cho thành phần lớp truyền qua

Mã ví dụ sau đây minh hoạ cách tạo một lớp truyền tải và sử dụng lớp đó trong quá trình kết hợp.

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

Các loại đối tượng mới

Hằng số enum mới

Bổ sung enum XrObjectType bằng:

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

Bổ sung enum 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

Bổ sung enum XrResult bằng:

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Enum mới

Cấu trúc mới

Hàm mới

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 1, ngày 11 tháng 9 năm 2024 (Levana Chen)
    • Nội dung mô tả ban đầu của tiện ích