QGIS API Documentation  3.20.0-Odense (decaadbb31)
Classes | Public Types | Signals | Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
QgsMapRendererJob Class Referenceabstract

Abstract base class for map rendering implementations. More...

#include <qgsmaprendererjob.h>

Inheritance diagram for QgsMapRendererJob:
Inheritance graph
[legend]

Classes

struct  Error
 

Public Types

typedef QList< QgsMapRendererJob::ErrorErrors
 

Signals

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

Public Member Functions

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

Static Public Attributes

static const QString LABEL_CACHE_ID
 QgsMapRendererCache ID string for cached label image. More...
 
static const QString LABEL_PREVIEW_CACHE_ID
 QgsMapRendererCache ID string for cached label image during preview compositions only. More...
 
static const QgsSettingsEntryBool settingsLogCanvasRefreshEvent = QgsSettingsEntryBool( QStringLiteral( "Map/logCanvasRefreshEvent" ), QgsSettings::NoSection, false )
 Settings entry log canvas refresh event. More...
 

Protected Member 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. More...
 
void cleanupSecondPassJobs (LayerRenderJobs &jobs)
 
void logRenderingTime (const LayerRenderJobs &jobs, const LayerRenderJobs &secondPassJobs, const LabelRenderJob &labelJob)
 
LayerRenderJobs prepareJobs (QPainter *painter, QgsLabelingEngine *labelingEngine2, bool deferredPainterSet=false)
 Creates a list of layer rendering jobs and prepares them for later render. More...
 
bool prepareLabelCache () const
 Prepares the cache for storing the result of labeling. More...
 
LabelRenderJob prepareLabelingJob (QPainter *painter, QgsLabelingEngine *labelingEngine2, bool canUseLabelCache=true)
 Prepares a labeling job. More...
 
LayerRenderJobs prepareSecondPassJobs (LayerRenderJobs &firstPassJobs, LabelRenderJob &labelJob)
 Prepares jobs for a second pass, if selective masks exist (from labels or symbol layers). More...
 

Static Protected Member Functions

static QImage composeImage (const QgsMapSettings &settings, const LayerRenderJobs &jobs, const LabelRenderJob &labelJob, const QgsMapRendererCache *cache=nullptr)
 
static void composeSecondPass (LayerRenderJobs &secondPassJobs, LabelRenderJob &labelJob)
 Compose second pass images into first pass images. More...
 
static Q_DECL_DEPRECATED void drawLabeling (const QgsMapSettings &settings, QgsRenderContext &renderContext, QgsLabelingEngine *labelingEngine2, QPainter *painter)
 
static void drawLabeling (QgsRenderContext &renderContext, QgsLabelingEngine *labelingEngine2, QPainter *painter)
 
static QImage layerImageToBeComposed (const QgsMapSettings &settings, const LayerRenderJob &job, const QgsMapRendererCache *cache)
 

Protected Attributes

QgsMapRendererCachemCache = nullptr
 
Errors mErrors
 
QHash< QString, int > mLayerRenderingTimeHints
 Approximate expected layer rendering time per layer, by layer ID. More...
 
QHash< QgsWeakMapLayerPointer, int > mPerLayerRenderingTime
 Render time (in ms) per layer, by layer ID. More...
 
bool mRecordRenderingTime = true
 true if layer rendering time should be recorded. More...
 
QElapsedTimer mRenderingStart
 
int mRenderingTime = 0
 
QgsMapSettings mSettings
 

Detailed Description

Abstract base class for map rendering implementations.

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:

  1. Prepare QgsMapSettings with rendering configuration (extent, layer, map size, ...)
  2. Create QgsMapRendererJob subclass with QgsMapSettings instance
  3. Connect to job's finished() signal
  4. Call start(). Map rendering will start in background, the function immediately returns
  5. 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:

Since
QGIS 2.4

Definition at line 213 of file qgsmaprendererjob.h.

Member Typedef Documentation

◆ Errors

Definition at line 288 of file qgsmaprendererjob.h.

Constructor & Destructor Documentation

◆ QgsMapRendererJob()

QgsMapRendererJob::QgsMapRendererJob ( const QgsMapSettings settings)

Member Function Documentation

◆ cancel()

virtual 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.

Implemented in QgsMapRendererStagedRenderJob, QgsMapRendererSequentialJob, QgsMapRendererParallelJob, and QgsMapRendererCustomPainterJob.

◆ cancelWithoutBlocking()

virtual void QgsMapRendererJob::cancelWithoutBlocking ( )
pure virtual

Triggers cancellation 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.

Implemented in QgsMapRendererStagedRenderJob, QgsMapRendererSequentialJob, QgsMapRendererParallelJob, and QgsMapRendererCustomPainterJob.

