XR_ANDROID_light_estimation OpenXR 拡張機能

名前の文字列

XR_ANDROID_light_estimation

拡張機能の種類

インスタンスの拡張

登録されている電話番号

701

リビジョン

1

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

OpenXR 1.0

最終更新日

2024-09-18

IP ステータス

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

寄与者

Jared Finder、Google

Cairn Overturf、Google

Spencer Quin、Google

Levana Chen、Google

Nihav Jain、Google

概要

この拡張機能により、ヘッドセットの周囲の現実環境の照明を表すデータをアプリがリクエストできるようになります。この情報は、仮想オブジェクトのレンダリング時に使用し、配置されているシーンと同じ条件で照明を当てることができます。

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

アプリは、xrGetSystemProperties を呼び出すときに XrSystemLightEstimationPropertiesANDROID 構造を XrSystemProperties に連結することで、システムが光の推定をサポートしているかどうかを検査できます。

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

メンバーの説明

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

アプリは、xrGetSystemProperties を呼び出すときに XrSystemProperties を XrSystemLightEstimationPropertiesANDROID 構造で拡張することで、システムが光の推定をサポートできるかどうかを検査できます。

システムが光の推定をサポートできない場合は、supportsLightEstimation に XR_FALSE、xrCreateLightEstimatorANDROID から XR_ERROR_FEATURE_UNSUPPORTED を返します。

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

ライト エスティメータ ハンドルを作成する

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

XrLightEstimatorANDROID ハンドルはライト エスティメータを表します。このハンドルを使用すると、この拡張機能の他の関数を使用して照明の推定情報にアクセスできます。

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

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

パラメータの説明

  • session は、ライト エスティメータを作成する XrSession です。
  • createInfo は、ライト エスティメータの作成に使用されるパラメータを含む XrLightEstimatorCreateInfoANDROID 構造体へのポインタです。
  • outHandle は、作成された XrLightEstimatorANDROID が返されるハンドルへのポインタです。

アプリケーションは、xrCreateLightEstimatorANDROID 関数を使用してライト エスティメータを作成できます。

  • システムが光の推定をサポートしていない場合、xrCreateLightEstimatorANDROID は XR_ERROR_FEATURE_UNSUPPORTED を返します。
  • 呼び出し元のアプリに必要な権限が付与されていない場合、xrCreateLightEstimatorANDROID は XR_ERROR_PERMISSION_INSUFFICIENT を返します。

返されたライト エスティメーター ハンドルは、後で API 呼び出しで使用される可能性があります。アプリケーションが光量推定データへのアクセスを終了したことをランタイムに示す場合は、xrDestroyLightEstimatorANDROID を使用してハンドルを破棄する必要があります。

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

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • 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

XrLightEstimatorCreateInfoANDROID 構造体には、XrLightEstimatorANDROID ハンドルを作成する情報が記述されています。

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    void*              next;
} XrLightEstimatorCreateInfoANDROID;

メンバーの説明

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

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

xrDestroyLightEstimatorANDROID 関数は、estimator とその基盤となるリソースを解放します。

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

パラメータの説明

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

スレッドセーフ

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

戻りコード

成功

  • XR_SUCCESS

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

照明の推定データにアクセスする

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

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

パラメータの説明

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

戻りコード

成功

  • 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_TIME_INVALID

XrLightEstimateGetInfoANDROID は、光の推定データを取得するために必要な情報を記述します。

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    void*              next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。
  • space は、返された光の方向と球面調和関数が表現される参照空間を定義する XrSpace です。
  • time は、アプリケーションが光の推定値をクエリする時刻を記述する XrTime です。

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

XrLightEstimateANDROID 構造体には、光の推定データが含まれています。

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

メンバーの説明

アンビエント ライト、球面調和関数、プライマリ ディレクショナル ライトの光の推定情報を取得するには、アプリケーションで、XrAmbientLightANDROID、XrSphericalHarmonicsANDROID、XrDirectionalLightANDROID の各構造のインスタンスを XrLightEstimateANDROID::next に連結します。

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

XrAmbientLightANDROID 構造体には、シーンの周囲光に関する光量推定データが含まれます。

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。有効な構造は XrSphericalHarmonicsANDROID と XrDirectionalLightANDROID です。
  • state は、光量推定値の状態を表す XrLightEstimateStateANDROID です。
  • intensity は、周囲光の強度を表す XrVector3 です。ベクトルの各要素は、赤、緑、青の各チャネルに対応しています。
  • colorCorrection は、ガンマ空間の値を持つ XrVector3 です。ガンマ補正済みレンダリングの色をこれらの値でコンポーネントごとに乗算します。

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

XrSphericalHarmonicsANDROID 構造には、シーンの照明を表す球面調和が含まれています。

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。有効な構造は XrAmbientLightANDROID と XrDirectionalLightANDROID です。
  • state は、光量推定値の状態を表す XrLightEstimateStateANDROID です。
  • kind は、アプリがリクエストした XrSphericalHarmonicsKindANDROID です。
  • coefficients は、9 行 3 列の 2 次元 float 配列です。3 つの列は、それぞれ赤、緑、青の色チャネルに対応しています。各チャネルには 9 個の球面調和係数があります。

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

XrDirectionalLightANDROID 構造体には、光の推定データが含まれています。

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

メンバーの説明

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

XrSphericalHarmonicsKindANDROID 列挙型は、アプリケーションがリクエストしている球面調和関数のタイプをランタイムに識別します。

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1
} XrSphericalHarmonicsKindANDROID;

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

列挙型

説明

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

球面調和係数は、メインライトからの寄与を除いた環境光の放射輝度関数を表します。

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

球面調和係数は、メインライトからの寄与を含む環境光の放射輝度関数を表します。

XrLightEstimateStateANDROID 列挙型は、アプリケーションがリクエストしている球面調和関数のタイプをランタイムに識別します。

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1
} XrLightEstimateStateANDROID;

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

列挙型

説明

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

照明の見積もりが有効である

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

照明の見積もりが正しくない

光の推定のサンプルコード

次のサンプルコードは、実行時に考えられるすべての光量推定量を取得する方法を示しています。

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.

XrLightEstimatorANDROID estimator;
XrLightEstimatorCreateInfoANDROID createInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID};
CHK_XR(xrCreateLightEstimatorANDROID(session, &createInfo, &estimator));

// Every frame
XrTime updateTime;  // Time used for the current frame's simulation update.

XrLightEstimateGetInfoANDROID info = {
    .type = XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID,
    .space = appSpace,
    .time = updateTime,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
};

XrSphericalHarmonicsANDROID totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
    .next = &directionalLight,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
    .next = &totalSh,
};

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &ambientSh,
};

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &ambientLight,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight if each
  // struct has a valid state field
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

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

  • XrLightEstimator

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

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

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

  • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_ANDROID
  • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
  • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
  • XR_TYPE_AMBIENT_LIGHT_ANDROID

新しい列挙型

新しい構造

新機能

問題

変更履歴

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