Microsoft DirectX 8.0

CTransInPlaceFilter Class

CTransInPlaceFilter class hierarchy

Base class for implementing an in-place transform filter.

Declaration: Transfrm.h

The CTransInPlaceFilter class is designed for filters that transform data in place, rather than copying the data across buffers.

Whenever possible, the filter uses a single allocator. For details, see CompleteConnect.

To use this class, derive a new class from CTransInPlaceFilter and implement the following methods:

This filter uses the CTransInPlaceInputPin class for its input pin, and the CTransInPlaceOutputPin class for its output pin. Typically, you do not need to override these pin classes. The filter creates both pins in the GetPin method. If you do override the pin classes, you must override GetPin to create your custom pins.

Protected Methods
CopyCopies a media sample.
InputPinRetrieves a pointer to the filter's input pin.
OutputPinRetrieves a pointer to the filter's output pin.
TypesMatchDetermines whether the input media type matches the output media type.
UsingDifferentAllocatorsDetermines whether the input and output pins are using different allocators.
Public Methods
CTransInPlaceFilterConstructor method.
GetPinRetrieves a pin.
GetMediaTypeRetrieves a preferred media type for the output pin.
DecideBufferSizeSets the output pin's buffer requirements.
CheckTransformChecks whether an input media type is compatible with an output media type.
CompleteConnectCompletes a pin connection.
ReceiveReceives a media sample, processes it, and delivers it to the downstream filter.
Pure Virtual Methods
TransformTransforms a sample in place.

CTransInPlaceFilter::CheckTransform

CTransInPlaceFilter Class

Checks whether an input media type is compatible with an output media type.

Syntax

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

Parameters

mtIn
Pointer to a CMediaType object that specifies the input type.
mtOut
Pointer to a CMediaType object that specifies the output type.

Return Value

Returns S_OK.

Remarks

This method overrides the CTransformFilter::CheckTransform method. The methods in CTransInPlace call the CTransformFilter::CheckInputType method instead of CheckTransform, with the assumption that the input and output types are the same.

CTransInPlaceFilter::CompleteConnect

CTransInPlaceFilter Class

Completes a pin connection.

Syntax

HRESULT CompleteConnect(
    PIN_DIRECTION direction,
    IPin *pReceivePin
);

Parameters

direction
Member of the PIN_DIRECTION enumerated type, specifying which pin on the filter is making the connection.
pReceivePin
Pointer to the IPin interface of the other pin in this connection attempt.

Return Value

Returns an HRESULT. Possible values include those shown in the following table.

S_OKSuccess.
VFW_E_NOT_IN_GRAPHThe filter is not in a filter graph.

Remarks

This method overrides the CTransformFilter::CompleteConnect method.

The behavior of the filter depends on the order of the pin connections:

The filter performs all pin reconnections by calling the CBaseFilter::ReconnectPin method. The ReconnectPin method, in turn, calls the IFilterGraph2::ReconnectEx method on the filter graph manager.

CTransInPlaceFilter::Copy

CTransInPlaceFilter Class

Copies a media sample.

Syntax

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

Parameters

pSource
Pointer to the IMediaSample interface of the sample.

Return Value

Returns a pointer to the IMediaSample interface on the new sample.

Remarks

This method retrieves an empty buffer from the downstream allocator. It copies all of the sample properties from pSource into the new sample, along with the actual data in the sample. If the filter is using two allocators, it calls this method to copy data across buffers.

CTransInPlaceFilter::CTransInPlaceFilter

CTransInPlaceFilter Class

Constructor method.

Syntax

CTransInPlaceFilter(
    TCHAR *pObjectName,
    LPUNKNOWN lpUnk,
    REFCLSID clsid,
    HRESULT *phr,
    bool bModifiesData = true
);

Parameters

pObjectName
String containing the debug name of the filter. For more information, see CBaseObject.
lpUnk
Pointer to the owner of this object. If the object is aggregated, pass a pointer to the aggregating object's IUnknown interface. Otherwise, set this parameter to NULL.
clsid
Class identifier of the filter.
phr
Ignored.
bModifiesData
Boolean value that specifies whether the filter modifies the input data. If TRUE, the filter modifies the data. Otherwise, the filter passes the data downstream unchanged.

CTransInPlaceFilter::DecideBufferSize

CTransInPlaceFilter Class

Sets the output pin's buffer requirements.

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 an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess
E_FAILFailure

