Android XR for OpenXR | Android Developers

Android Dev Summit が、 Android XR 専用のトラックとともに帰ってきます。ぜひお試しいただき、フィードバックをお寄せください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

拡張機能の種類

インスタンス拡張

登録済みの内線番号

797

リビジョン

承認ステータス

未批准

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

OpenXR 1.0

最終更新日

2026-03-10

IP ステータス

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

寄与者

Brian Chen、Google
Kyle Chen、Google
Nihav Jain、Google
Spencer Quin、Google

概要

光学シースルーデバイスが導入されるにあたり、アプリがパススルーの暗さを調整して、アプリのコンテキストと最適なブレンドをユーザーに提供できるようにするだけでなく、安全上の理由から、システムがパススルーの暗さを解除できるようにすることも重要です。

この拡張機能は、アプリが現在の調光レベルを設定および取得するための 2 つの関数と、調光レベルが変更されたときにブロードキャストするイベントを提供します。

システム機能を検査する

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

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

メンバーの説明

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

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

ランタイムが supportsGlobalDimming に対して XR_FALSE を返す場合、ランタイムは xrGetGlobalDimmingLevelANDROID が呼び出されたときに XR_ERROR_FEATURE_UNSUPPORTED を返さなければなりません。

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

XrSystemGlobalDimmingPropertiesANDROID を使用する前に、XR_ANDROID_global_passthrough_dimming 拡張機能を有効にする必要があります。
type は XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID にする必要があります。
next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

サポートされているグローバル減光レベルを列挙する

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

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

メンバーの説明

instance は、systemId の取得元のインスタンスです。
systemId は、サポートされているレベルが列挙される XrSystemId です。
supportedGlobalDimmingLevelCapacityInput は supportedGlobalDimmingLevels 配列の容量です。0 の場合は、必要な容量を取得するリクエストであることを示します。
supportedGlobalDimmingLevelCountOutput は、書き込まれた supportedGlobalDimmingLevels の数へのポインタ、または supportedGlobalDimmingLevelCapacityInput が不十分な場合は必要な容量へのポインタです。
supportedGlobalDimmingLevels は、サポートされているレベルの配列へのポインタですが、supportedGlobalDimmingLevelCapacityInput が 0 の場合は NULL になる可能性があります。

返された supportedGlobalDimmingLevelCountOutput が 0 の場合、0.0 ～ 1.0 のすべてのグローバル減光レベルがサポートされます。

xrEnumerateSupportedGlobalDimmingLevelsANDROID は、XrSystemId でサポートされているグローバル調光レベルを列挙します。サポートされているレベルは、XrInstance の存続期間中に変更してはなりません。返されるレベルのリストは、昇順で並べ替える必要があります。

ランタイムは、指定された systemId と instance の存続期間について、この列挙から常に同一のバッファコンテンツを返さなければなりません。

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

xrEnumerateSupportedGlobalDimmingLevelsANDROID を呼び出す前に、XR_ANDROID_global_passthrough_dimming 拡張機能を有効にする必要があります。
instance は、有効な XrInstance ハンドルでなければなりません。
supportedGlobalDimmingLevelCountOutput は uint32_t 値へのポインタでなければなりません
supportedGlobalDimmingLevelCapacityInput が 0 でない場合、supportedGlobalDimmingLevels は supportedGlobalDimmingLevelCapacityInput float 値の配列へのポインタでなければなりません。

戻りコード

成功

XR_SUCCESS

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SIZE_INSUFFICIENT
XR_ERROR_SYSTEM_INVALID
XR_ERROR_VALIDATION_FAILURE

グローバル減光レベルを構成する

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

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

パラメータの説明

type は、この構造の XrStructureType です。
next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
globalDimmingLevel は 0.0（透明）～ 1.0（不透明）の値です。ランタイムは、この値をサポートされている最も近いグローバル調光レベルにマッピングする場合があります。アプリは、この値を -1.0 に設定して、現在の減光レベルが優先されることを示すことができます。

