QgsMapRendererJob class

Abstract base class for map rendering implementations.

Contents

The API is designed in a way that rendering is done asynchronously, therefore the caller is not blocked while the rendering is in progress. Non-blocking operation is quite important because the rendering can take considerable amount of time.

Common use case: 0. prepare QgsMapSettings with rendering configuration (extent, layer, map size, ...)

  1. create QgsMapRendererJob subclass with QgsMapSettings instance
  2. connect to job's finished() signal
  3. call start(). Map rendering will start in background, the function immediately returns
  4. at some point, slot connected to finished() signal is called, map rendering is done

It is possible to cancel the rendering job while it is active by calling cancel() function.

The following subclasses are available:

Derived classes

class QgsMapRendererCustomPainterJob
Job implementation that renders everything sequentially using a custom painter.
class QgsMapRendererQImageJob
Intermediate base class adding functionality that allows client to query the rendered image.

Public static variables

static const QString LABEL_CACHE_ID
QgsMapRendererCache ID string for cached label image.

Public functions

void cancel() pure virtual
Stop the rendering job - does not return until the job has terminated.
void cancelWithoutBlocking() pure virtual
Triggers cancelation of the rendering job without blocking.
auto errors() const -> Errors
List of errors that happened during the rendering job - available when the rendering has been finished.
auto featureFilterProvider() const -> const QgsFeatureFilterProvider*
Returns the feature filter provider used by the QgsRenderContext of each LayerRenderJob.
auto isActive() const -> bool pure virtual
Tell whether the rendering job is currently running in background.
auto mapSettings() const -> const QgsMapSettings&
Returns map settings with which this job was started.
auto perLayerRenderingTime() const -> QHash<QgsMapLayer*, int>
Returns the render time (in ms) per layer.
auto renderingTime() const -> int
Returns the total time it took to finish the job (in milliseconds).
void setCache(QgsMapRendererCache* cache)
Assign a cache to be used for reading and storing rendered images of individual layers.
void setFeatureFilterProvider(const QgsFeatureFilterProvider* f)
Set the feature filter provider used by the QgsRenderContext of each LayerRenderJob.
void start() pure virtual
Start the rendering job and immediately return.
auto takeLabelingResults() -> QgsLabelingResults* pure virtual
Gets pointer to internal labeling engine (in order to get access to the results).
auto usedCachedLabels() const -> bool pure virtual
Returns true if the render job was able to use a cached labeling solution.
void waitForFinished() pure virtual
Block until the job has finished.

Signals

void finished()
emitted when asynchronous rendering is finished (or canceled).
void renderingLayersFinished()
Emitted when the layers are rendered.

Protected static functions

static auto composeImage(const QgsMapSettings& settings, const LayerRenderJobs& jobs, const LabelRenderJob& labelJob) -> QImage
static auto drawLabeling(const QgsMapSettings& settings, QgsRenderContext& renderContext, QgsLabelingEngine* labelingEngine2, QPainter* painter) -> Q_DECL_DEPRECATED void deprecated
static void drawLabeling(QgsRenderContext& renderContext, QgsLabelingEngine* labelingEngine2, QPainter* painter)

Protected functions

void cleanupJobs(LayerRenderJobs& jobs)
void cleanupLabelJob(LabelRenderJob& job)
Handles clean up tasks for a label job, including deletion of images and storing cached label results.
void logRenderingTime(const LayerRenderJobs& jobs, const LabelRenderJob& labelJob)
auto prepareJobs(QPainter* painter, QgsLabelingEngine* labelingEngine2) -> LayerRenderJobs
auto prepareLabelCache() const -> bool
Prepares the cache for storing the result of labeling.
auto prepareLabelingJob(QPainter* painter, QgsLabelingEngine* labelingEngine2, bool canUseLabelCache = true) -> LabelRenderJob
Prepares a labeling job.

Protected variables

