CBaseAllocator Class

Microsoft DirectShow 9.0

CBaseAllocator Class

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

**  Header:** Declared in Amfilter.h; include Streams.h.

**  Library:** Use Strmbase.lib (retail builds) or Strmbasd.lib (debug builds).

Protected Member Variables
m_lFree	Pointer to a list of available (free) media samples.
m_hSem	Semaphore that is signaled when a sample becomes available.
m_lWaiting	Count of threads waiting for samples.
m_lCount	Number of buffers to provide.
m_lAllocated	Number of buffers currently allocated.
m_lSize	Size of each buffer.
m_lAlignment	Alignment of each buffer.
m_lPrefix	Prefix of each buffer.
m_bChanged	Flag indicating whether the buffer requirements have changed.
m_bCommitted	Flag indicating whether the allocator has been committed.
m_bDecommitInProgress	Flag indicating whether a decommit operation is in progress.
m_pNotify	Pointer to a callback interface, which is called when samples are released.
m_fEnableReleaseCallback	Flag indicating whether the release callback is enabled.
Protected Methods
Alloc	Allocates memory for the buffers. Virtual.
Public Methods
CBaseAllocator	Constructor method.
~CBaseAllocator	Destructor method.
SetNotify	Obsolete.
GetFreeCount	Retrieves the number of media samples that are not in use.
NotifySample	Releases any threads that are waiting for samples.
SetWaiting	Increments the count of waiting threads.
Pure Virtual Methods
Free	Releases all of the buffer memory.
IMemAllocator Methods
SetProperties	Specifies the number of buffers to allocate and the size of each buffer.
GetProperties	Retrieves the number of buffers that the allocator will create, and the buffer properties.
Commit	Allocates the memory for the buffers.
Decommit	Decommits the buffers.
GetBuffer	Retrieves a media sample that contains a buffer.
ReleaseBuffer	Returns a media sample to the list of free media samples.