XR_ANDROID_light_estimation

名前文字列

XR_ANDROID_light_estimation

拡張機能のタイプ

インスタンス拡張機能

登録済み拡張機能番号

701

リビジョン

1

批准ステータス

批准されていません

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

OpenXR 1.0

最終更新日

2025-03-13

IP ステータス

既知の IP クレームはありません。

寄与者

Jared Finder（Google）
Cairn Overturf（Google）
Spencer Quin（Google）
Levana Chen（Google）
Nihav Jain（Google）
Salar Khan（Google）
Scott Chung（Google）

概要

この拡張機能を使用すると、アプリケーションはヘッドセット周辺の実世界の環境の照明を表すデータをリクエストできます。アプリケーションは、この情報を使用して、配置されている実世界のシーンと同じ条件で仮想オブジェクトを照らすことができます 。

権限

この拡張機能は環境の照明情報を公開するため、Android アプリケーションはマニフェストに android.permission.SCENE_UNDERSTANDING_COARSE 権限を記載する必要があります 。android.permission.SCENE_UNDERSTANDING_COARSE 権限は危険な権限と見なされます。アプリケーションは、これらの関数を使用するために、実行時に権限をリクエストする必要があります 。

（保護レベル: 危険）

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

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

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

メンバーの説明

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

アプリケーションは、xrGetSystemProperties を呼び出すときに XrSystemProperties を XrSystemLightEstimationPropertiesANDROID 構造体で拡張することで、システムが照明推定をサポートできるかどうかを確認できます 。

ランタイムが XR_FALSE に対して supportsLightEstimation を返す場合、ランタイムは xrCreateLightEstimatorANDROID から XR_ERROR_FEATURE_UNSUPPORTED を返す**必要があります** 。

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

照明推定ハンドルの作成

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

照明推定データはランタイムによって生成され、XrLightEstimatorANDROID ハンドルを使用してアプリケーションと共有されます。

このハンドルを使用して、この拡張機能の他の関数を使用して照明推定情報にアクセスできます 。

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

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

パラメータの説明

アプリケーションは、xrCreateLightEstimatorANDROID 関数を使用して照明推定を作成します。

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

アプリケーションが照明推定データへのアクセスを終了したことをランタイムに示す場合は、xrDestroyLightEstimatorANDROID を使用してハンドルを破棄する必要があります 。

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

戻りコード

成功

  • 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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

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

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

メンバーの説明

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

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

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

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

パラメータの説明

xrDestroyLightEstimatorANDROID 関数は、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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

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

メンバーの説明

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

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

  • XR_ANDROID_light_estimation 拡張機能を XrLightEstimateGetInfoANDROID を使用する前に有効にする必要があります
  • type は XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROIDにする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタにする必要があります
  • space は有効な XrSpace ハンドル**にする必要があります** 。

XrLightEstimateANDROID 構造体には照明推定データが含まれます。

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

メンバーの説明

すべての照明推定構造体で state が XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID の場合、構造体内の他のフィールドは任意の値になります。つまり、値は未定義です。

周囲光、球面調和関数、主方向光の照明推定情報を取得するために、アプリケーションは、XrAmbientLightANDROID、XrSphericalHarmonicsANDROID、XrDirectionalLightANDROID の各構造体のインスタンスを XrLightEstimateANDROID :: `next` にチェーンできます 。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 は、XrVector3f であり、周囲光の強度を表します。ベクトルの各コンポーネントは、それぞれ赤、緑、青のチャンネルに対応しています。

  • colorCorrection は、XrVector3f で、ガンマ空間の値を持つものです。ガンマ色空間でレンダリングする場合は、レンダリング後に最終的に計算された色に対してコンポーネントごとに乗算します。線形空間でレンダリングする場合は、まず 2.2 乗して値を線形空間に変換し、レンダリング後に最終的に計算された色に対してコンポーネントごとに乗算します。

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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

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 個の球面調和関数係数があります。

coefficients は、方向を入力として受け取り、その方向から来る光の色を出力する特別な関数で使用されます。詳細については、こちらの論文をご覧ください。

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

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

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

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

列挙型 説明

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

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

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

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

XrDirectionalLightANDROID 構造体には照明推定データが含まれます。

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

メンバーの説明

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

XrLightEstimateStateANDROID 列挙型は、ランタイムから返される照明推定の状態を示します。

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

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

列挙型 説明

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

照明推定は有効です

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

照明推定は無効です

照明推定のサンプルコード

次のサンプルコードは、ランタイムから取得できるすべての照明推定量を取得する方法を示しています。

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

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

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));

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

新しいコマンド

新しい構造体

新しい列挙型

新しい列挙型定数

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • XrObjectType の拡張 :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • XrStructureType の拡張 :

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

問題

変更履歴

  • リビジョン 1、2024-09-16（Cairn Overturf）

    • 拡張機能の最初の説明