Introduction to the Filter Base Classes
[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]
This article describes the Microsoft DirectShow base class library. This library is intended for filter developers, but application writers might find some of the helper classes and debugging utilities useful. The base class library is not required for DirectShow programming, however.
The following sections summarize the most important base classes in the library.
COM Object Classes
The following classes support the creation of COM objects:
| Class | Description |
|---|---|
| CBaseObject | Base object class. |
| CUnknown | Implements the IUnknown interface. |
Most of the DirectShow classes derive from CBaseObject. This class provides debugging assistance by keeping a count of all the active objects in the DLL at run time. In debug builds, the DLL asserts if it is unloaded while the object count is greater than zero. This makes it easier to track down leaks caused by reference-counting problems.
All of the base classes that support COM interfaces derive from CUnknown, which inherits CBaseObject. The CUnknown class supports reference counting, QueryInterface, and aggregration. For more information, see How to Implement IUnknown.
Filter and Pin Classes
The following classes support the creation of DirectShow filter and pin objects:
| Class | Description |
|---|---|
| CBaseFilter | Base class for filters. Implements the IBaseFilter interface. |
| CBasePin | Base class for pins. Implements the IPin and IQualityControl interfaces. |
| CBaseInputPin | Base class for input pins that use local memory transport. Implements the IMemInputPin interface. This class derives from CBasePin. |
| CBaseOutputPin | Base class for output pins that use IMemInputPin connections. This class derives from CBasePin. |
The following classes are useful for creating more specialized types of filters:
| Class | Description |
|---|---|
| CSource | Base class for source filters. This class is designed for creating push sources. It is not suitable for pull sources, such as file readers. To create output pins for this class, use the CSourceStream class. |
| CTransformFilter | Base class for transform filters. This class performs a copy on the data. The pins for this class are CTransformInputPin and CTransformOutputPin. |
| CTransInPlaceFilter | Base class for transform filters that do not copy data. This class performs the data processing directly on the input data before passing it downstream. The pins for this class are CTransInPlaceInputPin and CTransInPlaceOutputPin. |
| CVideoTransformFilter | Base class for video transform filters. This class derives from CTransformFilter and adds support for quality control. |
| CBaseRenderer | Base class for renderer filters. The input pin for this class is CRendererInputPin. |
| CBaseVideoRenderer | Base class for video renderers. This class derives from CBaseRenderer. |
To use these classes, you must derive your own class and write code to support the functionality that is specific to your filter. The more specialized the base class, the less code you will need to write in your derived class.
Helper Objects
The following classes implement helper objects that are used by filters and pins. Most of these classes can be used without deriving new classes from them:
| Class | Description |
|---|---|
| CPullPin | Helper object for input pins on parser filters. Supports IAsyncReader connections with pull sources. |
| COutputQueue | Helper object for output pins that queue samples for delivery on a worker thread. |
| CSourceSeeking | Help object for implementing seeking on a source filter with exactly one output pin. (This class is not designed for filters with multiple pins, such as parsers.) |
| CEnumPins | Enumerator object for enumerating pins on a filter. Implements the IEnumPins interface. |
| CEnumMediaTypes | Enumerator object for enumerating preferred media types on a pin. Implements the IEnumMediaTypes interface. |
| CMemAllocator | Memory allocator object. Implements the IMemAllocator interface. |
| CMediaSample | Media sample object. Implements the IMediaSample2 interface. |
| CBaseReferenceClock | Base class for reference clocks. Implements the IReferenceClock interface. |
| CMediaType | Helper object for manipulating AM_MEDIA_TYPE structures. |