CTransformFilter Class

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.

• CheckInputType
• CheckTransform
• DecideBufferSize
• GetMediaType
• Transform

For more information about using this class to create a transform filter, see Creating a Transform Filter.

Protected Data Members

m_bEOSDelivered	End-of-stream delivery status flag.
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).
m_bSampleSkipped	Status flag that indicates if a frame was skipped.
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_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.

Member Functions

CTransformFilter

Constructs a CTransformFilter object.

Overridable Member Functions

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	Retrieves one of the media types that the output pin supports (pure virtual).
GetPin	Retrieves the pin for the index specified.
GetPinCount	Retrieves 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

FindPin	Retrieves the pin with the specified identifier.
Pause	Transitions the filter to State_Paused state if it is not in this state already, and informs the derived class.
Stop	Transitions the filter to State_Stopped state if it is not in this state already, and informs the derived class.

CTransformFilter::AlterQuality

---

CTransformFilter Class

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

Syntax

virtual HRESULT AlterQuality(
    Quality q
);

Parameters

q

Quality-control notification message.

Return Value

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.

Remarks

This member function returns S_FALSE by default. It is called by the CTransformOutputPin::Notify member function before calling the CBaseInputPin::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.

CTransformFilter::BeginFlush

---

CTransformFilter Class

Receives notification of entering the flushing state and passes it downstream.

Syntax

virtual HRESULT BeginFlush(void);

Return Value

Returns an HRESULT value.

Remarks

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.

CTransformFilter::BreakConnect

---

CTransformFilter Class

Informs the derived class when the connection is broken.

Syntax

virtual HRESULT BreakConnect(
    PIN_DIRECTION dir
);

Parameters

dir

Direction of the pin.

Return Value

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

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.

CTransformFilter::CheckConnect

---

CTransformFilter Class

Informs the derived class when the connection process is starting.

Syntax

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

Parameters

dir

Direction of the pin.

pPin

Pointer to the pin making the connection.

Return Value

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

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.

CTransformFilter::CheckInputType

---

CTransformFilter Class

Verifies that the input pin supports the media type, and proposes the output pin's media type.

Syntax

virtual HRESULT CheckInputType(
    const CMediaType *mtIn
    )
PURE;

Parameters

mtIn

Pointer to an input media type object.

Return Value

The overriding member function returns an HRESULT value.

Remarks

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.

CTransformFilter::CheckTransform

---

CTransformFilter Class

Verifies that the input and output pins support the media type.

Syntax

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

Parameters

mtIn

Pointer to the input media type object.

mtOut

Pointer to the output media type object.

Return Value

The overriding member function returns an HRESULT value.

Remarks

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.

CTransformFilter::CompleteConnect

---

CTransformFilter Class

Informs the derived class when the connection process has completed.

Syntax

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

Parameters

direction

Pin direction.

pReceivePin

Pointer to the output pin that is being connected to.

Return Value

Returns an HRESULT value. Returns NOERROR by default.

Remarks

This member function is called by both CTransformInputPin::CompleteConnect and CTransformOutputPin::CompleteConnect. Override this member function to handle special cases in both input and output pin connections.

CTransformFilter::CTransformFilter

---

CTransformFilter Class

Constructs a CTransformFilter object.

Syntax

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

Parameters

pObjectName

Pointer to the name given to the CTransformFilter object.

lpUnk

Pointer to the controlling IUnknown interface.

clsid

Class identifier of the CTransformFilter class.

Return Value

No return value.

Remarks

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.)

CTransformFilter::DecideBufferSize

---

CTransformFilter Class

Sets the number and size of buffers required for the transfer.

Syntax

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

Parameters

pAlloc

Pointer to the allocator assigned to the transfer.

ppropInputRequest

Pointer to the requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.

Return Value

Returns an HRESULT value.

Remarks

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.

CTransformFilter::EndFlush

---

CTransformFilter Class

Receives notification of leaving the flushing state and passes it downstream.

Syntax

virtual HRESULT EndFlush(void);

Return Value

Returns an HRESULT value.

Remarks

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.

CTransformFilter::EndOfStream

---

CTransformFilter Class

