XR_ANDROID_hand_mesh OpenXR 확장 프로그램

이름 문자열

XR_ANDROID_hand_mesh

확장 프로그램 유형

인스턴스 연장

등록된 부속 번호

704

버전

1

확장 프로그램 및 버전 종속 항목

OpenXR 1.0

최종 수정일

2024-09-10

IP 상태

알려진 IP 소유권 주장이 없습니다.

도움을 주신 분들

니하브 자인, Google

케인 오버터프, Google

스펜서 퀸, Google

레바나 첸, Google

개요

이 확장 프로그램은 동적 손 메시로 표시되는 손 추적을 사용 설정합니다.

이 확장 프로그램은 사용자 손의 맞춤 표현 메시지에 대한 정점 및 색인 버퍼를 제공하기 위한 것입니다. 가림 및 시각화에 사용할 수 있습니다.

이 확장 프로그램은 다른 손 추적 목적으로 사용해서는 안 됩니다.

손 추적 데이터는 민감한 개인 정보가 될 수 있으며 개인 정보 보호 및 무결성과 밀접하게 연결되어 있습니다. 손 동작 추적 데이터를 저장하거나 전송하는 애플리케이션은 항상 사용자에게 이를 수락하도록 적극적으로 요청하는 것이 좋습니다.

시스템 기능 검사

애플리케이션은 xrGetSystemProperties를 호출할 때 XrSystemHandMeshTrackingPropertiesANDROID 구조를 XrSystemProperties에 연결하여 시스템이 손 추적 메시를 처리할 수 있는지 검사할 수 있습니다.

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

회원 설명

  • type은 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다. 핵심 OpenXR 또는 이 확장 프로그램에는 이러한 구조가 정의되어 있지 않습니다.
  • supportsHandMeshTracking는 선택한 XrSystemId가 손 메시 추적을 지원하는지 나타내는 XrBool32입니다.
  • supportsTextureUV는 선택한 XrSystemId가 메시 정점의 텍스처 UV를 지원하는지 나타내는 XrBool32입니다.
  • supportsVertexNormal는 선택한 XrSystemId가 메시 꼭지점의 꼭지점 법선을 지원하는지 여부를 나타내는 XrBool32입니다.

supportsHandMeshTracking이 XR_FALSE인 경우 시스템에서 손 메시 추적을 지원하지 않으므로 애플리케이션은 손 메시 기능을 사용하지 않아야 합니다. 이 경우 xrCreateHandMeshTrackerANDROID는 XR_ERROR_FEATURE_UNSUPPORTED를 반환합니다.

supportsHandMeshTracking가 XR_TRUE를 반환하면 시스템에서 손 메시 추적을 지원합니다. 애플리케이션은 프레임마다 xrGetHandMeshANDROID를 호출할 때 XrHandMeshANDROID::indexCount 및 XrHandMeshANDROID::vertexCount를 사용하여 손 메시 버퍼에 액세스하고 렌더링 루프에서 재사용해야 합니다(MUST).

supportsTextureUV가 XR_FALSE를 반환하면 시스템에서 메시 꼭짓점의 텍스처 UV를 지원하지 않으므로 애플리케이션은 xrGetHandMeshANDROID를 호출할 때 XrHandMeshANDROID::textureUVs NULL를 수신합니다.

supportsVertexNormal가 XR_FALSE를 반환하면 시스템에서 메시 정점의 정점 노멀을 지원하지 않으므로 애플리케이션은 xrGetHandMeshANDROID를 호출할 때 XrHandMeshANDROID::normals NULL를 수신합니다.

유효한 사용 (암시적)

손 메시 위치 추적기 핸들 만들기

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

XrHandMeshTrackerANDROID 핸들은 손 메시 추적 및 관련 리소스 관리를 위한 손 메시 추적기를 나타냅니다.

이 핸들은 이 확장 프로그램의 다른 함수를 사용하여 손 메시 버퍼에 액세스하는 데 사용할 수 있습니다.

애플리케이션은 xrCreateHandMeshTrackerANDROID 함수를 사용하여 XrHandMeshTrackerANDROID 핸들을 만들 수 있습니다. 

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

매개변수 설명

