XR_ANDROID_composition_layer_passthrough_mesh OpenXR 拡張機能

名前の文字列

XR_ANDROID_composition_layer_passthrough_mesh

拡張機能の種類

インスタンスの拡張

登録されている電話番号

463

リビジョン

1

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

OpenXR 1.0

最終更新日

2024-09-18

IP ステータス

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

寄与者

Grant Yoshida、Google

Kevin Moule、Google

Vasiliy Baranov、Google

Peter Chen、Google

Levana Chen、Google

概要

複数の環境のブレンドモードをサポートするデバイスの場合、システムはパススルー構成を提供して、没入型ビューからユーザーに物理環境を表示する場合があります。

この拡張機能により、アプリケーションは追加のコンポジション レイヤ XrCompositionLayerPassthroughANDROID を介して、任意のジオメトリにパススルー テクスチャを投影できます。

パススルー レイヤの特性には、次のパラメータを使用します。ここで、投影は XrPassthroughLayerANDROID で表されます。

  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;

全画面パススルーの場合、アプリケーションは環境のブレンドモードを使用できます。

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

アプリは、xrGetSystemProperties を呼び出すときに XrSystemPassthroughLayerPropertiesANDROID 構造を XrSystemProperties に連結することで、システムがコンポジション レイヤ パススルー メッシュを処理できるかどうかを検査できます。

typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、そのような構造は定義されていません。
  • supportsPassthroughLayer は XrBool32 で、現在のシステムが合成レイヤ パススルー メッシュをサポートしているかどうかを示します。
  • maxMeshIndexCount は、パススルー メッシュで受け入れられるインデックスの最大数を返す uint32_t です。
  • maxMeshVertexCount は、パススルー メッシュで受け入れられる頂点の最大数を返す uint32_t です。

supportsPassthroughLayer が XR_FALSE を返す場合、システムはコンポジション レイヤ パススルー メッシュをサポートしていないため、xrCreatePassthroughLayerANDROID から XR_ERROR_FEATURE_UNSUPPORTED を受信します。supportsPassthroughLayer が XR_FALSE の場合、アプリケーションはコンポジション レイヤ パススルー メッシュの使用を避けるべきです。

supportsPassthroughLayer が XR_TRUE を返す場合、システムはコンポジション レイヤ パススルー メッシュをサポートしています。この場合、maxMeshIndexCount と maxMeshVertexCount はゼロ以外の数値を返します。アプリケーションは、xrCreatePassthroughLayerANDROID と xrSetPassthroughLayerMeshANDROID を呼び出すときに、パススルー メッシュを設定するための最大値として maxMeshIndexCount と maxMeshVertexCount を使用する必要があります。そうしないと、メッシュデータがサポートされている上限を超えていることを示す XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID が返される可能性があります。

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

パススルー レイヤの合成

XrCompositionLayerPassthroughANDROID には、xrEndFrame を呼び出すときにパススルー テクスチャを三角形メッシュにレンダリングするために必要な情報が含まれています。XrCompositionLayerPassthroughANDROID は、XrFrameEndInfo で使用されるベース ストラクチャ XrCompositionLayerBaseHeader のエイリアス型です。

typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。コア OpenXR またはこの拡張機能では、そのような構造は定義されていません。
  • layerFlags は、レイヤに適用するフラグを記述する XrCompositionLayerFlags のビットマスクです。
  • space は、レイヤメッシュの pose が時間の経過とともに評価される XrSpace です。
  • pose は、space の参照フレーム内のレイヤメッシュの位置と向きを定義する XrPosef です。
  • scale は、レイヤメッシュのスケールを定義する XrVector3f です。
  • opacity は、パススルー テクスチャの不透明度を [0, 1] の範囲で定義する float です。
  • layer は、xrCreatePassthroughLayerANDROID によって以前に作成された XrPassthroughLayerANDROID です。

アプリケーションは、作成された layer と XrPassthroughLayerMeshANDROID が提供する対応するメッシュを使用して、XrCompositionLayerPassthroughANDROID 構造を作成できます。

XrCompositionLayerPassthroughANDROID へのポインタは、選択したレイヤ順でベース構造 XrCompositionLayerBaseHeader へのポインタとして xrEndFrame で送信され、パススルー レイヤを最終フレーム出力に合成するようランタイムにリクエストできます。

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

