XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

拡張機能の種類

インスタンス拡張

登録済みの内線番号

719

リビジョン

3

承認ステータス

未批准

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

OpenXR 1.0

最終更新日

2025-05-15

IP ステータス

既知の IP 申し立てはありません。

寄与者

Spencer Quin、Google
Jared Finder、Google
Antonio Fontan、Google
Cairn Overturf、Google
Nihav Jain、Google
Salar Khan、Google
Sebastian Klose、Google
Jürgen Sturm、Google
Vinny DaSilva、Google
Ricardo Campbell、Google

概要

この拡張機能は、ユーザーの環境内の物理オブジェクトをほぼ表すメッシュを提供することを目的としています。

アプリは、この拡張機能を使用してシーンを可視化し、仮想オブジェクトを物理オブジェクトと相互作用（衝突など）させることができます。

シーンメッシュ データはランタイムによって生成され、XrSceneMeshingTrackerANDROID と XrSceneMeshSnapshotANDROID を使用してアプリと共有されます。アプリケーションは、xrGetAllSubmeshStatesANDROID から返される XrSceneSubmeshStateANDROID を介して、シーンのサブメッシュ情報内の値にアクセスできます。アプリケーションは、xrGetSubmeshDataANDROID から返される XrSceneSubmeshDataANDROID を介して、シーンのサブメッシュ データ内の値にアクセスできます。

シーン メッシュデータは機密性の高い個人情報であり、個人のプライバシーと完全性に密接に関連しています。シーン メッシュデータを保存または転送するアプリでは、ユーザーに明示的かつ具体的な同意を求めることを強くおすすめします。

権限

Android アプリのマニフェストには、android.permission.SCENE_UNDERSTANDING_FINE 権限が記載されている必要があります。android.permission.SCENE_UNDERSTANDING_FINE 権限は、ランタイムがユーザー環境を調査できるようにするため、機密情報に関わる権限と見なされます。

アプリは、これらの関数を使用するために、実行時に権限をリクエストしなければなりません。

• xrCreateSceneMeshingTrackerANDROID
• xrDestroySceneMeshingTrackerANDROID
• xrCreateSceneMeshSnapshotANDROID
• xrDestroySceneMeshSnapshotANDROID
• xrGetAllSubmeshStatesANDROID
• xrGetSubmeshDataANDROID

（保護レベル: dangerous）

システム機能を検査する

XrSystemSceneMeshingPropertiesANDROID 構造体は次のように定義されます。

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• supportsSceneMeshing は XrBool32 で、システムがシーン メッシュをサポートしているかどうかを示します。

アプリケーションは、xrGetSystemProperties を呼び出すときに XrSystemSceneMeshingPropertiesANDROID 構造体を XrSystemProperties にチェーンすることで、システムがシーン メッシュに対応しているかどうかを検査できます。

ランタイムが supportsSceneMeshing に対して XR_FALSE を返す場合、システムはシーン メッシュをサポートしていないため、xrCreateSceneMeshingTrackerANDROID から XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。supportsSceneMeshing が XR_FALSE の場合、アプリはシーン メッシュ機能の使用を避けるべきです。

ランタイムが supportsSceneMeshing に対して XR_TRUE を返す場合、システムはシーン メッシュ生成をサポートしています。

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

• XR_ANDROID_scene_meshing 拡張機能は、XrSystemSceneMeshingPropertiesANDROID を使用する前に有効にする必要があります。
• type は XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

XrSceneMeshSemanticLabelSetANDROID 列挙型は、シーン メッシュのセマンティック ラベルセットを記述します。この列挙型の各値は、セマンティック ラベルを含む別の列挙型を表します。たとえば、XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID 値は XrSceneMeshSemanticLabelANDROID セットを表します。

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID = 1000801000,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

列挙値の意味は次のとおりです。

列挙型の説明

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

このセマンティック ラベルセットは、セマンティック ラベルがないことを表します。

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

このセマンティック ラベルセットは XrSceneMeshSemanticLabelANDROID を表します。

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

このセマンティック ラベルセットは XrSceneMeshSemanticLabel2ANDROID を表します。（XR_ANDROID_scene_meshing_semantic_label2 拡張機能によって追加）

xrEnumerateSupportedSemanticLabelSetsANDROID 関数は次のように定義されます。

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

パラメータの説明

