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

QgsLabelingEngineFeedback *	labelingEngineFeedback ()
	Returns the associated labeling engine feedback object. More...

QgsLabelSink *	labelSink () 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 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	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 QgsLabelingResults *	takeLabelingResults ()=0
	Gets pointer to internal labeling engine (in order to get access to the results). More...

QgsRenderedItemResults *	takeRenderedItemResults ()
	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	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 (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	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)
	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...

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< QgsRenderedItemResults >	mRenderedItemResults

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

Member Typedef Documentation

◆ Errors

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

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

Since: QGIS 3.0

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

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

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

◆ 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

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

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

Since: QGIS 3.0

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

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 385 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 323 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 369 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()

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

◆ mCache

QgsMapRendererCache* QgsMapRendererJob::mCache = nullptr

protected

Definition at line 472 of file qgsmaprendererjob.h.

◆ mErrors

Errors QgsMapRendererJob::mErrors

protected

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

◆ mLayersRedrawnFromCache

QStringList QgsMapRendererJob::mLayersRedrawnFromCache

protected

Definition at line 495 of file qgsmaprendererjob.h.

◆ mPerLayerRenderingTime

QHash< QgsWeakMapLayerPointer, int > QgsMapRendererJob::mPerLayerRenderingTime

protected

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

Definition at line 477 of file qgsmaprendererjob.h.

◆ mRecordRenderingTime

bool QgsMapRendererJob::mRecordRenderingTime = true

protected

true if layer rendering time should be recorded.

Definition at line 489 of file qgsmaprendererjob.h.

◆ mRenderedItemResults

std::unique_ptr< QgsRenderedItemResults > QgsMapRendererJob::mRenderedItemResults

protected

Definition at line 492 of file qgsmaprendererjob.h.

◆ mRenderingStart

QElapsedTimer QgsMapRendererJob::mRenderingStart

protected

Definition at line 469 of file qgsmaprendererjob.h.

◆ mRenderingTime

int QgsMapRendererJob::mRenderingTime = 0

protected

Definition at line 474 of file qgsmaprendererjob.h.

◆ mSettings

QgsMapSettings QgsMapRendererJob::mSettings

protected

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

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

/build/qgis-3.24.2+99sid/src/core/maprenderer/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()

◆ ~QgsMapRendererJob()

Member Function Documentation

◆ cancel()

◆ cancelWithoutBlocking()

◆ cleanupJobs()

◆ cleanupLabelJob()

◆ cleanupSecondPassJobs()

◆ composeImage()

◆ composeSecondPass()

◆ drawLabeling() [1/2]

◆ drawLabeling() [2/2]

◆ errors()

◆ featureFilterProvider()

◆ finished

◆ isActive()

◆ labelingEngineFeedback()

◆ labelSink()

◆ layerImageToBeComposed()

◆ layerRendered

◆ layerRenderingStarted

◆ layersRedrawnFromCache()

◆ logRenderingTime()

◆ mapSettings()

◆ perLayerRenderingTime()

◆ prepareJobs()

◆ prepareLabelCache()

◆ prepareLabelingJob()

◆ prepareSecondPassJobs()

◆ renderingLayersFinished

◆ renderingTime()

◆ setCache()

◆ setFeatureFilterProvider()

◆ setLabelSink()

◆ setLayerRenderingTimeHints()

◆ start()

◆ takeLabelingResults()

◆ takeRenderedItemResults()

◆ usedCachedLabels()

◆ waitForFinished()

Member Data Documentation

◆ LABEL_CACHE_ID

◆ LABEL_PREVIEW_CACHE_ID

◆ mCache

◆ mErrors

◆ mLayerRenderingTimeHints

◆ mLayersRedrawnFromCache

◆ mPerLayerRenderingTime

◆ mRecordRenderingTime

◆ mRenderedItemResults

◆ mRenderingStart

◆ mRenderingTime

◆ mSettings

◆ settingsLogCanvasRefreshEvent