## 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.

When to Implement

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

When a capture filter runs, it sends frame numbers beginning with the sequence 0, 1, 2, 3 (numbers will be missing if frames were dropped). The time stamp of each frame sent corresponds to the filter graph clock's time when the image was digitized. The end time is the start time plus the video frame's duration.

Set the media time of each sample by using CMediaSample::SetMediaTime and using frame numbers for the start and end times. For example, the start-time and end-time sequence might appear as follows: (0,1) (1,2) (2,3). A downstream filter can easily tell that a frame was dropped by checking for gaps in the frame number sequence rather than by looking for gaps in the regular time stamps. The following start-time and end-time sequence reveals that frame number 3 was dropped: (1,2) (2,3) (4,5) (5,6).

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

If your filter runs, pauses, and then runs again, you must continue to deliver frames as if it never paused. The first frame after the second run can't be time stamped earlier than the last frame sent before the pause. That is, your filter must always increment the media time of each sample sent. Never send the same frame number twice, and never go back in time.

When to Use

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.

If you are using a WDM video capture filter, you can only query an output pin for this interface if the capture filter is connected to another filter in the graph.

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.

###

IAMDroppedFrames::GetAverageFrameSize

IAMDroppedFrames Interface

Retrieves the average size of frames that the pin dropped.

HRESULT GetAverageFrameSize(
long * plAverageSize );

##### Parameters

plAverageSize
  [out, retval] Average size of frames sent out the pin since the pin started streaming, in bytes.

##### Return Values

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

###

IAMDroppedFrames::GetDroppedInfo

IAMDroppedFrames Interface

Retrieves an array of frame numbers that the pin dropped.

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 Values

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.

HRESULT GetNumDropped(
long * plDropped );

##### Parameters

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

##### Return Values

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).

HRESULT GetNumNotDropped(
long * plNotDropped );

##### Parameters

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

##### Return Values

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

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.