◆ cleanupJobs()

void QgsMapRendererJob::cleanupJobs ( LayerRenderJobs &  jobs)
protected
Note
not available in Python bindings

◆ cleanupLabelJob()

void QgsMapRendererJob::cleanupLabelJob ( LabelRenderJob &  job)
protected

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

Note
not available in Python bindings
Since
QGIS 3.0

◆ cleanupSecondPassJobs()

void QgsMapRendererJob::cleanupSecondPassJobs ( LayerRenderJobs &  jobs)
protected
Note
not available in Python bindings

◆ composeImage()

static QImage QgsMapRendererJob::composeImage ( const QgsMapSettings settings,
const LayerRenderJobs &  jobs,
const LabelRenderJob &  labelJob,
const QgsMapRendererCache cache = nullptr 
)
staticprotected
Note
not available in Python bindings

◆ composeSecondPass()

static void QgsMapRendererJob::composeSecondPass ( LayerRenderJobs &  secondPassJobs,
LabelRenderJob &  labelJob 
)
staticprotected

Compose second pass images into first pass images.

First pass jobs pointed to by the second pass jobs must still exist.

Note
not available in Python bindings
Since
QGIS 3.12

◆ drawLabeling() [1/2]

static Q_DECL_DEPRECATED void QgsMapRendererJob::drawLabeling ( const QgsMapSettings settings,
QgsRenderContext renderContext,
QgsLabelingEngine labelingEngine2,
QPainter *  painter 
)
staticprotected
Note
not available in Python bindings
Deprecated:
Will be removed in QGIS 4.0

◆ drawLabeling() [2/2]

static void QgsMapRendererJob::drawLabeling ( QgsRenderContext renderContext,
QgsLabelingEngine labelingEngine2,
QPainter *  painter 
)
staticprotected
Note
not available in Python bindings

◆ errors()

Errors QgsMapRendererJob::errors ( ) const

List of errors that happened during the rendering job - available when the rendering has been finished.

◆ featureFilterProvider()

const QgsFeatureFilterProvider* QgsMapRendererJob::featureFilterProvider ( ) const
inline

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

Since
QGIS 3.0

Definition at line 275 of file qgsmaprendererjob.h.

◆ finished

void QgsMapRendererJob::finished ( )
signal

emitted when asynchronous rendering is finished (or canceled).

◆ isActive()

virtual bool QgsMapRendererJob::isActive ( ) const
pure virtual

Tell whether the rendering job is currently running in background.

Implemented in QgsMapRendererStagedRenderJob, QgsMapRendererSequentialJob, QgsMapRendererParallelJob, and QgsMapRendererCustomPainterJob.

◆ layerImageToBeComposed()

static QImage QgsMapRendererJob::layerImageToBeComposed ( const QgsMapSettings settings,
const LayerRenderJob &  job,
const QgsMapRendererCache cache 
)
staticprotected
Note
not available in Python bindings

◆ logRenderingTime()

void QgsMapRendererJob::logRenderingTime ( const LayerRenderJobs &  jobs,
const LayerRenderJobs &  secondPassJobs,
const LabelRenderJob &  labelJob 
)
protected
Note
not available in Python bindings

◆ mapSettings()

const QgsMapSettings& QgsMapRendererJob::mapSettings ( ) const

Returns map settings with which this job was started.

Returns
A QgsMapSettings instance with render settings
Since
QGIS 2.8

◆ perLayerRenderingTime()

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

Returns the render time (in ms) per layer.

Note
Not available in Python bindings.
Since
QGIS 3.0

◆ prepareJobs()

LayerRenderJobs QgsMapRendererJob::prepareJobs ( QPainter *  painter,
QgsLabelingEngine labelingEngine2,
bool  deferredPainterSet = false 
)
protected

Creates a list of layer rendering jobs and prepares them for later render.

The painter argument specifies the destination painter. If not set, the jobs will be rendered to temporary images. Alternatively, if the deferredPainterSet flag is true, then a painter value of nullptr skips this default temporary image creation. In this case, it is the caller's responsibility to correctly set a painter for all rendered jobs prior to rendering them.

Note
not available in Python bindings

◆ prepareLabelCache()

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.

Note
not available in Python bindings

◆ prepareLabelingJob()

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

Prepares a labeling job.

Note
not available in Python bindings
Since
QGIS 3.0

◆ prepareSecondPassJobs()

LayerRenderJobs QgsMapRendererJob::prepareSecondPassJobs ( LayerRenderJobs &  firstPassJobs,
LabelRenderJob &  labelJob 
)
protected

