CBaseAllocator class

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

The CBaseAllocator class is an abstract base class that implements an allocator. Allocators expose the IMemAllocator interface.

An allocator is an object that allocates memory buffers. The allocator maintains a list of available buffers. When a client (generally a filter) requests a buffer, the allocator retrieves one from the list. The client fills the buffer with data, and might pass the buffer to another object. Eventually the buffer is released and the allocator returns it to the list of available buffers.

Each buffer is encapsulated by an object called a media sample. Media samples are a way to package pointers to memory blocks within the Component Object Model (COM) framework. Media samples expose the IMediaSample interface, and are implemented using the CMediaSample class. A media sample contains a pointer to the associated buffer, which can be accessed by calling the IMediaSample::GetPointer method. For more information, see Samples and Allocators.

To use this class, perform the following steps:

1. Call the CBaseAllocator::SetProperties method to specify the buffer requirements, including the number of buffers and the size of each buffer.
2. Call the CBaseAllocator::Commit method to allocate the buffers.
3. Call the CBaseAllocator::GetBuffer method to retrieve media samples. This method blocks until the next sample becomes available.
4. When you are done with each sample, call the IUnknown::Release method on the sample. The sample is not deleted when its reference count reaches zero. Instead, the sample returns to the allocator's free list.
5. When you are done using the allocator, call the CBaseAllocator::Decommit method to free the memory for the buffers.

The Commit method calls the virtual method CBaseAllocator::Alloc, which allocates the memory for the buffers. The Decommit method calls the pure virtual method CBaseAllocator::Free, which frees the memory. Derived classes must override these two methods.

The CMemAllocator base class derives from CBaseAllocator. The filter base classes use the CMemAllocator class.

Requirements

See also

Providing a Custom Allocator