CBaseOutputPin::GetDeliveryBuffer

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

Retrieves an IMediaSample buffer suitable for passing across the connection.

Syntax

virtual HRESULT GetDeliveryBuffer(
  IMediaSample** ppSample,
  REFERENCE_TIME* pStartTime,
  REFERENCE_TIME* pEndTime,
  DWORD dwFlags
);

Parameters

• ppSample
  IMediaSample buffer to be provided.

• pStartTime
  Start time of the media sample (optional and can be NULL).

• pEndTime
  Stop time of the media sample (optional and can be NULL).

• dwFlags
  The following flags are supported.

  Value	Description
  AM_GBF_NOTASYNCPOINT	Dynamic format changes are not allowed on this buffer because it is not a key frame.
  AM_GBF_PREVFRAMESKIPPED	Buffer returned is not filled with data contiguous with any previous data sent.

Return Value

Returns E_NOINTERFACE if an allocator is not found; otherwise, returns the value returned from calling the IMemAllocator::GetBuffer method.

Remarks

The pin object must lock itself before calling this member function; otherwise, the filter graph could disconnect this pin from the input pin midway through the process.

If the filter has no worker threads, the lock is best applied on the IMemInputPin::Receive call; otherwise, it should be done when the worker thread is ready to deliver the sample.

This call can block; therefore, to avoid deadlocking with an IMediaFilter::Stop command, a two-tier locking scheme (such as that implemented in CTransformFilter) is required.

Only the second-level lock is acquired here. The IBaseFilter base class implementation of IMediaFilter::Stop first gets the first-level lock and then calls IMemAllocator::Decommit on the allocator.

This has the effect of making GetDeliveryBuffer return with a failure code. The Stop member function then gets the second-level lock and completes the command by calling Inactive for this pin.

No lock is needed when calling CBaseOutputPin::GetDeliveryBuffer when passing on samples using a worker thread. In this case, the CBaseFilter::Stop base class implementation acquires its filter-level lock and calls IMemAllocator::Decommit on the allocator, at which point the worker thread is freed to listen for a command to stop.

You must release the sample after this function.

If the connected input pin needs to hold on to the sample beyond the function, it adds the reference for the sample through IUnknown::AddRef. You must release this one and call CBaseOutputPin::GetDeliveryBuffer for the next. (You cannot reuse it directly.)

Requirements