C Specification

A XrHandMeshVertexBufferMSFT structure includes an array of vertices of the hand mesh represented in the hand mesh space.

// Provided by XR_MSFT_hand_tracking_mesh
typedef struct XrHandMeshVertexBufferMSFT {
    XrTime                   vertexUpdateTime;
    uint32_t                 vertexCapacityInput;
    uint32_t                 vertexCountOutput;
    XrHandMeshVertexMSFT*    vertices;
} XrHandMeshVertexBufferMSFT;

Members

Member Descriptions

  • vertexUpdateTime is an XrTime representing the time when the runtime receives the vertex buffer content or 0 to indicate a request to retrieve latest vertices regardless of existing content in vertices.

  • vertexCapacityInput is a positive uint32_t describes the capacity of the vertices array.

  • vertexCountOutput is a uint32_t filled in by the runtime with the count of vertices written in vertices.

  • vertices is an array of XrHandMeshVertexMSFT filled in by the runtime, specifying the vertices of the hand mesh including the position and normal vector in the hand mesh space.

Description

An application should preallocate the vertices array using the maxHandMeshVertexCount in XrSystemHandTrackingMeshPropertiesMSFT returned from xrGetSystemProperties. In this way, the application can avoid possible insufficient buffer sizes for each query, and therefore avoid reallocating memory each frame.

The input vertexCapacityInput must not be 0, and vertices must not be NULL, or else the runtime must return XR_ERROR_VALIDATION_FAILURE on calls to the xrUpdateHandMeshMSFT function.

If the input vertexCapacityInput is not sufficient to contain all output vertices, the runtime must return XR_ERROR_SIZE_INSUFFICIENT on calls to the xrUpdateHandMeshMSFT, do not change content in vertexUpdateTime and vertices, and return 0 for vertexCountOutput.

If the input vertexCapacityInput is equal to or larger than the maxHandMeshVertexCount in XrSystemHandTrackingMeshPropertiesMSFT returned from xrGetSystemProperties, the runtime must not return XR_ERROR_SIZE_INSUFFICIENT on calls to the xrUpdateHandMeshMSFT because of insufficient vertex buffer size.

If the input vertexUpdateTime is 0, and the capacity of the vertices array is sufficient, and hand mesh tracking is active, the runtime must return the latest non-zero vertexUpdateTime, and fill in the vertexCountOutput and vertices fields.

If the input vertexUpdateTime is not 0, the runtime can either return without changing vertexCountOutput or the content in vertices, and return XR_FALSE for vertexBufferChanged indicating the vertices are not changed; or return a new non-zero vertexUpdateTime and fill in latest data in vertexCountOutput and vertices and return XR_TRUE for vertexBufferChanged indicating the vertices are updated to a newer version.

An application can keep the XrHandMeshVertexBufferMSFT structure for each frame in frame loop and use the returned vertexUpdateTime to detect the changes of the content in vertices. The application can therefore avoid unnecessary processing of vertices, such as coping them to GPU memory.

Valid Usage (Implicit)

See Also

XR_MSFT_hand_tracking_mesh, XrHandMeshMSFT, XrHandMeshVertexMSFT, XrSystemHandTrackingMeshPropertiesMSFT, XrTime, xrUpdateHandMeshMSFT

Document Notes

For more information, see the OpenXR Specification

This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2023 The Khronos Group Inc.

This work is licensed under a Creative Commons Attribution 4.0 International License.