• instance は、アプリケーションによって作成された XrInstance です。
• systemId は、xrGetSystem から再試行された XrSystemId です。
• supportedSemanticLabelSetsInputCapacity は supportedSemanticLabelSets の容量です。必要な容量を取得する場合は 0 にします。
• supportedSemanticLabelSetsOutputCount は、書き込まれた supportedSemanticLabelSets の数へのポインタ、または supportedSemanticLabelSetsInputCapacity が不十分な場合は必要な容量へのポインタです。
• supportedSemanticLabelSets は、XrSceneMeshSemanticLabelSetANDROID の配列へのポインタです。supportedSemanticLabelSetsInputCapacity が 0 の場合、NULL になることがあります。
• 必要な supportedSemanticLabelSets サイズの取得方法の詳細については、バッファサイズ パラメータの章をご覧ください。

アプリは、xrEnumerateSupportedSemanticLabelSetsANDROID 関数を使用して、システムでサポートされているセマンティック ラベルセットを列挙しても構いません。

この列挙値は、セマンティック ラベルセットがないことを表し、アプリケーションが頂点セマンティクスを必要としない場合に使用できるため、すべてのシステムは少なくとも XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID をサポートしなければなりません。

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

• XR_ANDROID_scene_meshing 拡張機能は、xrEnumerateSupportedSemanticLabelSetsANDROID を呼び出す前に有効にする必要があります。
• instance は、有効な XrInstance ハンドルでなければなりません。
• supportedSemanticLabelSetsOutputCount は uint32_t 値へのポインタでなければなりません
• supportedSemanticLabelSetsInputCapacity が 0 でない場合、supportedSemanticLabelSets は supportedSemanticLabelSetsInputCapacity 個の XrSceneMeshSemanticLabelSetANDROID 値の配列へのポインタでなければなりません

戻りコード

成功

• XR_SUCCESS

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SYSTEM_INVALID
• XR_ERROR_VALIDATION_FAILURE

シーン メッシュ トラッカー ハンドルを作成する

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

XrSceneMeshingTrackerANDROID ハンドルは、シーン メッシュと関連リソースの管理を行うシーン メッシュ トラッカーを表します。

このハンドルは、この拡張機能の xrCreateSceneMeshSnapshotANDROID を使用してシーンメッシュ スナップショットを作成するために使用できます。

xrCreateSceneMeshingTrackerANDROID 関数は次のように定義されます。

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

パラメータの説明

• session は、シーン メッシュ トラッカーがアクティブになる XrSession です。
• createInfo は、作成するシーン メッシュ トラッカーを記述するために使用される XrSceneMeshingTrackerCreateInfoANDROID 構造体へのポインタです。
• tracker は、返された XrSceneMeshingTrackerANDROID ハンドルです。

アプリケーションは、xrCreateSceneMeshingTrackerANDROID 関数を使用して XrSceneMeshingTrackerANDROID ハンドルを作成できます。

システムがシーン メッシュをサポートしていない場合、ランタイムは xrCreateSceneMeshingTrackerANDROID から XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。この場合、ランタイムは、xrGetSystemProperties 関数が呼び出されたときに、XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing に対して XR_FALSE を返さなければなりません。これにより、アプリはシーン メッシュ トラッカーの作成を回避できます。

アプリケーションは、シーン メッシュ トラッカーを作成する際に、XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet でシステムがサポートするセマンティック ラベルセットのみを使用する必要があります。アプリがサポートされていないシーンメッシュ頂点セマンティック ラベルセットを使用している場合、ランタイムは xrCreateSceneMeshingTrackerANDROID から XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。

アプリは、xrEnumerateSupportedSemanticLabelSetsANDROID 関数を使用して、サポートされているセマンティック ラベルセットのリストを列挙できます。

xrCreateSceneMeshingTrackerANDROID ハンドルは、シーン メッシュ生成のすべてのリソースを所有します。シーン メッシュ エクスペリエンスが終了したら、アプリケーションは xrDestroySceneMeshingTrackerANDROID 関数を介してハンドルを破棄しなければなりません。

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

• XR_ANDROID_scene_meshing 拡張機能は、xrCreateSceneMeshingTrackerANDROID を呼び出す前に有効にする必要があります。
• session は、有効な XrSession ハンドルでなければなりません。
• createInfo は、有効な XrSceneMeshingTrackerCreateInfoANDROID 構造体へのポインタでなければなりません。
• tracker は、XrSceneMeshingTrackerANDROID ハンドルへのポインタでなければなりません

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FEATURE_UNSUPPORTED
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

