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.

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.

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

Top of Page