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

#include <qgsmaprendererjob.h>

Inheritance diagram for QgsMapRendererJob:

[legend]

Classes
struct	Error

Public Types
typedef QList< QgsMapRendererJob::Error >	Errors

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 QgsFeatureFilterProvider *	featureFilterProvider () 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 QgsMapSettings &	mapSettings () 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...

virtual void	start ()=0
	Start the rendering job and immediately return. More...

virtual QgsLabelingResults *	takeLabelingResults ()=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...

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
QgsMapRendererCache *	mCache = 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:

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

QgsMapRendererSequentialJob - renders map in one background thread to an image
QgsMapRendererParallelJob - renders map in multiple background threads to an image
QgsMapRendererCustomPainterJob - renders map with given QPainter in one background thread

Since: QGIS 2.4

Definition at line 212 of file qgsmaprendererjob.h.

Member Typedef Documentation

◆ Errors

typedef QList<QgsMapRendererJob::Error> QgsMapRendererJob::Errors

Definition at line 287 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 274 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 303 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 267 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()

virtual void QgsMapRendererJob::start ( )

pure virtual

Start the rendering job and immediately return.

Does nothing if the rendering is already in progress.

Implemented in QgsMapRendererStagedRenderJob, QgsMapRendererSequentialJob, QgsMapRendererParallelJob, and QgsMapRendererCustomPainterJob.

◆ 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

Block until the job has finished.

Implemented in QgsMapRendererStagedRenderJob, QgsMapRendererSequentialJob, QgsMapRendererParallelJob, and QgsMapRendererCustomPainterJob.

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

◆ mCache

QgsMapRendererCache* QgsMapRendererJob::mCache = nullptr

protected

Definition at line 366 of file qgsmaprendererjob.h.

◆ mErrors

Errors QgsMapRendererJob::mErrors

protected

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

◆ mPerLayerRenderingTime

QHash< QgsWeakMapLayerPointer, int > QgsMapRendererJob::mPerLayerRenderingTime

protected

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

Definition at line 371 of file qgsmaprendererjob.h.

◆ mRecordRenderingTime

bool QgsMapRendererJob::mRecordRenderingTime = true

protected

true if layer rendering time should be recorded.

Definition at line 383 of file qgsmaprendererjob.h.

◆ mRenderingStart

QElapsedTimer QgsMapRendererJob::mRenderingStart

protected

Definition at line 363 of file qgsmaprendererjob.h.

◆ mRenderingTime

int QgsMapRendererJob::mRenderingTime = 0

protected

Definition at line 368 of file qgsmaprendererjob.h.

◆ mSettings

QgsMapSettings QgsMapRendererJob::mSettings

protected

Definition at line 362 of file qgsmaprendererjob.h.

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

/build/qgis-3.18.1+99unstable/src/core/qgsmaprendererjob.h

Classes

Public Types

Signals

Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Errors

Constructor & Destructor Documentation

◆ QgsMapRendererJob()

Member Function Documentation

◆ cancel()

◆ cancelWithoutBlocking()

◆ cleanupJobs()

◆ cleanupLabelJob()

◆ cleanupSecondPassJobs()

◆ composeImage()

◆ composeSecondPass()

◆ drawLabeling() [1/2]

◆ drawLabeling() [2/2]

◆ errors()

◆ featureFilterProvider()

◆ finished

◆ isActive()

◆ layerImageToBeComposed()

◆ logRenderingTime()

◆ mapSettings()

◆ perLayerRenderingTime()

◆ prepareJobs()

◆ prepareLabelCache()

◆ prepareLabelingJob()

◆ prepareSecondPassJobs()

◆ renderingLayersFinished

◆ renderingTime()

◆ setCache()

◆ setFeatureFilterProvider()

◆ setLayerRenderingTimeHints()

◆ start()

◆ takeLabelingResults()

◆ usedCachedLabels()

◆ waitForFinished()

Member Data Documentation

◆ LABEL_CACHE_ID

◆ LABEL_PREVIEW_CACHE_ID

◆ mCache

◆ mErrors

◆ mLayerRenderingTimeHints

◆ mPerLayerRenderingTime

◆ mRecordRenderingTime

◆ mRenderingStart

◆ mRenderingTime

◆ mSettings