IMFExtendedCameraControl

このインターフェイスは、キャプチャデバイスの拡張プロパティを構成するために使用します。

このインターフェイスのインスタンスは、IMFExtendedCameraController::GetExtendedCameraControl を呼び出して取得します。

サポートされないプロパティ

一部の KSCAMERA_EXTENDEDPROP_ プロパティは、この API ではサポートされていない点に注意してください。それらの機能は、クライアントアプリからは WinRT のメディアキャプチャ API を通じてのみアクセスできます。

KSPROPERTY_CAMERACONTROL_EXTENDED_WARMSTART

このプロパティの動作は、次の WinRT API を通じて公開されます。

• PrepareLowLagPhotoCaptureAsync
• PrepareLowLagRecordToCustomSinkAsync
• PrepareLowLagRecordToStorageFileAsync
• PrepareLowLagRecordToStreamAsync

これらの API は、選択されたメディアタイプでキャプチャパイプラインを構成し、ドライバーピンを一時停止状態にします。これによりドライバーに対して、その操作に必要なハードウェアリソースを割り当て・構成するよう通知されます。これは、リソースの準備を前倒しで行うことで、レイテンシを最小化するのに役立ちます。

ウォームスタート機能はキャプチャデバイスにとって任意のコントロールである点に注意してください。したがって、そのコントロールが利用できない場合、上記の API はウォームスタントの動作を提供しません。ただしこれらの API はキャプチャのシンク側は引き続き構成するため、使用することで一定の利点があります。

KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOMODE

このプロパティの動作は、次の WinRT API を通じて公開されます。

• PrepareLowLagPhotoSequenceCaptureAsync
• PrepareVariablePhotoSequenceCaptureAsync

これらの API は、パイプラインのキャプチャ側とシンク側の両方を構成し、ドライバーピンを実行状態にして、フレームをキャプチャしますが、まだパイプラインには渡しません。フレームは、キャプチャ操作が開始されたときにパイプラインを通じて渡され始めます。

この機能はキャプチャデバイスにとって任意のコントロールである点に注意してください。したがって、そのコントロールが利用できない場合、上記の API はエラーを返します。

例

次の例は、KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON フラグを設定し、その設定をコミットする方法を示します。

if (FAILED(m_cameraController->GetExtendedCameraControl(MF_CAPTURE_ENGINE_MEDIASOURCE,
    KSPROPERTY_CAMERACONTROL_EXTENDED_TORCHMODE,
    cameraControl.put())))
{
    // Return false to indicate that the Torch Mode control is not available.
    return false;
}

ULONGLONG capabilities = cameraControl->GetCapabilities();

// Check if the torch can be turned on.
if (capabilities & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON)
{
    // Check if the torch is off.
    if ((cameraControl->GetFlags() & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON) == 0)
    {
        // Torch is off. Tell the camera to turn it on.
        check_hresult(cameraControl->SetFlags(KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON));
        // Write the changed settings to the driver.
        check_hresult(cameraControl->CommitSettings());
    }
}

キャプチャデバイスがサポートするプロパティ機能を照会します。

プロパティ機能に対応する ULONGLONG です。サポートされるプロパティと機能は、ksmedia.h で定義されるヘッダーファイル内に、命名規則 KSCAMERA_EXTENDEDPROP_ に従った定数として定義されています。詳細については、KSPROPERTYSETID_ExtendedCameraControl を参照してください。

特定の機能が存在するかどうかは、この関数の戻り値とビットごとの AND 演算を行うことで確認します。一部のドライバーでは、どのコントロールがサポートされているかを判別できるようにするために、カメラデバイスのプレビューが実行状態である必要があります。プレビューストリームが実行される前に特定のコントロールがサポートされているかを確認した場合、そのコントロールはビデオデバイスによってサポートされていても、サポートされていない(したがって利用できない)と示されることがあります。

次の例は、KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON 機能のサポートを照会する方法を示します。

if (FAILED(m_cameraController->GetExtendedCameraControl(MF_CAPTURE_ENGINE_MEDIASOURCE,
    KSPROPERTY_CAMERACONTROL_EXTENDED_TORCHMODE,
    cameraControl.put())))
{
    // Return false to indicate that the Torch Mode control is not available.
    return false;
}

ULONGLONG capabilities = cameraControl->GetCapabilities();

