DirectShow Animated Header -- CTransInPlaceFilter Class DirectShow Animated Header -- CTransInPlaceFilter Class* Microsoft DirectShow SDK
*Index  *Topic Contents
*Previous Topic: CTransformOutputPin Class
*Next Topic: CTransInPlaceInputPin Class

CTransInPlaceFilter Class


CTransInPlaceFilter class hierarchy

CTransInPlaceFilter is an abstract base class that provides support for a simple transform filter with a single input and a single output. It is derived from the CUnknown class, and supports the IBaseFilter interface, the IMediaFilter interface, and two pins. Each pin supports the IPin interface and uses the shared memory transport based on the IMemInputPin interface. The filter uses classes derived from the CBaseMediaFilter class to support IBaseFilter and IMediaFilter. The input pin is derived from the CBaseInputPin class, and the output pin is derived from the CBaseOutputPin class.

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

Protected Data Members
Name Description
m_idTransInPlace Performance-measuring identifier.

Member Functions
Name Description
Copy Returns a pointer to an identical copy of a media sample.
CTransInPlaceFilter Constructs a CTransInPlaceFilter object.
InputPin Returns a pointer to the input pin associated with the filter.
OutputPin Returns a pointer to the output pin associated with the filter.

Overridable Member Functions
Name Description
CheckTransform Verifies that the media type is supported by input and output pins.
CompleteConnect Reconnects the input or output pin if necessary.
DecideBufferSize Determines the size of the transport buffer.
GetMediaType Returns the media type to be used by the output pin.
GetPin Returns a pin if an index is specified.
Receive Receives the sample, calls the derived class's Transform member function, and then delivers the sample.
RegisterPerfId Registers a performance measurement identifier (if PERF is defined).
Transform Performs transformation operations in place on the IMediaSample interface (pure virtual).


CTransInPlaceFilter::CheckTransform

CTransInPlaceFilter Class

Verifies that the media is supported by input and output pins.

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

Parameters
mtIn
Input pin media type.
mtOut
Output pin media type.
Return Values

Returns S_OK by default.

Remarks

This member function overrides the CTransformFilter::CheckTransform member function. The base class functions that call this member function are overridden in this class to call the CTransformFilter::CheckInputType member function that is overridden in the derived class, with the assumption that the type does not change. Usually there is no reason for this member function to be called. In debug builds some calls will be made, and returning S_OK ensures that these calls do not assert.


CTransInPlaceFilter::CompleteConnect

CTransInPlaceFilter Class

Reconnects the input or output pin if necessary.

HRESULT CompleteConnect(
  PIN_DIRECTION direction,
  IPin *pReceivePin
  );

Parameters
direction
Pin direction.
pReceivePin
Pointer to the output pin to which to connect.
Return Values

Returns NOERROR if successful; otherwise, returns VFW_E_NOT_IN_GRAPH if the filter is not part of a graph, or returns an HRESULT that indicates the error. HRESULT can be one of the following standard constants, or other values not listed:
Value Meaning
E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.

Remarks

This member function overrides the CTransformFilter::CompleteConnect member function. It is called by one of the pin classes at the end of a successful connection. Because the input and output pins must both use the same allocator, this member function reconnects the opposite pin if necessary.

When the input pin is first connected, the output pin has not yet been connected and the downstream filter's allocator is unknown, so the allocator for the input pin is chosen to be the upstream pin's allocator. When the transform filter's output pin is connected, however, it has access to the downstream filter's allocator and should force a reconnect on the input pin and offer that allocator. When the input pin is reconnected, it forces a reconnect on the output pin if the allocator chosen for the input pin's connection differs from the output pin's connection. This member function supplies the reconnection for either output or input pins.


CTransInPlaceFilter::Copy

CTransInPlaceFilter Class

Creates a copy of the specified media sample.

IMediaSample * CTransInPlaceFilter::Copy(
  IMediaSample *pSource
  );

Parameters
pSource
Pointer to an object that implements the IMediaSample interface.
Return Values

Returns a pointer to the new sample.


CTransInPlaceFilter::CTransInPlaceFilter

CTransInPlaceFilter Class

Constructs a CTransInPlaceFilter object.

