XR_ANDROID_hand_mesh Расширение OpenXR

Имя Строка

XR_ANDROID_hand_mesh

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

704

Пересмотр

1

Зависимости расширений и версий

OpenXR 1.0

Дата последнего изменения

2024-09-10

Статус ИС

Нет известных претензий на права интеллектуальной собственности.

Участники

Нихав Джайн, Google

Керн Овертерф, Google

Спенсер Куин, Google

Левана Чен, Google

Обзор

Это расширение позволяет отслеживать положение руки, представляя ее в виде динамической сетки руки.

Это расширение предназначено для предоставления буферов вершин и индексов для сетки персонализированного представления рук пользователя. Его можно использовать для окклюзии и визуализации.

Это расширение не следует использовать для других целей отслеживания рук.

Данные отслеживания рук могут быть конфиденциальной личной информацией и тесно связаны с личной конфиденциальностью и целостностью. Настоятельно рекомендуется, чтобы приложения, которые хранят или передают данные отслеживания рук, всегда запрашивали у пользователя активное и конкретное согласие на это.

Проверить возможности системы

Приложение может проверить, способна ли система вручную отслеживать сетки, привязав структуру XrSystemHandMeshTrackingPropertiesANDROID к XrSystemProperties при вызове xrGetSystemProperties .

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

Описания участников

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.
  • supportsHandMeshTracking — это XrBool32 , указывающий, поддерживает ли выбранный XrSystemId отслеживание сетки руки.
  • supportsTextureUV — это XrBool32 , указывающий, поддерживает ли выбранный XrSystemId текстурные UV-координаты для вершин сетки.
  • supportsVertexNormal — это XrBool32 , указывающий, поддерживает ли выбранный XrSystemId нормали вершин для вершин сетки.

Приложение должно избегать использования возможностей сетки рук, когда supportsHandMeshTracking имеет значение XR_FALSE , поскольку это означает, что система не поддерживает отслеживание сетки рук. В этом случае xrCreateHandMeshTrackerANDROID вернет XR_ERROR_FEATURE_UNSUPPORTED .

Если supportsHandMeshTracking возвращает XR_TRUE , система поддерживает отслеживание сетки рук. Приложение должно использовать XrHandMeshANDROID::indexCount и XrHandMeshANDROID::vertexCount для доступа к буферам сетки рук и повторного использования их в своем цикле рендеринга при вызове xrGetHandMeshANDROID в каждом кадре.

Если supportsTextureUV возвращает XR_FALSE , система не поддерживает UV-развертки текстур для вершин сетки, и поэтому приложение получит XrHandMeshANDROID::textureUVs NULL при вызове xrGetHandMeshANDROID .

Если supportsVertexNormal возвращает XR_FALSE , система не поддерживает нормали вершин для вершин сетки, и поэтому приложение получит XrHandMeshANDROID::normals NULL при вызове xrGetHandMeshANDROID .

Допустимое использование (подразумеваемое)

Создайте ручку трекера сетки для рук 

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

Дескриптор XrHandMeshTrackerANDROID представляет собой трекер ручной сетки для отслеживания ручной сетки и управления соответствующими ресурсами.

Этот дескриптор можно использовать для доступа к буферам ручной сетки с использованием других функций этого расширения.

Приложение может создать дескриптор XrHandMeshTrackerANDROID с помощью функции xrCreateHandMeshTrackerANDROID .

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

Описание параметров

  • session — это XrSession , в котором будет активен трекер ручной сетки.
  • createInfo — это XrHandMeshTrackerCreateInfoANDROID , используемый для указания трекера сетки руки.
  • handMeshTracker — это возвращаемый дескриптор XrHandMeshTrackerANDROID .

Если система не поддерживает отслеживание сетки рук, xrCreateHandMeshTrackerANDROID вернет XR_ERROR_FEATURE_UNSUPPORTED .

Дескриптор XrHandMeshTrackerANDROID владеет всеми ресурсами для отслеживания сетки руки. После завершения отслеживания сетки руки приложение должно уничтожить дескриптор с помощью функции xrDestroyHandMeshTrackerANDROID .

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • 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

Структура XrHandMeshTrackerCreateInfoANDROID описывает информацию для создания дескриптора XrHandMeshTrackerANDROID .

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

Описания участников

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.

Допустимое использование (подразумеваемое)

Функция xrDestroyHandMeshTrackerANDROID освобождает handMeshTracker и базовые ресурсы после завершения отслеживания сетки рук.

XrResult xrDestroyHandMeshTrackerANDROID(
    XrHandMeshTrackerANDROID handMeshTracker);

Описание параметров

Допустимое использование (подразумеваемое)

Безопасность потока

  • Доступ к handMeshTracker и любым дочерним дескрипторам должен быть синхронизирован извне.

Коды возврата

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Найдите ручные сетки

Приложение может использовать функцию xrGetHandMeshANDROID для получения сетки руки в заданной временной метке. Положение вершин сетки руки и нормаль представлены в пространстве, указанном XrHandMeshGetInfoANDROID::baseSpace при вызове xrGetHandMeshANDROID .

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

Описание параметров

Приложение может использовать функцию xrGetHandMeshANDROID для доступа к буферам сетки рук, созданным средой выполнения.

Приложение должно вызвать xrBeginFrame хотя бы один раз в течение сеанса перед первым вызовом xrGetHandMeshANDROID .

