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]allocThe custom allocator to be used by the new buffer pool.
The referenced object must be valid while the buffer pool exists.
[out]errReference 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_configThe caching behavior of the new buffer pool
[in]allocThe custom allocator to be used by the new buffer pool.
The referenced object must be valid while the buffer pool exists.
[out]errReference 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_configThe caching behavior of the new buffer pool
[in]allocThe custom allocator to be used by the new buffer pool.
[out]errReference 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_configThe caching behavior of the new buffer pool
[out]errReference 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]allocThe custom allocator to be used by the new buffer pool.
[out]errReference 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]errReference 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_typeImage type of the requested buffer.
[in]alloc_optionsStructure containing advanced allocation options.
[out]errReference 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_typeImage type of the requested buffer.
[out]errReference to an error handler. See Error Handling for details.
Returns
The new image buffer, or nullptr if an error occurs.