QgsImageCache Class Reference

A cache for images derived from raster files. More...

#include <qgsimagecache.h>

Inheritance diagram for QgsImageCache:

Signals
void	remoteImageFetched (const QString &url)
	Emitted when the cache has finished retrieving an image file from a remote url.
Signals inherited from QgsAbstractContentCacheBase
void	remoteContentFetched (const QString &url)
	Emitted when the cache has finished retrieving content from a remote url.

Public Member Functions
	QgsImageCache (QObject *parent=nullptr)
	Constructor for QgsImageCache, with the specified parent object.
	~QgsImageCache () override
long	maximumSize () const
	Returns the maximum size of the cache, in bytes.
int	nextFrameDelay (const QString &path, int currentFrame=0, bool blocking=false)
	For image formats that support animation, this function returns the number of milliseconds to wait until displaying the next frame in the animation.
QSize	originalSize (const QString &path, bool blocking=false) const
	Returns the original size (in pixels) of the image at the specified path.
QImage	pathAsImage (const QString &path, const QSize size, const bool keepAspectRatio, const double opacity, bool &fitsInCache, bool blocking=false, double targetDpi=96, int frameNumber=-1, bool *isMissing=nullptr)
	Returns the specified path rendered as an image.
void	prepareAnimation (const QString &path)
	Prepares for optimized retrieval of frames for the animation at the given path.
int	totalFrameCount (const QString &path, bool blocking=false)
	Returns the total frame count of the image at the specified path.
Public Member Functions inherited from QgsAbstractContentCache< QgsImageCacheEntry >
	QgsAbstractContentCache (QObject *parent=nullptr, const QString &typeString=QString(), long maxCacheSize=20000000, int fileModifiedCheckTimeout=30000)
	Constructor for QgsAbstractContentCache, with the specified parent object.
	~QgsAbstractContentCache () override
Public Member Functions inherited from QgsAbstractContentCacheBase
	QgsAbstractContentCacheBase (QObject *parent)
	Constructor for QgsAbstractContentCacheBase, with the specified parent object.

Friends
class	TestQgsImageCache

Additional Inherited Members
Static Public Member Functions inherited from QgsAbstractContentCacheBase
static bool	isBase64Data (const QString &path)
	Returns true if path represents base64 encoded data.
static bool	parseBase64DataUrl (const QString &path, QString *mimeType=nullptr, QString *data=nullptr)
	Parses a path to determine if it represents a base 64 encoded HTML data URL, and if so, extracts the components of the URL.
Protected Slots inherited from QgsAbstractContentCacheBase
Protected Member Functions inherited from QgsAbstractContentCache< QgsImageCacheEntry >
QgsImageCacheEntry *	findExistingEntry (QgsImageCacheEntry *entryTemplate)
	Returns the existing entry from the cache which matches entryTemplate (deleting entryTemplate when done), or if no existing entry is found then entryTemplate is transferred to the cache and returned.
QByteArray	getContent (const QString &path, const QByteArray &missingContent, const QByteArray &fetchingContent, bool blocking=false) const
	Gets the file content corresponding to the given path.
