QGIS API Documentation  3.22.4-Białowieża (ce8e65e95e)
Signals | Public Member Functions | Friends | List of all members
QgsImageCache Class Reference

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

#include <qgsimagecache.h>

Inheritance diagram for QgsImageCache:
Inheritance graph
[legend]

Signals

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

Public Member Functions

 QgsImageCache (QObject *parent=nullptr)
 Constructor for QgsImageCache, with the specified parent object. More...
 
QSize originalSize (const QString &path, bool blocking=false) const
 Returns the original size (in pixels) of the image at the specified path. More...
 
QImage pathAsImage (const QString &path, const QSize size, const bool keepAspectRatio, const double opacity, bool &fitsInCache, bool blocking=false, double targetDpi=96, bool *isMissing=nullptr)
 Returns the specified path rendered as an image. More...
 
- 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. More...
 
 ~QgsAbstractContentCache () override
 
- Public Member Functions inherited from QgsAbstractContentCacheBase
 QgsAbstractContentCacheBase (QObject *parent)
 Constructor for QgsAbstractContentCacheBase, with the specified parent object. More...
 

Friends

class TestQgsImageCache
 

Additional Inherited Members

- 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. More...
 
QByteArray getContent (const QString &path, const QByteArray &missingContent, const QByteArray &fetchingContent, bool blocking=false) const
 Gets the file content corresponding to the given path. More...
 
void onRemoteContentFetched (const QString &url, bool success) override
 Triggered after remote content (i.e. More...
 
void trimToMaximumSize ()
 Removes the least used cache entries until the maximum cache size is under the predefined size limit. More...
 
bool waitForTaskFinished (QgsNetworkContentFetcherTask *task) const
 Blocks the current thread until the task finishes (or user's preset network timeout expires) More...
 
- 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. More...
 
- Protected Attributes inherited from QgsAbstractContentCache< QgsImageCacheEntry >
long mMaxCacheSize
 Maximum cache size. More...
 
QRecursiveMutex mMutex
 
long mTotalSize
 Estimated total size of all cached content. More...
 

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 105 of file qgsimagecache.h.

Constructor & Destructor Documentation

◆ QgsImageCache()

QgsImageCache::QgsImageCache ( QObject *  parent = nullptr)

Constructor for QgsImageCache, with the specified parent object.

Definition at line 84 of file qgsimagecache.cpp.

Member Function Documentation

◆ 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 166 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,
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.

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

The size parameter 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.

If keepAspectRatio is true, then the original raster aspect ratio will be maintained during any resampling operations.

An opacity parameter dictates the opacity of the image.

If the resultant raster was of a sufficiently small size to store in the cache, then fitsInCache will be set to true.

The blocking boolean 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.

Since QGIS 3.22 the targetDpi argument 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.

Definition at line 113 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.

Friends And Related Function Documentation

◆ TestQgsImageCache

friend class TestQgsImageCache
friend

Definition at line 185 of file qgsimagecache.h.


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