시스템에서 손 메시 추적을 지원하지 않으면 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 함수를 사용하여 지정된 타임스탬프의 손 메시를 검색할 수 있습니다. 손 메시의 정점 위치와 법선은 xrGetHandMeshANDROID를 호출할 때 XrHandMeshGetInfoANDROID::baseSpace에 지정된 공간에 표시됩니다.

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

매개변수 설명

애플리케이션은 xrGetHandMeshANDROID 함수를 사용하여 런타임에서 생성된 손 메시 버퍼에 액세스할 수 있습니다.

애플리케이션은 xrGetHandMeshANDROID를 처음 호출하기 전에 세션 중에 xrBeginFrame을 한 번 이상 호출해야 합니다.

애플리케이션은 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는 time에서 정점의 변환을 찾을 참조 공간을 정의하는 XrSpace입니다.
  • time는 애플리케이션이 손 메시지를 쿼리하려는 시간을 설명하는 XrTime입니다.

유효한 사용 (암시적)

  • XrHandMeshGetInfoANDROID를 사용하기 전에 XR_ANDROID_hand_mesh 확장 프로그램을 사용 설정해야 합니다.
  • type는 XR_TYPE_HAND_MESH_GET_INFO_ANDROID여야 합니다.
  • next는 NULL이거나 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
  • baseSpace는 유효한 XrSpace 핸들여야 합니다.

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는 손 메시의 indices 수 역할을 하는 uint32_t입니다.
  • vertexCount는 손 메시의 positions 수 역할을 하는 uint32_t입니다. 시스템에서 지원하는 경우 textureUVs 또는 normals에도 사용할 수 있습니다.
  • indices는 시계 반대 방향 와인더 순서로 삼각형의 메시 색인을 나타내는 uint32_t 배열입니다. 가리키는 값의 수는 indexCount입니다.
  • textureUVs는 정점 텍스처 좌표를 나타내는 NULL 또는 XrVector2f 배열입니다. 가리키는 값의 수는 vertexCount입니다.
  • positions는 baseSpaceFromVertexSpace의 꼭짓점 위치를 나타내는 XrVector3f 배열입니다. 가리키는 값의 수는 vertexCount입니다.
  • normals는 baseSpaceFromVertexSpace의 정점 법선을 나타내는 NULL 또는 XrVector3f 배열입니다. 가리키는 값의 수는 vertexCount입니다.
  • baseSpaceFromVertexSpace는 xrGetHandMeshANDROID를 호출할 때 XrHandMeshGetInfoANDROID::baseSpace에 있는 꼭짓점 XrSpace입니다. 애플리케이션은 이를 사용하여 렌더링 중에 메시 정점과 법선의 좌표 공간을 변환할 수 있습니다.

시곗바늘 메시는 삼각형 목록으로 표시되며 시곗바늘 외부에서 볼 때 각 삼각형의 꼭짓점은 시계 반대 방향 순서입니다.

반환된 isActive 값이 XR_FALSE이면 손이 활발하게 추적되지 않고 있음을 나타냅니다. 예를 들어 손이 센서의 범위를 벗어나거나 입력 포커스가 애플리케이션에서 사라졌거나 애플리케이션에 손 추적 데이터에 액세스할 권한이 없는 경우입니다.

반환된 isActive 값이 XR_TRUE이면 시스템에서 지원하는 경우 textureUVs 및 normals를 포함하여 indices 및 positions에 표시된 손 추적 메시지가 xrGetHandMeshANDROID 함수에 제공된 XrHandMeshGetInfoANDROID::time의 최신 데이터로 업데이트됩니다.

XrHandMeshANDROID에서 반환된 손 메시 버퍼가 가리키는 메모리는 런타인이 소유하고 애플리케이션과 공유됩니다. XrHandMeshTrackerANDROID 핸들이 유효한 동안에는 다음 xrBeginFrame 호출 시까지 모든 스레드에서 메모리에 안전하게 액세스할 수 있습니다.

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

새로운 객체 유형

새로운 enum 상수

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

새로운 enum

새로운 구조

새로운 함수

문제

버전 기록

  • 버전 1, 2024년 9월 10일 (레바나 첸)
    • 초기 확장 프로그램 설명