CTransInPlaceFilter(
  TCHAR * pObjectName,
  LPUNKNOWN lpUnk,
  REFCLSID clsid,
  HRESULT * phr
  );

Parameters
pObjectName
Name given to the CTransInPlaceFilter object.
lpUnk
Pointer to LPUNKNOWN.
clsid
Class identifier of the CTransInPlaceFilter class.
phr
Pointer to the HRESULT value for resulting information.
Return Values

No return value.


CTransInPlaceFilter::DecideBufferSize

CTransInPlaceFilter Class

Determines the size of the transport buffer.

HRESULT DecideBufferSize(
  IMemAllocator * pAlloc,
  ALLOCATOR_PROPERTIES * pProperties
  );

Parameters
pAlloc
Pointer to the IMemAllocator object used by the output pin.
pProperties
Requested allocator properties for count, size, and alignment, as specified by the ALLOCATOR_PROPERTIES structure.
Return Values

Returns NOERROR if successful; otherwise, returns an HRESULT value indicating the error. HRESULT can be one of the following standard constants, or other values not listed:
Value Meaning
E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.

Remarks

This member function overrides the CTransformFilter::DecideBufferSize member function. It is called when the filter must provide its own allocator. Allocator requirements are obtained from the filter's input pin and passed to the output pin.


CTransInPlaceFilter::GetMediaType

CTransInPlaceFilter Class

Returns the media type to be used by the output pin.

HRESULT GetMediaType(
  int iPosition,
  CMediaType *pMediaType
  );

Parameters
iPosition
Position of the media type in the media type list.
pMediaType
Returned media type object.
Return Values

Returns E_UNEXPECTED because it is not expected to be called.

Remarks

In the CTransformFilter class, this member function is called by the associated input or output pin class's GetMediaType member function to retrieve the next media type in the list and return it to the pin's CBasePin::EnumMediaTypes member function.

However, in the CTransInPlaceFilter class, the pin classes override the CBasePin::EnumMediaTypes member function so that it bypasses the filter and calls the enumerator of the opposite connected pin. (For example, the output pin enumerator uses the upstream filter's enumerator, and the input pin uses the connected downstream filter's enumerator.) Therefore, this member function should never be called by the inplace pin classes. It is implemented to prevent "undefined pure virtual" compiler warnings.


CTransInPlaceFilter::GetPin

CTransInPlaceFilter Class

Returns a pin if an index is specified.

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 is implemented and need not be overridden unless one or more of the transform pin classes (CTransInPlaceInputPin or CTransInPlaceOutputPin) are being overridden.


CTransInPlaceFilter::InputPin

CTransInPlaceFilter Class

Retrieves a pointer to the input pin associated with the filter.

CTransInPlaceInputPin *InputPin( );

Return Values

Returns a pointer to a CTransInPlaceInputPin object.

Remarks

This member function is protected.


CTransInPlaceFilter::OutputPin

CTransInPlaceFilter Class

Retrieves a pointer to the output pin associated with the filter.

CTransInPlaceOutputPin *OutputPin( );

Return Values

Returns a pointer to a CTransInPlaceOutputPin object.

Remarks

This member function is protected.


CTransInPlaceFilter::Receive

CTransInPlaceFilter Class

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

HRESULT Receive(
  IMediaSample *pSample
  );

Parameters
pSample
Sample to deliver.
Return Values

Returns an HRESULT value that depends on the implementation of the derived class' Transform function. HRESULT can be one of the following standard constants, or other values not listed:
Value Meaning
E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This member function overrides the CTransformFilter::Receive member function. Override it only if you need more control of the process.


CTransInPlaceFilter::RegisterPerfId

CTransInPlaceFilter 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 "TransinPlace". 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.


CTransInPlaceFilter::Transform

CTransInPlaceFilter Class

Transforms the data in pSample in place.

virtual HRESULT Transform(
  IMediaSample *pSample
  ) PURE;

Parameters
pSample
Pointer to the input IMediaSample interface.
Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:
Value Meaning
E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

You must supply this member function in the derived class to perform the actual work of your filter. This member function is called by CTransInPlaceFilter::Receive before passing the sample on to the downstream filter. Transform can return S_FALSE to indicate that the sample should not be delivered downstream.

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

*Top of Page