ImFusion::BackgroundImageExporter Class Reference

#include <ImFusion/Stream/BackgroundImageExporter.h>

Writes image data to disk in a background thread using the ImFusionImage async interface. More...

Inheritance diagram for ImFusion::BackgroundImageExporter:

Detailed Description

Writes image data to disk in a background thread using the ImFusionImage async interface.

This class provides non-blocking image export functionality, allowing images to be queued for saving to disk independent of the recording to memory. The exporter runs in a separate thread with its own OpenGL context, enabling safe handling of OpenGL-based images through GL::SyncObject synchronization.

The typical workflow consists of three steps:

1. Call initializeFile() to set up the output file and compression options
2. Call addImage() repeatedly for each image to be saved (non-blocking)
3. Call finalizeFile() to complete the file and wait for all images to be written

Note

This class can only be used once to export images to a file. Multiple initializeFile, addImage, and finalizeFile cycles are not supported.

This class is not thread-safe. The user must ensure that calls of initializeFile, addImage, and finalizeFile are synchronized when using this class in a multi-threaded context.

All image pixel types are supported for uncompressed recording. FFV1 compression requires unsigned char images; other pixel types will be skipped with a warning when compression is enabled.

The SharedImageSet container passed to initializeFile() must contain at least one image for metadata extraction. The container is cloned internally to decouple its lifetime from the background export task.

// Create exporter
BackgroundImageExporter exporter;
 
// Initialize file with a container containing at least one image
SharedImageSet container;
container.add(firstImage);  // At least one image required for metadata
exporter.initializeFile(&container, "output.bin", false);  // false = no FFV1 compression
 
// Add images as they arrive (non-blocking)
for (int i = 0; i < numImages; ++i)
{
    std::shared_ptr<const SharedImage> image = getNextImage();
    double timestamp = getImageTimestamp(i);
 
    // Optional: provide GL sync object if the SharedImage contains an OpenGL image
    std::optional<GL::SyncObject> glSync;
    if (image->containsGlImage())
    {
        glSync = GL::SyncObject();
        GL::flush();
    }
 
    exporter.addImage(image, timestamp, std::move(glSync));
}
 
// Finalize and wait for all images to be saved (blocking)
exporter.finalizeFile();

The class internally uses the async functionality of ImFusionImage.

See also

ImFusionImage::startSaveAsync(), ImFusionImage::addFrameAsync(), ImFusionImage::closeAsync()

Public Member Functions
	BackgroundImageExporter ()
	Constructs a new BackgroundImageExporter instance.
virtual	~BackgroundImageExporter ()
	Destroys the exporter.
void	initializeFile (SharedImageSet *container, const std::string &path, bool ffv1Compression)
	Initializes a file for live recording.
void	addImage (std::shared_ptr< const SharedImage > img, double timestamp, std::optional< GL::SyncObject > glSync=std::nullopt)
	Adds an image to the save queue.
void	finalizeFile ()
	Finalizes the file recording and waits for all images to be saved.
bool	isInitialized () const
	Returns true if the exporter is initialized and ready to accept images.

Constructor & Destructor Documentation

BackgroundImageExporter()

ImFusion::BackgroundImageExporter::BackgroundImageExporter

(

)

Constructs a new BackgroundImageExporter instance.

Launches a background thread with its own OpenGL context for saving the images. The exporter is ready to use after construction, but initializeFile() must be called before adding images.

~BackgroundImageExporter()

virtual ImFusion::BackgroundImageExporter::~BackgroundImageExporter ( )

virtual

Destroys the exporter.

Warning

finalizeFile() must be called before destruction. The destructor will assert if the exporter is still initialized as the file would not be usable afterwards.

Member Function Documentation

initializeFile()

void ImFusion::BackgroundImageExporter::initializeFile	(	SharedImageSet *	container,
		const std::string &	path,
		bool	ffv1Compression )

Initializes a file for live recording.

Sets up the output file and prepares the exporter for image saving. The provided SharedImageSet must contain at least one image to ensure correct metadata extraction. This method is blocking and will open the file immediately.

Parameters

container	SharedImageSet containing at least one image for metadata extraction. The container is cloned internally to decouple its lifetime from the background export task.
path	File path where images will be saved. The file is opened in binary mode.
ffv1Compression	If true, enables FFV1 codec compression for the saved images. If false, images are saved in uncompressed raw format.

Note

This method must be called before addImage() can be used.

addImage()

void ImFusion::BackgroundImageExporter::addImage	(	std::shared_ptr< const SharedImage >	img,
		double	timestamp,
		std::optional< GL::SyncObject >	glSync = std::nullopt )

Adds an image to the save queue.

Queues an image for saving in the background thread. This method is non-blocking and returns immediately. The image is saved asynchronously by the background thread.

Parameters

img	Shared pointer to the image to save. Must be of unsigned char type. Images with other pixel types will be skipped with a warning.
timestamp	Timestamp associated with the image, stored for later retrieval.
glSync	Optional GL::SyncObject for synchronizing OpenGL contexts when the image contains OpenGL-based images. If provided, the background thread will wait for the sync object before accessing the image data.

Note

initializeFile() must be called before this method.

finalizeFile()

void ImFusion::BackgroundImageExporter::finalizeFile

(

)

Finalizes the file recording and waits for all images to be saved.

This method is blocking and will not return until all images have been saved.

After calling this method, the exporter is reset and isInitialized returns false.

Note

This method must be called before destruction to ensure the file is properly finalized and all images are saved.

The file will not be readable until this method completes successfully.

---

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

• ImFusion/Stream/BackgroundImageExporter.h