void	onRemoteContentFetched (const QString &url, bool success) override
	Triggered after remote content (i.e.
void	trimToMaximumSize ()
	Removes the least used cache entries until the maximum cache size is under the predefined size limit.
bool	waitForTaskFinished (QgsNetworkContentFetcherTask *task) const
	Blocks the current thread until the task finishes (or user's preset network timeout expires)
Protected Member Functions inherited from QgsAbstractContentCacheBase
virtual bool	checkReply (QNetworkReply *reply, const QString &path) const
	Runs additional checks on a network reply to ensure that the reply content is consistent with that required by the cache.
Protected Attributes inherited from QgsAbstractContentCache< QgsImageCacheEntry >
long	mMaxCacheSize
	Maximum cache size.
QRecursiveMutex	mMutex
long	mTotalSize
	Estimated total size of all cached content.

Detailed Description

A cache for images derived from raster files.

QgsImageCache stores pre-rendered resampled versions of raster image files, allowing efficient reuse without incurring the cost of resampling on every render.

QgsImageCache is not usually directly created, but rather accessed through QgsApplication::imageCache().

Since

QGIS 3.6

Definition at line 131 of file qgsimagecache.h.

Constructor & Destructor Documentation

QgsImageCache()

QgsImageCache::QgsImageCache

(

QObject *

parent = nullptr

)

Constructor for QgsImageCache, with the specified parent object.

Definition at line 93 of file qgsimagecache.cpp.

~QgsImageCache()

QgsImageCache::~QgsImageCache ( )

overridedefault

Member Function Documentation

maximumSize()

long QgsImageCache::maximumSize ( ) const

inline

Returns the maximum size of the cache, in bytes.

Since

QGIS 3.26

Definition at line 150 of file qgsimagecache.h.

nextFrameDelay()

int QgsImageCache::nextFrameDelay	(	const QString &	path,
		int	currentFrame = 0,
		bool	blocking = false
	)

For image formats that support animation, this function returns the number of milliseconds to wait until displaying the next frame in the animation.

If the image format doesn't support animation, 0 is returned.

path may be a local file, remote (HTTP) url, or a base 64 encoded string (with a "base64:" prefix).

If path is a remote file, then -1 may be returned while the image is in the process of being fetched.

The blocking boolean forces to wait for loading before returning the frame delay. The content is loaded in the same thread to ensure provided the original size. WARNING: the blocking parameter must NEVER be true from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external scripts or QGIS server.

If the image could not be read or is not an animated format then -1 is returned.

Since

QGIS 3.26

Definition at line 275 of file qgsimagecache.cpp.

originalSize()

QSize QgsImageCache::originalSize	(	const QString &	path,
		bool	blocking = false
	)		const

Returns the original size (in pixels) of the image at the specified path.

path may be a local file, remote (HTTP) url, or a base 64 encoded string (with a "base64:" prefix).

If path is a remote file, then an invalid size may be returned while the image is in the process of being fetched.

The blocking boolean forces to wait for loading before returning the original size. The content is loaded in the same thread to ensure provided the original size. WARNING: the blocking parameter must NEVER be true from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external scripts or QGIS server.

If the image could not be read then an invalid QSize is returned.

Definition at line 217 of file qgsimagecache.cpp.

pathAsImage()

QImage QgsImageCache::pathAsImage	(	const QString &	path,
		const QSize	size,
		const bool	keepAspectRatio,
		const double	opacity,
		bool &	fitsInCache,
		bool	blocking = false,
		double	targetDpi = 96,
		int	frameNumber = -1,
		bool *	isMissing = nullptr
	)

Returns the specified path rendered as an image.

If possible, a pre-existing cached version of the image will be used. If not, the image is fetched and resampled to the desired size, and then the result cached for subsequent lookups.

Parameters

path	may be a local file, remote (HTTP) url, or a base 64 encoded string (with a "base64:" prefix).
size	dictates the target size of the image. An invalid size indicates the original raster image size (with no resampling). A size in which the width or height is set to zero will have the zeroed value automatically computed when keepAspectRatio is true.
keepAspectRatio	if true then the original raster aspect ratio will be maintained during any resampling operations.
opacity	dictates the opacity of the image (between 0 and 1).
fitsInCache	will be set to true if the resultant raster was of a sufficiently small size to store in the cache
blocking	if true, forces to wait for loading before returning image. The content is loaded in the same thread to ensure provided the image. WARNING: the blocking parameter must NEVER be true from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external scripts or QGIS server.
targetDpi	(since QGIS 3.22) can be used to specify an explicit DPI to render the image at. This is used for some image formats (e.g. PDF) to ensure that content is rendered at the desired DPI. This argument is only used when an invalid size argument is specified. If a valid size is specified then the image will always be rendered at this size, regardless of the targetDpi.
frameNumber	(since QGIS 3.26) specifies a frame number for image formats which support animations. This should be set to -1 if not required.
isMissing	will be set to true if returned image is the "broken" image placeholder

Returns

rendered image

Definition at line 139 of file qgsimagecache.cpp.

prepareAnimation()

void QgsImageCache::prepareAnimation

(

const QString &

path

)

Prepares for optimized retrieval of frames for the animation at the given path.

Since

QGIS 3.26

Definition at line 297 of file qgsimagecache.cpp.

remoteImageFetched

void QgsImageCache::remoteImageFetched ( const QString &  url )

signal

Emitted when the cache has finished retrieving an image file from a remote url.

totalFrameCount()

int QgsImageCache::totalFrameCount	(	const QString &	path,
		bool	blocking = false
	)

Returns the total frame count of the image at the specified path.

path may be a local file, remote (HTTP) url, or a base 64 encoded string (with a "base64:" prefix).

If path is a remote file, then -1 may be returned while the image is in the process of being fetched.

The blocking boolean forces to wait for loading before returning the frame count. The content is loaded in the same thread to ensure provided the original size. WARNING: the blocking parameter must NEVER be true from GUI based applications (like the main QGIS application) or crashes will result. Only for use in external scripts or QGIS server.

If the image could not be read or is not an animated format then -1 is returned

Since

QGIS 3.26

Definition at line 253 of file qgsimagecache.cpp.

Friends And Related Symbol Documentation

TestQgsImageCache

friend class TestQgsImageCache

friend

Definition at line 269 of file qgsimagecache.h.

---

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

• /build/qgis-3.41.0+git20241225+af5edcb665c+99sid/src/core/qgsimagecache.h
• /build/qgis-3.41.0+git20241225+af5edcb665c+99sid/src/core/qgsimagecache.cpp