CVideoTransformFilter Class

CVideoTransformFilter class hierarchy

The CVideoTransformFilter class is designed primarily as a base class for AVI decompressor filters. It is based on a "copying" transform class and assumes that the output buffer will likely be a video buffer or Microsoft® DirectDraw® buffer, although this could be used as a base class for other types of transform filters. The main feature of this class is that it enables quality-control management in a transform filter. This means that it decides to drop frames based on receiving a quality notification from the renderer, and taking into account other factors about the media stream it is processing and the filter's own behavior.

Every time the CVideoTransformFilter::Receive member function is called, it calls CVideoTransformFilter::ShouldSkipFrame to determine whether to start, continue, or stop skipping frames. This member function starts skipping samples only if all the following conditions are true.

The average time to decode is more than one fourth of the frame time.
The filter is running at least one frame late.
The next anticipated key frame is estimated to be no more than one frame early.
The occurrence of key frames is sufficiently frequent.

After the class starts to skip frames, it will skip all frames until a key frame appears, at which time it resets the m_bSkipping flag and processes the sample.

Key frames are defined as AVI key frames or MPEG I frames. These require no history to decode and, if they are skipped, no other frames can be decoded until the next key frame. Non-key frames include AVI non-key frames, MPEG P frames, and MPEG B frames. MPEG B frames are treated the same as other non-key frames by this class. (MPEG B frames can be dropped without the need to skip further frames; however, because this class is aimed primarily at AVI decompressors, it does not allow for this. Once any frame is skipped, all frames are skipped up to the next key frame.)

Protected Data Members

m_bNoSkip Set to TRUE to prevent skipping to the next key frame (for debugging the filter).
m_bQualityChanged Status flag that indicates if the stream has degraded. This is set to TRUE in CVideoTransformFilter::Receive if the call to the derived class Transform member function fails. (Receive returns NOERROR in this case because returning S_FALSE indicates that end-of-stream has arrived.)
m_bSkipping Set to TRUE if the filter is skipping to the next key frame.
m_idFrameType Performance-measuring frame type identifier (available if PERF is defined). Logs 1 for key frames; logs 2 for nonkey frames.
m_idLate Performance identifier for measuring lateness (available if PERF is defined).
m_idSkip Performance identifier for measuring frame skipping (available if PERF is defined).
m_idTimeTillKey Performance identifier that represents an estimate of the time in milliseconds until the next key frame arrives (available if PERF is defined).
m_itrAvgDecode Average time required to decode (transform) the sample. If this is less than one-fourth of the frame time, it is assumed the quality problems are not being generated by this filter and no frames are dropped.
m_itrLate Amount of time that the current frame is late. This is originally set to the value of the Quality structure's Late member passed in the quality control message from the renderer filter. It is decremented by the frame time of each frame that is skipped.
m_nFramesSinceKeyFrame Used to count frames since the last key frame.
m_nKeyFramePeriod The largest observed interval between key frames.
m_nWaitForKey Used to ensure output after a format change before getting the first key frame. When nonzero, frames are not passed to the renderer. Set to 30 when format is changed and decremented on each nonkey frame.
m_tDecodeStart Time since the start of the decoding.

Member Functions

AlterQuality Receives a quality-control notification from the output pin and provides an opportunity to alter the quality of the media stream.
CVideoTransformFilter Constructs a CVideoTransformFilter object.
ShouldSkipFrame Determines if the filter should start, continue, or stop skipping frames.

Overridable Member Functions

EndFlush Receives notification of leaving the flushing state and passes it downstream.
Receive Receives the media sample and either skips the sample or transforms and delivers the media sample.
RegisterPerfId Registers a performance measurement identifier.
StartStreaming Overrides CTransformFilter::StartStreaming to reset the quality control information when streaming starts or flushing starts.

CVideoTransformFilter::AlterQuality

CVideoTransformFilter Class

Receives a quality-control notification and provides an opportunity to alter the quality of the media stream.

Syntax

virtual HRESULT AlterQuality(
    Quality q
);

Parameters

q
Quality-control notification message.

Return Value

Returns E_FAIL by default.

Remarks

This member function overrides the CTransformFilter::AlterQuality member function. It is called by the CTransformOutputPin::Notify member function before calling the CBaseInputPin::PassNotify member function to pass the quality control message upstream. This function sets the CVideoTransformFilter::m_itrLate data member to the value Quality structure's Late member so that the filter can determine whether to skip frames. It returns E_FAIL so that the renderer downstream will continue to handle quality control.

CVideoTransformFilter::CVideoTransformFilter

CVideoTransformFilter Class

Constructs a CVideoTransformFilter object.

Syntax

CVideoTransformFilter(
    TCHAR *pName,
    LPUNKNOWN pUnk,
    REFCLSID clsid
);

Parameters

pName
Pointer to the name given to the CVideoTransformFilter object.
pUnk
Pointer to the controlling IUnknown interface.
clsid
Class identifier of the CVideoTransformFilter class.

Return Value

No return value.

CVideoTransformFilter::EndFlush

CVideoTransformFilter Class

Receives notification that the filter is leaving the flushing state and passes it downstream.

Syntax

HRESULT EndFlush(void);

Return Value

