Microsoft DirectX 8.0

IMemAllocator Interface

Allocates media samples, for moving data between pins.

This interface is used by pins that share allocators, when the input pin exposes the IMemInputPin interface. The pins negotiate which pin will provide the allocator. The allocator is used to allocate memory buffers, retrieve empty buffers, and release buffers. Not every filter creates its own allocator, so one allocator might be used by several filters. For more information, see Connection Model.

Applications typically do not use this interface.

To use an allocator, perform the following steps:

  1. Call the IMemAllocator::SetProperties method to specify the buffer requirements, including the number of buffers and the size of each buffer.
  2. Call the IMemAllocator::Commit method to allocate the buffers.
  3. Call the IMemAllocator::GetBuffer method to retrieve media samples. This method blocks until the next sample becomes available.
  4. 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.
  5. When you are done using the allocator, call the IMemAllocator::Decommit method to free the memory for the buffers.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IMemAllocator methodsDescription
SetPropertiesSpecifies the number of buffers to allocate and the size of each buffer.
GetPropertiesRetrieves the number of buffers that the allocator will create, and the buffer properties.
CommitAllocates the buffer memory.
DecommitReleases the memory for the buffers.
GetBufferRetrieves a media sample that contains an empty buffer.
ReleaseBufferReleases a media sample.

IMemAllocator::Commit

IMemAllocator Interface

Allocates the buffer memory.

Syntax

HRESULT Commit(void);

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
VFW_E_SIZENOTSETBuffer requirements were not set.

Remarks

Before calling this method, call the IMemAllocator::SetProperties method to specify the buffer requirements.

You must call this method before calling the IMemAllocator::GetBuffer method.

IMemAllocator::Decommit

IMemAllocator Interface

Releases the memory for the buffers.

Syntax

HRESULT Decommit(void);

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

Any threads waiting in the IMemAllocator::GetBuffer method return with an error. Further calls to GetBuffer fail, until the IMemAllocator::Commit method is called.

IMemAllocator::GetBuffer

IMemAllocator Interface

Retrieves a media sample that contains an empty buffer.

Syntax

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

Parameters

ppBuffer
[out] Address of a variable that receives a pointer to the buffer's IMediaSample interface.
pStartTime
[in] Pointer to the start time of the sample, or NULL.
pEndTime
[in] Pointer to the ending time of the sample, or NULL.
dwFlags
[in] Bitwise combination of zero or more of the following flags.
  • AM_GBF_NOTASYNCPOINT: This sample is not a synchronization point. Dynamic format changes are not allowed on this sample.
  • AM_GBF_PREVFRAMESKIPPED: This sample is the first after a discontinuity. (Only the video renderer uses this flag.)
  • AM_GBF_NOWAIT: Do not wait for a buffer to become available.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
VFW_E_NOT_COMMITTEDAllocator is decommitted.
VFW_E_TIMEOUTTimed out.

Remarks

By default, this method blocks until a free sample is available or the allocator is decommitted. If the caller specifies the AM_GBF_NOWAIT flag and no sample is available, the allocator can return immediately with a return value of VFW_E_TIMEOUT. However, allocators are not required to support this flag.

The sample returned in ppBuffer has a valid buffer pointer. The caller is responsible for setting any other properties on the sample, such as the time stamps, the media times, or the sync-point property. (For more information, see IMediaSample.)

The pStartTime and pEndTime parameters are not applied to the sample. The allocator might use these values to determine which buffer it retrieves. For example, the Video Renderer filter uses these values to synchronize switching between Microsoft® DirectDraw® surfaces. To set the time stamp on the sample, call the IMediaSample::SetTime method.

You must call the IMemAllocator::Commit method before calling this method. This method fails after the IMemAllocator::Decommit method is called. If the method succeeds, the IMediaSample interface that it returns has an outstanding reference count. Be sure to release the interface when you are done using it.

IMemAllocator::GetProperties

IMemAllocator Interface

Retrieves the number of buffers that the allocator will create, and the buffer properties.

Syntax

HRESULT GetProperties(
    ALLOCATOR_PROPERTIES *pProps
);

Parameters

pProps
[out] Pointer to an ALLOCATOR_PROPERTIES structure that receives the allocator properties.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

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

IMemAllocator::ReleaseBuffer

IMemAllocator Interface

Releases a media sample.

Syntax

HRESULT ReleaseBuffer(
    IMediaSample *pBuffer
);

Parameters

pBuffer
[in] Pointer to the media sample's IMediaSample interface.

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the error.

Remarks

When a media sample's reference count reaches zero, it calls this method with itself as the pBuffer parameter. This method releases the sample back to the allocator's list of available samples.

IMemAllocator::SetProperties

IMemAllocator Interface

Specifies the number of buffers to allocate and the size of each buffer.

Syntax

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

Parameters

pRequest
Pointer to an ALLOCATOR_PROPERTIES structure that contains the buffer requirements.
pActual
Pointer to an ALLOCATOR_PROPERTIES structure that receives the actual buffer properties.

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_POINTERNULL pointer argument.
VFW_E_ALREADY_COMMITTEDCannot change allocated memory while the filter is active.
VFW_E_BADALIGNAn invalid alignment was specified.
VFW_E_BUFFERS_OUTSTANDINGOne or more buffers are still active.

Remarks

This method specifies the buffer requirements, but does not allocate any buffers. Call the IMemAllocator::Commit method to allocate buffers.

The caller allocates two ALLOCATOR_PROPERTIES structures. The pRequest parameter contains the caller's buffer requirements, including the number of buffers and the size of each buffer. When the method returns, the pActual parameter contains the actual buffer properties, as set by the allocator.

When this method is called, the allocator must not be committed or have outstanding buffers.