Class BufferPool

The buffer pool allows allocating additional buffers for use by the program.

Inheritance
object
HandleObject
BufferPool
Implements
Inherited Members
Namespace: ic4
Assembly: ic4dotnet.dll
Syntax
public class BufferPool : HandleObject, IDisposable
Remarks

Most programs will only use buffers provided by one of the sink types. However, some programs require additional buffers, for example to use as destination for image processing.

To create additional buffers, first create a buffer pool by calling the constructor BufferPool(ulong, ulong?, IBufferAllocator). Then, use GetBuffer(ImageType, uint, int, ulong) to request a new buffer with a specified image type. Allocation options can be specified to customize the image buffer's memory alignment, pitch and total buffer size.

When an image buffer is no longer required, call Dispose() on it. The image buffer will then be returned to the buffer pool.

The buffer pool has configurable caching behavior. By default, the buffer pool will cache one image buffer and return it the next time a matching image buffer is requested.

Image buffers objects created by the buffer pool are still valid after the buffer pool itself has been disposed.

Constructors

BufferPool(ulong, ulong?, IBufferAllocator)

Create a new buffer pool, optionally specifying a caching behavior and a custom allocator.

Declaration
public BufferPool(ulong cacheFramesMax = 1, ulong? cacheBytesMax = null, IBufferAllocator customAllocator = null)
Parameters
Type Name Description
ulong cacheFramesMax

Maximum number of frames to keep in the buffer pool's cache
ulong? cacheBytesMax

Maximum size of the buffer pool cache in bytes, or null to not limit by size
IBufferAllocator customAllocator

The custom allocator to be used by the new buffer pool, or null to use the default allocator.
Exceptions
Type Condition
IC4Exception

Check ErrorCode and ToString() for details.

Methods

GetBuffer(ImageType, uint, int, ulong)

Requests a buffer from the buffer pool.

Declaration
public ImageBuffer GetBuffer(ImageType imageType, uint alignment = 0, int pitch = 0, ulong bufferSize = 0)
Parameters
Type Name Description
ImageType imageType

Image type of the requested buffer.
uint alignment

Specifies the alignment of the address of the buffer's memory.

Setting this to 0 lets the buffer pool select an alignment automatically.

The alignment must be a power of 2.
int pitch

Specifies the pitch to use when allocating the buffer.

A value of 0 lets the buffer pool select a pitch automatically.

Setting a pitch that is smaller than the amount of memory required to store one line of image data will lead to an error.
ulong bufferSize

Overrides the automatic buffer size calculation.

A value of 0 lets the buffer pool calculate the required buffer size automatically.

Setting a size that is smaller than the amount of memory required to store an image of a known format will lead to an error.
Returns
Type Description
ImageBuffer

The new image buffer
Remarks

The buffer is either newly allocated, or retrieved from the buffer pool's buffer cache.

Exceptions
Type Condition
ArgumentNullException

imageType is null.
IC4Exception

Check ErrorCode and ToString() for details.

Implements