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

m_idTransInPlace Performance-measuring identifier.

Member Functions

Copy Retrieves a pointer to an identical copy of a media sample.
CTransInPlaceFilter Constructs a CTransInPlaceFilter object.
InputPin Retrieves a pointer to the input pin associated with the filter.
OutputPin Retrieves a pointer to the output pin associated with the filter.

Overridable Member Functions

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 Retrieves the media type to be used by the output pin.
GetPin Retrieves 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.

Syntax

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

Parameters

mtIn
Pointer to the input pin media type.
mtOut
Pointer to the output pin media type.

Return Value

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.

Syntax

HRESULT CompleteConnect(
    PIN_DIRECTION direction,
    IPin *pReceivePin
    );

Parameters

direction
Pin direction.
pReceivePin
Pointer to the output pin to which to connect.

Return Value

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

Syntax

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

Parameters

pSource
Pointer to an object that implements the IMediaSample interface.

Return Value

Returns a pointer to the new sample.

CTransInPlaceFilter::CTransInPlaceFilter

CTransInPlaceFilter Class

Constructs a CTransInPlaceFilter object.

Syntax

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

Parameters

pObjectName
Pointer to the name given to the CTransInPlaceFilter object.
lpUnk
Pointer to the controlling IUnknown interface.
clsid
Class identifier of the CTransInPlaceFilter class.
phr
Pointer to the HRESULT value for resulting information.

Return Value

No return value.

CTransInPlaceFilter::DecideBufferSize

CTransInPlaceFilter Class

Determines the size of the transport buffer.

Syntax

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

Parameters

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

Return Value

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

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

Syntax

HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
    );

Parameters

iPosition
Position of the media type in the media type list.
pMediaType
Pointer to the returned media type object.

Return Value

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 in-place pin classes. It is implemented to prevent "undefined pure virtual" compiler warnings.

CTransInPlaceFilter::GetPin

CTransInPlaceFilter Class

Retrieves a pin if an index is specified.

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

Syntax

CTransInPlaceInputPin *InputPin(void);

Return Value

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.

Syntax

CTransInPlaceOutputPin *OutputPin(void);

Return Value

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.

Syntax

HRESULT Receive(
    IMediaSample *pSample
    );

Parameters

pSample
Pointer to the sample to deliver.

Return Value

Returns an HRESULT value that depends on the implementation of the derived class's Transform function. HRESULT can be one of the following standard constants, or other values not listed.
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.

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

Syntax

virtual HRESULT Transform(
    IMediaSample *pSample
    ) PURE;

Parameters

pSample
Pointer to the input IMediaSample interface.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.
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.

Copy	Retrieves a pointer to an identical copy of a media sample.
CTransInPlaceFilter	Constructs a CTransInPlaceFilter object.
InputPin	Retrieves a pointer to the input pin associated with the filter.
OutputPin	Retrieves a pointer to the output pin associated with the filter.

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	Retrieves the media type to be used by the output pin.
GetPin	Retrieves 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).

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.