QGIS API Documentation  3.37.0-Master (a5b4d9743e8)
Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
QgsMapLayerRenderer Class Referenceabstract

Base class for utility classes that encapsulate information necessary for rendering of map layers. More...

#include <qgsmaplayerrenderer.h>

Inheritance diagram for QgsMapLayerRenderer:
Inheritance graph
[legend]

Public Member Functions

 QgsMapLayerRenderer (const QString &layerID, QgsRenderContext *context=nullptr)
 Constructor for QgsMapLayerRenderer, with the associated layerID and render context. More...
 
virtual ~QgsMapLayerRenderer ()
 
QStringList errors () const
 Returns list of errors (problems) that happened during the rendering. More...
 
virtual QgsFeedbackfeedback () const
 Access to feedback object of the layer renderer (may be nullptr) More...
 
virtual Qgis::MapLayerRendererFlags flags () const
 Returns flags which control how the map layer rendering behaves. More...
 
virtual bool forceRasterRender () const
 Returns true if the renderer must be rendered to a raster paint device (e.g. More...
 
bool isReadyToCompose () const
 Returns whether the renderer has already drawn (at least partially) some data. More...
 
QString layerId () const
 Gets access to the ID of the layer rendered by this class. More...
 
virtual bool render ()=0
 Do the rendering (based on data stored in the class). More...
 
QgsRenderContextrenderContext ()
 Returns the render context associated with the renderer. More...
 
const QgsRenderContextrenderContext () const
 Returns the render context associated with the renderer. More...
 
virtual void setLayerRenderingTimeHint (int time)
 Sets approximate render time (in ms) for the layer to render. More...
 
QList< QgsRenderedItemDetails * > takeRenderedItemDetails ()
 Takes the list of rendered item details from the renderer. More...
 

Protected Member Functions

void appendRenderedItemDetails (QgsRenderedItemDetails *details)
 Appends the details of a rendered item to the renderer. More...
 

Protected Attributes

QStringList mErrors
 
QString mLayerID
 
bool mReadyToCompose = true
 The flag must be set to false in renderer's constructor if wants to use the smarter map redraws functionality https://github.com/qgis/QGIS-Enhancement-Proposals/issues/181. More...
 

Static Protected Attributes

static constexpr int MAX_TIME_TO_USE_CACHED_PREVIEW_IMAGE = 3000
 Maximum time (in ms) to allow display of a previously cached preview image while rendering layers, before switching to a progressive rendering display. More...
 

Detailed Description

Base class for utility classes that encapsulate information necessary for rendering of map layers.

The rendering is typically done in a background thread, so it is necessary to keep all structures required for rendering away from the original map layer because it may change any time.

Because the data needs to be copied (to avoid the need for locking), it is highly desirable to use copy-on-write where possible. This way, the overhead of copying (both memory and CPU) will be kept low. Qt containers and various Qt classes use implicit sharing.

The scenario will be:

  1. renderer job (doing preparation in the GUI thread) calls QgsMapLayer::createMapRenderer() and gets instance of this class. The instance is initialized at that point and should not need additional calls to QgsVectorLayer.
  2. renderer job (still in GUI thread) stores the renderer for later use.
  3. renderer job (in worker thread) calls QgsMapLayerRenderer::render()
  4. renderer job (again in GUI thread) will check errors() and report them

Definition at line 51 of file qgsmaplayerrenderer.h.

Constructor & Destructor Documentation

◆ QgsMapLayerRenderer()

QgsMapLayerRenderer::QgsMapLayerRenderer ( const QString &  layerID,
QgsRenderContext context = nullptr 
)
inline

Constructor for QgsMapLayerRenderer, with the associated layerID and render context.

Definition at line 58 of file qgsmaplayerrenderer.h.

◆ ~QgsMapLayerRenderer()

QgsMapLayerRenderer::~QgsMapLayerRenderer ( )
virtualdefault

Member Function Documentation

◆ appendRenderedItemDetails()

void QgsMapLayerRenderer::appendRenderedItemDetails ( QgsRenderedItemDetails details)
protected

Appends the details of a rendered item to the renderer.

Rendered item details can be retrieved by calling takeRenderedItemDetails().

Ownership of details is transferred to the renderer.

See also
takeRenderedItemDetails()
Since
QGIS 3.22

Definition at line 42 of file qgsmaplayerrenderer.cpp.

◆ errors()

QStringList QgsMapLayerRenderer::errors ( ) const
inline

Returns list of errors (problems) that happened during the rendering.

Definition at line 104 of file qgsmaplayerrenderer.h.

◆ feedback()

QgsFeedback * QgsMapLayerRenderer::feedback ( ) const
virtual

◆ flags()

Qgis::MapLayerRendererFlags QgsMapLayerRenderer::flags ( ) const
virtual

Returns flags which control how the map layer rendering behaves.

Since
QGIS 3.34

Reimplemented in QgsTiledSceneLayerRenderer, and QgsPointCloudLayerRenderer.

Definition at line 27 of file qgsmaplayerrenderer.cpp.

◆ forceRasterRender()

bool QgsMapLayerRenderer::forceRasterRender ( ) const
virtual

Returns true if the renderer must be rendered to a raster paint device (e.g.

QImage).

Some layer settings require layers to be effectively "flattened" while rendering maps, which is achieved by first rendering the layer onto a raster paint device and then compositing the resultant image onto the final map render.

E.g. if a layer contains features with transparency or alternative blending modes, and the effects of these opacity or blending modes should be restricted to only affect other features within the SAME layer, then a flattened raster based render is required.

Subclasses should return true whenever their corresponding layer settings require the layer to always be rendered using a raster paint device.

Since
QGIS 3.18

Reimplemented in QgsVectorTileLayerRenderer, QgsVectorLayerRenderer, QgsTiledSceneLayerRenderer, QgsRasterLayerRenderer, QgsGroupLayerRenderer, QgsPointCloudLayerRenderer, QgsMeshLayerRenderer, and QgsAnnotationLayerRenderer.

Definition at line 22 of file qgsmaplayerrenderer.cpp.

◆ isReadyToCompose()

bool QgsMapLayerRenderer::isReadyToCompose ( ) const
inline

Returns whether the renderer has already drawn (at least partially) some data.

Since
QGIS 3.18

Definition at line 130 of file qgsmaplayerrenderer.h.

◆ layerId()

QString QgsMapLayerRenderer::layerId ( ) const
inline

Gets access to the ID of the layer rendered by this class.

Definition at line 107 of file qgsmaplayerrenderer.h.

◆ render()

virtual bool QgsMapLayerRenderer::render ( )
pure virtual

Do the rendering (based on data stored in the class).

Returns true if the layer was completely rendered successfully (i.e. the render was not canceled early).

Implemented in QgsVectorTileLayerRenderer, QgsVectorLayerRenderer, QgsTiledSceneLayerRenderer, QgsRasterLayerRenderer, QgsGroupLayerRenderer, QgsPointCloudLayerRenderer, QgsMeshLayerRenderer, and QgsAnnotationLayerRenderer.

◆ renderContext() [1/2]

QgsRenderContext* QgsMapLayerRenderer::renderContext ( )
inline

Returns the render context associated with the renderer.

Since
QGIS 3.10

Definition at line 114 of file qgsmaplayerrenderer.h.

◆ renderContext() [2/2]

const QgsRenderContext* QgsMapLayerRenderer::renderContext ( ) const
inline

Returns the render context associated with the renderer.

Note
Not available in Python bindings
Since
QGIS 3.18

Definition at line 122 of file qgsmaplayerrenderer.h.

◆ setLayerRenderingTimeHint()

virtual void QgsMapLayerRenderer::setLayerRenderingTimeHint ( int  time)
inlinevirtual

Sets approximate render time (in ms) for the layer to render.

This can be used to specifies a hint at the expected render times for the layer, so that the individual layer renderer subclasses can apply heuristics and determine appropriate update intervals during the render operation.

Note
Not available in Python bindings.
Since
QGIS 3.18

Reimplemented in QgsVectorLayerRenderer, and QgsPointCloudLayerRenderer.

Definition at line 142 of file qgsmaplayerrenderer.h.

◆ takeRenderedItemDetails()

QList< QgsRenderedItemDetails * > QgsMapLayerRenderer::takeRenderedItemDetails ( )

Takes the list of rendered item details from the renderer.

Ownership of items is transferred to the caller.

See also
appendRenderedItemDetails()
Since
QGIS 3.22

Definition at line 37 of file qgsmaplayerrenderer.cpp.

Member Data Documentation

◆ MAX_TIME_TO_USE_CACHED_PREVIEW_IMAGE

constexpr int QgsMapLayerRenderer::MAX_TIME_TO_USE_CACHED_PREVIEW_IMAGE = 3000
staticconstexprprotected

Maximum time (in ms) to allow display of a previously cached preview image while rendering layers, before switching to a progressive rendering display.

Note
Not available in Python bindings
Since
QGIS 3.18

Definition at line 184 of file qgsmaplayerrenderer.h.

◆ mErrors

QStringList QgsMapLayerRenderer::mErrors
protected

Definition at line 155 of file qgsmaplayerrenderer.h.

◆ mLayerID

QString QgsMapLayerRenderer::mLayerID
protected

Definition at line 156 of file qgsmaplayerrenderer.h.

◆ mReadyToCompose

bool QgsMapLayerRenderer::mReadyToCompose = true
protected

The flag must be set to false in renderer's constructor if wants to use the smarter map redraws functionality https://github.com/qgis/QGIS-Enhancement-Proposals/issues/181.

The flag must be set to true by renderer when the data is fetched and the renderer actually started to update the destination image.

When the flag is set to false, the image from QgsMapRendererCache is used instead to avoid flickering.

Since
QGIS 3.18

Definition at line 174 of file qgsmaplayerrenderer.h.


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