Microsoft DirectX 8.0 |
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 | |
---|---|
Copy | Copies a media sample. |
InputPin | Retrieves a pointer to the filter's input pin. |
OutputPin | Retrieves a pointer to the filter's output pin. |
TypesMatch | Determines whether the input media type matches the output media type. |
UsingDifferentAllocators | Determines whether the input and output pins are using different allocators. |
Public Methods | |
CTransInPlaceFilter | Constructor method. |
GetPin | Retrieves a pin. |
GetMediaType | Retrieves a preferred media type for the output pin. |
DecideBufferSize | Sets the output pin's buffer requirements. |
CheckTransform | Checks whether an input media type is compatible with an output media type. |
CompleteConnect | Completes a pin connection. |
Receive | Receives a media sample, processes it, and delivers it to the downstream filter. |
Pure Virtual Methods | |
Transform | Transforms a sample in place. |
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.
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_OK Success. VFW_E_NOT_IN_GRAPH The 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:
- If the input pin is connected first, the connection uses a temporary allocator. When the output pin is connected, the filter reconnects the input pin. Reconnecting the input pin causes the upstream filter to renegotiate the allocator. At that point, the input pin proposes an allocator from the downstream filter. For more information, see CTransInPlaceInputPin::GetAllocator.
- If the output pin is connected first, the output pin does not select an allocator. When the input pin is connected, it negotiates an allocator for both connections. If the input and output media types are not the same, the filter reconnects the output pin using the input type.
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.
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.
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.
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_OK Success E_FAIL Failure
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.
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.
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.
Retrieves a pointer to the filter's input pin.
Syntax
CTransInPlaceInputPin *InputPin(void);
Return Value
Returns the CTransformFilter.m_pInput member variable.
Retrieves a pointer to the filter's output pin.
Syntax
CTransInPlaceOutputPin *OutputPin(void);
Return Value
Returns the CTransformFilter.m_pOutput member variable.
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_OK Success E_UNEXPECTED Unexpected 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.
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_FALSE Do not deliver this sample. S_OK Success.
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.
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.
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.