QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
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 layerRendered (const QString &layerId)
 Emitted when a layer has completed rendering. More...
 
void layerRenderingStarted (const QString &layerId)
 Emitted just before rendering starts for a particular layer. More...
 
void renderingLayersFinished ()
 Emitted when the layers are rendered. More...
 

Public Member Functions

 QgsMapRendererJob (const QgsMapSettings &settings)
 
 ~QgsMapRendererJob () override
 
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...
 
QgsLabelingEngineFeedbacklabelingEngineFeedback ()
 Returns the associated labeling engine feedback object. More...
 
QgsLabelSinklabelSink () const
 Returns the label sink associated to this rendering job. More...
 
QStringList layersRedrawnFromCache () const
 Returns a list of the layer IDs for all layers which were redrawn from cached images. 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 setLabelSink (QgsLabelSink *sink)
 Assigns the label sink which will take over responsibility for handling labels during the rendering job. 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...
 
QgsRenderedItemResultstakeRenderedItemResults ()
 Takes the rendered item results from the map render job and returns them. 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 ELEVATION_MAP_CACHE_PREFIX
 QgsMapRendererCache prefix string for cached elevation map image. More...
 
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 QgsSettingsEntryBoolsettingsLogCanvasRefreshEvent = new QgsSettingsEntryBool( QStringLiteral( "logCanvasRefreshEvent" ), QgsSettingsTree::sTreeMap, false )
 Settings entry log canvas refresh event. More...
 

Protected Member Functions