QHash<QgsWeakMapLayerPointer, int> mPerLayerRenderingTime
Render time (in ms) per layer, by layer ID.

Function documentation

void QgsMapRendererJob::cancel() pure virtual

Stop the rendering job - does not return until the job has terminated.

Does nothing if the rendering is not active.

void QgsMapRendererJob::cancelWithoutBlocking() pure virtual

Triggers cancelation of the rendering job without blocking.

The render job will continue to operate until it is able to cancel, at which stage the finished() signal will be emitted. Does nothing if the rendering is not active.

const QgsFeatureFilterProvider* QgsMapRendererJob::featureFilterProvider() const

Returns the feature filter provider used by the QgsRenderContext of each LayerRenderJob.

const QgsMapSettings& QgsMapRendererJob::mapSettings() const

Returns map settings with which this job was started.

Returns A QgsMapSettings instance with render settings

QHash<QgsMapLayer*, int> QgsMapRendererJob::perLayerRenderingTime() const

Returns the render time (in ms) per layer.

int QgsMapRendererJob::renderingTime() const

Returns the total time it took to finish the job (in milliseconds).

void QgsMapRendererJob::setCache(QgsMapRendererCache* cache)

Assign a cache to be used for reading and storing rendered images of individual layers.

Does not take ownership of the object.

void QgsMapRendererJob::setFeatureFilterProvider(const QgsFeatureFilterProvider* f)

Set the feature filter provider used by the QgsRenderContext of each LayerRenderJob.

Ownership is not transferred and the provider must not be deleted before the render job.

void QgsMapRendererJob::start() pure virtual

Start the rendering job and immediately return.

Does nothing if the rendering is already in progress.

QgsLabelingResults* QgsMapRendererJob::takeLabelingResults() pure virtual

Gets pointer to internal labeling engine (in order to get access to the results).

This should not be used if cached labeling was redrawn - see usedCachedLabels().

bool QgsMapRendererJob::usedCachedLabels() const pure virtual

Returns true if the render job was able to use a cached labeling solution.

If so, any previously stored labeling results (see takeLabelingResults()) should be retained.

void QgsMapRendererJob::renderingLayersFinished() signal

Emitted when the layers are rendered.

Rendering labels is not yet done. If the fully rendered layer including labels is required use finished() instead.

static QImage QgsMapRendererJob::composeImage(const QgsMapSettings& settings, const LayerRenderJobs& jobs, const LabelRenderJob& labelJob) protected

static Q_DECL_DEPRECATED void QgsMapRendererJob::drawLabeling(const QgsMapSettings& settings, QgsRenderContext& renderContext, QgsLabelingEngine* labelingEngine2, QPainter* painter) protected

static void QgsMapRendererJob::drawLabeling(QgsRenderContext& renderContext, QgsLabelingEngine* labelingEngine2, QPainter* painter) protected

void QgsMapRendererJob::cleanupJobs(LayerRenderJobs& jobs) protected

void QgsMapRendererJob::cleanupLabelJob(LabelRenderJob& job) protected

Handles clean up tasks for a label job, including deletion of images and storing cached label results.

void QgsMapRendererJob::logRenderingTime(const LayerRenderJobs& jobs, const LabelRenderJob& labelJob) protected

LayerRenderJobs QgsMapRendererJob::prepareJobs(QPainter* painter, QgsLabelingEngine* labelingEngine2) protected

bool QgsMapRendererJob::prepareLabelCache() const protected

Prepares the cache for storing the result of labeling.

Returns false if the render cannot use cached labels and should not cache the result.

LabelRenderJob QgsMapRendererJob::prepareLabelingJob(QPainter* painter, QgsLabelingEngine* labelingEngine2, bool canUseLabelCache = true) protected

Prepares a labeling job.

Variable documentation

static const QString QgsMapRendererJob::LABEL_CACHE_ID

QgsMapRendererCache ID string for cached label image.