Tiện ích OpenXR XR_ANDROID_hand_mesh

Chuỗi tên

XR_ANDROID_hand_mesh

Loại phần mở rộng

Tiện ích thực thể

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

704

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-10

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

Nihav Jain, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Tổng quan

Tiện ích này cho phép theo dõi cử chỉ tay được biểu thị dưới dạng lưới tay động.

Tiện ích này nhằm cung cấp vùng đệm đỉnh và chỉ mục cho lưới của hình ảnh đại diện cá nhân cho bàn tay của người dùng. Bạn có thể sử dụng tính năng này cho việc che khuất và trực quan hoá.

Bạn không nên sử dụng tiện ích này cho các mục đích theo dõi chuyển động tay khác.

Dữ liệu theo dõi chuyển động tay có thể là thông tin cá nhân nhạy cảm và liên quan chặt chẽ đến quyền riêng tư và tính toàn vẹn cá nhân. Các ứng dụng lưu trữ hoặc chuyển dữ liệu theo dõi chuyển động tay nên luôn yêu cầu người dùng chấp nhận một cách chủ động và cụ thể.

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ể theo dõi lưới bằng tay hay không bằng cách nối chuỗi cấu trúc XrSystemHandMeshTrackingPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties.

typedef struct XrSystemHandMeshTrackingPropertiesANDROID {
  XrStructureType    type;
  void*              next;
  XrBool32           supportsHandMeshTracking;
  XrBool32           supportsTextureUV;
  XrBool32           supportsVertexNormal;
} XrSystemHandMeshTrackingPropertiesANDROID;

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.
  • supportsHandMeshTracking là XrBool32, cho biết liệu XrSystemId đã chọn có hỗ trợ tính năng theo dõi lưới tay hay không.
  • supportsTextureUV là XrBool32, cho biết liệu XrSystemId đã chọn có hỗ trợ UV hoạ tiết cho các đỉnh lưới hay không.
  • supportsVertexNormal là XrBool32, cho biết liệu XrSystemId đã chọn có hỗ trợ pháp tuyến đỉnh cho các đỉnh lưới hay không.

Ứng dụng nên tránh sử dụng các tính năng lưới tay khi supportsHandMeshTracking là XR_FALSE, vì điều này có nghĩa là hệ thống không hỗ trợ tính năng theo dõi lưới tay. Trong trường hợp này, xrCreateHandMeshTrackerANDROID sẽ trả về XR_ERROR_FEATURE_UNSUPPORTED.

Nếu supportsHandMeshTracking trả về XR_TRUE, hệ thống sẽ hỗ trợ tính năng theo dõi lưới tay. Ứng dụng nên sử dụng XrHandMeshANDROID::indexCount và XrHandMeshANDROID::vertexCount để truy cập vào vùng đệm lưới tay và sử dụng lại các vùng đệm đó trong vòng lặp kết xuất khi gọi xrGetHandMeshANDROID mỗi khung.

Nếu supportsTextureUV trả về XR_FALSE, thì hệ thống sẽ không hỗ trợ UV kết cấu cho các đỉnh lưới, do đó, ứng dụng sẽ nhận được XrHandMeshANDROID::textureUVs NULL khi gọi xrGetHandMeshANDROID.

Nếu supportsVertexNormal trả về XR_FALSE, thì hệ thống sẽ không hỗ trợ pháp tuyến đỉnh cho các đỉnh lưới, do đó, ứng dụng sẽ nhận được XrHandMeshANDROID::normals NULL khi gọi xrGetHandMeshANDROID.

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

Tạo tay cầm của trình theo dõi lưới

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

Tay cầm XrHandMeshTrackerANDROID đại diện cho một trình theo dõi lưới tay để theo dõi lưới tay và quản lý các tài nguyên liên quan.

Bạn có thể sử dụng tay cầm này để truy cập vào vùng đệm lưới tay bằng các hàm khác trong tiện ích này.

Ứng dụng có thể tạo một tay điều khiển XrHandMeshTrackerANDROID bằng cách sử dụng hàm xrCreateHandMeshTrackerANDROID. 

XrResult xrCreateHandMeshTrackerANDROID(
    XrSession                                   session,
    const XrHandMeshTrackerCreateInfoANDROID*   createInfo,
    XrHandMeshTrackerANDROID*                   handMeshTracker);

Nội dung mô tả tham số

Nếu hệ thống không hỗ trợ tính năng theo dõi lưới tay, thì xrCreateHandMeshTrackerANDROID sẽ trả về XR_ERROR_FEATURE_UNSUPPORTED.

Tên người dùng XrHandMeshTrackerANDROID sở hữu tất cả tài nguyên để theo dõi lưới bàn tay. Sau khi hoàn tất trải nghiệm theo dõi lưới tay, ứng dụng phải huỷ tay cầm bằng cách sử dụng hàm xrDestroyHandMeshTrackerANDROID.

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_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_LIMIT_REACHED

