QGIS API Documentation  2.99.0-Master (40f86b2)
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< 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 cancelation 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
 
virtual bool isActive () const =0
 Tell whether the rendering job is currently running in background. More...
 
const QgsMapSettingsmapSettings () const
 Return map settings with which this job was started. More...
 
int renderingTime () const
 Find out how long 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)
 
void setRequestedGeometryCacheForLayers (const QStringList &layerIds)
 Set which vector layers should be cached while rendering. More...
 
virtual void start ()=0
 Start the rendering job and immediately return. More...
 
virtual QgsLabelingResultstakeLabelingResults ()=0
 Get 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...
 

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 logRenderingTime (const LayerRenderJobs &jobs, const LabelRenderJob &labelJob)
 
LayerRenderJobs prepareJobs (QPainter *painter, QgsLabelingEngine *labelingEngine2)
 
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...
 

Static Protected Member Functions

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

Protected Attributes

QgsMapRendererCachemCache = nullptr
 
Errors mErrors
 
QTime 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: 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:

Note
added in 2.4

Definition at line 109 of file qgsmaprendererjob.h.

Member Typedef Documentation

◆ Errors

Definition at line 176 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 QgsMapRendererCustomPainterJob, QgsMapRendererSequentialJob, and QgsMapRendererParallelJob.

◆ cancelWithoutBlocking()

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

Implemented in QgsMapRendererCustomPainterJob, QgsMapRendererSequentialJob, and QgsMapRendererParallelJob.

◆ 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
added in QGIS 3.0
not available in python bindings

◆ composeImage()

static QImage QgsMapRendererJob::composeImage ( const QgsMapSettings settings,
const LayerRenderJobs &  jobs,
const LabelRenderJob &  labelJob 
)
staticprotected
Note
not available in python bindings

◆ drawLabeling()

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

Definition at line 316 of file qgsmaprenderercustompainterjob.cpp.

◆ 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
Note
Added in QGIS 3.0 Returns the feature filter provider used by the QgsRenderContext of each LayerRenderJob.

Definition at line 163 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 QgsMapRendererCustomPainterJob, QgsMapRendererSequentialJob, and QgsMapRendererParallelJob.

◆ logRenderingTime()

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

◆ mapSettings()

const QgsMapSettings& QgsMapRendererJob::mapSettings ( ) const

Return map settings with which this job was started.

Returns
A QgsMapSettings instance with render settings
Note
added in 2.8

◆ prepareJobs()

LayerRenderJobs QgsMapRendererJob::prepareJobs ( QPainter *  painter,
QgsLabelingEngine labelingEngine2 
)
protected
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
added in QGIS 3.0

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

Note
Added in QGIS 3.0

◆ renderingTime()

int QgsMapRendererJob::renderingTime ( ) const
inline

Find out how long it took to finish the job (in milliseconds)

Definition at line 191 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
Note
Added in QGIS 3.0 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 158 of file qgsmaprendererjob.h.

◆ setRequestedGeometryCacheForLayers()

void QgsMapRendererJob::setRequestedGeometryCacheForLayers ( const QStringList &  layerIds)
inline

Set which vector layers should be cached while rendering.

Note
The way how geometries are cached is really suboptimal - this method may be removed in future releases

Definition at line 188 of file qgsmaprendererjob.h.

◆ start()

virtual void QgsMapRendererJob::start ( )
pure virtual

Start the rendering job and immediately return.

Does nothing if the rendering is already in progress.

Implemented in QgsMapRendererCustomPainterJob, QgsMapRendererSequentialJob, and QgsMapRendererParallelJob.

◆ takeLabelingResults()

virtual QgsLabelingResults* QgsMapRendererJob::takeLabelingResults ( )
pure virtual

Get 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 QgsMapRendererCustomPainterJob, QgsMapRendererSequentialJob, and QgsMapRendererParallelJob.

◆ 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()
Note
added in QGIS 3.0

Implemented in QgsMapRendererCustomPainterJob, QgsMapRendererSequentialJob, and QgsMapRendererParallelJob.

◆ waitForFinished()

virtual void QgsMapRendererJob::waitForFinished ( )
pure virtual

Block until the job has finished.

Implemented in QgsMapRendererCustomPainterJob, QgsMapRendererSequentialJob, and QgsMapRendererParallelJob.

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 204 of file qgsmaprendererjob.h.

◆ mCache

QgsMapRendererCache* QgsMapRendererJob::mCache = nullptr
protected

Definition at line 226 of file qgsmaprendererjob.h.

◆ mErrors

Errors QgsMapRendererJob::mErrors
protected

Definition at line 224 of file qgsmaprendererjob.h.

◆ mRenderingStart

QTime QgsMapRendererJob::mRenderingStart
protected

Definition at line 223 of file qgsmaprendererjob.h.

◆ mRenderingTime

int QgsMapRendererJob::mRenderingTime = 0
protected

Definition at line 228 of file qgsmaprendererjob.h.

◆ mSettings

QgsMapSettings QgsMapRendererJob::mSettings
protected

Definition at line 222 of file qgsmaprendererjob.h.


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