XR_ANDROID_light_estimation OpenXR 拡張機能

Name String

XR_ANDROID_light_estimation

拡張機能の種類

インスタンスの拡張

登録されている電話番号

701

リビジョン

1

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

OpenXR 1.0

最終更新日

2025-01-17

IP ステータス

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

寄与者

Jared Finder、Google

Cairn Overturf、Google

Spencer Quin、Google

Levana Chen、Google

Nihav Jain、Google

Salar Khan、Google

Scott Chung、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;

メンバーの説明

環境照明キューブマップ、アンビエント ライト、球面調和、プライマリ ディレクショナル ライトのライト推定情報を取得するには、アプリケーションで、XrEnvironmentLightingCubemapANDROID、XrAmbientLightANDROID、XrSphericalHarmonicsANDROID、XrDirectionalLightANDROID の各構造のインスタンスを XrLightEstimateANDROID::next にそれぞれ連結します。

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

XrEnvironmentLightingCubemapANDROID 構造体には、シーンの環境照明に関するキューブマップ形式の光推定データが含まれています。

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は NULL または構造体チェーンの次の構造体へのポインタです。有効な構造は、XrSphericalHarmonicsANDROID、XrAmbientLightANDROID、XrDirectionalLightANDROID です。
  • state は、光量推定値の状態を表す XrLightEstimateStateANDROID です。
  • cubemapRightImage は、キューブマップの右側の R32G32B32_SFLOAT バッファを表す float* です。これは HDR であるため、浮動小数点値は 1.0 より大きくすることができます。
  • cubemapLeftImage は、キューブマップの左側の R32G32B32_SFLOAT バッファを表す float* です。これは HDR であるため、浮動小数点値は 1.0 より大きくすることができます。
  • cubemapTopImage は、キューブマップの上側の R32G32B32_SFLOAT バッファを表す float* です。これは HDR であるため、浮動小数点値は 1.0 より大きくすることができます。
  • cubemapBottomImage は、キューブマップの下側の R32G32B32_SFLOAT バッファを表す float* です。これは HDR であるため、浮動小数点値は 1.0 より大きくすることができます。
  • cubemapFrontImage は、キューブマップの前面の R32G32B32_SFLOAT バッファを表す float* です。これは HDR であるため、浮動小数点値は 1.0 より大きくすることができます。
  • resolution は、キューブマップの各側の画像の幅と高さを表す uint32_t です。これは HDR であるため、浮動小数点値は 1.0 より大きくすることができます。
  • rotation は、キューブマップの回転を表す XrQuaternionf です。
  • centerExposureTime は、キューブマップがキャプチャされた時刻を表す XrTime です。キューブマップ間の補間に便利です。

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

  • XrEnvironmentLightingCubemapANDROID を使用する前に、XR_ANDROID_light_estimation 拡張機能を有効にする必要があります。
  • type は XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID にする必要があります
  • next は NULL であるか、構造体チェーンの次の構造体への有効なポインタである必要があります。
  • state は有効な XrLightEstimateStateANDROID 値である必要があります。
  • cubemapRightImage は有効な浮動小数点値へのポインタである必要があります。
  • cubemapLeftImage は有効な浮動小数点値へのポインタである必要があります。
  • cubemapTopImage は有効な浮動小数点値へのポインタである必要があります。
  • cubemapBottomImage は有効な浮動小数点値へのポインタである必要があります。
  • cubemapFrontImage は有効な浮動小数点値へのポインタである必要があります。
  • cubemapBackImage は有効な浮動小数点値へのポインタである必要があります。

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

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

メンバーの説明

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

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

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

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

メンバーの説明

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

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,
};


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

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

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight,
  // lightingCubemap, 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
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

新しい列挙型

新しい構造

新機能

問題

変更履歴

  • リビジョン 2、2025 年 1 月 17 日（Salar Khan）
    • 環境照明キューブマップのサポートを追加しました
  • リビジョン 1、2024 年 9 月 16 日（Cairn Overturf）
    • 最初の拡張機能の説明