IMemAllocator::GetBuffer method (strmif.h)

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The GetBuffer method retrieves a media sample that contains an empty buffer.

Syntax

HRESULT GetBuffer(
  [out] IMediaSample   **ppBuffer,
  [in]  REFERENCE_TIME *pStartTime,
  [in]  REFERENCE_TIME *pEndTime,
  [in]  DWORD          dwFlags
);

Parameters

[out] ppBuffer

Receives a pointer to the buffer's IMediaSample interface. The caller must release the interface.

[in] pStartTime

Pointer to the start time of the sample, or NULL.

[in] pEndTime

Pointer to the ending time of the sample, or NULL.

[in] dwFlags

Bitwise combination of zero or more of the following flags:

Return value

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

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 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.

Requirements

See also

Error and Success Codes

IMemAllocator Interface