Cấu trúc XrHandMeshTrackerCreateInfoANDROID mô tả thông tin để tạo một tay cầm XrHandMeshTrackerANDROID. 

typedef struct XrHandMeshTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrHandMeshTrackerCreateInfoANDROID;

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.

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

Hàm xrDestroyHandMeshTrackerANDROID sẽ giải phóng handMeshTracker và các tài nguyên cơ bản khi bạn hoàn tất trải nghiệm theo dõi lưới tay. 

XrResult xrDestroyHandMeshTrackerANDROID(
    XrHandMeshTrackerANDROID handMeshTracker);

Nội dung mô tả tham 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 handMeshTracker 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_HANDLE_INVALID

Tìm lưới tay

Ứng dụng có thể sử dụng hàm xrGetHandMeshANDROID để truy xuất lưới tay tại một dấu thời gian nhất định. Vị trí và pháp tuyến của các đỉnh của lưới tay được biểu thị trong không gian do XrHandMeshGetInfoANDROID::baseSpace chỉ định khi gọi xrGetHandMeshANDROID.

XrResult xrGetHandMeshANDROID(
    XrHandMeshTrackerANDROID                    handMeshTracker,
    const XrHandMeshGetInfoANDROID*             getInfo,
    XrHandTrackingMeshesANDROID*                handMeshes);

Nội dung mô tả tham số

Ứng dụng có thể sử dụng hàm xrGetHandMeshANDROID để truy cập vào vùng đệm lưới tay do môi trường thời gian chạy tạo.

Ứng dụng nên gọi xrBeginFrame ít nhất một lần trong phiên trước khi thực hiện lệnh gọi đầu tiên đến xrGetHandMeshANDROID.

Ứng dụng nên sử dụng XrHandMeshANDROID::indexCount và XrHandMeshANDROID::vertexCount để truy cập vào vùng đệm lưới tay và sử dụng lại các vùng đệm đó trong vòng lặp kết xuất khi gọi xrGetHandMeshANDROID mỗi khung hình.

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_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID

XrHandMeshGetInfoANDROID mô tả thông tin cần thiết để lấy dữ liệu lưới bàn tay. 

typedef struct XrHandMeshGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
} XrHandMeshGetInfoANDROID;

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.
  • baseSpace là một XrSpace xác định không gian tham chiếu để xác định phép biến đổi cho các đỉnh tại time.
  • time là XrTime mô tả thời điểm ứng dụng muốn truy vấn lưới tay.

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

Cấu trúc XrHandTrackingMeshesANDROID chứa dữ liệu lưới cho cả hai tay. 

typedef struct XrHandTrackingMeshesANDROID {
    XrStructureType      type;
    void*                next;
    XrHandMeshANDROID    leftHandMesh;
    XrHandMeshANDROID    rightHandMesh;
} XrHandTrackingMeshesANDROID;

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.
  • leftHandMesh là XrHandMeshANDROID cho tay trái.
  • rightHandMesh là XrHandMeshANDROID cho bàn tay phải.

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

Cấu trúc XrHandMeshANDROID chứa dữ liệu và vùng đệm để nhận dữ liệu theo dõi lưới bàn tay từ hàm xrGetHandMeshANDROID cho một bàn tay.

typedef struct XrHandMeshANDROID {
    XrBool32             isActive;
    XrTime               dynamicLastUpdateTime;
    uint32_t             indexCount;
    uint32_t             vertexCount;
    const uint32_t*      indices;
    const XrVector2f*    textureUVs;
    const XrVector3f*    positions;
    const XrVector3f*    normals;
    XrPosef              baseSpaceFromVertexSpace;
} XrHandMeshANDROID;

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.
  • isActive là XrBool32 cho biết liệu trình theo dõi lưới tay hiện tại có đang hoạt động và dữ liệu lưới có hợp lệ hay không.
  • dynamicLastUpdateTime là XrTime chỉ định thời điểm cập nhật vùng đệm động gần đây nhất.
  • indexCount là một uint32_t đóng vai trò là số lượng indices của lưới bàn tay.
  • vertexCount là uint32_t đóng vai trò là số positions của lưới bàn tay. Bạn cũng có thể sử dụng phương thức này cho textureUVs hoặc normals khi hệ thống hỗ trợ các phương thức này.
  • indices là một mảng uint32_t đại diện cho các chỉ mục lưới cho tam giác theo thứ tự cuộn ngược chiều kim đồng hồ. Số lượng giá trị được trỏ đến là indexCount.
  • textureUVs là NULL hoặc một mảng XrVector2f đại diện cho toạ độ kết cấu đỉnh. Số lượng giá trị được trỏ đến là vertexCount.
  • positions là một mảng XrVector3f đại diện cho các vị trí đỉnh trong baseSpaceFromVertexSpace. Số lượng giá trị được trỏ đến là vertexCount.
  • normals là NULL hoặc mảng XrVector3f đại diện cho các pháp tuyến đỉnh trong baseSpaceFromVertexSpace. Số lượng giá trị được trỏ đến là vertexCount.
  • baseSpaceFromVertexSpace là đỉnh XrSpace nằm trong XrHandMeshGetInfoANDROID::baseSpace khi gọi xrGetHandMeshANDROID. Các ứng dụng có thể sử dụng thông tin này để biến đổi không gian toạ độ của các đỉnh và pháp tuyến của lưới trong quá trình kết xuất.

