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.
When to Implement
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 (see Vidcap.cpp and Vidcap.h in the \Samples\DS\Vidcap directory for a sample implementation).
When to Use
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. |
Asks a pin to use the allocator buffer properties set in the ALLOCATOR_PROPERTIES structure.
HRESULT SuggestAllocatorProperties(
const ALLOCATOR_PROPERTIES *pprop
);
Returns an HRESULT value that depends on the implementation of the interface.
An application must call this function before two pins are connected. If the pins are connected before this method is called, the buffer will have already been negotiated by the filter graph 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.
IAMBufferNegotiation::GetAllocatorProperties
Retrieves the properties of the allocator that a pin is using.
HRESULT GetAllocatorProperties(
ALLOCATOR_PROPERTIES *pprop
);
Returns an HRESULT value that depends on the implementation of the interface.
Call this method only after the pins connect.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.