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.

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.

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 the particular device of the allocator allocated a memory pointer.
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.

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 the particular device of the allocator allocated a memory pointer.
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.

Syntax

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

Parameters

ppBuffer
[out] Pointer that will receive the address of the allocated memory buffer.
pdwcbBuffer
[in, out] Pointer to a DWORD whose input value is the number of bytes to allocate and whose output value is the actual number of bytes allocated.

Return Value

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.

IAMDevMemoryAllocator::CheckMemory

IAMDevMemoryAllocator Interface

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

Syntax

HRESULT CheckMemory(
    const BYTE *pBuffer
);

Parameters

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

Return Value

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.

Syntax

HRESULT Free(
    BYTE *pBuffer
);

Parameters

pBuffer
[in] Pointer to the allocated memory.

Return Value

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.

Syntax

HRESULT GetDevMemoryObject(
    IUnknown **ppUnkInner,
    IUnknown *pUnkOuter
);

Parameters

ppUnkInner
[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 Value

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.

Syntax

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

Parameters

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

Return Value

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.