IMFExtendedCameraControl interface (mfidl.h)

Article
02/16/2023

This interface is used to configure a capture device's extended properties. Supported properties and capabilities are defined in the header file defined in ksmedia.h as constants with the naming convention KSCAMERA_EXTENDEDPROP_.

Inheritance

The IMFExtendedCameraControl interface inherits from the IUnknown interface.

Methods

The IMFExtendedCameraControl interface has these methods.


IMFExtendedCameraControl::CommitSettings Commits the configured control settings to the camera driver.
IMFExtendedCameraControl::GetCapabilities Queries for property capabilities supported by the capture device.
IMFExtendedCameraControl::GetFlags Queries for property flags on the capture device.
IMFExtendedCameraControl::LockPayload Locks the internal payload buffer contained in the capture device control to enable querying or changing the payload.
IMFExtendedCameraControl::SetFlags Sets the flags for a property on the capture device.
IMFExtendedCameraControl::UnlockPayload Unlocks the raw payload contained in the capture device control.

Remarks

Get an instance of this interface by calling IMFExtendedCameraController::GetExtendedCameraControl

Unsupported properties

Note that some KSCAMERA_EXTENDEDPROP_ properties are unsupported for this API. Their functionality can only be accessed by client apps through the WinRT media capture APIs.

KSPROPERTY_CAMERACONTROL_EXTENDED_WARMSTART

The behavior of this property is exposed through the following WinRT APIs:

These APIs cause the capture pipeline to be configured with the selected media type and put the driver pin is put into a paused state, which informs the driver to get the hardware resources allocated/configured for the operation. This helps to minimize the latency by front-loading the preparation of resources.

Note that the warm start functionality is an optional control for capture devices, so if the control is not available, the APIs above will not provide the warm start behavior. These APIs will still configure the sink side of the capture so there is some benefit to using them.

KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOMODE

The behavior of this property is exposed through the following WinRT APIs:

These APIs configure the both the capture and sink side of the pipeline and put the driver pin into the running state, capturing frames but not yet passing the frames to the pipeline. The frames begin passing through the pipeline when the capture operation is started.

Note that this functionality is an optional control for capture devices, so if the control is not available, the APIs above return an error.

Examples

The following example demonstrates setting the KSCAMERA_EXTENDEDPROP_VIDEOTORCH_ON flag and committing the setting.

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());
    }
}

Requirements

Requirement	Value
Minimum supported client	Windows 10 Build 20348
Minimum supported server	Windows 10 Build 20348
Header	mfidl.h

Share via