Index Topic Contents | |||
Previous Topic: CTransformOutputPin Class Next Topic: CTransInPlaceInputPin Class |
CTransInPlaceFilter Class
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 Class
CTransInPlaceFilter::CheckTransformVerifies 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 Class
CTransInPlaceFilter::CompleteConnectReconnects 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 Class
CTransInPlaceFilter::CopyCreates 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 Class
CTransInPlaceFilter::CTransInPlaceFilterConstructs 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 Class
CTransInPlaceFilter::DecideBufferSizeDetermines 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 Class
CTransInPlaceFilter::GetMediaTypeReturns 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 Class
CTransInPlaceFilter::GetPinReturns 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 Class
CTransInPlaceFilter::InputPinRetrieves 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 Class
CTransInPlaceFilter::OutputPinRetrieves 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 Class
CTransInPlaceFilter::ReceiveReceives 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 Class
CTransInPlaceFilter::RegisterPerfIdRegisters 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 Class
CTransInPlaceFilter::TransformTransforms 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.