XrSceneMeshingTrackerCreateInfoANDROID 構造体は次のように定義されます。

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• semanticLabelSet は、シーン メッシュに使用するセマンティック ラベルセットを指定するために使用される XrSceneMeshSemanticLabelSetANDROID です。これが XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID に設定されている場合、ランタイムは XrSceneSubmeshDataANDROID :: vertexSemantics バッファフィールドを無視します。
• enableNormals は、シーンのメッシュデータを取得するときに、シーンのメッシュ バッファにメッシュ頂点の頂点法線を含めるかどうかを指定するために使用される XrBool32 です。

XrSceneMeshingTrackerCreateInfoANDROID 構造体は、XrSceneMeshingTrackerANDROID ハンドルを作成するための情報を記述します。

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

• XrSceneMeshingTrackerCreateInfoANDROID を使用する前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• type は XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
• semanticLabelSet は、有効な XrSceneMeshSemanticLabelSetANDROID 値でなければ

xrDestroySceneMeshingTrackerANDROID 関数は次のように定義されます。

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

パラメータの説明

• tracker は、以前に xrCreateSceneMeshingTrackerANDROID によって作成された XrSceneMeshingTrackerANDROID です。

xrDestroySceneMeshingTrackerANDROID 関数は、シーン メッシュ エクスペリエンスが終了すると、tracker と基盤となるリソースを解放します。

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

• xrDestroySceneMeshingTrackerANDROID を呼び出す前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• tracker は、有効な XrSceneMeshingTrackerANDROID ハンドルでなければなりません

スレッドセーフ

• tracker とその子ハンドルへのアクセスは、外部で同期する必要があります。

戻りコード

成功

• XR_SUCCESS

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

シーンメッシュ スナップショット ハンドルを作成する

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

XrSceneMeshSnapshotANDROID ハンドルは、シーンメッシュ スナップショットを表します。このスナップショットは、xrCreateSceneMeshSnapshotANDROID を使用して作成されます。この関数は、関数呼び出し時のシーンメッシュ データのスナップショットを取得します。

このハンドルは、xrGetAllSubmeshStatesANDROID と xrGetSubmeshDataANDROID を使用してサブメッシュの情報とデータを取得するために使用できます。

xrCreateSceneMeshSnapshotANDROID 関数は次のように定義されます。

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

パラメータの説明

• tracker は、以前に xrCreateSceneMeshingTrackerANDROID で作成された XrSceneMeshingTrackerANDROID ハンドルです。
• createInfo は、シーンメッシュ スナップショットの作成に必要な情報を含む XrSceneMeshSnapshotCreateInfoANDROID 構造体へのポインタです。
• outSnapshotCreationResult は、XrSceneMeshSnapshotCreationResultANDROID オブジェクトへのポインタです。このオブジェクトには、ランタイムによってスナップショット作成結果が入力されます。

アプリケーションは、xrCreateSceneMeshSnapshotANDROID 関数を使用して、シーン メッシュ トラッカーからシーン メッシュ スナップショットを作成できます。この関数は、XrSceneMeshSnapshotANDROID ハンドルと、XrSceneMeshSnapshotCreationResultANDROID 構造体にラップされた XrSceneMeshTrackingStateANDROID を返します。ハンドルは、技術的には作成時のシーンメッシュ データのスナップショットです。このハンドルは、xrGetAllSubmeshStatesANDROID と xrGetSubmeshDataANDROID をそれぞれ使用して、シーンメッシュの情報とデータをクエリするために使用できます。

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

• xrCreateSceneMeshSnapshotANDROID を呼び出す前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• tracker は、有効な XrSceneMeshingTrackerANDROID ハンドルでなければなりません
• createInfo は、有効な XrSceneMeshSnapshotCreateInfoANDROID 構造体へのポインタでなければなりません。
• outSnapshotCreationResult は XrSceneMeshSnapshotCreationResultANDROID 構造体へのポインタでなければなりません。

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_POSE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID

XrSceneMeshSnapshotCreateInfoANDROID 構造体は次のように定義されます。

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• baseSpace は、シーンのサブメッシュのポーズ情報が表される XrSpace です。
• time は、シーンメッシュが処理または表示される時間を記述する XrTime です。通常は XrFrameState :: predictedDisplayTime です。
• boundingBox は、シーンメッシュを取得する境界ボックスを記述する XrBoxf です。

