IAMBufferNegotiation Interface

The IAMBufferNegotiation interface tells a pin what kind of buffer specifications it should use when connected. Use this interface when an application requires control over allocating the number of buffers that pins will use when transporting media samples between filters.

The IAMBufferNegotiation::SuggestAllocatorProperties method accepts an ALLOCATOR_PROPERTIES structure that contains the allocator's count, size, alignment, and prefix properties that you want to use. Typically, you set only the cBuffers member of the ALLOCATOR_PROPERTIES structure, which refers to the number of buffers at the specified allocator. All other properties should indicate a negative number to enable your capture hardware to use its own default values.

If a negative value is specified for cBuffers, the allocator will try to allocate as many buffers as it needs, which depends on the available resources and capture frame rate. If you specify a higher value, the allocator will try to allocate more buffers, up to the system's available memory. Allocating a lower number of buffers can result in dropped frames. For teleconferencing applications, it may be desirable to set this number to a smaller value (for example, 2 is a reasonable setting if the network can only support transmission of 2 frames per second (fps) at a given video format and resolution).

Applications can call the IAMBufferNegotiation::GetAllocatorProperties method to retrieve the properties of the allocator being used.

Implement this interface when your pin will connect to another pin by using the IMemInputPin interface and you want to enable an application to allocate the buffer settings to be used for transporting media samples between filters. All capture filters should support this interface to enable applications to specify precise settings for buffers (for a sample implementation, see Vidcap.cpp and Vidcap.h in the Samples\Multimedia\DShow\src\Vidcap subdirectory of the DirectX Media SDK).

Teleconferencing applications should use this interface to specify a minimal number of buffers. This tells the capture filter not to waste resources buffering information in slower capture or disk-writing scenarios.

Methods in Vtable Order

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

IAMBufferNegotiation methods Description

SuggestAllocatorProperties Asks a pin to use the allocator buffer properties set in the ALLOCATOR_PROPERTIES structure.
GetAllocatorProperties Retrieves the properties of the allocator being used by a pin.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMBufferNegotiation methods	Description
SuggestAllocatorProperties	Asks a pin to use the allocator buffer properties set in the ALLOCATOR_PROPERTIES structure.
GetAllocatorProperties	Retrieves the properties of the allocator being used by a pin.

IAMBufferNegotiation::GetAllocatorProperties

IAMBufferNegotiation Interface

Retrieves the properties of the allocator that a pin is using.

Syntax

HRESULT GetAllocatorProperties(
  ALLOCATOR_PROPERTIES *pprop
  );

Parameters

pprop
[out] Pointer to an ALLOCATOR_PROPERTIES structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

Call this method only after the pins connect.

IAMBufferNegotiation::SuggestAllocatorProperties

IAMBufferNegotiation Interface

Asks a pin to use the allocator buffer properties set in the ALLOCATOR_PROPERTIES structure.

Syntax

HRESULT SuggestAllocatorProperties(
  const ALLOCATOR_PROPERTIES *pprop
  );

Parameters

pprop
[in] Pointer to an ALLOCATOR_PROPERTIES structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

An application must call this function before two pins are connected. If the pins are connected before you call this method, then the filter graph will have already negotiated the buffer and it will be too late for an application to preallocate them.
Applications must call this method on both pins being connected to ensure that the other pin doesn't overrule the application's request. However, if one pin doesn't support this interface, a single call will be sufficient.
Use a negative number for any element in the ALLOCATOR_PROPERTIES structure to set properties to default values.