BufferPool Class Reference

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

Classes

struct	AllocationOptions Contains options to configure the allocation when requesting an image buffer from a buffer pool. More...
struct	CacheConfig Configures the buffer pool's caching behavior. More...

Public Member Functions

std::shared_ptr< ImageBuffer >	getBuffer (const ImageType &image_type, const AllocationOptions &alloc_options, Error &err=Error::Default()) const Request a buffer from the buffer pool.
std::shared_ptr< ImageBuffer >	getBuffer (const ImageType &image_type, Error &err=Error::Default()) const Gets a buffer from the buffer pool.

Static Public Member Functions

static std::shared_ptr< BufferPool >	create (const CacheConfig &cache_config, BufferAllocator &alloc, Error &err=Error::Default()) Create a new buffer pool, specifying a caching behavior and a custom allocator.
static std::shared_ptr< BufferPool >	create (const CacheConfig &cache_config, const std::shared_ptr< BufferAllocator > &alloc, Error &err=Error::Default()) Create a new buffer pool, specifying a caching behavior and a custom allocator.
static std::shared_ptr< BufferPool >	create (BufferAllocator &alloc, Error &err=Error::Default()) Create a new buffer pool, specifying a custom allocator.
static std::shared_ptr< BufferPool >	create (const std::shared_ptr< BufferAllocator > &alloc, Error &err=Error::Default()) Create a new buffer pool, specifying a custom allocator.
static std::shared_ptr< BufferPool >	create (const CacheConfig &cache_config, Error &err=Error::Default()) Create a new buffer pool, specifying a caching behavior.
static std::shared_ptr< BufferPool >	create (Error &err=Error::Default()) Create a new buffer pool, using default caching behavior and the default allocator.

Detailed Description

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

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 using BufferPool::create. Then, use BufferPool::getBuffer to create 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.

Image buffers owned by the program are tracked by instances of std::shared_ptr<ImageBuffer>. When the image buffer is no longer required, reset all pointers to 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 created by the buffer pool are still valid after the buffer pool itself has been destroyed.

Buffer pool objects are neither copyable nor movable, and are only handled via std::shared_ptr<BufferPool>.

Member Function Documentation

◆ create() [1/6]

static std::shared_ptr< BufferPool > create	(	BufferAllocator &	alloc,
		Error &	err = `Error::Default()`
	)

inlinestatic

Create a new buffer pool, specifying a custom allocator.

Parameters

[in]	alloc	The custom allocator to be used by the new buffer pool. The referenced object must be valid while the buffer pool exists.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: The new buffer pool, or nullptr if an error occurs.

◆ create() [2/6]

static std::shared_ptr< BufferPool > create	(	const CacheConfig &	cache_config,
		BufferAllocator &	alloc,
		Error &	err = `Error::Default()`
	)

inlinestatic

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

Parameters

[in]	cache_config	The caching behavior of the new buffer pool
[in]	alloc	The custom allocator to be used by the new buffer pool. The referenced object must be valid while the buffer pool exists.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: The new buffer pool, or nullptr if an error occurs.

◆ create() [3/6]

static std::shared_ptr< BufferPool > create	(	const CacheConfig &	cache_config,
		const std::shared_ptr< BufferAllocator > &	alloc,
		Error &	err = `Error::Default()`
	)

inlinestatic

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

Parameters

[in]	cache_config	The caching behavior of the new buffer pool
[in]	alloc	The custom allocator to be used by the new buffer pool.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: The new buffer pool, or nullptr if an error occurs.

◆ create() [4/6]

static std::shared_ptr< BufferPool > create	(	const CacheConfig &	cache_config,
		Error &	err = `Error::Default()`
	)

inlinestatic

Create a new buffer pool, specifying a caching behavior.

Parameters

[in]	cache_config	The caching behavior of the new buffer pool
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: The new buffer pool, or nullptr if an error occurs.

◆ create() [5/6]

static std::shared_ptr< BufferPool > create	(	const std::shared_ptr< BufferAllocator > &	alloc,
		Error &	err = `Error::Default()`
	)

inlinestatic

Create a new buffer pool, specifying a custom allocator.

Parameters

[in]	alloc	The custom allocator to be used by the new buffer pool.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: The new buffer pool, or nullptr if an error occurs.

◆ create() [6/6]

static std::shared_ptr< BufferPool > create ( Error & err = Error::Default() )

inlinestatic

Create a new buffer pool, using default caching behavior and the default allocator.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: The new buffer pool, or nullptr if an error occurs.

◆ getBuffer() [1/2]

std::shared_ptr< ImageBuffer > getBuffer	(	const ImageType &	image_type,
		const AllocationOptions &	alloc_options,
		Error &	err = `Error::Default()`
	)		const

inline

Request a buffer from the buffer pool.

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

Parameters

[in]	image_type	Image type of the requested buffer.
[in]	alloc_options	Structure containing advanced allocation options.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: The new image buffer, or nullptr if an error occurs.

◆ getBuffer() [2/2]

std::shared_ptr< ImageBuffer > getBuffer	(	const ImageType &	image_type,
		Error &	err = `Error::Default()`
	)		const

inline

Gets a buffer from the buffer pool.

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

Parameters

[in]	image_type	Image type of the requested buffer.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: The new image buffer, or nullptr if an error occurs.