IMemAllocator Interface

The IMemAllocator interface allocates IMediaSample blocks to be used for data transfer between pins. The blocks can be provided by the input pin, output pin, or a third party. Release the IMediaSample object by calling the IUnknown::Release method.

When to Implement

Implement this interface if you are providing a buffer for media samples. This is typically done by filters that originate, copy, or provide a destination for the media stream. For example, a source filter provides an allocator corresponding to the incoming media, and a renderer filter provides an allocator corresponding to the hardware memory (DirectX®, for example). Intermediate transform filters can create their own allocator if copying samples and not writing directly to the renderer's allocator. Use the CBaseAllocator class to implement the IMemAllocator interface.

When to Use

Filters use this interface when retrieving or sending media samples. The allocator used might actually belong to a filter further upstream or downstream than the next filter, because many filters choose to pass the allocators through and simply modify the data in place.

Methods in Vtable Order

IUnknown methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

IMemAllocator methods	Description
SetProperties	Specifies a desired number of blocks, size of the blocks, and block alignment figure. This method returns the actual values for the same.
GetProperties	Determines the size, number, and alignment of blocks.
Commit	Commits the memory for the specified buffers.
Decommit	Releases the memory for the specified buffers.
GetBuffer	Retrieves a container for a sample.
ReleaseBuffer	Releases a container for a sample.

---

IMemAllocator::Commit

IMemAllocator Interface

Commits the memory for the specified buffers.

HRESULT Commit(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

The IMemAllocator::SetProperties method must be called before calling this method. The IMemAllocator::GetBuffer method fails if it is called before this method.

---

IMemAllocator::Decommit

IMemAllocator Interface

Releases the memory for the specified buffers.

HRESULT Decommit(void);

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

Any threads waiting in the IMemAllocator::GetBuffer method return with an error after this method is called. The IMemAllocator::GetBuffer method fails if it is called before the IMemAllocator::Commit method or after this method.

---

IMemAllocator::GetBuffer

IMemAllocator Interface

Retrieves a container for a sample.

HRESULT GetBuffer(
  IMediaSample ** ppBuffer,
  REFERENCE_TIME * pStartTime,
  REFERENCE_TIME * pEndTime,
  DWORD dwFlags
  );

Parameters

ppBuffer

[out] Pointer to a retrieved media sample buffer.

pStartTime

[in] Either NULL or set to the beginning time of the sample to retrieve. Only the video renderer uses this.

pEndTime

[in] Either NULL or set to the ending time of the sample to retrieve. Only the video renderer uses this.

dwFlags

[in] GetBuffer supports the following flags.

AM_GBF_NOTASYNCPOINT

Dynamic format changes are not allowed on this buffer because it is not a key frame.

AM_GBF_PREVFRAMESKIPPED

Set to TRUE if this sample is the first after a discontinuity. Only the video renderer uses this.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

IMemAllocator::GetBuffer is a locking, synchronous method to get the next free buffer. Upon return, the properties are invalid, but the buffer pointer and size are correct. This method succeeds only if memory has been committed. GetBuffer returns with an error value if it is blocked waiting for a buffer, and the IMemAllocator::Decommit method is called on another thread.

If the pStartTime and pEndTime parameters are not NULL, they specify the intended start and end time for the sample in stream time (reference clock time minus the stream time offset). The Video Renderer applies these parameters when using DirectDraw to schedule when to return a sample. If pStartTime and pEndTime are NULL the Video Renderer will not use DirectDraw.

---

IMemAllocator::GetProperties

IMemAllocator Interface

Returns the properties being used on this allocator.

HRESULT GetProperties(
  ALLOCATOR_PROPERTIES * pProps
  );

Parameters

pProps

[out] Allocator properties.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

Calls to this method need not succeed until the IMemAllocator::Commit method is called.

---

IMemAllocator::ReleaseBuffer

IMemAllocator Interface

Releases the CMediaSample object.

HRESULT ReleaseBuffer(
  IMediaSample *pBuffer
  );

Parameters

pBuffer

[in] Buffer to release.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

---

IMemAllocator::SetProperties

IMemAllocator Interface

Specifies the size, number, and alignment of blocks.

HRESULT SetProperties(
  ALLOCATOR_PROPERTIES * pRequest,
  ALLOCATOR_PROPERTIES * pActual
  );

Parameters

pRequest

[in] Requested allocator properties.

pActual

[out] Allocator properties actually set.

Return Values

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed:

Value	Meaning
E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.

Remarks

The pRequest parameter is filled in by the caller with the requested values for the count, number, and alignment as specified by the ALLOCATOR_PROPERTIES structure. The pActual parameter is filled in by the allocator with the closest values that it can provide for the request. This method cannot be called unless the allocator has been decommitted using the IMemAllocator::Decommit method.

This method assumes that blocks are all the same size.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page