// Check if the torch can be turned on.
if (capabilities & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON)
{
    // Check if the torch is off.
    if ((cameraControl->GetFlags() & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON) == 0)
    {
        // Torch is off. Tell the camera to turn it on.
        check_hresult(cameraControl->SetFlags(KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON));
        // Write the changed settings to the driver.
        check_hresult(cameraControl->CommitSettings());
    }
}

キャプチャデバイス上のプロパティにフラグを設定します。

成功した場合は S_OK を返します。

プロパティフラグを設定する前に、IMFExtendedCameraControl::GetCapabilities を呼び出してサポートされる機能を確認できます。次の例は、KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON 機能のサポートを照会する方法を示します。

if (FAILED(m_cameraController->GetExtendedCameraControl(MF_CAPTURE_ENGINE_MEDIASOURCE,
    KSPROPERTY_CAMERACONTROL_EXTENDED_TORCHMODE,
    cameraControl.put())))
{
    // Return false to indicate that the Torch Mode control is not available.
    return false;
}

ULONGLONG capabilities = cameraControl->GetCapabilities();

// Check if the torch can be turned on.
if (capabilities & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON)
{
    // Check if the torch is off.
    if ((cameraControl->GetFlags() & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON) == 0)
    {
        // Torch is off. Tell the camera to turn it on.
        check_hresult(cameraControl->SetFlags(KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON));
        // Write the changed settings to the driver.
        check_hresult(cameraControl->CommitSettings());
    }
}

キャプチャデバイス上のプロパティフラグを照会します。

プロパティフラグに対応する ULONGLONG です。サポートされるプロパティとフラグは、ksmedia.h で定義されるヘッダーファイル内に、命名規則 KSCAMERA_EXTENDEDPROP_ に従った定数として定義されています。詳細については、KSPROPERTYSETID_ExtendedCameraControl を参照してください。

キャプチャデバイス上のプロパティフラグは、IMFExtendedCameraControl::SetFlags を呼び出して設定します。プロパティフラグを設定する前に、IMFExtendedCameraControl::GetCapabilities を呼び出してサポートされる機能を確認できます。次の例は、KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON 機能のサポートを照会する方法を示します。

if (FAILED(m_cameraController->GetExtendedCameraControl(MF_CAPTURE_ENGINE_MEDIASOURCE,
    KSPROPERTY_CAMERACONTROL_EXTENDED_TORCHMODE,
    cameraControl.put())))
{
    // Return false to indicate that the Torch Mode control is not available.
    return false;
}

ULONGLONG capabilities = cameraControl->GetCapabilities();

// Check if the torch can be turned on.
if (capabilities & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON)
{
    // Check if the torch is off.
    if ((cameraControl->GetFlags() & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON) == 0)
    {
        // Torch is off. Tell the camera to turn it on.
        check_hresult(cameraControl->SetFlags(KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON));
        // Write the changed settings to the driver.
        check_hresult(cameraControl->CommitSettings());
    }
}

ペイロードの照会または変更を可能にするため、キャプチャデバイスコントロールに含まれる内部ペイロードバッファをロックします。

成功した場合は S_OK を返します。

キャプチャデバイスコントロールに含まれる生のペイロードのロックを解除します。

成功した場合は S_OK を返します。

キャプチャデバイスコントロール内のペイロードは、IMFExtendedCameraControl::LockPayload を呼び出してロックします。

構成したコントロール設定をカメラドライバーにコミットします。

成功した場合は S_OK を返します。

次の例は、KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON フラグを設定し、その設定をコミットする方法を示します。

if (FAILED(m_cameraController->GetExtendedCameraControl(MF_CAPTURE_ENGINE_MEDIASOURCE,
    KSPROPERTY_CAMERACONTROL_EXTENDED_TORCHMODE,
    cameraControl.put())))
{
    // Return false to indicate that the Torch Mode control is not available.
    return false;
}

ULONGLONG capabilities = cameraControl->GetCapabilities();

// Check if the torch can be turned on.
if (capabilities & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON)
{
    // Check if the torch is off.
    if ((cameraControl->GetFlags() & KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON) == 0)
    {
        // Torch is off. Tell the camera to turn it on.
        check_hresult(cameraControl->SetFlags(KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON));
        // Write the changed settings to the driver.
        check_hresult(cameraControl->CommitSettings());
    }
}