QgsRenderContext class

Contains information about the context of a rendering operation.

Reference

The context of a rendering operation defines properties such as the conversion ratio between screen and map units, the extents to be rendered etc.

Public types

enum Flag { DrawEditingInfo = 0x01, ForceVectorOutput = 0x02, UseAdvancedEffects = 0x04, UseRenderingOptimization = 0x08, DrawSelection = 0x10, DrawSymbolBounds = 0x20, RenderMapTile = 0x40, Antialiasing = 0x80, RenderPartialOutput = 0x100, RenderPreviewJob = 0x200 }: Enumeration of flags that affect rendering operations.
enum TextRenderFormat { TextFormatAlwaysOutlines, TextFormatAlwaysText }: Options for rendering text.

Public static functions

static auto fromMapSettings(const QgsMapSettings& mapSettings) -> QgsRenderContext: create initialized QgsRenderContext instance from given QgsMapSettings
static auto fromQPainter(QPainter* painter) -> QgsRenderContext: Creates a default render context given a pixel based QPainter destination.

Public functions

auto convertFromMapUnits(double sizeInMapUnits, QgsUnitTypes::RenderUnit outputUnit) const -> double: Converts a size from map units to the specified units.
auto convertMetersToMapUnits(double meters) const -> double: Convert meter distances to active MapUnit values for QgsUnitTypes::RenderMetersInMapUnits.
auto convertToMapUnits(double size, QgsUnitTypes::RenderUnit unit, const QgsMapUnitScale& scale = QgsMapUnitScale()) const -> double: Converts a size from the specified units to map units.
auto convertToPainterUnits(double size, QgsUnitTypes::RenderUnit unit, const QgsMapUnitScale& scale = QgsMapUnitScale()) const -> double: Converts a size from the specified units to painter units (pixels).
auto coordinateTransform() const -> QgsCoordinateTransform: Returns the current coordinate transform for the context.
auto distanceArea() const -> const QgsDistanceArea&: A general purpose distance and area calculator, capable of performing ellipsoid based calculations.
auto expressionContext() -> QgsExpressionContext&: Gets the expression context.
auto expressionContext() const -> const QgsExpressionContext&: Gets the expression context (const version).
auto extent() const -> const QgsRectangle&: When rendering a map layer, calling this method returns the "clipping" extent for the layer (in the layer's CRS).
auto featureFilterProvider() const -> const QgsFeatureFilterProvider*: Gets the filter feature provider used for additional filtering of rendered features.
auto flags() const -> Flags: Returns combination of flags used for rendering.
auto geometry() const -> const QgsAbstractGeometry*: Returns pointer to the unsegmentized geometry.
auto labelingEngine() const -> QgsLabelingEngine*: Gets access to new labeling engine (may be nullptr)
auto painter() -> QPainter*: Returns the destination QPainter for the render operation.
auto pathResolver() const -> const QgsPathResolver&: Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
auto rendererScale() const -> double: Returns the renderer map scale.
auto scaleFactor() const -> double: Returns the scaling factor for the render to convert painter units to physical sizes.
auto segmentationTolerance() const -> double: Gets the segmentation tolerance applied when rendering curved geometries.
auto segmentationToleranceType() const -> QgsAbstractGeometry::SegmentationToleranceType: Gets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
void setCoordinateTransform(const QgsCoordinateTransform& t): Sets the current coordinate transform for the context.
void setDistanceArea(const QgsDistanceArea& distanceArea): A general purpose distance and area calculator, capable of performing ellipsoid based calculations.
void setExpressionContext(const QgsExpressionContext& context): Sets the expression context.
void setExtent(const QgsRectangle& extent): When rendering a map layer, calling this method sets the "clipping" extent for the layer (in the layer's CRS).
void setFeatureFilterProvider(const QgsFeatureFilterProvider* ffp): Set a filter feature provider used for additional filtering of rendered features.
void setFlag(Flag flag, bool on = true): Enable or disable a particular flag (other flags are not affected)
void setFlags(QgsRenderContext::Flags flags): Set combination of flags that will be used for rendering.
void setGeometry(const QgsAbstractGeometry* geometry): Sets pointer to original (unsegmentized) geometry.
void setLabelingEngine(QgsLabelingEngine* engine2): Assign new labeling engine.
void setPainter(QPainter* p): Sets the destination QPainter for the render operation.
void setPathResolver(const QgsPathResolver& resolver): Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.g.
void setRendererScale(double scale): Sets the renderer map scale.
void setScaleFactor(double factor): Sets the scaling factor for the render to convert painter units to physical sizes.
void setSegmentationTolerance(double tolerance): Sets the segmentation tolerance applied when rendering curved geometries.
void setSegmentationToleranceType(QgsAbstractGeometry::SegmentationToleranceType type): Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)
void setShowSelection(bool showSelection): Sets whether vector selections should be shown in the rendered map.
void setTextRenderFormat(TextRenderFormat format): Sets the text render format, which dictates how text is rendered (e.g.
void setTransformContext(const QgsCoordinateTransformContext& context): Sets the context's coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.
void setUseAdvancedEffects(bool enabled): Used to enable or disable advanced effects such as blend modes.
auto showSelection() const -> bool: Returns true if vector selections should be shown in the rendered map.
auto testFlag(Flag flag) const -> bool: Check whether a particular flag is enabled.
auto textRenderFormat() const -> TextRenderFormat: Returns the text render format, which dictates how text is rendered (e.g.
auto transformContext() const -> QgsCoordinateTransformContext: Returns the context's coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.
auto useAdvancedEffects() const -> bool: Returns true if advanced effects such as blend modes such be used.
auto useRenderingOptimization() const -> bool: Returns true if the rendering optimization (geometry simplification) can be executed.
auto vectorSimplifyMethod() const -> const QgsVectorSimplifyMethod&: Added in QGIS v2.4.

Enum documentation

enum QgsRenderContext::Flag

Enumeration of flags that affect rendering operations.

Enumerators
DrawEditingInfo	Enable drawing of vertex markers for layers in editing mode.
ForceVectorOutput	Vector graphics should not be cached and drawn as raster images.
UseAdvancedEffects	Enable layer opacity and blending effects.
UseRenderingOptimization	Enable vector simplification and other rendering optimizations.
DrawSelection	Whether vector selections should be shown in the rendered map.
DrawSymbolBounds	Draw bounds of symbols (for debugging/testing)
RenderMapTile	Draw map such that there are no problems between adjacent tiles.
Antialiasing	Use antialiasing while drawing.
RenderPartialOutput	Whether to make extra effort to update map image with partially rendered layers (better for interactive map canvas). Added in QGIS 3.0.
RenderPreviewJob	Render is a 'canvas preview' render, and shortcuts should be taken to ensure fast rendering.

enum QgsRenderContext::TextRenderFormat

Options for rendering text.

Enumerators
TextFormatAlwaysOutlines	Always render text using path objects (AKA outlines/curves). This setting guarantees the best quality rendering, even when using a raster paint surface (where sub-pixel path based text rendering is superior to sub-pixel text-based rendering). The downside is that text is converted to paths only, so users cannot open created vector outputs for post-processing in other applications and retain text editability. This setting also guarantees complete compatibility with the full range of formatting options available through QgsTextRenderer and QgsTextFormat, some of which may not be possible to reproduce when using a vector-based paint surface and TextFormatAlwaysText mode. A final benefit to this setting is that vector exports created using text as outlines do not require all users to have the original fonts installed in order to display the text in its original style.
TextFormatAlwaysText	Always render text as text objects. While this mode preserves text objects as text for post-processing in external vector editing applications, it can result in rendering artifacts or poor quality rendering, depending on the text format settings. Even with raster based paint devices, TextFormatAlwaysText can result in inferior rendering quality to TextFormatAlwaysOutlines. When rendering using TextFormatAlwaysText to a vector based device (e.g. PDF or SVG), care must be taken to ensure that the required fonts are available to users when opening the created files, or default fallback fonts will be used to display the output instead. (Although PDF exports MAY automatically embed some fonts when possible, depending on the user's platform).

Enumerators

TextFormatAlwaysOutlines

Always render text using path objects (AKA outlines/curves).

This setting guarantees the best quality rendering, even when using a raster paint surface (where sub-pixel path based text rendering is superior to sub-pixel text-based rendering). The downside is that text is converted to paths only, so users cannot open created vector outputs for post-processing in other applications and retain text editability.

This setting also guarantees complete compatibility with the full range of formatting options available through QgsTextRenderer and QgsTextFormat, some of which may not be possible to reproduce when using a vector-based paint surface and TextFormatAlwaysText mode.

A final benefit to this setting is that vector exports created using text as outlines do not require all users to have the original fonts installed in order to display the text in its original style.

TextFormatAlwaysText

Always render text as text objects.

While this mode preserves text objects as text for post-processing in external vector editing applications, it can result in rendering artifacts or poor quality rendering, depending on the text format settings.

Even with raster based paint devices, TextFormatAlwaysText can result in inferior rendering quality to TextFormatAlwaysOutlines.

When rendering using TextFormatAlwaysText to a vector based device (e.g. PDF or SVG), care must be taken to ensure that the required fonts are available to users when opening the created files, or default fallback fonts will be used to display the output instead. (Although PDF exports MAY automatically embed some fonts when possible, depending on the user's platform).

Function documentation

static QgsRenderContext QgsRenderContext::fromMapSettings(const QgsMapSettings& mapSettings)

create initialized QgsRenderContext instance from given QgsMapSettings

static QgsRenderContext QgsRenderContext::fromQPainter(QPainter* painter)

Creates a default render context given a pixel based QPainter destination.

If no painter is specified or the painter has no device, then a default DPI of 88 will be assumed.

double QgsRenderContext::convertFromMapUnits(double sizeInMapUnits, QgsUnitTypes::RenderUnit outputUnit) const

Converts a size from map units to the specified units.

double QgsRenderContext::convertMetersToMapUnits(double meters) const

Convert meter distances to active MapUnit values for QgsUnitTypes::RenderMetersInMapUnits.

double QgsRenderContext::convertToMapUnits(double size, QgsUnitTypes::RenderUnit unit, const QgsMapUnitScale& scale = QgsMapUnitScale()) const

Converts a size from the specified units to map units.

The conversion respects the limits specified by the optional scale parameter.

double QgsRenderContext::convertToPainterUnits(double size, QgsUnitTypes::RenderUnit unit, const QgsMapUnitScale& scale = QgsMapUnitScale()) const

Converts a size from the specified units to painter units (pixels).

The conversion respects the limits specified by the optional scale parameter.

QgsCoordinateTransform QgsRenderContext::coordinateTransform() const

Returns the current coordinate transform for the context.

This represents the coordinate transform required to transform a layer which is being rendered back to the CRS of the rendered map. If no coordinate transformation is required, or the render context is not associated with a map layer render, then an invalid coordinate transformation is returned.

const QgsDistanceArea& QgsRenderContext::distanceArea() const

A general purpose distance and area calculator, capable of performing ellipsoid based calculations.

QgsExpressionContext& QgsRenderContext::expressionContext()

Gets the expression context.

This context should be used for all expression evaluation associated with this render context.

const QgsExpressionContext& QgsRenderContext::expressionContext() const

Gets the expression context (const version).

This context should be used for all expression evaluation associated with this render context.

const QgsRectangle& QgsRenderContext::extent() const

When rendering a map layer, calling this method returns the "clipping" extent for the layer (in the layer's CRS).

This extent is a "worst-case" scenario, which is guaranteed to cover the complete visible portion of the layer when it is rendered to a map. It is often larger than the actual visible portion of that layer.

const QgsFeatureFilterProvider* QgsRenderContext::featureFilterProvider() const

Gets the filter feature provider used for additional filtering of rendered features.

Returns	the filter feature provider

Flags QgsRenderContext::flags() const

Returns combination of flags used for rendering.

QgsLabelingEngine* QgsRenderContext::labelingEngine() const

Gets access to new labeling engine (may be nullptr)

QPainter* QgsRenderContext::painter()

Returns the destination QPainter for the render operation.

const QgsPathResolver& QgsRenderContext::pathResolver() const

Returns the path resolver for conversion between relative and absolute paths during rendering operations, e.g.

for resolving relative symbol paths.

double QgsRenderContext::rendererScale() const

Returns the renderer map scale.

This will match the desired scale denominator for the rendered map, eg 1000.0 for a 1:1000 map render.

double QgsRenderContext::scaleFactor() const

Returns the scaling factor for the render to convert painter units to physical sizes.

This is usually equal to the number of pixels per millimeter.

void QgsRenderContext::setCoordinateTransform(const QgsCoordinateTransform& t)

Sets the current coordinate transform for the context.

This represents the coordinate transform required to transform the layer which is being rendered back to the CRS of the rendered map.

Set to an invalid QgsCoordinateTransform to indicate that no transformation is required.

void QgsRenderContext::setDistanceArea(const QgsDistanceArea& distanceArea)

A general purpose distance and area calculator, capable of performing ellipsoid based calculations.

Will be used to convert meter distances to active MapUnit values for QgsUnitTypes::RenderMetersInMapUnits

void QgsRenderContext::setExpressionContext(const QgsExpressionContext& context)

Sets the expression context.

This context is used for all expression evaluation associated with this render context.

void QgsRenderContext::setExtent(const QgsRectangle& extent)

When rendering a map layer, calling this method sets the "clipping" extent for the layer (in the layer's CRS).

This extent should be a "worst-case" scenario, which is guaranteed to completely cover the entire visible portion of the layer when it is rendered to the map. It may be larger than the actual visible area, but MUST contain at least the entire visible area.

void QgsRenderContext::setFeatureFilterProvider(const QgsFeatureFilterProvider* ffp)

Set a filter feature provider used for additional filtering of rendered features.

Parameters
ffp	the filter feature provider

void QgsRenderContext::setFlag(Flag flag, bool on = true)

Enable or disable a particular flag (other flags are not affected)

void QgsRenderContext::setFlags(QgsRenderContext::Flags flags)

Set combination of flags that will be used for rendering.

void QgsRenderContext::setLabelingEngine(QgsLabelingEngine* engine2)

Assign new labeling engine.

void QgsRenderContext::setPainter(QPainter* p)

Sets the destination QPainter for the render operation.

Ownership of the painter is not transferred and the QPainter destination must stay alive for the duration of any rendering operations.

void QgsRenderContext::setPathResolver(const QgsPathResolver& resolver)

Sets the path resolver for conversion between relative and absolute paths during rendering operations, e.g.

for resolving relative symbol paths.

void QgsRenderContext::setRendererScale(double scale)

Sets the renderer map scale.

This should match the desired scale denominator for the rendered map, eg 1000.0 for a 1:1000 map render.

void QgsRenderContext::setScaleFactor(double factor)

Sets the scaling factor for the render to convert painter units to physical sizes.

This should usually be equal to the number of pixels per millimeter.

void QgsRenderContext::setSegmentationTolerance(double tolerance)

Sets the segmentation tolerance applied when rendering curved geometries.

Parameters
tolerance	the segmentation tolerance

void QgsRenderContext::setSegmentationToleranceType(QgsAbstractGeometry::SegmentationToleranceType type)

Sets segmentation tolerance type (maximum angle or maximum difference between curve and approximation)

Parameters
type	the segmentation tolerance typename

void QgsRenderContext::setShowSelection(bool showSelection)

Sets whether vector selections should be shown in the rendered map.

Parameters
showSelection	set to true if selections should be shown

void QgsRenderContext::setTextRenderFormat(TextRenderFormat format)

Sets the text render format, which dictates how text is rendered (e.g.

as paths or real text objects).

void QgsRenderContext::setTransformContext(const QgsCoordinateTransformContext& context)

Sets the context's coordinate transform context, which stores various information regarding which datum transforms should be used when transforming points from a source to destination coordinate reference system.

bool QgsRenderContext::showSelection() const

Returns true if vector selections should be shown in the rendered map.

Returns	true if selections should be shown

bool QgsRenderContext::testFlag(Flag flag) const

Check whether a particular flag is enabled.

TextRenderFormat QgsRenderContext::textRenderFormat() const

Returns the text render format, which dictates how text is rendered (e.g.