void cleanupJobs (std::vector< LayerRenderJob > &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 (std::vector< LayerRenderJob > &jobs)
 
void initSecondPassJobs (std::vector< LayerRenderJob > &secondPassJobs, LabelRenderJob &labelJob) const
 Initialize secondPassJobs according to what have been rendered (mask clipping path e.g.) in first pass jobs and labelJob. More...
 
void logRenderingTime (const std::vector< LayerRenderJob > &jobs, const std::vector< LayerRenderJob > &secondPassJobs, const LabelRenderJob &labelJob)
 
std::vector< LayerRenderJob > 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...
 
std::vector< LayerRenderJob > prepareSecondPassJobs (std::vector< LayerRenderJob > &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 std::vector< LayerRenderJob > &jobs, const LabelRenderJob &labelJob, const QgsMapRendererCache *cache=nullptr)
 
static void composeSecondPass (std::vector< LayerRenderJob > &secondPassJobs, LabelRenderJob &labelJob, bool forceVector=false)
 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 QgsElevationMap layerElevationToBeComposed (const QgsMapSettings &settings, const LayerRenderJob &job, const QgsMapRendererCache *cache)
 
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...
 
QStringList mLayersRedrawnFromCache
 
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...
 
std::unique_ptr< QgsRenderedItemResultsmRenderedItemResults
 
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:

Definition at line 298 of file qgsmaprendererjob.h.

Member Typedef Documentation

◆ Errors

Definition at line 391 of file qgsmaprendererjob.h.

Constructor & Destructor Documentation

◆ QgsMapRendererJob()

QgsMapRendererJob::QgsMapRendererJob ( const QgsMapSettings settings)

◆ ~QgsMapRendererJob()

QgsMapRendererJob::~QgsMapRendererJob ( )
override

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 ( std::vector< LayerRenderJob > &  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

◆ cleanupSecondPassJobs()

void QgsMapRendererJob::cleanupSecondPassJobs ( std::vector< LayerRenderJob > &  jobs)
protected
Note
not available in Python bindings

◆ composeImage()

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

◆ composeSecondPass()

static void QgsMapRendererJob::composeSecondPass ( std::vector< LayerRenderJob > &  secondPassJobs,
LabelRenderJob &  labelJob,
bool  forceVector = false 
)
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.

Definition at line 378 of file qgsmaprendererjob.h.

◆ finished

void QgsMapRendererJob::finished ( )
signal

emitted when asynchronous rendering is finished (or canceled).

◆ initSecondPassJobs()

void QgsMapRendererJob::initSecondPassJobs ( std::vector< LayerRenderJob > &  secondPassJobs,
LabelRenderJob &  labelJob 
) const
protected

Initialize secondPassJobs according to what have been rendered (mask clipping path e.g.) in first pass jobs and labelJob.

Since
QGIS 3.26

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

◆ labelingEngineFeedback()

QgsLabelingEngineFeedback* QgsMapRendererJob::labelingEngineFeedback ( )

Returns the associated labeling engine feedback object.

Callers can connect to the signals in this object to receive granular progress reports during the labeling steps.

Note
Not available in Python bindings
Since
QGIS 3.24

◆ labelSink()

QgsLabelSink* QgsMapRendererJob::labelSink ( ) const
inline

Returns the label sink associated to this rendering job.

Note
Not available in Python bindings.
Since
QGIS 3.24

Definition at line 408 of file qgsmaprendererjob.h.

◆ layerElevationToBeComposed()

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

◆ layerImageToBeComposed()

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

◆ layerRendered

void QgsMapRendererJob::layerRendered ( const QString &  layerId)
signal

Emitted when a layer has completed rendering.

Note
the QgsMapRendererParallelJob subclass does not emit this signal.
Since
QGIS 3.24

◆ layerRenderingStarted

void QgsMapRendererJob::layerRenderingStarted ( const QString &  layerId)
signal

Emitted just before rendering starts for a particular layer.

Note
the QgsMapRendererParallelJob subclass does not emit this signal.
Since
QGIS 3.24

◆ layersRedrawnFromCache()

QStringList QgsMapRendererJob::layersRedrawnFromCache ( ) const

Returns a list of the layer IDs for all layers which were redrawn from cached images.

This method should only be called after the render job is completed.

Since
QGIS 3.22

◆ logRenderingTime()

void QgsMapRendererJob::logRenderingTime ( const std::vector< LayerRenderJob > &  jobs,
const std::vector< LayerRenderJob > &  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

◆ perLayerRenderingTime()

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

Returns the render time (in ms) per layer.

Note
Not available in Python bindings.

◆ prepareJobs()

std::vector< LayerRenderJob > 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

◆ prepareSecondPassJobs()

std::vector< LayerRenderJob > QgsMapRendererJob::prepareSecondPassJobs ( std::vector< LayerRenderJob > &  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.

◆ renderingTime()

int QgsMapRendererJob::renderingTime ( ) const
inline

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

See also
perLayerRenderingTime()

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

Definition at line 372 of file qgsmaprendererjob.h.

◆ setLabelSink()

void QgsMapRendererJob::setLabelSink ( QgsLabelSink sink)
inline

Assigns the label sink which will take over responsibility for handling labels during the rendering job.

Note
Ownership is not transferred and the sink must exist for the lifetime of the map rendering job.
Not available in Python bindings.
Since
QGIS 3.24

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

◆ takeRenderedItemResults()

QgsRenderedItemResults* QgsMapRendererJob::takeRenderedItemResults ( )

Takes the rendered item results from the map render job and returns them.

Ownership is transferred to the caller.

Since
QGIS 3.22

◆ 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()

Implemented in QgsMapRendererStagedRenderJob, QgsMapRendererSequentialJob, QgsMapRendererParallelJob, and QgsMapRendererCustomPainterJob.

◆ waitForFinished()

virtual void QgsMapRendererJob::waitForFinished ( )
pure virtual

Member Data Documentation

◆ ELEVATION_MAP_CACHE_PREFIX

const QString QgsMapRendererJob::ELEVATION_MAP_CACHE_PREFIX
static

QgsMapRendererCache prefix string for cached elevation map image.

Note
not available in Python bindings
Since
QGIS 3.30

Definition at line 479 of file qgsmaprendererjob.h.

◆ 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 465 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 472 of file qgsmaprendererjob.h.

◆ mCache

QgsMapRendererCache* QgsMapRendererJob::mCache = nullptr
protected

Definition at line 524 of file qgsmaprendererjob.h.

◆ mErrors

Errors QgsMapRendererJob::mErrors
protected

Definition at line 522 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 536 of file qgsmaprendererjob.h.

◆ mLayersRedrawnFromCache

QStringList QgsMapRendererJob::mLayersRedrawnFromCache
protected

Definition at line 547 of file qgsmaprendererjob.h.

◆ mPerLayerRenderingTime

QHash< QgsWeakMapLayerPointer, int > QgsMapRendererJob::mPerLayerRenderingTime
protected

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

Definition at line 529 of file qgsmaprendererjob.h.

◆ mRecordRenderingTime

bool QgsMapRendererJob::mRecordRenderingTime = true
protected

true if layer rendering time should be recorded.

Definition at line 541 of file qgsmaprendererjob.h.

◆ mRenderedItemResults

std::unique_ptr< QgsRenderedItemResults > QgsMapRendererJob::mRenderedItemResults
protected

Definition at line 544 of file qgsmaprendererjob.h.

◆ mRenderingStart

QElapsedTimer QgsMapRendererJob::mRenderingStart
protected

Definition at line 521 of file qgsmaprendererjob.h.

◆ mRenderingTime

int QgsMapRendererJob::mRenderingTime = 0
protected

Definition at line 526 of file qgsmaprendererjob.h.

◆ mSettings

QgsMapSettings QgsMapRendererJob::mSettings
protected

Definition at line 520 of file qgsmaprendererjob.h.

◆ settingsLogCanvasRefreshEvent

const QgsSettingsEntryBool * QgsMapRendererJob::settingsLogCanvasRefreshEvent = new QgsSettingsEntryBool( QStringLiteral( "logCanvasRefreshEvent" ), QgsSettingsTree::sTreeMap, false )
static

Settings entry log canvas refresh event.

Definition at line 483 of file qgsmaprendererjob.h.


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