Приложение должно использовать XrHandMeshANDROID::indexCount и XrHandMeshANDROID::vertexCount для доступа к буферам сетки рук и повторного использования их в цикле рендеринга при вызове xrGetHandMeshANDROID в каждом кадре.

Допустимое использование (подразумеваемое)

Коды возврата

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • 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 описывает информацию, необходимую для получения данных сетки руки.

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

Описания участников

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.
  • baseSpace — это XrSpace , определяющий опорное пространство, в котором следует разместить преобразование для вершин в time .
  • time — это XrTime , описывающее время, в которое приложение хочет запросить сетку руки.

Допустимое использование (подразумеваемое)

Структура XrHandTrackingMeshesANDROID содержит данные сетки для обеих рук.

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

Описания участников

  • type — XrStructureType этой структуры.
  • next — NULL или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре OpenXR или в этом расширении.
  • leftHandMesh — это XrHandMeshANDROID для левой руки.
  • rightHandMesh — это XrHandMeshANDROID для правой руки.

Допустимое использование (подразумеваемое)

Структура XrHandMeshANDROID содержит данные и буферы для получения данных отслеживания сетки руки от функции xrGetHandMeshANDROID для одной руки.

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;

Описания участников

  • type — XrStructureType этой структуры.
  • next является NULL или указателем на следующую структуру в цепочке структуры. Такие структуры не определены в Core OpenXR или в этом расширении.
  • isActive — это XrBool32 , указывающий, активен ли текущий трекер сетки руки и действительны ли данные сетки.
  • dynamicLastUpdateTime — это XrTime , указывающий время последнего обновления динамических буферов.
  • indexCount — это uint32_t , служащий числом indices сетки руки.
  • vertexCount — это uint32_t , служащий числом positions сетки руки. Его также можно использовать для textureUVs или normals если они поддерживаются системой.
  • indices — это массив uint32_t , представляющий индексы сетки для треугольников в порядке намотки против часовой стрелки. Количество значений, на которые указывает indexCount .
  • textureUVs — это NULL или массив XrVector2f , представляющий координаты текстуры вершин. Количество значений, на которые указывает, — vertexCount .
  • positions — это массив XrVector3f , представляющий позиции вершин в baseSpaceFromVertexSpace . Количество значений, на которые указывает, — vertexCount .
  • normals — это NULL или массив XrVector3f , представляющий нормали вершин в baseSpaceFromVertexSpace . Количество значений, на которые указывает, — vertexCount .
  • baseSpaceFromVertexSpace — это вершина XrSpace , расположенная в XrHandMeshGetInfoANDROID::baseSpace при вызове xrGetHandMeshANDROID . Приложения могут использовать это для преобразования координатного пространства вершин сетки и нормалей во время рендеринга.

Сетка руки представлена ​​в виде списков треугольников, и вершины каждого треугольника расположены в порядке против часовой стрелки, если смотреть снаружи руки.

Если возвращаемое значение isActive равно XR_FALSE , это означает, что рука не отслеживается активно; например, рука находится за пределами диапазона датчика, фокус ввода удален из приложения или у приложения нет разрешений на доступ к данным отслеживания руки.

Если возвращаемое значение isActive равно XR_TRUE , сетка отслеживания руки, представленная в indices и positions , включая textureUVs и normals , если они поддерживаются системой, обновляются в соответствии с последними данными XrHandMeshGetInfoANDROID::time, предоставленными функции xrGetHandMeshANDROID .

Память, на которую указывают буферы сетки рук, возвращаемые в XrHandMeshANDROID , принадлежит среде выполнения и используется совместно с приложением. Доступ к памяти безопасен из любого потока до следующего вызова xrBeginFrame , пока дескриптор XrHandMeshTrackerANDROID действителен.

  • Значения, на которые указывают indices и textureUVs не являются динамическими.
  • Указатель и значения, на которые указывают positions и normals являются динамическими , и оба могут изменяться между вызовами xrBeginFrame . Приложение может использовать dynamicLastUpdateTime для проверки того, изменились ли значения с момента последнего кадра, и избежать ненужной обработки данных, когда нет никаких изменений.

Допустимое использование (подразумеваемое)

  • Перед использованием XrHandMeshANDROID необходимо включить расширение XR_ANDROID_hand_mesh
  • indices должны быть указателями на допустимое значение uint32_t
  • textureUVs должен быть указателем на допустимую структуру XrVector2f
  • positions должен быть указателем на допустимую структуру XrVector3f
  • normals должны быть указателем на допустимую структуру XrVector3f

Пример кода для отслеживания сетки рук

В следующем примере кода показано, как получить доступ к буферам сетки рук для рендеринга. 

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

Новые типы объектов

Новые константы перечисления

Перечисление XrObjectType расширено с помощью:

  • XR_OBJECT_TYPE_HAND_MESH_TRACKER_ANDROID

Перечисление 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

Новые перечисления

Новые структуры

Новые функции

Проблемы

История версий

  • Редакция 1, 10 сентября 2024 г. (Левана Чен)
    • Первоначальное описание расширения

OpenXR™ и логотип OpenXR являются товарными знаками компании Khronos Group Inc. и зарегистрированы в качестве товарного знака в Китае, Европейском Союзе, Японии и Великобритании.