Prepares jobs for a second pass, if selective masks exist (from labels or symbol layers).

Must be called after prepareJobs and prepareLabelingJob. It returns a list of new jobs for a second pass and also modifies labelJob and firstPassJobs if needed (image and mask image allocation if needed)

Note
not available in Python bindings
Since
QGIS 3.12

◆ renderingLayersFinished

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.

Since
QGIS 3.0

◆ renderingTime()

int QgsMapRendererJob::renderingTime ( ) const
inline

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

See also
perLayerRenderingTime()

Definition at line 304 of file qgsmaprendererjob.h.

◆ setCache()

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.

◆ setFeatureFilterProvider()

void QgsMapRendererJob::setFeatureFilterProvider ( const QgsFeatureFilterProvider f)
inline

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.

Since
QGIS 3.0

Definition at line 268 of file qgsmaprendererjob.h.

◆ setLayerRenderingTimeHints()

void QgsMapRendererJob::setLayerRenderingTimeHints ( const QHash< QString, int > &  hints)

Sets approximate render times (in ms) for map layers.

This can be used to specifies hints at the expected render times for layers, so that the individual layer renderers can apply heuristics and determine appropriate update intervals during the render operation.

The keys for hints must be set to the corresponding layer IDs.

Note
Not available in Python bindings.
Since
QGIS 3.18

◆ start()

void QgsMapRendererJob::start ( )

Start the rendering job and immediately return.

Does nothing if the rendering is already in progress.

◆ takeLabelingResults()

virtual 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().

See also
usedCachedLabels()

Implemented in QgsMapRendererStagedRenderJob, QgsMapRendererSequentialJob, QgsMapRendererParallelJob, and QgsMapRendererCustomPainterJob.

◆ usedCachedLabels()

virtual 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.

See also
takeLabelingResults()
Since
QGIS 3.0

Implemented in QgsMapRendererStagedRenderJob, QgsMapRendererSequentialJob, QgsMapRendererParallelJob, and QgsMapRendererCustomPainterJob.

◆ waitForFinished()

virtual void QgsMapRendererJob::waitForFinished ( )
pure virtual

Member Data Documentation

◆ LABEL_CACHE_ID

const QString QgsMapRendererJob::LABEL_CACHE_ID
static

QgsMapRendererCache ID string for cached label image.

Note
not available in Python bindings

Definition at line 338 of file qgsmaprendererjob.h.

◆ LABEL_PREVIEW_CACHE_ID

const QString QgsMapRendererJob::LABEL_PREVIEW_CACHE_ID
static

QgsMapRendererCache ID string for cached label image during preview compositions only.

Note
not available in Python bindings
Since
QGIS 3.18

Definition at line 345 of file qgsmaprendererjob.h.

◆ mCache

QgsMapRendererCache* QgsMapRendererJob::mCache = nullptr
protected

Definition at line 372 of file qgsmaprendererjob.h.

◆ mErrors

Errors QgsMapRendererJob::mErrors
protected

Definition at line 370 of file qgsmaprendererjob.h.

◆ mLayerRenderingTimeHints

QHash< QString, int > QgsMapRendererJob::mLayerRenderingTimeHints
protected

Approximate expected layer rendering time per layer, by layer ID.

Since
QGIS 3.18

Definition at line 384 of file qgsmaprendererjob.h.

◆ mPerLayerRenderingTime

QHash< QgsWeakMapLayerPointer, int > QgsMapRendererJob::mPerLayerRenderingTime
protected

Render time (in ms) per layer, by layer ID.

Definition at line 377 of file qgsmaprendererjob.h.

◆ mRecordRenderingTime

bool QgsMapRendererJob::mRecordRenderingTime = true
protected

true if layer rendering time should be recorded.

Definition at line 389 of file qgsmaprendererjob.h.

◆ mRenderingStart

QElapsedTimer QgsMapRendererJob::mRenderingStart
protected

Definition at line 369 of file qgsmaprendererjob.h.

◆ mRenderingTime

int QgsMapRendererJob::mRenderingTime = 0
protected

Definition at line 374 of file qgsmaprendererjob.h.

◆ mSettings

QgsMapSettings QgsMapRendererJob::mSettings
protected

Definition at line 368 of file qgsmaprendererjob.h.

◆ settingsLogCanvasRefreshEvent

const QgsSettingsEntryBool QgsMapRendererJob::settingsLogCanvasRefreshEvent = QgsSettingsEntryBool( QStringLiteral( "Map/logCanvasRefreshEvent" ), QgsSettings::NoSection, false )
inlinestatic

Settings entry log canvas refresh event.

Definition at line 349 of file qgsmaprendererjob.h.


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