The core class for reading/writing and storing images in an optimized way. More...

Collaboration diagram for ImageFactory:

Public Member Functions
void	addFormatHandler (ImageFormatHandler *handler)
	Registers a format handler with this ImageFactory instance.
void	addImageCompressed (const StringView &id, const Buffer< uint01 > &compressed, bool clear_other)
	Adds a compressed image to the cache, auto-detecting the compression format.
void	addImageCompressed (const StringView &id, const StringView &extension, const Buffer< uint01 > &compressed, bool clear_other)
	Adds a compressed image with a known format extension to the cache.
void	addImageCompressed (const StringView &id, const StringView &extension, const Buffer< uint01 > &compressed, const Vector< 2, uint04 > &size, bool clear_other)
	Adds a compressed image with a known format extension and explicit dimensions to the cache.
void	addImageFile (const StringView &id, const File &file, bool clear_other)
	Adds an image to the cache by reading from a file on disk.
void	addImageUncompressed (const StringView &id, const Buffer< uint01 > &uncompressed, bool clear_other)
	Adds an uncompressed (raw ARGB) image to the cache.
void	addImageUncompressed (const StringView &id, const Buffer< uint01 > &uncompressed, const Vector< 2, uint04 > &size, bool clear_other)
	Adds an uncompressed (raw ARGB) image with explicit dimensions to the cache.
Dictionary< String, DynamicPointer< ImageCacheData > >	cachedData () const
	Returns a copy of the internal cache dictionary mapping image IDs to their cache data.
const Buffer< uint01 > &	calculateAndGetDecompressed (ImageCacheData &data)
	Ensures the decompressed data is available, decompressing if necessary, and returns it.
bool	canRead (const File &file)
	Checks whether any registered handler can read the given file.
void	clearAllImageData (const StringView &id)
	Removes all cached data (compressed, decompressed, metadata) for the given image.
StringView	compressionFormat (const StringView &id)
	Returns the compression format extension of the cached image's compressed data.
void	convertColorTheme (const Buffer< std::pair< LABColor, LABColor > > &color, String &image, bool preserve_brightness, bool preserve_alpha)
	Remaps the colors of a cached image using LAB color space substitutions.
void	convertDirectory (const File &directory, const StringView &from_ext, const StringView &to_ext)
	Converts all images in a directory from one format to another.
void	copyImage (const StringView &id_destination, const StringView &id_source)
	Copies cached image data from one identifier to another.
bool	determineCompressionFormat (ImageCacheData &data)
	Attempts to determine the compression format of the image's compressed data by inspecting its header bytes.
ImageReadPointer	getCompressed (const StringView &id, StringView default_extension=".png")
	Retrieves the compressed data for the cached image in its current or default format.
ImageReadPointer	getCompressedInFormat (const StringView &id, const Buffer< StringView > &acceptable_formats)
	Retrieves the compressed data for the cached image in one of the acceptable formats.
ImageReadPointer	getCompressedInFormat (const StringView &id, const StringView &extension)
	Retrieves the compressed data for the cached image, converting to a specific format.
ImageWritePointer	getEditableData (const StringView &id)
	Returns a writable pointer to the image cache data with a write lock acquired.
ImageReadPointer	getMetaData (const StringView &id)
	Retrieves metadata for the cached image, reading it from the source if necessary.
ImageReadPointer	getReadOnlyData (const StringView &id) const
	Returns a read-only pointer to the image cache data with a read lock acquired.
ImageReadPointer	getSize (const StringView &id)
	Retrieves the image dimensions without fully decompressing the image data.
virtual void	getSupportedFormats (AlocatingAlignedBuffer< FileFormat, 64 > &formats, bool is_read) const
	Populates a buffer with all file formats supported by this factory and its handlers.
ImageReadPointer	getUncompressed (const StringView &id, bool ensure_valid_transparancy=false)
	Retrieves the uncompressed (raw ARGB) pixel data for the cached image.
void	handleMetaData (ImageCacheData &data)
	Reads and processes metadata (e.g., EXIF) from the image data using registered handlers.
