Microsoft DirectX 8.0

IAMBufferNegotiation Interface

The IAMBufferNegotiation interface is implemented on pins, particularly on pins in capture filters, to enable applications to control the buffer allocation process for the pin.

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.

If your application is performing audio preview (sending captured audio to an output device) and you find that the latency is too high, try specifying a smaller number of buffers.

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.

Filter developers: 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.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IAMBufferNegotiation methodsDescription
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 S_OK if successful, otherwise returns an HRESULT value indicating the cause of the failure. Possible error codes include the following:

E_FAILFailure.
E_POINTERNULL pointer.
VFW_E_NOT_CONNECTEDPin is not connected.

Remarks

Call this method only after the pins connect.

See Also

SuggestAllocatorProperties

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 S_OK if successful, otherwise returns an HRESULT value indicating the cause of the failure. Possible error codes include the following:

E_FAILFailure. (Could not use suggested properties.)
E_POINTERNULL pointer.
E_UNEXPECTEDUnexpected failure.
VFW_E_ALREADY_CONNECTEDPin is already connected.

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.

See Also

IAMBufferNegotiation::GetAllocatorProperties