Lưới kim đồng hồ được biểu thị trong danh sách tam giác và các đỉnh của mỗi tam giác được sắp xếp theo thứ tự ngược chiều kim đồng hồ khi nhìn từ bên ngoài kim đồng hồ.

Khi giá trị isActive được trả về là XR_FALSE, điều này cho biết tay không được theo dõi tích cực; ví dụ: tay nằm ngoài phạm vi của cảm biến, tiêu điểm đầu vào bị lấy ra khỏi ứng dụng hoặc ứng dụng không có quyền truy cập vào dữ liệu theo dõi tay.

Khi giá trị isActive được trả về là XR_TRUE, lưới theo dõi tay được biểu thị trong indices và positions, bao gồm cả textureUVs và normals nếu hệ thống hỗ trợ, sẽ được cập nhật thành dữ liệu mới nhất của XrHandMeshGetInfoANDROID::time được cung cấp cho hàm xrGetHandMeshANDROID.

Bộ nhớ được trỏ đến bởi vùng đệm lưới tay được trả về trong XrHandMeshANDROID thuộc sở hữu của thời gian chạy và được chia sẻ với ứng dụng. Bạn có thể truy cập bộ nhớ một cách an toàn từ bất kỳ luồng nào cho đến lệnh gọi tiếp theo đến xrBeginFrame trong khi tay cầm XrHandMeshTrackerANDROID hợp lệ.

  • Các giá trị được indices và textureUVs trỏ đến không phải là động
  • Con trỏ và các giá trị mà positions và normals trỏ đến là động, cả hai có thể thay đổi giữa các lệnh gọi đến xrBeginFrame. Ứng dụng có thể sử dụng dynamicLastUpdateTime để kiểm tra xem các giá trị có thay đổi kể từ khung hình cuối cùng hay không và tránh xử lý dữ liệu không cần thiết khi không có thay đổi nào.

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

  • Bạn phải bật tiện ích XR_ANDROID_hand_mesh trước khi sử dụng XrHandMeshANDROID
  • indices phải là con trỏ đến một giá trị uint32_t hợp lệ
  • textureUVs phải là con trỏ đến một cấu trúc XrVector2f hợp lệ
  • positions phải là con trỏ đến một cấu trúc XrVector3f hợp lệ
  • normals phải là con trỏ đến một cấu trúc XrVector3f hợp lệ

Mã ví dụ để theo dõi lưới tay

Mã ví dụ sau đây minh hoạ cách truy cập vào vùng đệm lưới tay để kết xuất.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup.
XrSpace appPlaySpace; // Created at app startup.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateHandMeshTrackerANDROID xrCreateHandMeshTrackerANDROID; // previously initialized
PFN_xrDestroyHandMeshTrackerANDROID xrDestroyHandMeshTrackerANDROID; // previously initialized
PFN_xrGetHandMeshANDROID xrGetHandMeshANDROID; // previously initialized

// Inspect system capability
XrSystemHandMeshTrackingPropertiesANDROID handMeshTrackingProps = {
  .type = XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &handMeshTrackingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!handMeshTrackingProps.supportsHandMeshTracking) {
  // hand mesh tracking is not supported.
  return;
}

XrHandMeshTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
};
XrHandMeshTrackerANDROID handMeshTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateHandMeshTrackerANDROID(
    session, &trackerCreateInfo, &handMeshTracker));
// app update loop
while (true) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;

    // ...
    XrHandMeshGetInfoANDROID getInfo = {
        .type = XR_TYPE_HAND_MESH_GET_INFO_ANDROID,
        .baseSpace = appPlaySpace,
        .time = time,
    };
    XrHandTrackingMeshesANDROID handMeshes = {
        .type = XR_TYPE_HAND_TRACKING_MESHES_ANDROID
    };
    CHK_XR(xrGetHandMeshANDROID(handMeshTracker, &getInfo, &handMeshes));

    if (handMeshes.leftHandMesh.isActive) {
        // access vertex/index buffers for rendering.
    }

    // ...
    // Finish frame loop
    // ...
}

CHECK_XR(xrDestroyHandMeshTracker(handMeshTracker));

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

Hằng số enum mới

Bổ sung enum XrObjectType bằng:

  • XR_OBJECT_TYPE_HAND_MESH_TRACKER_ANDROID

Bổ sung enum XrStructureType:

  • XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_HAND_MESH_GET_INFO_ANDROID
  • XR_TYPE_HAND_TRACKING_MESHES_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 10 tháng 9 năm 2024 (Levana Chen)
    • Nội dung mô tả ban đầu của tiện ích