Class: QgsMapRendererCache¶

Responsible for keeping a cache of rendered images resulting from a map rendering job.

Once a job has a rendered image stored in the cache (using setCacheImage(…)), the cache listens to repaintRequested() signals from dependent layers. If triggered, the cache removes the rendered image (and disconnects from the layers).

When user pans/zooms the canvas, the cache is also used in rendering period for particular layers between the first render update and the moment the layer actually has partially rendered something in the resulting image.

The class is thread-safe (multiple classes can access the same instance safely).

Class Hierarchy¶

Base classes¶

QObject

Methods

`cacheImage`	Returns the cached image for the specified cacheKey.
`clear`	Invalidates the cache contents, clearing all cached images.
`clearCacheImage`	Removes an image from the cache with matching cacheKey.
`dependentLayers`	Returns a list of map layers on which an image in the cache depends.
`hasAnyCacheImage`	Returns `True` if the cache contains an image with the specified cacheKey with any cache's parameters (extent and scale)
`hasCacheImage`	Returns `True` if the cache contains an image with the specified cacheKey that has the same extent and scale as the cache's global extent and scale
`init`	Initialize cache: sets extent and scale parameters and clears the cache if any parameters have changed since last initialization.
`invalidateCacheForLayer`	Invalidates cached images which relate to the specified map layer.
`setCacheImage`	Set the cached image for a particular cacheKey, using the current cache parameters.
`setCacheImageWithParameters`	Set the cached image for a particular cacheKey, using a specific extent and mapToPixel (which may differ from the current cache parameters).
`transformedCacheImage`	Returns the cached image for the specified cacheKey transformed to the particular extent and scale.
`updateParameters`	Sets extent and scale parameters

class qgis.core.QgsMapRendererCache[source]¶

Bases: QObject

cacheImage(self, cacheKey: str | None) → QImage[source]¶

Returns the cached image for the specified cacheKey. The cacheKey usually matches the QgsMapLayer.id() which the image is a render of. Returns a null image if it is not cached.

See also

setCacheImage()

See also

hasCacheImage()

Parameters:: cacheKey (Optional[str])
Return type:: QImage

clear(self)[source]¶: Invalidates the cache contents, clearing all cached images.

See also

clearCacheImage()

clearCacheImage(self, cacheKey: str | None)[source]¶

Removes an image from the cache with matching cacheKey.

See also

clear()

Parameters:: cacheKey (Optional[str])

dependentLayers(self, cacheKey: str | None) → List[QgsMapLayer]¶

Returns a list of map layers on which an image in the cache depends.

Parameters:: cacheKey (Optional[str])
Return type:: List[QgsMapLayer]

hasAnyCacheImage(self, cacheKey: str | None, minimumScaleThreshold: float = 0, maximumScaleThreshold: float = 0) → bool[source]¶

Returns True if the cache contains an image with the specified cacheKey with any cache’s parameters (extent and scale)

The optional minimumScaleThreshold and maximumScaleThreshold arguments can be used to specify a range of acceptable cached scales vs current cache scale parameter. E.g. if the minimumScaleThreshold is 0.5 and maximumScaleThreshold is 2.0, then only cached images with a scale between 0.5 * current cache scale and 2.0 * current cache scale will be considered.

See also

transformedCacheImage()

Added in version 3.18.

Parameters:

cacheKey (Optional[str])
minimumScaleThreshold (float = 0)
maximumScaleThreshold (float = 0)

Return type:

bool

hasCacheImage(self, cacheKey: str | None) → bool[source]¶

Returns True if the cache contains an image with the specified cacheKey that has the same extent and scale as the cache’s global extent and scale

See also

cacheImage()

Parameters:: cacheKey (Optional[str])
Return type:: bool

init(self, extent: QgsRectangle, scale: float) → bool[source]¶

Initialize cache: sets extent and scale parameters and clears the cache if any parameters have changed since last initialization.

Return type:: bool
Returns:: flag whether the parameters are the same as last time

Deprecated since version 3.18: Will be removed in QGIS 4.0. Use the updateParameters() and clear().

Parameters:

extent (QgsRectangle)
scale (float)

invalidateCacheForLayer(self, layer: QgsMapLayer | None)[source]¶

Invalidates cached images which relate to the specified map layer.

Added in version 3.14.

Parameters:: layer (Optional[QgsMapLayer])

setCacheImage(self, cacheKey: str | None, image: QImage, dependentLayers: Iterable[QgsMapLayer] = [])[source]¶

Set the cached image for a particular cacheKey, using the current cache parameters.

The cacheKey usually matches the QgsMapLayer.id() which the image is a render of.

A list of dependentLayers should be passed containing all layer on which this cache image is dependent. If any of these layers triggers a repaint then the cache image will be cleared.

See also

setCacheImageWithParameters()

See also

cacheImage()

Parameters:

cacheKey (Optional[str])
image (QImage)
dependentLayers (Iterable[QgsMapLayer] = [])

setCacheImageWithParameters(self, cacheKey: str | None, image: QImage, extent: QgsRectangle, mapToPixel: QgsMapToPixel, dependentLayers: Iterable[QgsMapLayer] = [])[source]¶

Set the cached image for a particular cacheKey, using a specific extent and mapToPixel (which may differ from the current cache parameters).

The cacheKey usually matches the QgsMapLayer.id() which the image is a render of.

A list of dependentLayers should be passed containing all layer on which this cache image is dependent. If any of these layers triggers a repaint then the cache image will be cleared.

See also

cacheImage()

Added in version 3.18.

Parameters:

cacheKey (Optional[str])
image (QImage)
extent (QgsRectangle)
mapToPixel (QgsMapToPixel)
dependentLayers (Iterable[QgsMapLayer] = [])

transformedCacheImage(self, cacheKey: str | None, mtp: QgsMapToPixel) → QImage[source]¶

Returns the cached image for the specified cacheKey transformed to the particular extent and scale.

The cacheKey usually matches the QgsMapLayer.id() which the image is a render of. Returns a null image if it is not cached.

See also

hasAnyCacheImage()

Added in version 3.18.

Parameters:

cacheKey (Optional[str])
mtp (QgsMapToPixel)

Return type:

QImage

updateParameters(self, extent: QgsRectangle, mtp: QgsMapToPixel) → bool[source]¶

Sets extent and scale parameters

Return type:: bool
Returns:: flag whether the parameters are the same as last time

Added in version 3.18.

Parameters:

extent (QgsRectangle)
mtp (QgsMapToPixel)