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

Name	Description
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

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

virtual HRESULT AlterQuality(
  Quality q
  );

Parameters

q

Quality-control notification message.

Return Values

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.

virtual HRESULT BeginFlush( );

Return Values

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.

virtual HRESULT BreakConnect(
  PIN_DIRECTION dir
  );

Parameters

dir

Direction of the pin.

Return Values

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.

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

Parameters

dir

Direction of the pin.

pPin

Pointer to the pin making the connection.

Return Values

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.

virtual HRESULT CheckInputType(
  const CMediaType* mtIn
  )
PURE;

Parameters

mtIn

Pointer to an input media type object.

Return Values

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.

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 Values

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.

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

Parameters

direction

Pin direction.

pReceivePin

Pointer to the output pin that is being connected to.

Return Values

Returns an HRESULT value.

Remarks

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.

---

CTransformFilter::CTransformFilter

CTransformFilter Class

Constructs a CTransformFilter object.

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

Parameters

pObjectName

Name given to the CTransformFilter object.

lpUnk

Pointer to LPUNKNOWN.

clsid

Class identifier of the CTransformFilter class.

Return Values

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.

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

Parameters

pAlloc

Allocator assigned to the transfer.

ppropInputRequest

Requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.

Return Values

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.

virtual HRESULT EndFlush( );

Return Values

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.

virtual HRESULT EndOfStream( );

Return Values

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.

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

Parameters

Id

Identifier of the pin.

ppPin

Pointer to the IPin interface for this pin after the filter has been restored.

Return Values

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

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

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

Parameters

iPosition

Position of the media type in the media type list.

pMediaType

Returned media type object.

Return Values

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

Returns a pin for a specified index.

virtual CBasePin * GetPin(
  int n
  );

Parameters

n

Index of the pin to return.

Return Values

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

Returns the number of pins on the filter.

virtual int GetPinCount( );

Return Values

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.

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 Values

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.

HRESULT Pause (void);

Return Values

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.

HRESULT Receive(
  IMediaSample *pSample
  );

Parameters

pSample

Media sample to receive.

Return Values

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.

virtual void RegisterPerfId( );

Return Values

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.

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

Parameters

direction

Pin direction.

pmt

Pointer to the media type object.

Return Values

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.

virtual HRESULT StartStreaming( );

Return Values

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.

HRESULT Stop(void);

Return Values

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.

virtual HRESULT StopStreaming( );

Return Values

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.

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

Parameters

pIn

Pointer to the input IMediaSample interface.

pOut

Pointer to the output IMediaSample interface.

Return Values

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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page