パススルー レイヤ ハンドルを作成する

XrPassthroughLayerANDROID ハンドルは、XrCompositionLayerPassthroughANDROID の動作を定義するパススルー レイヤを表します。

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

アプリは、xrCreatePassthroughLayerANDROID を呼び出して XrPassthroughLayerANDROID ハンドルを作成できます。返された XrPassthroughLayerANDROID ハンドルは、後で API 呼び出しで使用できます。

XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);

パラメータの説明

アプリケーションは、XrPassthroughLayerCreateInfoANDROID::vertexCapacity と XrPassthroughLayerCreateInfoANDROID::indexCapacity でパススルー メッシュ インデックスの数を指定し、xrGetSystemProperties の呼び出し時に XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount と XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount によって返される最大値以下にする必要があります。createInfo で定義されたメッシュ インデックスの数が最大値を超えると、xrCreatePassthroughLayerANDROID は XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID エラーを返します。

XrPassthroughLayerANDROID ハンドルは、最終的には xrDestroyPassthroughLayerANDROID 関数を使用して解放する必要があります。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

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

typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。XrPassthroughLayerMeshANDROID を次のチェーンで指定して、xrCreatePassthroughLayerANDROID を呼び出すときにパススルー レイヤの初期メッシュを指定できます。
  • vertexCapacity は、このレイヤのメッシュの頂点バッファの最大容量を表す uint32_t です。指定されていない場合は 0 です。指定する場合、このレイヤに設定されたメッシュの XrPassthroughLayerMeshANDROID::vertexCount は vertexCapacity 以下にする必要があります。
  • indexCapacity は、このレイヤのメッシュのインデックス バッファの最大容量を表す uint32_t です。未指定の場合は 0 です。指定する場合、このレイヤに設定されたメッシュの XrPassthroughLayerMeshANDROID::indexCount は indexCapacity 以下にする必要があります。

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

アプリは xrDestroyPassthroughLayerANDROID 関数を使用して、パススルー レイヤと基盤となるリソースを解放できます。

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

パラメータの説明

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

スレッドセーフ

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

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

パススルー レイヤのメッシュを設定する

アプリは xrSetPassthroughLayerMeshANDROID 関数を使用して、パススルー レイヤのメッシュを設定できます。

XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);

パラメータの説明

アプリは、xrGetSystemProperties を呼び出すときに XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount と XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount によって返される最大値以下のパススルー メッシュ インデックス数を XrPassthroughLayerMeshANDROID::vertexCount と XrPassthroughLayerMeshANDROID::indexCount に指定する必要があります。xrSetPassthroughLayerMeshANDROID の mesh で指定されたメッシュ インデックスの数が最大値を超える場合、XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID が返されます。

xrCreatePassthroughLayerANDROID を使用して layer を作成するときに、メッシュ バッファの容量が XrPassthroughLayerCreateInfoANDROID::vertexCapacity と XrPassthroughLayerCreateInfoANDROID::indexCapacity で指定されている場合、mesh で定義されたメッシュ インデックスの数が容量を超えると、xrSetPassthroughLayerMeshANDROID で XR_ERROR_SIZE_INSUFFICIENT エラーが返されます。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

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

typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。
  • windingOrder はメッシュの三角形の XrWindingOrderANDROID です。これは、メッシュのレンダリング時にバックフェイス カリングに使用されます。
  • vertexCount は、メッシュ内の頂点の数を表す uint32_t です。XrPassthroughLayerCreateInfoANDROID::vertexCapacity が指定されている場合、vertexCount は vertexCapacity 以下にする必要があります。
    • vertices は、三角メッシュの頂点位置を含む XrVector3f の配列へのポインタです。
  • indexCount は、三角メッシュのインデックス数を表す uint32_t です。最後の indexCount % 3 インデックス（存在する場合）は描画されません。XrPassthroughLayerCreateInfoANDROID::indexCapacity が指定されている場合、indexCount は indexCapacity 以下にする必要があります。
  • indices は、三角メッシュのインデックスを含む uint16_t の配列へのポインタです。

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