XrSceneMeshSnapshotCreateInfoANDROID 構造体は、XrSceneMeshSnapshotANDROID ハンドルを作成するための情報を記述します。

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

• XrSceneMeshSnapshotCreateInfoANDROID を使用する前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• type は XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
• baseSpace は有効な XrSpace ハンドルでなければなりません

XrSceneMeshSnapshotCreationResultANDROID 構造体は次のように定義されます。

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• snapshot は、ランタイムによって作成された XrSceneMeshSnapshotANDROID ハンドルです。
• trackingState は、スナップショット作成時のシーン メッシュ トラッカーの状態を表す XrSceneMeshTrackingStateANDROID です。

XrSceneMeshSnapshotCreationResultANDROID 構造体には、xrCreateSceneMeshSnapshotANDROID から返されたシーンメッシュ スナップショットの作成結果が格納されます。

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

• XrSceneMeshSnapshotCreationResultANDROID を使用する前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• type は XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
• snapshot は、有効な XrSceneMeshSnapshotANDROID ハンドルでなければ
• trackingState は、有効な XrSceneMeshTrackingStateANDROID 値でなければなりません。

XrSceneMeshTrackingStateANDROID 列挙型は、シーン メッシュ トラッカーのトラッキング状態を表します。この列挙型の各値は、シーン メッシュ トラッカーの状態を表します。

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

列挙値の意味は次のとおりです。

列挙型の説明

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

トラッカーは、メッシュデータを提供する準備がまだできていません。

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

アクティビティ トラッカーがアクティブにトラッキングしている。

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

トラッカーは、前回のメッシュ更新以降に統合する有効な測定値を待機しています。

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

トラッカーが複数のサイクルで有効な測定値を受信しておらず、エラー状態になっています。

この状態は、アプリケーションへの追加情報としてのみ機能します。他のエラーの原因がない場合、ランタイムは、トラッカーの現在の XrSceneMeshTrackingStateANDROID に関係なく、アプリケーションがスナップショットを作成してそこからデータを取得できるようにしなければなりません。状態が XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID でない場合、スナップショットが最新でないか、空である可能性があります。

シーンメッシュ スナップショットからシーンメッシュ データを取得する

xrGetAllSubmeshStatesANDROID 関数は次のように定義されます。

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

パラメータの説明

• snapshot は、以前に xrCreateSceneMeshSnapshotANDROID で作成された XrSceneMeshSnapshotANDROID ハンドルです。
• submeshStateCapacityInput は submeshStates の容量です。必要な容量を取得する場合は 0 にします。
• submeshStateCountOutput は、書き込まれた submeshStates の数へのポインタ、または submeshStateCapacityInput が不十分な場合は必要な容量へのポインタです。
• submeshStates は、XrSceneSubmeshStateANDROID 構造体の配列へのポインタです。ランタイムは、この配列にシーンメッシュ内のすべてのサブメッシュの状態を出力します。submeshStateCapacityInput が 0 の場合、NULL になることがあります。
• 必要な submeshStates サイズの取得方法の詳細については、バッファサイズ パラメータの章をご覧ください。

アプリは、xrGetAllSubmeshStatesANDROID 関数を使用して、シーンメッシュ内のすべてのサブメッシュの状態を取得できます。これには、アプリケーションがデータを必要とするサブメッシュを選択できるようにするための基本情報が含まれています。

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

• xrGetAllSubmeshStatesANDROID を呼び出す前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• snapshot は、有効な XrSceneMeshSnapshotANDROID ハンドルでなければ
• submeshStateCountOutput は uint32_t 値へのポインタでなければなりません
• submeshStateCapacityInput が 0 でない場合、submeshStates は submeshStateCapacityInput XrSceneSubmeshStateANDROID 構造の配列へのポインタでなければなりません。

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_VALIDATION_FAILURE

XrSceneSubmeshStateANDROID 構造体は次のように定義されます。

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• submeshId は、サブメッシュを識別する XrUuid です。
• lastUpdatedTime は、サブメッシュが最後に更新された時刻を表す XrTime です。
• submeshPoseInBaseSpace は、シーンメッシュ スナップショットの作成に使用されるベース空間内のサブメッシュのポーズを表す XrPosef です。ポーズは、サブメッシュ境界ボックスの中心でもあります。
• bounds は、サブメッシュを囲む境界ボックスの寸法を記述する XrExtent3Df です。この境界は、シーンメッシュ ハンドルの作成に使用されたベース空間で定義されます。

