ImageBufferAllocator Class

Provides the byte arrays the library uses for pixels, decoders, encoders and scratch memory, in place of the process-wide pool (ImageBufferPool), for the images and operations of a configuration (ImageConfiguration.BufferAllocator).

public abstract class ImageBufferAllocator

Remarks

Use it to take the memory of the library from a pool of your own (an ArrayPool<T>, pinned arrays shared with native code, a pool per tenant), or to measure what it allocates. The resource limits are unchanged: before renting a buffer, the library charges ImageBufferAllocator.GetBufferLength bytes to the operation and rejects the request with an ImageResourceLimitException when it exceeds ImageResourceLimits.MaxLiveAllocationBytes, so the allocator is never asked for more than the limits allow.

The library rents an array with ImageBufferAllocator.Rent, uses its first length bytes, and returns it exactly once with ImageBufferAllocator.Return when the image is disposed or the operation ends, after which it never reads or writes it. It clears the bytes it exposes, so ImageBufferAllocator.Rent may return arrays with any content. An array whose length is not the one ImageBufferAllocator.GetBufferLength declared is returned and the operation fails with an InvalidOperationException. An exception of ImageBufferAllocator.Rent, such as an OutOfMemoryException, fails the operation and releases what it acquired.

The methods are called concurrently by the images and the operations that use the configuration (and by the workers of an operation that runs in parallel): an implementation must be thread-safe. Requests are from 1 byte to Array.MaxLength bytes. The memory that Image.WrapMemory wraps is the caller's, and never comes from the allocator.

Example

var allocator = new PinnedAllocator();
var configuration = new ImageConfiguration { BufferAllocator = allocator };
using (var image = new Image<Rgba32>(64, 64, configuration))
{
    image.GaussianBlur(2);
    using var clone = image.CloneAs<Rgba64>();
    Assert.True(allocator.LiveBytes > 0);
}

// Every array is returned once the images are disposed
Assert.Equal(0, allocator.LiveBytes);

Constructors

NameDescription
ImageBufferAllocator()Initializes a new instance of the ImageBufferAllocator class.

ImageBufferAllocator()

ImageBufferAllocator.cs

Initializes a new instance of the ImageBufferAllocator class.

protected ImageBufferAllocator()

Methods

NameDescription
GetBufferLength(int)Gets the length of the array ImageBufferAllocator.Rent returns for a request, which is the size the library charges.
Rent(int)Rents an array of ImageBufferAllocator.GetBufferLength bytes.
Return(byte[])Returns an array that ImageBufferAllocator.Rent gave. The library does not use it afterward.

GetBufferLength(int)

ImageBufferAllocator.cs

Gets the length of the array ImageBufferAllocator.Rent returns for a request, which is the size the library charges.

public virtual int GetBufferLength(int length)

Parameters

length int
The requested length, from 1 to Array.MaxLength.

Returns

int The length of the array, from length to Array.MaxLength. The default is length.

Rent(int)

Rents an array of ImageBufferAllocator.GetBufferLength bytes.

public abstract byte[] Rent(int length)

Parameters

length int
The requested length, from 1 to Array.MaxLength.

Returns

byte[] An array of exactly ImageBufferAllocator.GetBufferLength bytes, with any content.

Return(byte[])

Returns an array that ImageBufferAllocator.Rent gave. The library does not use it afterward.

public abstract void Return(byte[] buffer)

Parameters

buffer byte[]
The array.