IAMDroppedFrames Interface

The IAMDroppedFrames interface provides information to an application from a capture filter about frames that the filter dropped (that is, did not send), the frame rate achieved (the length of time the graph ran divided by the number of frames not dropped), and the data rate achieved (the length of time the graph ran divided by the average frame size). A high number of dropped frames can detract from the smoothness of the video clip.

If your application uses the IAMStreamControl interface or ICaptureGraphBuilder::ControlStream to turn a pin off, a video capture driver may still be counting dropped and non-dropped frames, whose counts probably don't interest you. If your application is interested in the number of dropped and non-dropped frames only while the pin is ON, you can ask for the dropped and non-dropped counts by calling IAMDroppedFrames::GetNumDropped and IAMDroppedFrames::GetNumNotDropped immediately after turning on a pin with IAMStreamControl::StartAt or ICaptureGraphBuilder::ControlStream, and then subtract those numbers from the numbers returned from subsequent calls to GetNumDropped or GetNumNotDropped to find out just the number dropped while the pin was on (which is probably the figure you are interested in). If your call to IAMStreamControl::StartAt or ICaptureGraphBuilder::ControlStream is not a call to turn the pin on immediately, but instead turns the pin on at some specified time in the future, then you should wait until you get the notification (EC_STREAM_CONTROL_STARTED) before calling GetNumDropped and GetNumNotDropped initially. See the documentation on IAMStreamControl for more information on this. See the CAPTURE sample for an example of a capture application that uses both interfaces correctly.

A capture filter's video output pin should always implement this interface.

Every time a capture filter goes from State_Stopped to State_Paused, it should reset all counts to zero.

For more implementation details regarding this interface, see Write a Video Capture Filter.

Applications should use this interface all the time when capturing to update the current capture status. After capturing is done, applications should use this interface to determine the final capture results.

Note Not all methods of this interface might be implemented. Many filters only implement GetNumDropped and GetNumNotDropped.

Methods in Vtable Order

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

IAMDroppedFrames methods Description

GetNumDropped Retrieves the total number of frames that the pin dropped since it last started streaming.
GetNumNotDropped Retrieves the total number of frames that the pin delivered downstream (did not drop).
GetDroppedInfo Retrieves an array of frame numbers that were dropped.
GetAverageFrameSize Retrieves the average size of frames that were not dropped.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMDroppedFrames methods	Description
GetNumDropped	Retrieves the total number of frames that the pin dropped since it last started streaming.
GetNumNotDropped	Retrieves the total number of frames that the pin delivered downstream (did not drop).
GetDroppedInfo	Retrieves an array of frame numbers that were dropped.
GetAverageFrameSize	Retrieves the average size of frames that were not dropped.

IAMDroppedFrames::GetAverageFrameSize

IAMDroppedFrames Interface

Retrieves the average size of frames that the pin dropped.

Syntax

HRESULT GetAverageFrameSize(
    long *plAverageSize );

Parameters

plAverageSize
[out, retval] Pointer to the average size of frames sent out by the pin since the pin started streaming, in bytes.

Return Value

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

Remarks

If no data is captured in the call to GetAverageFrameSize, plAverageSize will return with the value of zero.

IAMDroppedFrames::GetDroppedInfo

IAMDroppedFrames Interface

Retrieves an array of frame numbers that the pin dropped.

Syntax

HRESULT GetDroppedInfo(
    long lSize,
    long *plArray,
    long *plNumCopied );

Parameters

lSize
[in] Requested number of elements in the array.
plArray
[out] Pointer to the array.
plNumCopied
[out, retval] Pointer to the number of array elements filled in. This number can differ from lSize because the filter determines an arbitrary number of elements to save and it might not save this information for as many frames as you requested.

Return Value

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

Remarks

The filter will fill the array with the frame numbers of up to the first lSize number of frames dropped, and it will set plNumCopied accordingly.

IAMDroppedFrames::GetNumDropped

IAMDroppedFrames Interface

Retrieves the total number of frames that the pin dropped since it last started streaming.

Syntax

HRESULT GetNumDropped(
    long *plDropped );

Parameters

plDropped
[out] Pointer to the total number of dropped frames.

Return Value

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

IAMDroppedFrames::GetNumNotDropped

IAMDroppedFrames Interface

Retrieves the total number of frames that the pin delivered downstream (did not drop).

Syntax

HRESULT GetNumNotDropped(
  long *plNotDropped );

Parameters

plNotDropped
[out] Pointer to the total number of frames that weren't dropped.

Return Value

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