Remarks

This method overrides the CTransformFilter::DecideBufferSize method. It exists for compatibility with previous versions of the CTransInPlaceFilter class. In the current version, the upstream output pin negotiates directly with the downstream input pin for the allocator. The filter's output pin is not involved.

CTransInPlaceFilter::GetMediaType

CTransInPlaceFilter Class

Retrieves a preferred media type for the output pin.

Syntax

HRESULT GetMediaType(
    int iPosition,
    CMediaType *pMediaType
);

Parameters

iPosition
Zero-based index value.
pMediaType
Pointer to a CMediaType object that receives the media type.

Return Value

Returns E_UNEXPECTED.

Remarks

This method overrides the CTransformFilter::GetMediaType method. In the CTransInPlaceFilter class, each pin calls the opposite connected pin to enumerate preferred media types. The input pin calls the downstream filter's input pin, and the output pin calls the upstream filter's output pin. Therefore, the filter's GetMediaType method is never called.

CTransInPlaceFilter::GetPin

CTransInPlaceFilter Class

Retrieves a pin.

Syntax

virtual CBasePin *GetPin(
    int n
);

Parameters

n
Number of the specified pin, indexed from zero. On this filter, pin 0 is the input pin, and pin 1 is the output pin.

Return Value

Returns a pointer to the CBasePin object that implements the pin, or NULL if the method fails.

Remarks

This method overrides the CTransformFilter::GetPin method. The first time the method is called, it creates both pins.

This method does not increment the reference count on the returned pin, so the returned pin does not have an outstanding reference count. If the caller needs to keep a reference on the pin, it should call the IUnknown::AddRef method on the pin.

If the filter uses the default CTransInPlaceInputPin and CTransInPlaceOutputPin pins, you probably do not need to override this method. If the filter uses pins that extend those classes, however, you must override this method to create pins of that type.

CTransInPlaceFilter::InputPin

CTransInPlaceFilter Class

Retrieves a pointer to the filter's input pin.

Syntax

CTransInPlaceInputPin *InputPin(void);

Return Value

Returns the CTransformFilter.m_pInput member variable.

CTransInPlaceFilter::OutputPin

CTransInPlaceFilter Class

Retrieves a pointer to the filter's output pin.

Syntax

CTransInPlaceOutputPin *OutputPin(void);

Return Value

Returns the CTransformFilter.m_pOutput member variable.

CTransInPlaceFilter::Receive

CTransInPlaceFilter Class

Receives a media sample, processes it, and delivers it to the downstream filter.

Syntax

HRESULT Receive(
    IMediaSample *pSample
);

Parameters

pSample
Pointer to the IMediaSample interface on the sample.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess
E_UNEXPECTEDUnexpected error

Remarks

The filter's input pin calls this method when it receives a sample. The filter calls the Transform method, which the derived class must implement. The Transform method processes the data. If the filter is using only one allocator, it passes pSample directly to the Tranform method. Otherwise, it copies pSample and passes the copy.

If the Transform method returns S_FALSE, the Receive method drops the sample. On the first dropped sample, the filter sends an EC_QUALITY_CHANGE event to the filter graph manager. Otherwise, if the Transform method returns S_OK, the filter delivers the output sample. To do so, it calls the IMemInputPin::Receive method on the downstream input pin.

CTransInPlaceFilter::Transform

CTransInPlaceFilter Class

Transforms a sample in place.

Syntax

virtual HRESULT Transform(
    IMediaSample *pSample
) PURE;

Parameters

pSample
Pointer to the sample's IMediaSample interface.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_FALSEDo not deliver this sample.
S_OKSuccess.

Remarks

The derived class must implement this method. Transform the sample data in place. If the filter is using two allocators, it copies the data from the input sample to a new sample, and passes the copy to this method.

If the filter should not deliver this sample (for example, to support quality control), the method should return S_FALSE.

CTransInPlaceFilter::TypesMatch

CTransInPlaceFilter Class

Determines whether the input media type matches the output media type.

Syntax

BOOL TypesMatch(void);

Return Value

Returns TRUE if the input and output media types are the same, or FALSE otherwise.

CTransInPlaceFilter::UsingDifferentAllocators

CTransInPlaceFilter Class

Determines whether the input and output pins are using different allocators.

Syntax

BOOL UsingDifferentAllocators(void) const;

Return Value

Returns TRUE if the input and output pins are using different allocators, or FALSE otherwise.