ランタイムは、submeshId をサブメッシュが占有する物理空間のリージョンにマッピングするよう最善を尽くします。ランタイムは、このマッピングをいつでも失い、検出されたサブメッシュのサブセットに新しい UUID を割り当てることがあります。特に、ランタイムは、後続のアプリケーション インスタンスで同じメッシュに同じ UUID を再利用する必要はありません。

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

• XrSceneSubmeshStateANDROID を使用する前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• type は XR_TYPE_SCENE_SUBMESH_STATE_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

xrGetSubmeshDataANDROID 関数は次のように定義されます。

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

パラメータの説明

• snapshot は、以前に xrCreateSceneMeshSnapshotANDROID で作成された XrSceneMeshSnapshotANDROID ハンドルです。
• submeshDataCount は inoutSubmeshData の長さです。
• inoutSubmeshData は、アプリケーションによって割り当てられた XrSceneSubmeshDataANDROID の配列です。ランタイムは、XrSceneSubmeshDataANDROID :: submeshId で渡されたサブメッシュ ID に関連付けられたメッシュデータを使用して、各要素に値を入力します。

アプリは、xrGetSubmeshDataANDROID 関数を使用して、サブメッシュのバッチまたはすべてのサブメッシュを一度に取得できます。そのためには、XrSceneSubmeshDataANDROID のリストを渡し、各 XrSceneSubmeshDataANDROID :: submeshId を、取得するサブメッシュのそれぞれの ID に設定します。

XrSceneSubmeshDataANDROID :: submeshId は、inoutSubmeshData のすべての要素で一意でなければならず、同じ snapshot の xrGetAllSubmeshStatesANDROID で取得可能でなければなりません。サブメッシュ ID が無効な場合、または inoutSubmeshData 内の複数の要素に同じサブメッシュ ID がある場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

submeshDataCount は、xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput によって返される値以下でなければなりません。そうでない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

これは、選択したすべてのサブメッシュの頂点数とインデックス数をクエリする 2 コール イディオムで使用できます。

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

• XR_ANDROID_scene_meshing 拡張機能は、xrGetSubmeshDataANDROID を呼び出す前に有効にする必要があります。
• snapshot は、有効な XrSceneMeshSnapshotANDROID ハンドルでなければ
• inoutSubmeshData は、submeshDataCount XrSceneSubmeshDataANDROID 構造体の配列へのポインタでなければなりません
• submeshDataCount パラメータは 0 より大きい値にする必要があります。

戻りコード

成功

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_VALIDATION_FAILURE

XrSceneSubmeshDataANDROID 構造体は次のように定義されます。

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

メンバーの説明

• type は、この構造の XrStructureType です。
• next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
• submeshId は、サブメッシュを識別する XrUuid です。
• vertexCapacityInput は、vertexPositions、vertexNormals、vertexSemantics の容量、または必要な容量を取得する場合は 0 です。
• vertexCountOutput は、書き込まれた vertexPositions、vertexNormals、vertexSemantics の数へのポインタ、または vertexCapacityInput が不十分な場合は必要な容量へのポインタです。
• vertexPositions は XrVector3f の配列で、ランタイムはこれにサブメッシュの頂点位置を出力します。
• vertexNormals は XrVector3f の配列で、ランタイムはここにサブメッシュの頂点法線を出力します。アプリケーションが法線を無効にしてトラッカーを作成した場合、このフィールドは NULL のままにできます。
• vertexSemantics は uint8_t の配列で、ランタイムはサブメッシュの頂点セマンティクスをこの配列に出力します。アプリケーションが XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID セマンティック ラベルセットを使用してトラッカーを作成した場合、このフィールドは NULL のままにできます。
• indexCapacityInput は indices の容量です。必要な容量を取得する場合は 0 にします。
• indexCountOutput は、書き込まれた indices の数へのポインタ、または vertexCapacityInput が不十分な場合は必要な容量へのポインタです。
• indices は、ランタイムがサブメッシュのインデックスを出力する uint32_t の配列です。
• 必要な vertexPositions、vertexNormals、vertexSemantics、indices のサイズを取得する方法の詳細については、バッファサイズ パラメータの章をご覧ください。

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