globalDimmingLevel 値は、遮断される光の割合を指定します。値 0.0 は 0% の光遮断に対応し、1.0 は 100% の光遮断に対応します。遮られる光の割合は、一般的に次のように表すことができます。

100% - Light Transmittance%

ISO 8980-3:2022 に基づく光透過率の割合は、可視光の波長（380 nm ～ 780 nm）における入射放射束に対する透過放射束の比率として測定できます。

XrGlobalDimmingFrameEndInfoANDROID は、アプリが XrFrameEndInfo でチェーンして、優先グローバル調光レベルをリクエストできる構造です。

リクエストされた減光レベルが現在の減光レベルと異なる場合、ランタイムはリクエストされた減光レベルを優先しなければなりません。

ランタイムはグローバル減光レベルを制御し、安全上の理由から、優先されるグローバル減光レベルを無視する場合があります。

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

XrGlobalDimmingFrameEndInfoANDROID を使用する前に、XR_ANDROID_global_passthrough_dimming 拡張機能を有効にする必要があります。
type は XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID にする必要があります。
next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

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

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

パラメータの説明

session は有効な XrSession ハンドルです。
dimmingLevel は、現在の減光レベルへのポインタです。

返される dimmingLevel は 0.0 ～ 1.0 の範囲でなければなりません。0.0 は完全に透明、1.0 は完全に暗いことを意味します。

減光レベルが設定されていない場合、ランタイムは、パススルーが有効になっているときは減光レベルを 0.0 に、パススルーが無効になっているときは 1.0 に設定しなければなりません。

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

XR_ANDROID_global_passthrough_dimming 拡張機能は、xrGetGlobalDimmingLevelANDROID を呼び出す前に有効にする必要があります。
session は、有効な XrSession ハンドルでなければなりません。
dimmingLevel は float 値へのポインタでなければなりません

戻りコード

成功

XR_SUCCESS
XR_SESSION_LOSS_PENDING

失敗

XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_HANDLE_INVALID
XR_ERROR_INSTANCE_LOST
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

減光レベル変更イベント

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

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

メンバーの説明

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

アプリケーションは、xrPollEvent を使用してこのイベントを取得できます。このイベントは、アプリまたはデバイスの物理ボタンによって減光レベルが変更されたときに送信されます。

フォーカスされているアプリが別のアプリに切り替わった場合、このイベントは送信されません。

アプリは、xrGetGlobalDimmingLevelANDROID を呼び出して新しい減光レベルを取得し、それに応じて XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel を更新することで、イベントに対応する必要があります。イベントに応答することで、アプリケーションが優先減光レベルを変更したときにランタイムにシグナルが送信されることが保証されます。

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

XrEventDataGlobalDimmingLevelChangedANDROID を使用する前に、XR_ANDROID_global_passthrough_dimming 拡張機能を有効にする必要があります。
type は XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID にする必要があります。
next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。

コード例

システム機能を確認し、サポートされているグローバル調光レベルを列挙する

次のサンプルコードは、グローバルディミングがサポートされているかどうかを確認する方法を示しています。

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

調光レベル変更イベントをポーリングする

次のサンプルコードは、減光レベル変更イベントをポーリングする方法を示しています。

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

新しいコマンド

xrEnumerateSupportedGlobalDimmingLevelsANDROID
xrGetGlobalDimmingLevelANDROID

新しい構造

XrEventDataGlobalDimmingLevelChangedANDROID
XrFrameEndInfo の拡張:
- XrGlobalDimmingFrameEndInfoANDROID
XrSystemProperties の拡張:
- XrSystemGlobalDimmingPropertiesANDROID

新しい列挙型定数

XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
XR_ANDROID_global_passthrough_dimming_SPEC_VERSION
XrStructureType の拡張:
- XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
- XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
- XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

問題

変更履歴

リビジョン 1、2025-10-07（Brian Chen）
- 拡張機能の初期説明。