CBaseAllocator.GetBuffer method

[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 a buffer. This method implements the IMemAllocator::GetBuffer method.

Syntax

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

Parameters

ppBuffer

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

pStartTime

Pointer to the start time of the sample.

pEndTime

Pointer to the end time of the sample.

dwFlags

Bitwise combination of zero or more flags. The base class supports the following flag.

Value	Meaning
AM_GBF_NOWAIT	Do not wait for a buffer to become available.

Return value

Returns one of the following HRESULT values.

Return code	Description
S_OK	Success.
VFW_E_NOT_COMMITTED	Allocator was not committed.
VFW_E_TIMEOUT	Timed out.

Remarks

Unless the caller specifies the AM_GBF_NOWAIT flag in dwFlags, this method blocks until the next sample is available.

The retrieved media sample has a valid pointer to the allocated buffer. 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.

In the base class, the pStartTime and pEndTime parameters are ignored. Derived classes can use these values. For example, the allocator for the Video Renderer filter uses these values to synchronize switching between DirectDraw surfaces.

If the method needs to wait on a sample, it increments the count of waiting objects (CBaseAllocator::m_lCount) and the calls WaitForSingleObject function on the semaphore (CBaseAllocator::m_hSem). When a sample becomes available, it calls the CBaseAllocator::ReleaseBuffer method on the allocator, which increases the semaphore count by m_lCount (thereby releasing the waiting threads) and sets m_lCount back to zero.

Requirements

Requirement	Value
Header	Amfilter.h (include Streams.h)
Library	Strmbase.lib (retail builds); Strmbasd.lib (debug builds)

See also

CBaseAllocator Class