bool	hasImage (const StringView &id) const
	Checks whether an image with the given identifier exists in the cache.
bool	hasTransparency (ImageCacheData &data)
	Determines whether the image truly contains transparent pixels (not just an alpha channel).
Time	modifiedTime (const StringView &id) const
	Returns the last modification time of the cached image.
String	optimizedWriteFileName (const StringView &id, const Buffer< String > &optional_extensions=Buffer< String >())
	Determines the optimal file name and extension for writing the image to disk.
void	readFromBMP (ImageCacheData &data)
	Reads image data from a BMP-formatted source into the cache data.
bool	readFromCompressed (ImageCacheData &data)
	Reads image data from the compressed_data buffer in the cache data using registered handlers.
bool	readFromFile (ImageCacheData &data, StringView format_extension=StringView())
	Reads image data from the file referenced in the cache data.
void	removeFormatHandler (const UUID &handler)
	Removes a previously registered format handler by its UUID.
void	setWriteQuality (fltp08 quality)
	Sets the quality level used when writing compressed images (e.g., JPEG quality).
void	writeToFile (const StringView &id, const File &file)
	Writes the cached image to a file on disk.

Static Public Member Functions
static void	AddFormatHandler (ImageFormatHandler *handler)
	Registers a format handler with the global static handler registry, available to all ImageFactory instances.
static ImageFactory &	DefaultFactory ()
	Returns the singleton default ImageFactory instance.
static FileFormat	PNGFormat ()
	Creates and returns a FileFormat descriptor for the PNG image format.
static void	ReadJPG (const uint01 input, uint04 input_length, uint01 buffer, bool has_alpha, uint04 dst_line_span, const Vector< 2, uint04 > &offset)
	Decodes JPEG data from a memory buffer into a raw pixel buffer.
static void	RemoveFormatHandler (const UUID &handler)
	Removes a format handler from the global static handler registry.
static void	Resize (const Buffer< uint01 > &input, const Vector< 2, uint04 > &in_size, const Vector< 2, uint04 > &out_size, Buffer< uint01 > &output)
	Resizes raw pixel data from one resolution to another using bilinear or nearest-neighbor sampling.
static void	WriteToFile (const uint01 *data, Vector< 2, uint04 > size, uint04 px_size, const File &file, fltp08 write_quality=1.0)
	Writes raw pixel data to a file on disk in the format determined by the file extension.

Protected Attributes
Dictionary< String, DynamicPointer< ImageCacheData > >	m_cached_data
	Cache mapping image identifiers to their associated data.
Dictionary< UUID, ImageFormatHandler * >	m_format_handlers
	Instance-level registered format handlers keyed by UUID.
RWLock	m_lock
	Read-write lock protecting access to the cache and handler dictionaries.
fltp08	m_write_quality = 1.0
	Default write quality for compressed output (0.0 to 1.0).

Static Protected Attributes
static Dictionary< UUID, ImageFormatHandler * >	s_format_handlers
	Global static registry of format handlers shared across all ImageFactory instances.

Detailed Description

The core class for reading/writing and storing images in an optimized way.

All raw data is stored in ARGB 32-bit format. Compressed images consist of an in-memory format such as jpeg/png/etc

Definition at line 210 of file ImageFactory.h.

Member Function Documentation

◆ AddFormatHandler()

void ImageFactory::AddFormatHandler ( ImageFormatHandler * handler )

static

Registers a format handler with the global static handler registry, available to all ImageFactory instances.

Parameters

[in] handler Pointer to the ImageFormatHandler to register globally.

◆ addFormatHandler()

void ImageFactory::addFormatHandler ( ImageFormatHandler * handler )

Registers a format handler with this ImageFactory instance.

Parameters

[in] handler Pointer to the ImageFormatHandler to add. Ownership is not transferred.

◆ addImageCompressed() [1/3]

void ImageFactory::addImageCompressed	(	const StringView &	id,
		const Buffer< uint01 > &	compressed,
		bool	clear_other )

Adds a compressed image to the cache, auto-detecting the compression format.

