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

Строка имени

XR_ANDROID_hand_mesh

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

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

Зарегистрированный внутренний номер

704

Редакция

1

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

ОпенXR 1.0

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

10 сентября 2024 г.

IP-статус

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

Авторы

Нихав Джайн, 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 или указатель на следующую структуру в цепочке структур. Такие структуры не определены в ядре 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 , чтобы проверить, изменились ли значения с момента последнего кадра, и избежать ненужной обработки данных при отсутствии изменений.

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

  • Расширение XR_ANDROID_hand_mesh должно быть включено перед использованием XrHandMeshANDROID.
  • 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 г. (Левана Чен)
    • Первоначальное описание расширения