Class BufferPool

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

Inheritance

BufferPool

Implements

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

IDisposable