• XrSceneSubmeshDataANDROID を使用する前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• type は XR_TYPE_SCENE_SUBMESH_DATA_ANDROID にする必要があります。
• next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
• vertexCapacityInput が 0 でない場合、vertexPositions は vertexCapacityInput XrVector3f 構造体の配列へのポインタでなければなりません。
• vertexCapacityInput が 0 でない場合、vertexNormals は vertexCapacityInput XrVector3f 構造体の配列へのポインタでなければなりません。
• vertexCapacityInput が 0 でない場合、vertexSemantics は vertexCapacityInput uint8_t 値の配列へのポインタでなければなりません。
• indexCapacityInput が 0 でない場合、indices は indexCapacityInput uint32_t 値の配列へのポインタでなければなりません。

XrSceneMeshSemanticLabelANDROID 列挙型は、メッシュ頂点にラベルを付けるために使用できるセマンティック ラベルのデフォルト セットです。これにより、メッシュ頂点がどの物理環境サーフェス上にあるかを記述できます。この列挙型セットは、XrSceneMeshSemanticLabelSetANDROID の XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID 値で表されます。

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

列挙型の意味は次のとおりです。

列挙型の説明

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

このセマンティック ラベルは、対応するメッシュ要素が不明なオブジェクトを表していることを示します。

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

このセマンティック ラベルは、対応するメッシュ要素が床を表していることを示します。

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

このセマンティック ラベルは、対応するメッシュ要素が天井を表していることを示します。

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

このセマンティック ラベルは、対応するメッシュ要素が壁を表していることを示します。

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

このセマンティック ラベルは、対応するメッシュ要素がテーブルを表していることを示します。

シーンメッシュ スナップショットを破棄する

xrDestroySceneMeshSnapshotANDROID 関数は次のように定義されます。

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

パラメータの説明

• snapshot は、以前に xrCreateSceneMeshSnapshotANDROID で作成された XrSceneMeshSnapshotANDROID ハンドルで、この関数によって破棄されます。

アプリは、xrDestroySceneMeshSnapshotANDROID 関数を使用して、シーンメッシュ スナップショットを破棄できます。ハンドルが破棄されると、アプリはそれを使用してサブメッシュの情報やデータを取得できなくなります。トラッカー ハンドルはシーンメッシュ スナップショット ハンドルの親であるため、トラッカーが破棄されると、ハンドルは自動的に破棄されます。

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

• XR_ANDROID_scene_meshing 拡張機能は、xrDestroySceneMeshSnapshotANDROID を呼び出す前に有効にする必要があります。
• snapshot は、有効な XrSceneMeshSnapshotANDROID ハンドルでなければ

スレッドセーフ

• snapshot とその子ハンドルへのアクセスは、外部で同期する必要があります。

戻りコード

成功

• XR_SUCCESS

失敗

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

シーン メッシュのサンプルコード

次のサンプルコードは、レンダリング用のシーン メッシュ データにアクセスする方法を示しています。

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_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

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

• XrSceneMeshSnapshotANDROID
• XrSceneMeshingTrackerANDROID

新しいコマンド

• xrCreateSceneMeshSnapshotANDROID
• xrCreateSceneMeshingTrackerANDROID
• xrDestroySceneMeshSnapshotANDROID
• xrDestroySceneMeshingTrackerANDROID
• xrEnumerateSupportedSemanticLabelSetsANDROID
• xrGetAllSubmeshStatesANDROID
• xrGetSubmeshDataANDROID

新しい構造

• XrSceneMeshSnapshotCreateInfoANDROID
• XrSceneMeshSnapshotCreationResultANDROID
• XrSceneMeshingTrackerCreateInfoANDROID
• XrSceneSubmeshDataANDROID
• XrSceneSubmeshStateANDROID

• XrSystemProperties の拡張:

  • XrSystemSceneMeshingPropertiesANDROID

新しい列挙型

• XrSceneMeshSemanticLabelANDROID
• XrSceneMeshSemanticLabelSetANDROID
• XrSceneMeshTrackingStateANDROID

新しい列挙型定数

• XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
• XR_ANDROID_scene_meshing_SPEC_VERSION

• XrObjectType の拡張:

  • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
  • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

• XrStructureType の拡張:

  • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
  • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
  • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
  • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

問題

変更履歴

• リビジョン 3、2025-05-15（Salar Khan）

  • 拡張機能の初期説明