CTransformFilter is an abstract base class that supports a simple transform filter with a single input and a single output. It is derived from the CUnknown class, and it supports the IBaseFilter interface. Each pin, declared as Friends in this class, supports the IPin interface and uses the shared memory transport based on the IMemInputPin interface. The filter uses classes derived from the CBaseFilter class to support IBaseFilter; the CTransformInputPin input pin class is derived from the CBaseInputPin class, and the CTransformOutputPin output pin class is derived from the CBaseOutputPin class.
Note that, while most member functions in this class are designed to be overridden, the following pure virtual member functions must be overridden.
For more information about using this class to create a transform filter, see Creating a Transform Filter.
Protected Data Members
| Name | Description |
| m_idTransform | Identifier used for performance measurement. Available only when PERF is defined. |
| m_pInput | Pointer to the input pin class object. |
| m_pOutput | Pointer to the output pin class object. |
| m_csFilter | Critical section that protects the filter state. This critical section is held whenever the state is currently changing or might change. It is passed to the CBaseMediaFilter constructor so that the base class uses it too. |
| m_csReceive | Critical section that is held when processing events that occur on the receiving thread (CTransformInputPin::Receive and CTransformInputPin::EndOfStream). |
| m_bEOSDelivered | End-of-stream delivery status flag. |
| m_bSampleSkipped | Status flag that indicates if a frame was skipped. |
| m_bQualityChanged | Status flag that indicates if the stream has degraded. This is set to TRUE in CTransformFilter::Receive if the call to the derived class's Transform member function fails (CTransformFilter::Receive returns NOERROR in this case because returning S_FALSE indicates that the end-of-stream has arrived). |
Member Functions
| Name | Description |
| CTransformFilter | Constructs a CTransformFilter object. |
Overridable Member Functions
| Name | Description |
| AlterQuality | Receives a quality-control notification from the output pin and provides an opportunity to alter the media stream's quality. |
| BeginFlush | Receives notification of entering the flushing state and passes it downstream. |
| BreakConnect | Informs the derived class when the connection is broken. |
| CheckConnect | Informs the derived class when the connection process is starting. |
| CheckInputType | Verifies that the input pin supports the media type and proposes the media type of the output pin (pure virtual). |
| CheckTransform | Verifies that the input and output pins support the media type (pure virtual). |
| CompleteConnect | Informs the derived class when the connection process has completed. |
| DecideBufferSize | Sets the number and size of buffers required for the transfer (pure virtual). |
| EndFlush | Receives notification of leaving the flushing state and passes it downstream. |
| EndOfStream | Receives an end-of-stream notification and passes it downstream. |
| GetMediaType | Returns one of the media types that the output pin supports (pure virtual). |
| GetPin | Returns the pin for the index specified. |
| GetPinCount | Returns the number of pins on the filter. |
| NewSegment | Informs the derived class that a new segment has started and delivers it downstream. |
| Receive | Receives the media sample, calls the CTransformFilter::Transform member function, and then delivers the media sample. |
| RegisterPerfId | Registers a performance measurement identifier. |
| SetMediaType | Informs the derived class when the media type is established for the connection. |
| StartStreaming | Informs the derived class that streaming is starting. |
| StopStreaming | Informs the derived class that streaming is ending. |
| Transform | Performs transform operations, reading from the input IMediaSample interface and writing the data to the output IMediaSample interface (pure virtual). |
Implemented IBaseFilter Methods
| Name | Description |
| FindPin | Retrieves the pin with the specified identifier. |
| Stop | Transitions the filter to State_Stopped state if it is not in this state already, and informs the derived class. |
| Pause | Transitions the filter to State_Paused state if it is not in this state already, and informs the derived class. |
Receives a quality-control notification and provides an opportunity to alter the media stream's quality.
virtual HRESULT AlterQuality(
Quality q
);
Returns an HRESULT value. S_FALSE means to pass the message to the upstream filter (whether or not any action has been taken). An overriding member function can return NOERROR to indicate that the message has been handled completely (or as completely as possible) and no further action should be taken.
This member function returns S_FALSE by default. It is called by the CTransformOutputPin::Notify member function before calling the CTransformInputPin::PassNotify member function to pass the quality control message upstream. If the filter is responsible for affecting the quality of the media stream, override this member function and respond to the quality-notification message.
Receives notification of entering the flushing state and passes it downstream.
virtual HRESULT BeginFlush( );
Returns an HRESULT value.
By default, this member function calls the CBaseOutputPin::DeliverEndFlush member function on the output pin to send the BeginFlush notification to the next filter. Override this member function if you are using queued data or a worker thread.
Informs the derived class when the connection is broken.
virtual HRESULT BreakConnect(
PIN_DIRECTION dir
);
Returns NOERROR by default. The overriding member function returns an HRESULT value.
This member function is called by both CTransformInputPin::BreakConnect and CTransformOutputPin::BreakConnect. It returns NOERROR by default. Override this member function to handle special cases in both input and output pin connections. Special cases might typically be releasing interfaces obtained in the CTransformFilter::CheckConnect member function.
Informs the derived class when the connection process is starting.
virtual HRESULT CheckConnect(
PIN_DIRECTION dir,
IPin *pPin
);
Returns NOERROR by default. The overriding member function returns an HRESULT value.
This member function is called by both CTransformInputPin::CheckConnect and CTransformOutputPin::CheckConnect. Override this member function to handle special cases in both input and output pin connections. Special cases might include querying (obtaining) other interfaces.
Verifies that the input pin supports the media type, and proposes the output pin's media type.
virtual HRESULT CheckInputType(
const CMediaType* mtIn
)
PURE;
The overriding member function returns an HRESULT value.
You must override this member function to verify the media type. This member function must return an error if it cannot support the media type as an input. If it can, the overriding member function should propose the output media type supplied by the output pin.
Verifies that the input and output pins support the media type.
virtual HRESULT CheckTransform(
const CMediaType* mtIn,
const CMediaType* mtOut
) PURE;
The overriding member function returns an HRESULT value.
The derived class must implement this member function by overriding it. It should return an error if the filter cannot accept these types as its input and output types.
Informs the derived class when the connection process has completed.
virtual HRESULT CompleteConnect(
PIN_DIRECTION direction,
IPin *pReceivePin
);
Returns an HRESULT value.
This member function is called by both CTransformInputPin::CompleteConnect and CTransformOutputPin::CompleteConnect. It returns NOERROR by default. Override this member function to handle special cases in both input and output pin connections.
Constructs a CTransformFilter object.
CTransformFilter(
TCHAR * pObjectName,
LPUNKNOWN lpUnk,
CLSID clsid
);
No return value.
The constructor of the derived class calls this member function. The pin objects are not created at this time; they are created when calling the CTransformFilter::GetPin member function. Thus the pins (m_pInput and m_pOutput) cannot be referred to in the constructor unless GetPin is first called. (An external object can find pins only by enumerating them or by calling IBaseFilter::FindPin. These each call GetPin, so the pins are, in fact, created as soon as they are needed.)
Sets the number and size of buffers required for the transfer.
virtual HRESULT DecideBufferSize(
IMemAllocator * pAlloc,
ALLOCATOR_PROPERTIES * ppropInputRequest
) PURE;
Returns an HRESULT value.
This member function is called by the CTransformOutputPin::DecideBufferSize member function. Override and implement this member function to call the CMemAllocator::SetProperties member function with appropriate values for the output stream. This call might fail if the allocator cannot satisfy the request.
Receives notification of leaving the flushing state and passes it downstream.
virtual HRESULT EndFlush( );
Returns an HRESULT value.
This member function is called by the CTransformInputPin::EndFlush member function. Override this member function if you are using queued data or a worker thread. It calls CBaseOutputPin::DeliverEndFlush to deliver the notification downstream.
Receives an end-of-stream notification and passes it downstream.
virtual HRESULT EndOfStream( );
Returns an HRESULT value.
By default, this member function calls the CBaseOutputPin::DeliverEndOfStream member function on the output pin to send the end-of-stream notification to the next filter. Override this member function if you are using queued data or a worker thread. If you overrode CTransformFilter::Receive and have queued data, you must handle this condition and deliver EOS after all queued data is sent.
Retrieves the pin with the specified identifier.
HRESULT FindPin(
LPCWSTR Id,
IPin **ppPin
);
Returns NOERROR if the pin name was found; otherwise, returns VFW_E_NOT_FOUND.
This member function overrides the CBaseFilter::FindPin member function. If the Id parameter is "In", it retrieves the input pin's IPin pointer; if the Id parameter is "Out", it retrieves the output pin's IPin pointer.
The ppPin parameter is set to NULL if the identifier cannot be matched.
Returns one of the media types that the output pin supports (pure virtual).
virtual HRESULT GetMediaType(
int iPosition,
CMediaType *pMediaType
) PURE;
Returns an HRESULT value by the overriding member function. It returns VFW_S_NO_MORE_ITEMS when asked for a media type beyond the position list. It might return S_FALSE to indicate that the media type exists but is not currently usable. In this case, the IEnumMediaTypes::Next method skips this media type.
The derived class is responsible for implementing this member function and maintaining the list of media types that it supports.
The base transform class assumes that only the output pin proposes media types, because the output pin depends on the type of connection of the input pin. For this reason, it is only the CTransformOutputPin::GetMediaType member function of the output pin that is routed to this function.
Returns a pin for a specified index.
virtual CBasePin * GetPin(
int n
);
Returns a pointer to a CBasePin object.
This member function overrides the CBaseFilter::GetPin member function and need not be overridden unless one or more of the transform pin classes (CTransformInputPin or CTransformOutputPin) are overridden. Upon successful return, both pins are valid.
Returns the number of pins on the filter.
virtual int GetPinCount( );
Returns 2. If you override this class to support more pins, this member function returns the total number of pins on the filter.
This member function overrides the CBaseFilter::GetPinCount member function. The CTransformFilter class supports only one input pin and one output pin.
Informs the derived class that a new segment has started and delivers it downstream.
virtual HRESULT NewSegment(
REFERENCE_TIME tStart,
REFERENCE_TIME tStop,
double dRate
);
Returns an HRESULT value.
This member function is called by the CTransformInputPin::NewSegment member function and calls the CBaseOutputPin::DeliverNewSegment member function.
Transitions the filter to State_Paused state if it is not in this state already, and informs the derived class.
HRESULT Pause (void);
Returns an HRESULT value.
This member function overrides the CBaseFilter::Pause member function and implements the IMediaFilter::Pause method. It checks the input and output pin connections, calls CTransformFilter::StartStreaming, and finally calls the base class implementation (CBaseFilter::Pause).
Receives the media sample, calls the CTransformFilter::Transform member function, and then delivers the media sample.
HRESULT Receive(
IMediaSample *pSample
);
Returns an HRESULT value.
This member function is called by the CTransformInputPin::Receive member function, which implements the IMemInputPin::Receive method. If you override this member function, you might must also override CTransformFilter::EndOfStream, CTransformFilter::BeginFlush, and CTransformFilter::EndFlush.
Registers a performance measurement identifier.
virtual void RegisterPerfId( );
No return value.
By default, this member function registers the performance identifier (m_idTransform) with the string "Transform". Override this member function to register a performance measurement with a less generic string. This should be done to avoid confusion with other filters. This member function is enabled only when PERF is defined.
Informs the derived class when the media type is established for the connection.
virtual HRESULT SetMediaType(
PIN_DIRECTION direction,
const CMediaType *pmt
) PURE;
Returns NOERROR by default. The overriding member function returns an HRESULT value.
Override this member function to detect when the media type is set. The implementations of CTransformInputPin::SetMediaType and CTransformOutputPin::SetMediaType call this member function.
Informs the derived class that streaming is starting.
virtual HRESULT StartStreaming( );
Returns NOERROR by default. The overriding member function returns an HRESULT value.
The filter is in the process of switching to active mode (paused or running). Alternatively, you can override this member function to allocate any necessary resources.
Transitions the filter to State_Stopped state if it is not in this state already, and informs the derived class.
HRESULT Stop(void);
Returns an HRESULT value.
This member function overrides the CBaseFilter::Stop member function and implements the IMediaFilter::Stop method. It first decommits on the input and output pins by calling CBaseInputPin::Inactive and CBaseOutputPin::Inactive, and then calls CTransformFilter::StopStreaming to inform the derived class.
Informs the derived class that streaming is ending.
virtual HRESULT StopStreaming( );
Returns NOERROR by default. The overriding member function returns an HRESULT value.
The filter is in the process of leaving active mode and entering stopped mode. Override this member function to free any resources allocated in StartStreaming.
Performs transform operations of the filter.
virtual HRESULT Transform(
IMediaSample * pIn,
IMediaSample *pOut
) PURE;
The overriding member function returns an HRESULT value. If it returns S_FALSE, the default implementation of the sample will not be delivered by the default implementation of the CTransformFilter::Receive member function.
The CTransformFilter::Receive member function calls this member function, which must be overridden with a member function that implements the transform intended for the filter.
Perform your transform operation in the implementation of this member function, reading the data from the input IMediaSample interface and writing the data to the output IMediaSample interface. The member function returns when the transform is complete, without releasing or delivering either of the samples. Change properties on the output sample if they are not the same as the input sample. For example, change the start and stop time IMediaSample::SetTime), sample status flags (IMediaSample::IsSyncPoint), and so on.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.