Microsoft DirectX 8.0

CTransformFilter Class

CTransformFilter class hierarchy

Base class for implementing a transform filter.

Declaration: Transfrm.h

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 GetPin method. If you do override the pin classes, you must override GetPin to create your custom pins.

By default, the input pin does not propose a media type during the connection process. Therefore, the input connection will be made using a media type proposed by the upstream filter (assuming that any are valid). You should still register the input media types when you register the filter, so that the filter mapper will find it. For more information, see How to Register DirectShow Filters.

The output pin proposes a media type through the filter's GetMediaType method, which the derived class must implement. The output pin will refuse a connection unless the input pin has been connected.

This class does not queue the output data. Each output sample is delivered from inside the IMemInputPin::Receive method.

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.

Protected Member Variables
m_bEOSDeliveredFlag that indicates whether the filter has sent an end-of-stream notification.
m_bSampleSkippedFlag that indicates whether the most recent sample was dropped.
m_bQualityChangedFlag that indicates whether the quality has changed.
m_csFilterCritical section that protects the filter state.
m_csReceiveCritical section that protects the streaming state.
m_pInputPointer to the input pin.
m_pOutputPointer to the output pin.
Public Methods
CTransformFilterConstructor method.
~CTransformFilterDestructor method.
GetPinCountRetrieves the number of pins on the filter. Virtual.
GetPinRetrieves a pin. Virtual.
TransformTransforms an input sample to produce an output sample. Virtual.
StartStreamingCalled when the filter switches to the paused state. Virtual.
StopStreamingCalled when the filter switches to the stopped state. Virtual.
AlterQualityNotifies the filter that a quality change is requested. Virtual.
SetMediaTypeCalled when the media type is set on one of the filter's pins. Virtual.
CheckConnectDetermines whether a pin connection is suitable. Virtual.
BreakConnectReleases a pin from a connection. Virtual.
CompleteConnectCompletes a pin connection. Virtual.
ReceiveReceives a media sample, processes it, and delivers an output sample to the downstream filter. Virtual.
InitializeOutputSampleRetrieves a new output sample and initializes it.
EndOfStreamNotifies the filter that no additional data is expected from the input pin. Virtual.
BeginFlushBegins a flush operation. Virtual.
EndFlushEnds a flush operation. Virtual.
NewSegmentNotifies the filter that media samples received after this call are grouped as a segment. Virtual.
Pure Virtual Methods
CheckInputTypeChecks whether a specified media type is acceptable for input.
CheckTransformChecks whether an input media type is compatible with an output media type.
DecideBufferSizeSets the output pin's buffer requirements.
GetMediaTypeRetrieves a preferred media type for the output pin.
IMediaFilter Methods
StopStops the filter.
PausePauses the filter.
IBaseFilter Methods
FindPinRetrieves the pin with the specified identifier.

CTransformFilter.m_bEOSDelivered

CTransformFilter Class

Flag that indicates whether the filter has sent an end-of-stream notification.

Syntax

BOOL m_bEOSDelivered;

Syntax

If the filter pauses when it does not have an input connection, it sends an end-of-stream notification downstream and sets this flag to TRUE. The end-of-stream notification ensures that the downstream filter does not wait for samples. Note that the filter's EndOfStream method does not set this flag.

CTransformFilter.m_bSampleSkipped

CTransformFilter Class

Flag that indicates whether the most recent sample was dropped. If the Receive method drops a sample, it sets the value to TRUE.

Syntax

BOOL m_bSampleSkipped;

CTransformFilter.m_bQualityChanged

CTransformFilter Class

Flag that indicates whether the quality has changed. The first time that the filter drops a sample, it sends an EC_QUALITY_CHANGE event to the filter graph manager and sets this flag to TRUE. It does not send this event again until the filter stops and restarts, even if it continues to drop samples in the meantime.

Syntax

BOOL m_bQualityChanged;

CTransformFilter.m_csFilter

CTransformFilter Class

Critical section that protects the filter state. For more information, see Data Flow for Filter Developers.

Syntax

CCritSec m_csFilter;

CTransformFilter.m_csReceive

CTransformFilter Class

Critical section that protects the streaming state. For more information, see Data Flow for Filter Developers.

Syntax

CCritSec m_csReceive;

CTransformFilter.m_pInput

CTransformFilter Class

Pointer to the input pin.

Syntax

CTransformInputPin *m_pInput;

CTransformFilter.m_pOutput

CTransformFilter Class

Pointer to the output pin.

Syntax

CTransformOutputPin *m_pOutput;

CTransformFilter::AlterQuality

CTransformFilter Class

Notifies the filter that a quality change is requested.

