QGIS API Documentation  3.6.0-Noosa (5873452)
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 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
 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...
 
virtual void start ()=0
 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...
 

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 Q_DECL_DEPRECATED void drawLabeling (const QgsMapSettings &settings, QgsRenderContext &renderContext, QgsLabelingEngine *labelingEngine2, QPainter *painter)
 
static void drawLabeling (QgsRenderContext &renderContext, QgsLabelingEngine *labelingEngine2, QPainter *painter)
 

Protected Attributes

QgsMapRendererCachemCache = nullptr
 
Errors mErrors
 
QHash< QgsWeakMapLayerPointer, int > mPerLayerRenderingTime
 Render time (in ms) per layer, by layer ID. More...
 
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:

Since
QGIS 2.4

Definition at line 115 of file qgsmaprendererjob.h.

Member Typedef Documentation

◆ Errors

Definition at line 190 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
not available in Python bindings
Since
QGIS 3.0

◆ composeImage()

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

◆ drawLabeling() [1/2]

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

Definition at line 341 of file qgsmaprenderercustompainterjob.cpp.

◆ drawLabeling() [2/2]

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

Definition at line 321 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

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

Since
QGIS 3.0

Definition at line 177 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

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 
)
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
Since
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.

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 206 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 170 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

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 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()
Since
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 226 of file qgsmaprendererjob.h.

◆ mCache

QgsMapRendererCache* QgsMapRendererJob::mCache = nullptr
protected

Definition at line 248 of file qgsmaprendererjob.h.

◆ mErrors

Errors QgsMapRendererJob::mErrors
protected

Definition at line 246 of file qgsmaprendererjob.h.

◆ mPerLayerRenderingTime

QHash< QgsWeakMapLayerPointer, int > QgsMapRendererJob::mPerLayerRenderingTime
protected

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

Definition at line 253 of file qgsmaprendererjob.h.

◆ mRenderingStart

QTime QgsMapRendererJob::mRenderingStart
protected

Definition at line 245 of file qgsmaprendererjob.h.

◆ mRenderingTime

int QgsMapRendererJob::mRenderingTime = 0
protected

Definition at line 250 of file qgsmaprendererjob.h.

◆ mSettings

QgsMapSettings QgsMapRendererJob::mSettings
protected

Definition at line 244 of file qgsmaprendererjob.h.


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