XR_ANDROID_hand_mesh OpenXR 拡張機能

Name String

XR_ANDROID_hand_mesh

拡張機能の種類

インスタンスの拡張

登録されている電話番号

704

リビジョン

1

拡張機能とバージョンの依存関係

OpenXR 1.0

最終更新日

2024-09-10

IP ステータス

既知の IP に関する申し立てはありません。

寄与者

Nihav Jain、Google

Cairn Overturf、Google

Spencer Quin、Google

Levana Chen、Google

概要

この拡張機能を使用すると、動的なハンドメッシュとして表示されるハンド トラッキングが可能になります。

この拡張機能は、ユーザーの手のパーソナライズされた表現のメッシュに頂点バッファとインデックス バッファを提供することを目的としています。オクルージョンと可視化に使用できます。

この拡張機能は、他の手トラッキング目的には使用しないでください。

ハンド トラッキング データは機密性の高い個人情報であり、個人のプライバシーと完全性と密接に関連しています。ハンド トラッキング データを保存または転送するアプリでは、必ずユーザーにアクティブで明確な同意を求めることを強くおすすめします。

システムの機能を確認する

アプリは、xrGetSystemProperties を呼び出すときに XrSystemHandMeshTrackingPropertiesANDROID 構造を XrSystemProperties に連結することで、システムがハンド トラッキング メッシュに対応しているかどうかを検査できます。

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 をサポートしていないため、アプリは 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 を初めて呼び出す前に、セッション中に少なくとも 1 回 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 です。

有効な使用方法（暗黙的）

XrHandTrackingMeshesANDROID 構造体には、両手のメッシュデータが含まれています。

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、そのような構造は定義されていません。
  • leftHandMesh は左手の XrHandMeshANDROID です。
  • rightHandMesh は、右手の XrHandMeshANDROID です。

有効な使用方法（暗黙的）

XrHandMeshANDROID 構造体には、1 つの手に対して 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 の場合、indices と positions で表されるハンド トラッキング メッシュ（システムでサポートされている場合の textureUVs と normals を含む）は、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));

新しいオブジェクト タイプ

新しい列挙型定数

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、2024 年 9 月 10 日（Levana Chen）
    • 最初の拡張機能の説明