フラッシュライトのサポート
Windows のしきい値から、Windows.Media.Capture.MediaCapture インスタンスを作成しなくてもカメラ フラッシュをプログラムできる新しい WinRT Lamp API を公開します。 そうすることで、開発者は、コンピューティング デバイスを バッテリの寿命とパフォーマンスのために最適化できるように、電力を含む最小限のリソースを書くことによって (照明目的のみ)、フラッシュライト アプリケーションを作成できます。
これを実現するために、IHV/OEM は、次の機能をサポートする WDM ドライバーを実装する必要があります。
システムがすべてのフラッシュ デバイスを列挙できるようにします。
デバイスごとにフラッシュ ライトのオン/オフを切り替えます。
該当する場合は、デバイスごとに光の強度 (PowerPercent と同様) を調整します。
該当する場合は、デバイスごとにライトの色を指定します。
機能面では、上記のリストは MediaCapture (FlashControl や TorchControl など) のリストと大きく重複しています。 さらに、同じフラッシュ ハードウェアがランプとキャプチャ中のフラッシュの両方に使用されています。 そのため、IHV/OEM は、単一の WDM ドライバーを使用してフラッシュを排他的に制御する両方の種類の操作をサポートすることをお勧めします。 次の図は、概念を示しています。
上の例では、フラッシュ ハードウェア インスタンスは 1 つだけ (表示されている) であり、1 つの KMDF フラッシュ ドライバーによって管理されています。 フラッシュ ドライバーは、それぞれ特定の種類のクライアント (または WinRT API) を対象とする 2 つのデバイス インターフェイスを公開します。 たとえば、上記の図を次に示します。
WinRT MediaCapture API と AVStream ミニドライバーは常に、GUID_DEVINTERFACE_CAMERA_FLASH インターフェイスを介してフラッシュ ドライバーと通信します。一方、
WinRT Lamp API は常に、GUID_DEVINTERFACE_LAMP インターフェイスを介してフラッシュ ドライバーと通信します。
GUID_DEVINTERFACE_CAMERA_FLASH インターフェイスはベンダー固有の AVStream ミニドライバーによって使用されるため、IHV/OEM は自由に機能を定義できます。Windows によって制限されることはありません。
ただし、Microsoft は、WinRT Lamp API によって使用されるため、GUID_DEVINTERFACE_LAMP インターフェイスを標準化します。 GUID_DEVINTERFACE_LAMP の詳細については、「デバイス インターフェイス クラス GUID」を参照してください。
コンカレンシーのユース ケース
カメラとフラッシュライト アプリケーション間でのフラッシュの共有
通常、カメラ フラッシュはキャプチャ デバイスの従属周辺機器と見なされます。 キャプチャの実行中に、カメラ以外のシナリオと共有されるものではありません。 さらに複雑なことに、シャーシ搭載のフラッシュデバイスの数は非常に限られているので、実際には、フラッシュライト専用に予備のフラッシュを搭載することはありません。
ソフトウェアの観点から見ると、上記のように、カメラ アプリケーションとフラッシュライト アプリケーションが共存し、同時にフラッシュにアクセスされうるという課題があります。 たとえば、理論上、ユーザーはカメラ ビューファインダーの実行中にフラッシュライト アプリケーションを介して LED の状態を切り替えることができます。
カメラはフォーカスとキャプチャをサポートするためにフラッシュを正確に制御する必要があるため、ドライバーが画質を確保しながら相反する関心事のフラッシュ要求を解決することが困難な場合があります。 この問題に対処するために、次のポリシーがシステム レベルでコントラクトとして適用されます。
キャプチャ セッションが最初に開始された場合、フラッシュライト アプリケーションはキャプチャが停止するまでフラッシュを操作できません。
フラッシュライト アプリケーションは引き続きフラッシュ ドライバへのハンドルを取得することができますが、フラッシュ状態を変更する操作は即座にエラーになります。
AVStream ミニドライバーがフラッシュを解放するようにキャプチャが停止すると、フラッシュ ドライバーは、基になるハードウェアが使用可能になったことを示す PnP 通知 (非同期通知の GUID_LAMP_RESOURCES_AVAILABLE を参照) をポストする必要があります。 このような通知を受け取ると、フラッシュライト アプリケーションはそれに応じてフラッシュをプログラムすることができます。
フラッシュライト アプリケーションが最初に起動した場合、キャプチャ セッションは明示的な同意なしにフラッシュ ハードウェアをハイジャックすることができます。
"ハイジャック" とは、IHV/OEM が任意のプロトコル (GUID_DEVINTERFACE_CAMERA_FLASH インターフェイスを介して) を実装できることを意味します。これにより、AVStream ミニドライバーは、ハードウェアがまったく使用されていないかのようにフラッシュを取得できます。
ハイジャックが発生した場合、フラッシュ ドライバーは別の PnP 通知を投稿する必要があります (「非同期通知の GUID_LAMP_RESOURCES_LOST」を参照)、フラッシュが不本意に再割り当てされたことを示します(たとえば、UI を更新するなどして)、フラッシュライト アプリケーションが適切に動作するようにします。
複数のフラッシュライト アプリケーション間でフラッシュを共有する
カメラが関与せず、2 つのフラッシュライト アプリケーションが連続して実行される場合、ドライバーは、既に GUID_DEVINTERFACE_LAMP インターフェイスを取得している最初のクライアントにサービスを提供し続け、最初のクライアントが最終的にインターフェイスを解放するまで、すべての追加クライアントを拒否する必要があります。
つまり、GUID_DEVINTERFACE_LAMP インターフェイスでは、一度に 1 つのフラッシュライト クライアントのみが許可され、インターフェイスを取得する最初のクライアントは、他のクライアントが実行されないようにします (カメラ/AVStream は除外されます)。
デバイス インターフェイス クラス GUID
MediaCapture に依存しないフラッシュライトをサポートできる IHV/OEM フラッシュ ドライバーは、デバイス インターフェイス クラス GUID、 GUID_DEVINTERFACE_LAMP に登録する必要があります。
| Attribute | 設定 |
|---|---|
| 識別子 | GUID_DEVINTERFACE_LAMP |
| クラス GUID | {6C11E9E3-8232-4F0A-AD19-AAEC26CA5E98} |
GUID_DEVINTERFACE_CAMERA_FLASH のデバイス インターフェイス クラス GUID は、IHV/OEM によってカスタム定義できます。 ただし、GUID_DEVINTERFACE_LAMP のデバイス インターフェイス クラス GUID は Windows によって定義されます。
コントラクトでは、次の関数をサポートするために、デバイス インターフェイス、GUID_DEVINTERFACE_LAMP を公開するドライバーが必要です (詳細については、後のセクションを参照してください)。
IOCTL_LAMP_GET_CAPABILITIES_{WHITE|COLOR} – 基になるハードウェアでサポートされているすべてのモード (白のみとカラー色など) を取得する
IOCTL_LAMP_{GET|SET}_MODE – 現在のモードを取得または設定する
IOCTL_LAMP_{GET|SET}_INTENSITY_{WHITE|COLOR} – 光の強度を取得または設定する
IOCTL_LAMP_{GET|SET}_EMITTING_LIGHT – フラッシュ状態 (ON/OFF など) を取得または設定する
デバイスに異なる種類の複数のフラッシュ ハードウェア (白色 LED と Xenon フラッシュの両方など) があり、これらのハードウェアが異なるフラッシュ ドライバーによって制御されている場合、各ドライバーは、一意のインスタンス ID を持つ同じ GUID_DEVINTERFACE_LAMP インターフェイスを公開する必要があります。
デバイス インターフェイス プロパティ
コンピューティング デバイスは、異なるパネル上に 0 個以上のフラッシュ デバイスを含めることができるため、WinRT Lamp API には、アプリケーションが特定のインスタンスをプログラムできるように、すべてのフラッシュ ハードウェアを列挙するメカニズムが必要です。
カメラ ドライバーと同様に、デバイスの列挙をサポートするには、フラッシュ ドライバーは、ACPI _PLD v2 構造体をインターフェイス のプロパティ データとして各 GUID_DEVINTERFACE_LAMP インターフェイスに関連付ける必要があります。
IOCTL_LAMP_GET_CAPABILITIES_WHITE
IOCTL_LAMP_GET_CAPABILITIES_WHITE I/O 要求は、デバイスが白色ライトを出力するように構成されている場合にフラッシュの機能を照会します。
Definition
#define IOCTL_LAMP_BASE FILE_DEVICE_UNKNOWN
#define IOCTL_LAMP_GET_CAPABILITIES_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0000, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、LAMP_CAPABILITIES_WHITE 種類のバッファーを指します。 詳細については、「解説」を参照してください。
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength は、Irp->AssociatedIrp.SystemBuffer フィールドで渡されるバッファーの長さ (バイト単位) です。
出力パラメーター
Irp->AssociatedIrp.SystemBuffer には、フラッシュ ハードウェアでサポートされているすべての機能が用意されています。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。 Irp->IoStatus.Information は、バッファーを保持するために必要なバイト数に設定されます。
解説
必要に応じて、ドライバーが GUID_DEVINTERFACE_LAMP インターフェイスをサポートするフラッシュは、白色ライトの出力をサポートするために必要です。 この IOCTL のペイロードは、次のように定義されます。
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_WHITE.
typedef struct LAMP_CAPABILITIES_WHITE
{
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_WHITE;
IsLightIntensityAdjustable フィールドは、輝度レベルをプログラムできるかどうかを示します。 このフィールドが False と評価された場合は、基になるデバイスがオン/オフ スイッチのみをサポートし、光の強度を調整できないことを意味します。
IOCTL_LAMP_GET_CAPABILITIES_COLOR
IOCTL_LAMP_GET_CAPABILITIES_COLOR I/O 要求は、デバイスがカラー色ライトを出力するように構成されている場合にフラッシュの機能を照会します。
Definition
#define IOCTL_LAMP_GET_CAPABILITIES_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0001, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、LAMP_CAPABILITIES_COLOR 種類のバッファーを指します。 詳細については、「解説」を参照してください。
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength は、Irp->AssociatedIrp.SystemBuffer フィールドで渡されるバッファーの長さ (バイト単位) です。
出力パラメーター
Irp->AssociatedIrp.SystemBuffer には、フラッシュ ハードウェアでサポートされているすべての機能が用意されています。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。 Irp->IoStatus.Information は、バッファーを保持するために必要なバイト数に設定されます。
解説
この IOCTL のペイロードは、次のように定義されます。
// The output parameter type of IOCTL_LAMP_GET_CAPABILITIES_COLOR.
typedef struct LAMP_CAPABILITIES_COLOR
{
BOOLEAN IsSupported;
BOOLEAN IsLightIntensityAdjustable;
} LAMP_CAPABILITIES_COLOR;
最初のフィールド IsSupported は、フラッシュがカラー色ライトを放出できるかどうかを示します。 ハードウェアがカラー色ライトをサポートしていない場合、ドライバーはこのフィールドを False に設定する必要があります。
第 2 のフィールド、IsLightIntensityAdjustable は、輝度レベルをプログラムできるかどうかを示します。 フラッシュがカラー色ライトをサポートしていない場合 (たとえば、IsSupported は False と評価)、クライアントは IsLightIntensityAdjustable の値を破棄する必要があります。
IOCTL_LAMP_GET_MODE
IOCTL_LAMP_GET_MODE I/O 要求は、フラッシュが現在構成されているモードを照会します。
Definition
#define IOCTL_LAMP_GET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0002, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、次のように定義されている LAMP_MODE 種類のバッファーを指します。
typedef enum LAMP_MODE
{
LAMP_MODE_WHITE = 0,
LAMP_MODE_COLOR
} LAMP_MODE;
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength は、Irp->AssociatedIrp.SystemBuffer フィールドで渡されるバッファーの長さ (バイト単位) です。
出力パラメーター
Irp->AssociatedIrp.SystemBuffer には、LAMP_MODE 値が格納されます。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。 Irp->IoStatus.Information は、DWORD 値を保持するために必要なバイト数に設定されます。
この要求が行われた時点で MediaCapture セッションがデータをストリーミングしている場合、ドライバーは Irp->IoStatus.Status 経由でエラー (STATUS_RESOURCE_IN_USE) を返す必要があります。
IOCTL_LAMP_SET_MODE
IOCTL_LAMP_SET_MODE I/O 要求は、フラッシュが動作するモードを設定します。
Definition
#define IOCTL_LAMP_SET_MODE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0003, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、LAMP_MODE 種類のバッファーを指します。
出力パラメーター
なし。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。
この要求が行われた時点で MediaCapture セッションがデータをストリーミングしている場合、ドライバーは Irp->IoStatus.Status 経由でエラー (STATUS_RESOURCE_IN_USE) を返す必要があります。
IOCTL_LAMP_GET_INTENSITY_WHITE
IOCTL_LAMP_GET_INTENSITY_WHITE I/O 要求は、フラッシュが白色ライトを放射するように構成されている場合に、光の強度を照会します。
Definition
#define IOCTL_LAMP_GET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0004, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、LAMP_INTENSITY_WHITE 構造体を指します。 詳細については、「解説」を参照してください。
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength は、Irp->AssociatedIrp.SystemBuffer フィールドで渡されるバッファーの長さ (バイト単位) です。
出力パラメーター
Irp->AssociatedIrp.SystemBuffer には、光の強度情報が入力されます。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。
この要求が行われた時点で MediaCapture セッションがデータをストリーミングしている場合、ドライバーは Irp->IoStatus.Status 経由でエラー (STATUS_RESOURCE_IN_USE) を返す必要があります。
解説
この IOCTL のペイロード種類は、次のように定義されます。
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_WHITE.
typedef struct LAMP_INTENSITY_WHITE
{
BYTE Value;
} LAMP_INTENSITY_WHITE;
値フィールドは、0-100 の間の白色ライトの強度 (パーセント単位) です。
IOCTL_LAMP_SET_INTENSITY_WHITE
IOCTL_LAMP_SET_INTENSITY_WHITE I/O 要求は、フラッシュを指定された光強度に設定します。
Definition
#define IOCTL_LAMP_SET_INTENSITY_WHITE \
CTL_CODE(IOCTL_LAMP_BASE, 0x0005, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、LAMP_INTENSITY_WHITE 構造体を指します (詳細については、「IOCTL_LAMP_GET_INTENSITY_WHITE」を参照)。
出力パラメーター
なし。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。
この要求が行われた時点で MediaCapture セッションがデータをストリーミングしている場合、ドライバーは Irp->IoStatus.Status 経由でエラー (STATUS_RESOURCE_IN_USE) を返す必要があります。
IOCTL_LAMP_GET_INTENSITY_COLOR
IOCTL_LAMP_GET_INTENSITY_COLOR I/O 要求は、フラッシュがカラー色ライトを放射するように構成されている場合に、光の強度を照会します。
Definition
#define IOCTL_LAMP_GET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0006, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、LAMP_INTENSITY_COLOR 構造体を指します。 詳細については、「解説」を参照してください。
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength は、Irp->AssociatedIrp.SystemBuffer フィールドで渡されるバッファーの長さ (バイト単位) です。
出力パラメーター
Irp->AssociatedIrp.SystemBuffer には、光の強度情報が入力されます。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。
この要求が行われた時点で MediaCapture セッションがデータをストリーミングしている場合、ドライバーは Irp->IoStatus.Status 経由でエラー (STATUS_RESOURCE_IN_USE) を返す必要があります。
解説
この IOCTL のペイロード種類は、次のように定義されます。
// The I/O parameter type of IOCTL_LAMP_{GET|SET}_INTENSITY_COLOR.
typedef struct LAMP_INTENSITY_COLOR
{
BYTE Red; // Red light intensity in percentage (0-100)
BYTE Green; // Green light intensity in percentage (0-100)
BYTE Blue; // Blue light intensity in percentage (0-100)
} LAMP_INTENSITY_COLOR;
IOCTL_LAMP_SET_INTENSITY_COLOR
IOCTL_LAMP_SET_INTENSITY_COLOR I/O 要求は、フラッシュを指定された光強度に設定します。
Definition
#define IOCTL_LAMP_SET_INTENSITY_COLOR \
CTL_CODE(IOCTL_LAMP_BASE, 0x0007, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、LAMP_INTENSITY_COLOR 構造体を指します (詳細については、「IOCTL_LAMP_GET_INTENSITY_COLOR」を参照)。
出力パラメーター
なし。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。
この要求が行われた時点で MediaCapture セッションがデータをストリーミングしている場合、ドライバーは Irp->IoStatus.Status 経由でエラー (STATUS_RESOURCE_IN_USE) を返す必要があります。
IOCTL_LAMP_GET_EMITTING_LIGHT
(フラッシュ) ライトがオンになっている場合の IOCTL_LAMP_GET_EMITTING_LIGHT I/O 要求クエリ。
Definition
#define IOCTL_LAMP_GET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0008, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は BOOLEAN 種類のバッファーを指します。
IO_STACK_LOCATION.Parameters.DeviceIoControl.OutputBufferLength は、Irp->AssociatedIrp.SystemBuffer フィールドで渡されるバッファーの長さ (バイト単位) です。
出力パラメーター
Irp->AssociatedIrp.SystemBuffer は、フラッシュがオンになっていることを意味する TRUE のフラッシュ状態で満たされ (たとえば、発光など)、それ以外の場合は、FALSE になります。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。 Irp->IoStatus.Information は、DWORD 値を保持するために必要なバイト数に設定されます。
この要求が行われた時点で MediaCapture セッションがデータをストリーミングしている場合、ドライバーは Irp->IoStatus.Status 経由でエラー (STATUS_RESOURCE_IN_USE) を返す必要があります。
IOCTL_LAMP_SET_EMITTING_LIGHT
IOCTL_LAMP_SET_EMITTING_LIGHT I/O 要求は、(フラッシュ) ライトのオン/オフを切り替えます。
Definition
#define IOCTL_LAMP_SET_EMITTING_LIGHT
CTL_CODE(IOCTL_LAMP_BASE, 0x0009, METHOD_BUFFERED, FILE_ANY_ACCESS)
入力パラメーター
Irp->AssociatedIrp.SystemBuffer は、オン状態を示す TRUE を持つ BOOLEAN 種類のバッファーを指し、それ以外の場合は FALSE になります。
出力パラメーター
なし。
I/O の状態ブロック
ドライバーは、Irp->IoStatus.Status を STATUS_SUCCESS または適切なエラー状態に設定します。
この要求が行われた時点で MediaCapture セッションがデータをストリーミングしている場合、ドライバーは Irp->IoStatus.Status 経由でエラー (STATUS_RESOURCE_IN_USE) を返す必要があります。
非同期通知
コンカレンシーユース ケースで説明されているように、フラッシュ ドライバーは、リソースの可用性を報告するために PnP 通知を送信する必要があります。 これを行うには、シナリオに応じて、次の GUID を使用して IoReportTargetDeviceChange (または IoReportTargetDeviceChangeAsynchronous) を呼び出します。
キャプチャ セッション (または別のフラッシュライト アプリケーション) が開始されたため、フラッシュ リソースは削除されました。
Attribute 設定 識別子 GUID_LAMP_RESOURCES_LOST クラス GUID {F770E98C-4403-48C9-B1D2-4EEC3302E41F} フラッシュ リソースが使用可能になりました。
Attribute 設定 識別子 GUID_LAMP_RESOURCES_AVAILABLE クラス GUID {185FE7CE-2616-481B-9094-20BB893ACD81}
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示