Receives an end-of-stream notification and passes it downstream.

Syntax

virtual HRESULT EndOfStream(void);

Return Value

Returns an HRESULT value.

Remarks

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.

CTransformFilter::FindPin

---

CTransformFilter Class

Retrieves the pin with the specified identifier.

Syntax

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

Parameters

Id

Pointer to the identifier of the pin.

ppPin

Address of a pointer to the IPin interface for this pin after the filter has been restored.

Return Value

Returns NOERROR if the pin name was found; otherwise, returns VFW_E_NOT_FOUND.

Remarks

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.

CTransformFilter::GetMediaType

---

CTransformFilter Class

Retrieves one of the media types that the output pin supports (pure virtual).

Syntax

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

Parameters

iPosition

Position of the media type in the media type list.

pMediaType

Pointer to the returned media type object.

Return Value

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.

Remarks

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.

CTransformFilter::GetPin

---

CTransformFilter Class

Retrieves a pin for a specified index.

Syntax

virtual CBasePin * GetPin(
    int n
);

Parameters

n

Index of the pin to return.

Return Value

Returns a pointer to a CBasePin object.

Remarks

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.

CTransformFilter::GetPinCount

---

CTransformFilter Class

Retrieves the number of pins on the filter.

Syntax

virtual int GetPinCount(void);

Return Value

Returns 2. If you override this class to support more pins, this member function returns the total number of pins on the filter.

Remarks

This member function overrides the CBaseFilter::GetPinCount member function. The CTransformFilter class supports only one input pin and one output pin.

CTransformFilter::NewSegment

---

CTransformFilter Class

Informs the derived class that a new segment has started and delivers it downstream.

Syntax

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

Parameters

tStart

Start time of the segment.

tStop

Stop time of the segment.

dRate

Rate of the segment.

Return Value

Returns an HRESULT value.

Remarks

This member function is called by the CTransformInputPin::NewSegment member function and calls the CBaseOutputPin::DeliverNewSegment member function.

CTransformFilter::Pause

---

CTransformFilter Class

Transitions the filter to State_Paused state if it is not in this state already, and informs the derived class.

Syntax

HRESULT Pause (void);

Return Value

Returns an HRESULT value.

Remarks

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).

CTransformFilter::Receive

---

CTransformFilter Class

Receives the media sample, calls the CTransformFilter::Transform member function, and then delivers the media sample.

Syntax

HRESULT Receive(
    IMediaSample *pSample
);

Parameters

pSample

Pointer to the media sample to receive.

Return Value

Returns an HRESULT value.

Remarks

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.

CTransformFilter::RegisterPerfId

---

CTransformFilter Class

Registers a performance measurement identifier.

Syntax

virtual void RegisterPerfId(void);

Return Value

No return value.

Remarks

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.

CTransformFilter::SetMediaType

---

CTransformFilter Class

Informs the derived class when the media type is established for the connection.

Syntax

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

Parameters

direction

Pin direction.

pmt

Pointer to the media type object.

Return Value

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

Override this member function to detect when the media type is set. The implementations of CTransformInputPin::SetMediaType and CTransformOutputPin::SetMediaType call this member function.

CTransformFilter::StartStreaming

---

CTransformFilter Class

Informs the derived class that streaming is starting.

Syntax

virtual HRESULT StartStreaming(void);

Return Value

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

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.

CTransformFilter::Stop

---

CTransformFilter Class

Transitions the filter to State_Stopped state if it is not in this state already, and informs the derived class.

Syntax

HRESULT Stop(void);

Return Value

Returns an HRESULT value.

Remarks

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.

CTransformFilter::StopStreaming

---

CTransformFilter Class

Informs the derived class that streaming is ending.

Syntax

virtual HRESULT StopStreaming(void);

Return Value

Returns NOERROR by default. The overriding member function returns an HRESULT value.

Remarks

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.

CTransformFilter::Transform

---

CTransformFilter Class

Performs transform operations of the filter.

Syntax

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

Parameters

pIn

Pointer to the input IMediaSample interface.

pOut

Pointer to the output IMediaSample interface.

Return Value

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.

Remarks

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.

---

 Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.