Microsoft DirectX 9.0

CBaseAllocator Class

CBaseAllocator Class Hierarchy

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.