The IAMDevMemoryAllocator interface enables the creation of third-party memory allocators by using an on-board memory manager object. Many codec hardware manufacturers put on-board mapped memory for the codecs to improve the efficiency of buffer manipulation. This interface allocates that memory and provides the GetDevMemoryObject method to retrieve a device memory control object, which supports the IAMDevMemoryControl interface. Devices that share the same device ID can use the memory.
The global memory manager object exposes this interface to allocate memory from memory that is on a particular device.
When to Implement
Implement this interface when your pin must support the creation of on-board memory allocators. Source filters that are aware of on-board memory and need to create their own allocators should query for this interface, request an amount of memory and then create an allocator (aggregating the device memory control object). Source filters that don't need to create their own allocator could just use the allocator of the downstream pin (which also aggregates the device memory control object). The hardware-based filter can confirm the usage of its on-board memory by calling methods on the aggregated allocator.
When to Use
Use this interface when applications need to control the memory of codecs with on-board memory.
Methods in Vtable Order
| IUnknown methods | Description |
| QueryInterface | Retrieves pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| IAMDevMemoryAllocator methods | Description |
| GetInfo | Retrieves information about the memory capabilities. |
| CheckMemory | Tests whether a memory pointer was allocated by the specific instance (device) of the allocator. |
| Alloc | Allocates a memory buffer. |
| Free | Frees the previously allocated memory. |
| GetDevMemoryObject | Retrieves an IUnknown interface pointer to a device memory control object that can be aggregated with a custom allocator. |
Allocates a memory buffer.
HRESULT Alloc(
BYTE **ppBuffer,
DWORD *pdwcbBuffer
);
Returns S_OK if the desired quantity of memory was allocated, S_FALSE if memory was unavailable.
Call this method to allocate a block of memory from the available pool.
Tests whether a memory pointer was allocated by the specific instance (device) of the allocator.
HRESULT CheckMemory(
const BYTE *pBuffer
);
Returns S_OK if the on-board allocator allocated the memory, or S_FALSE if not. Memory that is on the particular device but not allocated will also return S_FALSE.
The hardware filter typically uses this method to test whether the pointer actually points to on-board memory.
Frees the previously allocated memory.
HRESULT Free(
BYTE *pBuffer
);
Returns E_INVALIDARG if the specified allocator didn't allocate the memory (that is, CheckMemory fails).
This method frees a block of memory from the pool.
Retrieves an IUnknown interface pointer to a device memory control object that can be aggregated with a custom allocator.
HRESULT GetDevMemoryObject(
IUnknown **ppUnkInnner,
IUnknown *pUnkOuter
);
Returns an HRESULT value that depends on the implementation of the interface.
The device memory control object is necessary to aggregate with the custom allocator because renderers that require the use of on-board memory will query for IAMDevMemoryControl when they receive a new allocator, to verify that the memory is from the same device. This occurs because the hardware filter will receive an IMemAllocator object, which might or might not use the on-board memory. To decide if it is a compatible allocator, the object would query for the IAMDevMemoryControl interface to access specific methods. The IAMDevMemoryControl creates an aggregated object that implements the methods of IAMDevMemoryControl (these are often hardware specific).
See COM documentation for rules on how the outer object implements aggregation.
Retrieves information about the memory capabilities.
HRESULT GetInfo(
DWORD *pdwcbTotalFree,
DWORD *pdwcbLargestFree,
DWORD *pdwcbTotalMemory,
DWORD *pdwcbMinimumChunk
);
Returns an HRESULT value that depends on the implementation of the interface.
Use this method to find out the total amount of memory available. This method returns values for the entire on-board memory that is available on that device. If multiple filters (devices) share the memory, it will return the amount available to that specific device, which might be a portion of the total amount of on-board memory. This amount will be implementation specific. For example, the on-board memory manager on the codec might be able to access all 32 megabytes (MB) of memory on the card. However, individual pin implementations of IAMDevMemoryAllocator only report a portion of this memory.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.