Parameters

[in]	id	The unique string identifier for the image.
[in]	compressed	The compressed image data buffer.
[in]	clear_other	Whether to clear other cached representations of this image.

◆ addImageCompressed() [2/3]

void ImageFactory::addImageCompressed	(	const StringView &	id,
		const StringView &	extension,
		const Buffer< uint01 > &	compressed,
		bool	clear_other )

Adds a compressed image with a known format extension to the cache.

Parameters

[in]	id	The unique string identifier for the image.
[in]	extension	The compression format extension (e.g., ".png", ".jpg").
[in]	compressed	The compressed image data buffer.
[in]	clear_other	Whether to clear other cached representations of this image.

◆ addImageCompressed() [3/3]

void ImageFactory::addImageCompressed	(	const StringView &	id,
		const StringView &	extension,
		const Buffer< uint01 > &	compressed,
		const Vector< 2, uint04 > &	size,
		bool	clear_other )

Adds a compressed image with a known format extension and explicit dimensions to the cache.

Parameters

[in]	id	The unique string identifier for the image.
[in]	extension	The compression format extension (e.g., ".png", ".jpg").
[in]	compressed	The compressed image data buffer.
[in]	size	The image dimensions (width, height) in pixels.
[in]	clear_other	Whether to clear other cached representations of this image.

◆ addImageFile()

void ImageFactory::addImageFile	(	const StringView &	id,
		const File &	file,
		bool	clear_other )

Adds an image to the cache by reading from a file on disk.

Parameters

[in]	id	The unique string identifier for the image.
[in]	file	The file to read image data from.
[in]	clear_other	Whether to clear other cached representations (compressed/decompressed) of this image.

◆ addImageUncompressed() [1/2]

void ImageFactory::addImageUncompressed	(	const StringView &	id,
		const Buffer< uint01 > &	uncompressed,
		bool	clear_other )

Adds an uncompressed (raw ARGB) image to the cache.

Parameters

[in]	id	The unique string identifier for the image.
[in]	uncompressed	The raw uncompressed pixel data buffer.
[in]	clear_other	Whether to clear other cached representations of this image.

Referenced by MaterialRaster::MaterialRaster(), OpenCVImageRaster::setup(), MaterialRaster::updateImage(), and OpenCVImageRaster::updateImage().

◆ addImageUncompressed() [2/2]

void ImageFactory::addImageUncompressed	(	const StringView &	id,
		const Buffer< uint01 > &	uncompressed,
		const Vector< 2, uint04 > &	size,
		bool	clear_other )

Adds an uncompressed (raw ARGB) image with explicit dimensions to the cache.

Parameters

[in]	id	The unique string identifier for the image.
[in]	uncompressed	The raw uncompressed pixel data buffer.
[in]	size	The image dimensions (width, height) in pixels.
[in]	clear_other	Whether to clear other cached representations of this image.

◆ cachedData()

Dictionary< String, DynamicPointer< ImageCacheData > > ImageFactory::cachedData ( ) const

Returns a copy of the internal cache dictionary mapping image IDs to their cache data.

Returns: A Dictionary mapping image identifier strings to their DynamicPointer<ImageCacheData>.

◆ calculateAndGetDecompressed()

const Buffer< uint01 > & ImageFactory::calculateAndGetDecompressed ( ImageCacheData & data )

Ensures the decompressed data is available, decompressing if necessary, and returns it.

Parameters

[in] data The image cache data to decompress if needed.

Returns: A const reference to the decompressed pixel data buffer.

◆ canRead()

bool ImageFactory::canRead ( const File & file )

Checks whether any registered handler can read the given file.

Parameters

[in] file The file to check.

Returns: True if the file can be read by at least one handler.

◆ clearAllImageData()

void ImageFactory::clearAllImageData ( const StringView & id )

Removes all cached data (compressed, decompressed, metadata) for the given image.

Parameters

[in] id The unique string identifier for the image to clear.

◆ compressionFormat()

StringView ImageFactory::compressionFormat ( const StringView & id )