Syntax

virtual HRESULT AlterQuality(
    Quality q
);

Parameters

q
Quality structure that contains the quality control message.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_FALSEDid not handle the quality message. The message should be passed upstream.
S_OKHandled the quality message. No further action is necessary.

The base class returns S_FALSE.

Remarks

Override this method if the filter can perform quality control. For more information, see Quality-Control Management.

CTransformFilter::BeginFlush

CTransformFilter Class

Begins a flush operation.

Syntax

virtual HRESULT BeginFlush(void);

Return Value

Returns S_OK or another HRESULT value.

Remarks

At the start of a flush operation, the input pin's CTransformInputPin::BeginFlush method calls this method. This method passes the BeginFlush call downstream.

If the derived class uses a worker thread to deliver samples, it should discard any queued data during a flush operation. That can be done either in the BeginFlush method, or in the EndFlush method. However, note that calls to BeginFlush are not synchronized with the streaming thread. If the BeginFlush method discards the queued data, the filter must be careful not to process any more data between the BeginFlush and EndFlush calls. For more information, see Data Flow for Filter Developers.

CTransformFilter::BreakConnect

CTransformFilter Class

Releases a pin from a connection.

Syntax

virtual HRESULT BreakConnect(
    PIN_DIRECTION dir
);

Parameters

dir
Member of the PIN_DIRECTION enumerated type, specifying which pin connection was broken (input or output).

Return Value

Returns S_OK.

Remarks

The CTransformInputPin::BreakConnect and CTransformOutputPin::BreakConnect methods call this method when a pin connection is broken. This method does nothing in the base class. If you override the CheckConnect method, override this method to release any resources obtained in the CheckConnect method, including interface pointers.

CTransformFilter::CheckConnect

CTransformFilter Class

Determines whether a pin connection is suitable.

Syntax

virtual HRESULT CheckConnect(
    PIN_DIRECTION dir,
    IPin *pPin
);

Parameters

dir
Member of the PIN_DIRECTION enumerated type, specifying which pin on the filter is making the connection.
pPin
Pointer to the IPin interface of the other pin in this connection attempt.

Return Value

Returns S_OK.

Remarks

The CTransformInputPin::CheckConnect and CTransformOutputPin::CheckConnect methods call this method during the pin connection process. This method does nothing in the base class. The derived class can override it. For example, the derived class might query the other pin for a particular interface.

CTransformFilter::CheckInputType

CTransformFilter Class

Checks whether a specified media type is acceptable for input.

Syntax

virtual HRESULT CheckInputType(
    const CMediaType *mtIn
) PURE;

Parameters

mtIn
Pointer to a CMediaType object that specifies the media type.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKMedia type is acceptable.
VFW_E_TYPE_NOT_ACCEPTEDMedia type is not acceptable.

Remarks

The derived class must implement this method. Return S_OK if the proposed input format is acceptable, or an error code otherwise.

This method does not need to verify that the input format is compatible with the output format (if any). The input pin verifies that by calling the CheckTransform method.

CTransformFilter::CheckTransform

CTransformFilter Class

Checks whether an input media type is compatible with an output media type.

Syntax

virtual HRESULT CheckTransform(
    const CMediaType *mtIn,
    const CMediaType *mtOut
) PURE;

Parameters

mtIn
Pointer to a CMediaType object that specifies the input type.
mtOut
Pointer to a CMediaType object that specifies the output type.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKThe media types are compatible.
VFW_E_TYPE_NOT_ACCEPTEDThe media types are not compatible.

Remarks

The derived class must implement this method. Return S_OK if the filter can accept both of the specified media types, or an error code otherwise.

CTransformFilter::CompleteConnect

CTransformFilter Class

Completes a pin connection.

Syntax

virtual HRESULT CompleteConnect(
    PIN_DIRECTION direction,
    IPin *pReceivePin
);

Parameters

direction
Member of the PIN_DIRECTION enumerated type, specifying which pin on the filter is making the connection.
pReceivePin
Pointer to the IPin interface of the other pin in this connection attempt.

Return Value

Returns S_OK.

Remarks

The CTransformInputPin::CompleteConnect and CTransformOutputPin::CompleteConnect methods call this method during the pin connection process. This method does nothing in the base class, but the derived class can override it.

CTransformFilter::CTransformFilter

CTransformFilter Class

Constructor method.

Syntax

CTransformFilter(
    TCHAR *pObjectName,
    LPUNKNOWN lpUnk,
    CLSID clsid
);

Parameters

