XR_ANDROID_light_estimation OpenXR 拡張機能

Name String

XR_ANDROID_light_estimation

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

701

リビジョン

1

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

OpenXR 1.0

最終更新日

2025-01-17

IP ステータス

既知の IP 申し立てはありません。

寄与者

Jared Finder, Google

Google の Cairn Overturf

Spencer Quin（Google）

Levana Chen（Google）

Nihav Jain、Google

Google の Salar Khan

Scott Chung（Google）

概要

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

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

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

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

メンバーの説明

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

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

システムが光推定をサポートできない場合、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 です。
  • 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;

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

Enum

説明

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;

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

Enum

説明

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-01-17（Salar Khan）
    • 環境照明キューブマップのサポートを追加
  • リビジョン 1、2024 年 9 月 16 日（Cairn Overturf）
    • 拡張機能の最初の説明

OpenXR™ および OpenXR のロゴは、Khronos Group Inc. が所有する商標であり、中国、欧州連合、日本、英国で商標として登録されています。