SharedImageRingBuffer Class Reference

#include <ImFusion/Stream/SharedImageRingBuffer.h>

Holds a vector of shared_ptr<SharedImage>, which can be used alternatively to avoid reallocation It provides methods to get the next buffer which is not held by some other listener as well, and can be hence written into. More...

Detailed Description

Holds a vector of shared_ptr<SharedImage>, which can be used alternatively to avoid reallocation It provides methods to get the next buffer which is not held by some other listener as well, and can be hence written into.

If no buffer is free, a new one will be allocated, until the specified size for the buffer ring is reached. Then the newest image will be discarded (the oldest image has the highest likelihood of being free if the stream listeners hold to the received images for a long time).

If the cache is large enough, asking for images with the same descriptor should never cause a new allocation after a ramp-up time. Images can be allocated in advance with ensureAllocated(), also for different resolutions (as long as the total number of allocated images is not above the maximum size). If the size of the images to be broadcasted changes, a different descriptor can be passed to getBuffer(): old incompatible images will be discarded as needed. ensureAllocated() can be used with the new descriptor to force allocation of a given number of images with the new format at once.

If a fixed number of independent "channels" with different resolutions must be published, it is advisable to create a SharedImageRingBuffer for each of them to ensure the maximum performance.

Usage example:

class MyImageStream : public ImageStream {
     MyImageStream() : m_ringBuffer(m_descriptor)
     {
          m_ringBuffer.ensureAllocated(2, m_descriptor); // optional: preallocates memory to avoid slowdowns on the first frame
     }
     void processingThread() {
          auto nextBuffer = m_ringBuffer->getBuffer(m_descriptor);
          nextBuffer.buffer.update(computationResult);  // copy the data to be broadcasted into the buffer
          ImageStreamData isd(this, std::move(nextBuffer.buffer)); // the move is important: only the buffer and each listener should hold a reference
          updateListenersData(isd);
     }
}

Classes
struct	SharedImageBuffer

Public Member Functions
size_t	size () const
	current number of buffers kept in memory
size_t	maxSize () const
	Maximum number of buffers to be kept in memory at the same time (default is 2)
void	setMaxSize (size_t newMaxSize)
	Set the maximum number of buffers to be kept in memory at the same time The cache will be truncated if necessary.
SharedImageBuffer	getBuffer (const ImageDescriptor &desc, Image::Location mainAllocationLocation=Image::Location::MEMORY)
	Get a buffer that can be currently written into and shared with listeners; it shall contain an image compatible with the given descriptor Optionally a memory location can be specified to directly allocate images that only reside in VRAM or in system RAM.
bool	mustAllocate (const ImageDescriptor &desc)
	true if no buffer with the given descriptor is available
void	clear ()
	Remove all buffers.
void	clearIncompatible (const ImageDescriptor &desc)
	Remove all buffers not compatible with the given descriptor.
size_t	ensureAllocated (size_t requestedBuffers, const ImageDescriptor &desc, Image::Location mainAllocationLocation=Image::Location::MEMORY)
	Allocate the buffers needed to reach the given number immediately if needed, expand the maximum size if necessary Existing buffers not compatible with the given descriptor will be only discarded if the maximum size is exceeded Optionally a memory location can be specified to directly allocate images that only reside in VRAM or in system RAM.

Member Function Documentation

getBuffer()

SharedImageBuffer getBuffer	(	const ImageDescriptor &	desc,
		Image::Location	mainAllocationLocation = Image::Location::MEMORY )

Get a buffer that can be currently written into and shared with listeners; it shall contain an image compatible with the given descriptor Optionally a memory location can be specified to directly allocate images that only reside in VRAM or in system RAM.

Currently only Image::Location::MEMORY and Image::Location::OPENGL are supported. (By default the image is allocated in system RAM).

ensureAllocated()

size_t ensureAllocated	(	size_t	requestedBuffers,
		const ImageDescriptor &	desc,
		Image::Location	mainAllocationLocation = Image::Location::MEMORY )

Allocate the buffers needed to reach the given number immediately if needed, expand the maximum size if necessary Existing buffers not compatible with the given descriptor will be only discarded if the maximum size is exceeded Optionally a memory location can be specified to directly allocate images that only reside in VRAM or in system RAM.

Currently only Image::Location::MEMORY and Image::Location::OPENGL are supported. (By default the image is allocated in system RAM).

Returns

The number of new buffers actually allocated

---

The documentation for this class was generated from the following file:

• ImFusion/Stream/SharedImageRingBuffer.h