XrWindingOrderANDROID 列挙型は、メッシュの三角形の巻き付け順序を識別します。これは、パススルー レイヤのメッシュをレンダリングする際のバックフェイス カリングにランタイムによって使用されます。

typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;

列挙値の説明

  • XR_WINDING_ORDER_UNKNOWN_ANDROID - メッシュの三角形の巻き付け順序が不明です。
  • XR_WINDING_ORDER_CW_ANDROID - メッシュの三角形の巻き順序は時計回りです。
  • XR_WINDING_ORDER_CCW_ANDROID  — メッシュの三角形の巻き順は反時計回りです。

パススルー レイヤの合成のサンプルコード

次のサンプルコードは、パススルー レイヤを作成し、合成で使用する方法を示しています。

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace space; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreatePassthroughLayerANDROID xrCreatePassthroughLayerANDROID; // previously initialized
PFN_xrDestroyPassthroughLayerANDROID xrDestroyPassthroughLayerANDROID; // previously initialized
PFN_xrSetPassthroughLayerMeshANDROID xrSetPassthroughLayerMeshANDROID; // previously initialized

// Inspect passthrough mesh system properties
XrSystemPassthroughLayerPropertiesANDROID passthroughLayerSystemProperties{
  XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{
  XR_TYPE_SYSTEM_PROPERTIES, &passthroughLayerSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!passthroughLayerSystemProperties.supportsPassthroughLayer) {
    // the system does not support composite layer passthrough mesh.
    return;
}

// The initial mesh for the layer.
XrPassthroughLayerMeshANDROID mesh = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID,
  .windingOrder = XR_WINDING_ORDER_CW_ANDROID,
  .vertexCount = 4,
  .vertices = {
    { 0, 0, 0 }, { 0, 1, 0 }, { 1, 1, 0 }, { 1, 0, 0 }
  },
  .indexCount = 6,
  .indices = {
    0, 1, 2,
    0, 2, 3
  },
};

// Create the layer. Layers are expected to persist across frames.
XrPassthroughLayerCreateInfoANDROID create_info = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID,
  .next = &mesh,
  .vertexCapacity = 0,
  .indexCapacity = 0,
};
XrPassthroughLayerANDROID layer;
CHK_XR(xrCreatePassthroughLayerANDROID(session, &create_info, &layer));

// Create a composition layer. Composition layers are submitted per frame.
XrCompositionLayerPassthroughANDROID passthrough_layer = {
  .type = XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID,
  .next = nullptr,
  .layerFlags = 0,
  .space = space,
  .pose = {
    .orientation = { 0.0f, 0.0f, 0.0f, 1.0f }
    .position = { 0.0f, 0.0f, 0.0f }
  },
  .scale = { 1.0f, 1.0f, 1.0f },
  .opacity = 1.0f,
  .layer = layer
};

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    // Submit composition layer in xrEndFrame.
    std::vector<XrCompositionLayerBaseHeader*> layers = {
        ...,
        &passthrough_layer,
        ...,
    };
    XrFrameEndInfo end_frame_info = { XR_TYPE_FRAME_END_INFO, nullptr };
    end_frame_info.layerCount = (uint32_t)layers.size();
    end_frame_info.layers = layers.data();
    CHK_XR(xrEndFrame(session, &end_frame_info));

    // Update the layer. Results can be seen the next time a passthrough composition
    // layer is submitted.
    mesh.indexCount = 9;
    const uint16_t new_index_buffer[] = {
        0, 1, 2,
        0, 2, 3,
        0, 1, 2
    };
    mesh.indexBuffer = &new_index_buffer[0];
    CHK_XR(xrSetPassthroughLayerMeshANDROID(&layer, &mesh));

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

// Clean up.
CHK_XR(xrDestroyPassthroughLayerANDROID(layer));

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

新しい列挙型定数

XrObjectType 列挙型が拡張され、次のように変更されました。

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

XrStructureType 列挙型が拡張され、次のように変更されました。

  • XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
  • XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
  • XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
  • XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID

XrResult 列挙型が拡張され、次が追加されました。

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

新しい列挙型

新しい構造

新機能

問題

変更履歴

  • リビジョン 1、2024 年 9 月 11 日（Levana Chen）
    • 最初の拡張機能の説明