CTransformFilter class

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

ctransformfilter class hierarchy

The CTransformFilter class is a base class for implementing transform filters. This class is designed for implementing a transform filter with one input pin and one output pin. It uses separate allocators for the input pin and the output pin. To create a filter that processes data in place, use the CTransInPlaceFilter class.

This filter uses the CTransformInputPin class for its input pin, and the CTransformOutputPin class for its output pin. Typically, you do not need to override these pin classes. Most of the pin methods call corresponding methods on the CTransformFilter class, so you can override the filter methods if necessary. The filter creates both pins in the CTransformFilter::GetPin method. If you do override the pin classes, you must override GetPin to create your custom pins.

To use this class, derive a new class from CTransformFilter and implement the following methods:

You might need to override other methods as well, depending on the requirements of your filter.

Media Types

This filter's input pin does not propose any media types; it relies on the upstream filter to propose the media types for the connection. The reason for this design is that in most cases, the upstream filter can provide more information about the format. For example, with video formats, the upstream filter knows the video dimensions and the frame rate, whereas the transform filter has no way to determine this information. If you want to change this behavior, override the input pin's GetMediaType method. When the upstream filter proposes a media type, the input pin calls the filter's CheckInputType method (pure virtual).

Until the input pin is connected, the output pin refuses all connections, and does not return any preferred media types. After the input pin is connected, the output pin returns a list of preferred types by calling the filter's GetMediaType method. It checks output types for the connection through the filter's CheckTransform method. (Both methods are pure virtual.) Typically, the input type will partly determine the acceptable output types.

Depending on the filter, you might want to register some of the filter's supported media types, so that the Filter Mapper object can locate your filter. For more information, see How to Register DirectShow Filters.

Streaming

This class does not queue the output data. Each output sample is delivered inside the IMemInputPin::Receive method. The Receive method calls the filter's Transform method (also pure virtual) to process the data.

For more information about using this class, see Writing Transform Filters.

Protected Member Variables Description
m_bEOSDelivered Flag that indicates whether the filter has sent an end-of-stream notification.
m_bSampleSkipped Flag that indicates whether the most recent sample was dropped.
m_bQualityChanged Flag that indicates whether the quality has changed.
m_csFilter Critical section that protects the filter state.
m_csReceive Critical section that protects the streaming state.
m_pInput Pointer to the input pin.
m_pOutput Pointer to the output pin.
Public Methods Description
CTransformFilter Constructor method.
~ CTransformFilter Destructor method.
GetPinCount Retrieves the number of pins on the filter. Virtual.
GetPin Retrieves a pin. Virtual.
Transform Transforms an input sample to produce an output sample. Virtual.
StartStreaming Called when the filter switches to the paused state. Virtual.
StopStreaming Called when the filter switches to the stopped state. Virtual.
AlterQuality Notifies the filter that a quality change is requested. Virtual.
SetMediaType Called when the media type is set on one of the filter's pins. Virtual.
CheckConnect Determines whether a pin connection is suitable. Virtual.
BreakConnect Releases a pin from a connection. Virtual.
CompleteConnect Completes a pin connection. Virtual.
Receive Receives a media sample, processes it, and delivers an output sample to the downstream filter. Virtual.
InitializeOutputSample Retrieves a new output sample and initializes it.
EndOfStream Notifies the filter that no additional data is expected from the input pin. Virtual.
BeginFlush Begins a flush operation. Virtual.
EndFlush Ends a flush operation. Virtual.
NewSegment Notifies the filter that media samples received after this call are grouped as a segment. Virtual.
Pure Virtual Methods Description
CheckInputType Checks whether a specified media type is acceptable for input.
CheckTransform Checks whether an input media type is compatible with an output media type.
DecideBufferSize Sets the output pin's buffer requirements.
GetMediaType Retrieves a preferred media type for the output pin.
IMediaFilter Methods Description
Stop Stops the filter.
Pause Pauses the filter.
IBaseFilter Methods Description
FindPin Retrieves the pin with the specified identifier.

Requirements

Requirement Value
Header
Transfrm.h (include Streams.h)
Library
Strmbase.lib (retail builds);
Strmbasd.lib (debug builds)