IAMVideoControl Interface

The IAMVideoControl interface enables you to flip a picture horizontally and/or vertically, set up a stream so it can capture from an external trigger (such as a camera button that the user pushes), simulate an external trigger in software, and list the available frame rates.

This interface uses the video control flags in the VideoControlFlags enumeration.

Implement this interface when your filter needs to control the video image or to list the frame rates.

Use this interface when your application runs on hardware that is capable of flipping and external triggering.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IAMVideoControl methods Description
GetCaps Retrieves the capabilities of the underlying hardware.
SetMode Sets the video control mode of operation.
GetMode Retrieves the video control mode of operation.
GetCurrentActualFrameRate Retrieves the actual frame rate at which the device is streaming. This method is used with devices, such as the Universal Serial Bus (USB) or cameras that use the IEEE 1394 serial standard, where the maximum frame rate can be limited by bandwidth availability. This is only available during video streaming.
GetMaxAvailableFrameRate Retrieves the maximum frame rate currently available based on bus bandwidth usage for connections such as USB and IEEE 1394 camera devices where the maximum frame rate can be limited by bandwidth availability.
GetFrameRateList Retrieves a list of available frame rates.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMVideoControl methods	Description
GetCaps	Retrieves the capabilities of the underlying hardware.
SetMode	Sets the video control mode of operation.
GetMode	Retrieves the video control mode of operation.
GetCurrentActualFrameRate	Retrieves the actual frame rate at which the device is streaming. This method is used with devices, such as the Universal Serial Bus (USB) or cameras that use the IEEE 1394 serial standard, where the maximum frame rate can be limited by bandwidth availability. This is only available during video streaming.
GetMaxAvailableFrameRate	Retrieves the maximum frame rate currently available based on bus bandwidth usage for connections such as USB and IEEE 1394 camera devices where the maximum frame rate can be limited by bandwidth availability.
GetFrameRateList	Retrieves a list of available frame rates.

IAMVideoControl::GetCaps

IAMVideoControl Interface

Retrieves the capabilities of the underlying hardware.

Syntax

HRESULT GetCaps (

  IPin *pPin,

  long *pCapsFlags

  );

Parameters

pPin
[in] Pointer to the pin to query capabilities from.
pCapsFlags
[out] Pointer to a value representing a combination of the flags from the VideoControlFlags enumeration.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Possible capabilities include one or more of the following: flipping the picture horizontally, flipping the picture vertically, enabling external triggers, and simulating external triggers.

IAMVideoControl::GetCurrentActualFrameRate

IAMVideoControl Interface

Retrieves the actual frame rate, expressed as a frame duration in 100-nanosecond units. USB (Universal Serial Bus) and IEEE 1394 cameras may provide lower frame rates than requested because of bandwidth availability. This is only available during video streaming.

Syntax

HRESULT GetCurrentActualFrameRate (

  IPin *pPin,

  LONGLONG *ActualFrameRate

  );

Parameters

pPin
[in] Pointer to the pin to retrieve the frame rate from.
ActualFrameRate
[out] Pointer to the frame rate in frame duration in 100-nanosecond units.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMVideoControl::GetFrameRateList

IAMVideoControl Interface

Retrieves a list of available frame rates.

Syntax

HRESULT GetFrameRateList (

  IPin *pPin,

  long iIndex,

  SIZE Dimensions,

  long *ListSize,

  LONGLONG **FrameRates

  );

Parameters

pPin
[in] Pointer to the pin to query for the list of frame rates.
iIndex
[in] Index of the format to query for frame rates. This index corresponds to the order in which formats are enumerated by IAMStreamConfig::GetStreamCaps. The value must range between zero and the number of supported VIDEO_STREAM_CONFIG_CAPS structures returned by IAMStreamConfig::GetNumberOfCapabilities) minus one.
Dimensions
[in] Frame image size (width and height) in pixels.
ListSize
[out] Pointer to the number of elements in the list of frame rates.
FrameRates
[out] Address of a pointer to an array of frame rates in 100-nanosecond units. Can be NULL if you only need ListSize.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The caller is responsible for freeing the memory through a call to CoTaskMemFree.

IAMVideoControl::GetMaxAvailableFrameRate

IAMVideoControl Interface

Retrieves the maximum frame rate currently available, based on bus bandwidth usage for connections, such as USB and IEEE 1394, where the maximum frame rate may be limited by bandwidth availability.

Syntax

HRESULT GetMaxAvailableFrameRate(

  IPin *pPin,

  long iIndex,

  SIZE Dimensions,

  LONGLONG *MaxAvailableFrameRate

  );

Parameters

pPin
[in] Pointer to the pin to retrieve the maximum frame rate from.
iIndex
[in] Index of the format to query for maximum frame rate. This index corresponds to the order in which formats are enumerated by IAMStreamConfig::GetStreamCaps. The value must range between zero and the number of supported VIDEO_STREAM_CONFIG_CAPS structures returned by IAMStreamConfig::GetNumberOfCapabilities) minus one.
Dimensions
[in] Frame image size (width and height) in pixels.
MaxAvailableFrameRate
[out] Pointer to the maximum available frame rate. The frame rate is expressed as frame duration in 100-nanosecond units.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMVideoControl::GetMode

IAMVideoControl Interface

Retrieves the video control mode of operation.

Syntax

HRESULT GetMode (

  IPin *pPin,

  long *Mode

  );

Parameters

pPin
[in] Pointer to the pin to retrieve the video control mode from.
Mode
[out] Pointer to a value representing a combination of the flags from the VideoControlFlags enumeration, which specify the video control mode.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Possible modes of operation include one or more of the following: flipping the picture horizontally, flipping the picture vertically, enabling external triggers, and simulating external triggers.

IAMVideoControl::SetMode

IAMVideoControl Interface

Sets the video control mode of operation.

Syntax

HRESULT SetMode (

  IPin *pPin,

  long Mode

  );

Parameters

pPin
[in] Pointer to the pin to set the video control mode on.
Mode
[in] Value specifying a combination of the flags from the VideoControlFlags enumeration to set the video control mode.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Possible modes of operation include one or more of the following: flipping the picture horizontally, flipping the picture vertically, enabling external triggers, and simulating external triggers.