Returns VFW_E_NOT_CONNECTED if the filter finds no input pin; otherwise, returns the value that the IPin::EndFlush method returns.

Remarks

This member function overrides the CTransformFilter::EndFlush member function to reset quality management information.

CVideoTransformFilter::Receive

CVideoTransformFilter Class

Receives the media sample and either skips the sample or transforms and delivers the media sample.

Syntax

HRESULT Receive(
    IMediaSample *pSample
);

Parameters

pSample
Pointer to the sample to deliver.

Return Value

Returns an HRESULT value.

Remarks

This member function overrides the CTransformFilter::Receive member function. Override only if you need more control of the process.

CVideoTransformFilter::RegisterPerfId

CVideoTransformFilter Class

Registers performance measurement identifiers.

Syntax

virtual void RegisterPerfId(void);

Return Value

No return value.

Remarks

By default, this member function registers the following performance identifiers.

Performance identifier Registered string

m_idSkip Video transform skip frame
m_idFrameType Video transform frame type
m_idLate Video transform lateness
m_idTimeTillKey Video transform estimated time to next key

This member function also calls CTransformFilter::RegisterPerfId for its performance identifier.
Override this member function if you want to register performance measurement identifiers in the derived class. If you do this, be sure to register these as well. This member function is enabled only when PERF is defined.

Performance identifier	Registered string
m_idSkip	Video transform skip frame
m_idFrameType	Video transform frame type
m_idLate	Video transform lateness
m_idTimeTillKey	Video transform estimated time to next key

CVideoTransformFilter::ShouldSkipFrame

CVideoTransformFilter Class

Determines if the filter should start, continue, or stop skipping frames.

Syntax

BOOL ShouldSkipFrame(
    IMediaSample *pIn
);

Parameters

pIn
Pointer to the received sample to be transformed or skipped.

Return Value

Returns TRUE if the filter should skip this sample; otherwise, returns FALSE.

Remarks

This member function sets the m_bSkipping member variable to FALSE if the sample is a key frame (sync point) and returns FALSE. This stops any skipping that has started. This member function starts skipping samples (sets m_bSkipping to TRUE and returns TRUE) only if all the following conditions are true.

The average time to decode is more than one-fourth of the frame time.
The filter is running at least one frame late.
The next anticipated key frame is estimated to be no more than one frame early.
The occurrence of key frames is sufficiently frequent.

This member function sends an EC_QUALITY_CHANGE notification when sample skipping starts. After skipping starts, all samples are skipped until the next key frame arrives.

CVideoTransformFilter::StartStreaming

CVideoTransformFilter Class

Overrides CTransformFilter::StartStreaming to reset the quality control information when streaming starts or flushing starts.

Syntax

virtual HRESULT StartStreaming(void);

Return Value

Returns NOERROR.

Remarks

This member function sets several quality control member variables to 0, including m_itrLate, m_nKeyFramePeriod, m_nFramesSinceKeyFrame, m_bSkipping, and m_tDecodeStart. It sets m_itrAvgDecode to 3000, and sets m_bQualityChanged and m_bSampleSkipped to FALSE.

m_bNoSkip	Set to TRUE to prevent skipping to the next key frame (for debugging the filter).
m_bQualityChanged	Status flag that indicates if the stream has degraded. This is set to TRUE in CVideoTransformFilter::Receive if the call to the derived class Transform member function fails. (Receive returns NOERROR in this case because returning S_FALSE indicates that end-of-stream has arrived.)
m_bSkipping	Set to TRUE if the filter is skipping to the next key frame.
m_idFrameType	Performance-measuring frame type identifier (available if PERF is defined). Logs 1 for key frames; logs 2 for nonkey frames.
m_idLate	Performance identifier for measuring lateness (available if PERF is defined).
m_idSkip	Performance identifier for measuring frame skipping (available if PERF is defined).
m_idTimeTillKey	Performance identifier that represents an estimate of the time in milliseconds until the next key frame arrives (available if PERF is defined).
m_itrAvgDecode	Average time required to decode (transform) the sample. If this is less than one-fourth of the frame time, it is assumed the quality problems are not being generated by this filter and no frames are dropped.
m_itrLate	Amount of time that the current frame is late. This is originally set to the value of the Quality structure's Late member passed in the quality control message from the renderer filter. It is decremented by the frame time of each frame that is skipped.
m_nFramesSinceKeyFrame	Used to count frames since the last key frame.
m_nKeyFramePeriod	The largest observed interval between key frames.
m_nWaitForKey	Used to ensure output after a format change before getting the first key frame. When nonzero, frames are not passed to the renderer. Set to 30 when format is changed and decremented on each nonkey frame.
m_tDecodeStart	Time since the start of the decoding.

AlterQuality	Receives a quality-control notification from the output pin and provides an opportunity to alter the quality of the media stream.
CVideoTransformFilter	Constructs a CVideoTransformFilter object.
ShouldSkipFrame	Determines if the filter should start, continue, or stop skipping frames.

EndFlush	Receives notification of leaving the flushing state and passes it downstream.
Receive	Receives the media sample and either skips the sample or transforms and delivers the media sample.
RegisterPerfId	Registers a performance measurement identifier.
StartStreaming	Overrides CTransformFilter::StartStreaming to reset the quality control information when streaming starts or flushing starts.