## IAMDevMemoryAllocator Interface

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.

###

IAMDevMemoryAllocator::Alloc

IAMDevMemoryAllocator Interface

Allocates a memory buffer.

HRESULT Alloc(
BYTE **ppBuffer,
DWORD *pdwcbBuffer
);

##### Parameters

ppBuffer
  [out] Address of a pointer to the allocated memory buffer.
pdwcbBuffer
  [in, out] For input, the number of bytes to allocate. For output, the number of actual bytes allocated.

##### Return Values

Returns S_OK if the desired quantity of memory was allocated, S_FALSE if memory was unavailable.

##### Remarks

Call this method to allocate a block of memory from the available pool.

##### See Also

IAMDevMemoryAllocator::Free

###

IAMDevMemoryAllocator::CheckMemory

IAMDevMemoryAllocator Interface

Tests whether a memory pointer was allocated by the specific instance (device) of the allocator.

HRESULT CheckMemory(
const BYTE *pBuffer
);

##### Parameters

pBuffer
  [in] Pointer to the allocated memory buffer's address.

##### Return Values

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.

##### Remarks

The hardware filter typically uses this method to test whether the pointer actually points to on-board memory.

###

IAMDevMemoryAllocator::Free

IAMDevMemoryAllocator Interface

Frees the previously allocated memory.

HRESULT Free(
BYTE *pBuffer
);

##### Parameters

pBuffer
  [in] Pointer to the allocated memory.

##### Return Values

Returns E_INVALIDARG if the specified allocator didn't allocate the memory (that is, CheckMemory fails).

##### Remarks

This method frees a block of memory from the pool.

###

IAMDevMemoryAllocator::GetDevMemoryObject

IAMDevMemoryAllocator Interface

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
);

##### Parameters

ppUnkInnner
  [out] Address of a pointer to the newly created control object's own IUnknown. This inner IUnknown interface should be released when the outer object is destroyed. The custom allocator should call the QueryInterface method on this pointer to obtain the IAMDevMemoryControl interface.
pUnkOuter
  [in] Pointer to the custom allocator's own IUnknown interface. This interface aggregates the device memory control object inside the custom allocator.

##### Return Values

Returns an HRESULT value that depends on the implementation of the interface.

##### Remarks

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.

###

IAMDevMemoryAllocator::GetInfo

IAMDevMemoryAllocator Interface

Retrieves information about the memory capabilities.

HRESULT GetInfo(
DWORD *pdwcbTotalFree,
DWORD *pdwcbLargestFree,
DWORD *pdwcbTotalMemory,
DWORD *pdwcbMinimumChunk
);

##### Parameters

pdwcbTotalFree
  [out] Total free memory size.
pdwcbLargestFree
  [out] Retrieves the largest free memory size.
pdwcbTotalMemory
  [out] Retrieves the total memory size.
pdwcbMinimumChunk
  [out] Retrieves the minimum chunk size, giving granularity and alignment rules.

##### Return Values

Returns an HRESULT value that depends on the implementation of the interface.

##### Remarks

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.