Returns the compression format extension of the cached image's compressed data.

Parameters

[in] id The unique string identifier for the image.

Returns: The format extension string (e.g., ".png"), or empty if unknown.

◆ convertColorTheme()

void ImageFactory::convertColorTheme	(	const Buffer< std::pair< LABColor, LABColor > > &	color,
		String &	image,
		bool	preserve_brightness,
		bool	preserve_alpha )

Remaps the colors of a cached image using LAB color space substitutions.

Parameters

[in]	color	Buffer of LAB color pairs (source, target) defining the color mapping.
[in]	image	The image identifier to convert (modified in place).
[in]	preserve_brightness	Whether to preserve the original pixel brightness during conversion.
[in]	preserve_alpha	Whether to preserve the original alpha channel during conversion.

◆ convertDirectory()

void ImageFactory::convertDirectory	(	const File &	directory,
		const StringView &	from_ext,
		const StringView &	to_ext )

Converts all images in a directory from one format to another.

Parameters

[in]	directory	The directory containing image files.
[in]	from_ext	The source format extension to convert from.
[in]	to_ext	The target format extension to convert to.

◆ copyImage()

void ImageFactory::copyImage	(	const StringView &	id_destination,
		const StringView &	id_source )

Copies cached image data from one identifier to another.

Parameters

[in]	id_destination	The target image identifier.
[in]	id_source	The source image identifier.

◆ DefaultFactory()

ImageFactory & ImageFactory::DefaultFactory ( )

static

Returns the singleton default ImageFactory instance.

Returns: A reference to the global default ImageFactory.

Referenced by MaterialRaster::MaterialRaster(), ImageChooserGallery::fillWithImages(), OpenCVImageRaster::setup(), GLESImageData::update(), MaterialRaster::updateImage(), and OpenCVImageRaster::updateImage().

◆ determineCompressionFormat()

bool ImageFactory::determineCompressionFormat ( ImageCacheData & data )

Attempts to determine the compression format of the image's compressed data by inspecting its header bytes.

Parameters

[in] data The image cache data whose compression_format field will be set.

Returns: True if the format was successfully determined.

◆ getCompressed()

ImageReadPointer ImageFactory::getCompressed	(	const StringView &	id,
		StringView	default_extension = ".png" )

Retrieves the compressed data for the cached image in its current or default format.

Parameters

[in]	id	The unique string identifier for the image.
[in]	default_extension	The preferred compression format if conversion is needed.

Returns: A read-locked pointer to the image cache data with populated compressed_data.

◆ getCompressedInFormat() [1/2]

ImageReadPointer ImageFactory::getCompressedInFormat	(	const StringView &	id,
		const Buffer< StringView > &	acceptable_formats )

Retrieves the compressed data for the cached image in one of the acceptable formats.

Parameters

[in]	id	The unique string identifier for the image.
[in]	acceptable_formats	A buffer of acceptable format extensions, in order of preference.

Returns: A read-locked pointer to the image cache data in a matching format.

◆ getCompressedInFormat() [2/2]

ImageReadPointer ImageFactory::getCompressedInFormat	(	const StringView &	id,
		const StringView &	extension )

Retrieves the compressed data for the cached image, converting to a specific format.

Parameters

[in]	id	The unique string identifier for the image.
[in]	extension	The required compression format extension.

Returns: A read-locked pointer to the image cache data in the requested format.

◆ getEditableData()

ImageWritePointer ImageFactory::getEditableData ( const StringView & id )

Returns a writable pointer to the image cache data with a write lock acquired.

Parameters

[in] id The unique string identifier for the image.

Returns: A write-locked pointer to the image cache data.

◆ getMetaData()

ImageReadPointer ImageFactory::getMetaData ( const StringView & id )

Retrieves metadata for the cached image, reading it from the source if necessary.

Parameters

[in] id The unique string identifier for the image.

Returns: A read-locked pointer to the image cache data with populated metadata.

◆ getReadOnlyData()

ImageReadPointer ImageFactory::getReadOnlyData ( const StringView & id ) const

