XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

719

リビジョン

3

Ratification Status（批准ステータス）

未批准

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

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

（保護レベル: 危険）

システムの機能を検証する

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 を返す場合、システムはシーン メッシュをサポートします。

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

• XrSystemSceneMeshingPropertiesANDROID を使用する前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります
• 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_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

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

列挙型の説明

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

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

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

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

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 関数を使用してハンドルを破棄しなければなりません。

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

• xrCreateSceneMeshingTrackerANDROID を呼び出す前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• 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 関数を使用して、シーン メッシュ トラッカーからシーン メッシュ スナップショットを作成できます。この関数は、XrSceneMeshSnapshotCreationResultANDROID 構造でラップされた XrSceneMeshTrackingStateANDROID とともに XrSceneMeshSnapshotANDROID ハンドルを返します。ハンドルは、作成時のシーン メッシュデータのスナップショットです。このハンドルは、それぞれ 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 :: submeshId で渡されたサブメッシュ ID に関連付けられたメッシュデータで各要素を埋める、アプリケーション割り当ての XrSceneSubmeshDataANDROID の配列です。

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

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

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

この can は、2 回の呼び出しイディオムで使用して、選択したすべてのサブメッシュの頂点とインデックスの数をクエリできます。

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

• xrGetSubmeshDataANDROID を呼び出す前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• 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 関数を使用してシーン メッシュ スナップショットを破棄できます。ハンドルが破棄されると、アプリケーションはそれを使用してサブメッシュ情報やデータを取得できなくなります。トラッカー ハンドルはシーン メッシュ スナップショット ハンドルの親であるため、トラッカーが破棄されるとハンドルは自動的に破棄されます。

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

• xrDestroySceneMeshSnapshotANDROID を呼び出す前に、XR_ANDROID_scene_meshing 拡張機能を有効にする必要があります。
• 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）

  • 拡張機能の最初の説明