pObjectName
String containing the debug name of the filter. For more information, see CBaseObject.
lpUnk
Pointer to the owner of this object. If the object is aggregated, pass a pointer to the aggregating object's IUnknown interface. Otherwise, set this parameter to NULL.
clsid
Class identifier of the filter.

Remarks

The constructor does not create the filter's pins. That happens during the first call to the GetPin method. The constructor initializes the m_pInput and m_pOutput member variables to NULL.

CTransformFilter::~CTransformFilter

CTransformFilter Class

Destructor method.

Syntax

~CTransformFilter(void);

CTransformFilter::DecideBufferSize

CTransformFilter Class

Sets the output pin's buffer requirements.

Syntax

virtual HRESULT DecideBufferSize(
    IMemAllocator *pAlloc,
    ALLOCATOR_PROPERTIES *ppropInputRequest
) PURE; 

Parameters

pAlloc
Pointer to the IMemAllocator interface on the output pin's allocator.
ppropInputRequest
Pointer to an ALLOCATOR_PROPERTIES structure that contains buffer requirements from the downstream input pin.

Return Value

Returns S_OK or another HRESULT value.

Remarks

The output pin's CTransformOutputPin::DecideBufferSize method calls this method. The derived class must implement this method. For more information, see CBaseOutputPin::DecideBufferSize.

CTransformFilter::EndFlush

CTransformFilter Class

Ends a flush operation.

Syntax

virtual HRESULT EndFlush(void);

Return Value

Returns S_OK or another HRESULT value.

Remarks

At the end of a flush operation, the input pin's CTransformInputPin::EndFlush method calls this method. This method passes the EndFlush call downstream.

If the derived class uses a worker thread to deliver samples, it must discard any queued data before sending the EndFlush call downstream. For more information, see Data Flow for Filter Developers.

CTransformFilter::EndOfStream

CTransformFilter Class

Notifies the filter that no additional data is expected from the input pin.

Syntax

virtual HRESULT EndOfStream(void);

Return Value

Returns S_OK or another HRESULT value.

Remarks

The input pin's CTransformInputPin::EndOfStream method calls this method. This method delivers the end-of-stream notification downstream. If the derived class uses a worker thread to deliver media samples, it should override this method and queue the end-of-stream notification.

CTransformFilter::FindPin

CTransformFilter Class

Retrieves the pin with the specified identifier. Implements the IBaseFilter::FindPin method.

Syntax

HRESULT FindPin(
    LPCWSTR Id,
    IPin **ppPin
);

Parameters

Id
Wide-character string that contains the pin identifier.
ppPin
Address of a variable that receives a pointer to the pin's IPin interface. If the method fails, *ppPin is set to NULL.

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.
VFW_E_NOT_FOUNDCould not find a pin with this identifier.

Remarks

The identifier for the input pin is In, and the identifier for the output pin is Out.

CTransformFilter::GetMediaType

CTransformFilter Class

Retrieves a preferred media type for the output pin.

Syntax

virtual HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
) PURE;

Parameters

iPosition
Zero-based index value.
pMediaType
Pointer to a CMediaType object that receives the media type.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OK Success.
VFW_S_NO_MORE_ITEMSIndex out of range.
E_INVALIDARGIndex less than zero.

Remarks

The output pin's CTransformOutputPin::GetMediaType method calls this method. The derived class must implement this method. For more information, see CBasePin::GetMediaType.

CTransformFilter::GetPin

CTransformFilter Class

Retrieves a pin.

Syntax

virtual CBasePin *GetPin(
    int n
);

Parameters

n
Number of the specified pin, indexed from zero. On this filter, pin 0 is the input pin, and pin 1 is the output pin.

Return Value

Returns a pointer to the CBasePin object that implements the pin, or NULL if the method fails.

Remarks

This method implements the pure virtual CBaseFilter::GetPin method. The first time the method is called, it creates both pins.

This method does not increment the reference count on the returned pin, so the returned pin does not have an outstanding reference count. If the caller needs to keep a reference on the pin, it should call the IUnknown::AddRef method on the pin.

If the filter uses the default CTransformInputPin and CTransformOutputPin pins, you probably do not need to override this method. If the filter uses pins that extend those classes, however, you must override this method to create pins of that type.

CTransformFilter::GetPinCount

CTransformFilter Class

Retrieves the number of pins on the filter.

Syntax

virtual int GetPinCount(void);

Return Value

Returns 2.

Remarks

This method overrides the CBaseFilter::GetPinCount method. This class supports exactly one input pin and one output pin.

CTransformFilter::InitializeOutputSample

CTransformFilter Class

Retrieves a new output sample and initializes it.

Syntax

HRESULT InitializeOutputSample(
    IMediaSample *pSample, 
    IMediaSample **ppOutSample
);