Returns a read-only pointer to the image cache data with a read lock acquired.

Parameters

[in] id The unique string identifier for the image.

Returns: A read-locked pointer to the image cache data.

◆ getSize()

ImageReadPointer ImageFactory::getSize ( const StringView & id )

Retrieves the image dimensions without fully decompressing the image data.

Parameters

[in] id The unique string identifier for the image.

Returns: A read-locked pointer to the image cache data with populated size field.

◆ getSupportedFormats()

virtual void ImageFactory::getSupportedFormats	(	AlocatingAlignedBuffer< FileFormat, 64 > &	formats,
		bool	is_read ) const

virtual

Populates a buffer with all file formats supported by this factory and its handlers.

Parameters

[in]	formats	The buffer to populate with supported FileFormat entries.
[in]	is_read	Whether to return read-supported formats (true) or write-supported formats (false).

◆ getUncompressed()

ImageReadPointer ImageFactory::getUncompressed	(	const StringView &	id,
		bool	ensure_valid_transparancy = false )

Retrieves the uncompressed (raw ARGB) pixel data for the cached image.

Parameters

[in]	id	The unique string identifier for the image.
[in]	ensure_valid_transparancy	Whether to verify and set the transparency flag accurately.

Returns: A read-locked pointer to the image cache data with populated decompressed_data.

Referenced by GLESImageData::update().

◆ handleMetaData()

void ImageFactory::handleMetaData ( ImageCacheData & data )

Reads and processes metadata (e.g., EXIF) from the image data using registered handlers.

Parameters

[in] data The image cache data to populate with metadata.

◆ hasImage()

bool ImageFactory::hasImage ( const StringView & id ) const

Checks whether an image with the given identifier exists in the cache.

Parameters

[in] id The unique string identifier for the image.

Returns: True if the image exists in the cache.

Referenced by GLESImageData::update().

◆ hasTransparency()

bool ImageFactory::hasTransparency ( ImageCacheData & data )

Determines whether the image truly contains transparent pixels (not just an alpha channel).

Parameters

[in] data The image cache data to check.

Returns: True if the image has actual transparent pixels.

◆ modifiedTime()

Time ImageFactory::modifiedTime ( const StringView & id ) const

Returns the last modification time of the cached image.

Parameters

[in] id The unique string identifier for the image.

Returns: The modification time, or an invalid Time if the image is not cached.

Referenced by GLESImageData::needsUpdate().

◆ optimizedWriteFileName()

String ImageFactory::optimizedWriteFileName	(	const StringView &	id,
		const Buffer< String > &	optional_extensions = Buffer< String >() )

Determines the optimal file name and extension for writing the image to disk.

Parameters

[in]	id	The unique string identifier for the image.
[in]	optional_extensions	Optional buffer of preferred extensions to consider.

Returns: The optimized file name string including extension.

◆ PNGFormat()

FileFormat ImageFactory::PNGFormat ( )

static

Creates and returns a FileFormat descriptor for the PNG image format.

Returns: A FileFormat representing PNG.

◆ readFromBMP()

void ImageFactory::readFromBMP ( ImageCacheData & data )

Reads image data from a BMP-formatted source into the cache data.

Parameters

[in] data The image cache data to populate.

◆ readFromCompressed()

bool ImageFactory::readFromCompressed ( ImageCacheData & data )

Reads image data from the compressed_data buffer in the cache data using registered handlers.

Parameters

[in] data The image cache data containing compressed data to decompress.

Returns: True if decompression succeeded.

◆ readFromFile()

bool ImageFactory::readFromFile	(	ImageCacheData &	data,
		StringView	format_extension = StringView() )

Reads image data from the file referenced in the cache data.

Parameters

[in]	data	The image cache data containing the file reference.
[in]	format_extension	Optional format hint for reading. If empty, the format is auto-detected.

Returns: True if the file was successfully read.

◆ ReadJPG()

void ImageFactory::ReadJPG	(	const uint01 *	input,
		uint04	input_length,
		uint01 *	buffer,
		bool	has_alpha,
		uint04	dst_line_span,
		const Vector< 2, uint04 > &	offset )

