Index
|
|
|
|
|
| |||
| |||
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.
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. IAMBufferNegotiation Interface
IAMBufferNegotiation::GetAllocatorPropertiesRetrieves the properties of the allocator that a pin is using.
HRESULT GetAllocatorProperties(
ALLOCATOR_PROPERTIES *pprop
);Parameters
- pprop
- [out] Pointer to an ALLOCATOR_PROPERTIES structure.
Return Values
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
Call this method only after the pins connect.
See Also
IAMBufferNegotiation Interface
IAMBufferNegotiation::SuggestAllocatorPropertiesAsks a pin to use the allocator buffer properties set in the ALLOCATOR_PROPERTIES structure.
HRESULT SuggestAllocatorProperties(
const ALLOCATOR_PROPERTIES *pprop
);Parameters
- pprop
- [in] Pointer to an ALLOCATOR_PROPERTIES structure.
Return Values
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.
See Also
IAMBufferNegotiation::GetAllocatorProperties
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.