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:
- Call the CBaseAllocator::SetProperties method to specify the buffer requirements, including the number of buffers and the size of each buffer.
- Call the CBaseAllocator::Commit method to allocate the buffers.
- Call the CBaseAllocator::GetBuffer method to retrieve media samples. This method blocks until the next sample becomes available.
- 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.
- 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. |