Parameters

pSample
Pointer to the input sample's IMediaSample interface.
ppOutSample
Address of a variable that receives a pointer to the output sample's IMediaSample interface.

Return Value

Returns S_OK or another HRESULT value.

Remarks

This method retrieves a new sample from the output pin's allocator. Then it copies the sample properties from the input sample to the output sample.

CTransformFilter::NewSegment

CTransformFilter Class

Notifies the filter that media samples received after this call are grouped as a segment.

Syntax

virtual HRESULT NewSegment(
    REFERENCE_TIME tStart,
    REFERENCE_TIME tStop,
    double dRate
);

Parameters

tStart
Start time of the segment, relative to the original source.
tStop
Stop time of the segment, relative to the original source.
dRate
Rate at which the segment should be processed.

Return Value

Returns S_OK.

Remarks

The input pin's CTransformInputPin::NewSegment method calls this method. This method delivers the NewSegment call to the downstream input pin.

CTransformFilter::Pause

CTransformFilter Class

Pauses the filter. Implements the IMediaFilter::Pause method.

Syntax

HRESULT Pause(void);

Return Value

Returns S_OK or another HRESULT value.

Remarks

This method calls the StartStreaming method. The StartStreaming method does nothing in the base class, but the derived class can override it.

CTransformFilter::Receive

CTransformFilter Class

Receives a media sample, processes it, and delivers an output sample to the downstream filter.

Syntax

HRESULT Receive(
    IMediaSample *pSample
);

Parameters

pSample
Pointer to the IMediaSample interface on the input sample.

Return Value

Returns an HRESULT value.

Remarks

The filter's input pin calls this method when it receives a sample. This method calls the InitializeOutputSample method, which prepares a new output sample. Then it calls the Transform method, which the derived class must implement. The Transform method processes the input data and produces output data.

If the Transform method returns S_FALSE, the Receive method drops this sample. On the first dropped sample, the filter sends an EC_QUALITY_CHANGE event to the filter graph manager. Otherwise, if the Transform method returns S_OK, the filter delivers the output sample. To do so, it calls the IMemInputPin::Receive method on the downstream input pin.

CTransformFilter::SetMediaType

CTransformFilter Class

Called when the media type is set on one of the filter's pins.

Syntax

virtual HRESULT SetMediaType(
    PIN_DIRECTION direction,
    const CMediaType *pmt
);

Parameters

direction
Member of the PIN_DIRECTION enumerated type, specifying a pin on the filter (input or output).
pmt
Pointer to a CMediaType object that specifies the media type.

Return Value

Returns S_OK.

Remarks

The CTransformInputPin::SetMediaType and CTransformOutputPin::SetMediaType methods call this method when a pin's media type is set. This method does nothing in the base class, but the derived class can override it.

CTransformFilter::StartStreaming

CTransformFilter Class

Called when the filter switches to the paused state.

Syntax

virtual HRESULT StartStreaming(void);

Return Value

Returns S_OK.

Remarks

This method does nothing in the base class, but the derived class can override it.

CTransformFilter::Stop

CTransformFilter Class

Stops the filter. Implements the IMediaFilter::Stop method.

Syntax

HRESULT Stop(void);

Return Value

Returns S_OK or another HRESULT value.

Remarks

After this method decommits both allocators, it calls the StopStreaming method. The StopStreaming method does nothing in the base class, but the derived class can override it.

CTransformFilter::StopStreaming

CTransformFilter Class

Called when the filter switches to the stopped state.

Syntax

virtual HRESULT StopStreaming(void);

Return Value

Returns S_OK.

Remarks

This method does nothing in the base class, but the derived class can override it.

CTransformFilter::Transform

CTransformFilter Class

Transforms an input sample to produce an output sample.

Syntax

virtual HRESULT Transform(
    IMediaSample *pIn,
    IMediaSample *pOut
)

Parameters

pIn
Pointer to the input sample's IMediaSample interface.
pOut
Pointer to the output sample's IMediaSample interface.

Return Value

The base class returns E_UNEXPECTED.

The derived class should return an HRESULT value, indicating success or failure. Possible values include those shown in the following table.

S_FALSEDo not deliver this sample.
S_OKSuccess.

Remarks

Override this method to produce output data. Read the input data from the sample specified by the pIn parameter, and write the new data into the sample specified by the pOut parameter.

Before the filter calls this method, it copies the properties from the input sample to the output sample. The Transform method should set any properties that differ between the two samples, using IMediaSample methods or the IMediaSample2 interface (if available).

If the filter should not deliver this sample (for example, to support quality control), the method should return S_FALSE.