Microsoft DirectX 8.0 |
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_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 | |
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 | |
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 | |
Stop | Stops the filter. |
Pause | Pauses the filter. |
IBaseFilter Methods | |
FindPin | Retrieves the pin with the specified identifier. |
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.
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;
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;
Critical section that protects the filter state. For more information, see Data Flow for Filter Developers.
Syntax
CCritSec m_csFilter;
Critical section that protects the streaming state. For more information, see Data Flow for Filter Developers.
Syntax
CCritSec m_csReceive;
Pointer to the input pin.
Syntax
CTransformInputPin *m_pInput;
Pointer to the output pin.
Syntax
CTransformOutputPin *m_pOutput;
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_FALSE Did not handle the quality message. The message should be passed upstream. S_OK Handled 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.
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.
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.
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.
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_OK Media type is acceptable. VFW_E_TYPE_NOT_ACCEPTED Media 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.
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_OK The media types are compatible. VFW_E_TYPE_NOT_ACCEPTED The 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.
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.
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.
Destructor method.
Syntax
~CTransformFilter(void);
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.
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.
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.
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_OK Success. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument. VFW_E_NOT_FOUND Could 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.
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_ITEMS Index out of range. E_INVALIDARG Index 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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_FALSE Do not deliver this sample. S_OK Success.
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.