static

Decodes JPEG data from a memory buffer into a raw pixel buffer.

Parameters

[in]	input	Pointer to the compressed JPEG data.
[in]	input_length	Length of the compressed data in bytes.
[in]	buffer	Destination buffer for decompressed pixel data.
[in]	has_alpha	Whether the destination buffer includes an alpha channel.
[in]	dst_line_span	The byte stride of each row in the destination buffer.
[in]	offset	Pixel offset (x, y) into the destination buffer where writing begins.

◆ RemoveFormatHandler()

void ImageFactory::RemoveFormatHandler ( const UUID & handler )

static

Removes a format handler from the global static handler registry.

Parameters

[in] handler The UUID of the handler to remove.

◆ removeFormatHandler()

void ImageFactory::removeFormatHandler ( const UUID & handler )

Removes a previously registered format handler by its UUID.

Parameters

[in] handler The UUID of the handler to remove.

◆ Resize()

void ImageFactory::Resize	(	const Buffer< uint01 > &	input,
		const Vector< 2, uint04 > &	in_size,
		const Vector< 2, uint04 > &	out_size,
		Buffer< uint01 > &	output )

static

Resizes raw pixel data from one resolution to another using bilinear or nearest-neighbor sampling.

Parameters

[in]	input	The source raw pixel data buffer.
[in]	in_size	The source image dimensions (width, height).
[in]	out_size	The target image dimensions (width, height).
[in]	output	The destination buffer for the resized pixel data.

Referenced by GLESImageData::update().

◆ setWriteQuality()

void ImageFactory::setWriteQuality ( fltp08 quality )

Sets the quality level used when writing compressed images (e.g., JPEG quality).

Parameters

[in] quality The write quality from 0.0 (lowest) to 1.0 (highest).

◆ WriteToFile()

void ImageFactory::WriteToFile	(	const uint01 *	data,
		Vector< 2, uint04 >	size,
		uint04	px_size,
		const File &	file,
		fltp08	write_quality = 1.0 )

static

Writes raw pixel data to a file on disk in the format determined by the file extension.

Parameters

[in]	data	Pointer to the raw pixel data.
[in]	size	The image dimensions (width, height) in pixels.
[in]	px_size	The number of bytes per pixel.
[in]	file	The destination file to write.
[in]	write_quality	The compression quality from 0.0 (lowest) to 1.0 (highest).

◆ writeToFile()

void ImageFactory::writeToFile	(	const StringView &	id,
		const File &	file )

Writes the cached image to a file on disk.

Parameters

[in]	id	The unique string identifier for the image.
[in]	file	The destination file to write to.

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

Design/Headers/ImageFactory.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ AddFormatHandler()

◆ addFormatHandler()

◆ addImageCompressed() [1/3]

◆ addImageCompressed() [2/3]

◆ addImageCompressed() [3/3]

◆ addImageFile()

◆ addImageUncompressed() [1/2]

◆ addImageUncompressed() [2/2]

◆ cachedData()

◆ calculateAndGetDecompressed()

◆ canRead()

◆ clearAllImageData()

◆ compressionFormat()

◆ convertColorTheme()

◆ convertDirectory()

◆ copyImage()

◆ DefaultFactory()

◆ determineCompressionFormat()

◆ getCompressed()

◆ getCompressedInFormat() [1/2]

◆ getCompressedInFormat() [2/2]

◆ getEditableData()

◆ getMetaData()

◆ getReadOnlyData()

◆ getSize()

◆ getSupportedFormats()

◆ getUncompressed()

◆ handleMetaData()

◆ hasImage()

◆ hasTransparency()

◆ modifiedTime()

◆ optimizedWriteFileName()

◆ PNGFormat()

◆ readFromBMP()

◆ readFromCompressed()

◆ readFromFile()

◆ ReadJPG()

◆ RemoveFormatHandler()

◆ removeFormatHandler()

◆ Resize()

◆ setWriteQuality()

◆ WriteToFile()

◆ writeToFile()