Skip to content
Permalink
Browse files
Doxymentation for QgsMapRendererJob + subclasses
  • Loading branch information
wonder-sk committed Jun 24, 2014
1 parent 68cc9f4 commit 2fedba0805427fbf25d779f992554dff8cee1cef
@@ -1,6 +1,11 @@

/** job implementation that renders everything sequentially using a custom painter.
* The returned image is always invalid (because there is none available).
/** Job implementation that renders everything sequentially using a custom painter.
*
* Also supports synchronous rendering in main thread for cases when rendering in background
* is not an option because of some technical limitations (e.g. printing to printer on some
* platforms).
*
* @note added in 2.4
*/
class QgsMapRendererCustomPainterJob : QgsMapRendererJob
{
@@ -11,7 +11,30 @@ struct LayerRenderJob

typedef QList<LayerRenderJob> LayerRenderJobs;

/** abstract base class renderer jobs that asynchronously start map rendering */
/**
* 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:
* - 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
*
* @note added in 2.4
*/
class QgsMapRendererJob : QObject
{
%TypeHeaderCode
@@ -102,6 +125,8 @@ class QgsMapRendererJob : QObject

/** Intermediate base class adding functionality that allows client to query the rendered image.
* The image can be queried even while the rendering is still in progress to get intermediate result
*
* @note added in 2.4
*/
class QgsMapRendererQImageJob : QgsMapRendererJob
{
@@ -1,5 +1,11 @@

/** job implementation that renders all layers in parallel */
/** Job implementation that renders all layers in parallel.
*
* The resulting map image can be retrieved with renderedImage() function.
* It is safe to call that function while rendering is active to see preview of the map.
*
* @note added in 2.4
*/
class QgsMapRendererParallelJob : QgsMapRendererQImageJob
{
%TypeHeaderCode
@@ -1,6 +1,12 @@


/** job implementation that renders everything sequentially in one thread */
/** Job implementation that renders everything sequentially in one thread.
*
* The resulting map image can be retrieved with renderedImage() function.
* It is safe to call that function while rendering is active to see preview of the map.
*
* @note added in 2.4
*/
class QgsMapRendererSequentialJob : QgsMapRendererQImageJob
{
%TypeHeaderCode
@@ -20,8 +20,13 @@

#include <QEventLoop>

/** job implementation that renders everything sequentially using a custom painter.
* The returned image is always invalid (because there is none available).
/** Job implementation that renders everything sequentially using a custom painter.
*
* Also supports synchronous rendering in main thread for cases when rendering in background
* is not an option because of some technical limitations (e.g. printing to printer on some
* platforms).
*
* @note added in 2.4
*/
class CORE_EXPORT QgsMapRendererCustomPainterJob : public QgsMapRendererJob
{
@@ -35,6 +35,9 @@ class QgsMapRendererCache;
class QgsPalLabeling;


/** Structure keeping low-level rendering job information.
* @note not part of public API!
*/
struct LayerRenderJob
{
QgsRenderContext context;
@@ -48,7 +51,30 @@ struct LayerRenderJob
typedef QList<LayerRenderJob> LayerRenderJobs;


/** abstract base class renderer jobs that asynchronously start map rendering */
/**
* 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:
* - 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
*
* @note added in 2.4
*/
class CORE_EXPORT QgsMapRendererJob : public QObject
{
Q_OBJECT
@@ -149,6 +175,8 @@ class CORE_EXPORT QgsMapRendererJob : public QObject

/** Intermediate base class adding functionality that allows client to query the rendered image.
* The image can be queried even while the rendering is still in progress to get intermediate result
*
* @note added in 2.4
*/
class CORE_EXPORT QgsMapRendererQImageJob : public QgsMapRendererJob
{
@@ -18,7 +18,13 @@

#include "qgsmaprendererjob.h"

/** job implementation that renders all layers in parallel */
/** Job implementation that renders all layers in parallel.
*
* The resulting map image can be retrieved with renderedImage() function.
* It is safe to call that function while rendering is active to see preview of the map.
*
* @note added in 2.4
*/
class CORE_EXPORT QgsMapRendererParallelJob : public QgsMapRendererQImageJob
{
Q_OBJECT
@@ -20,7 +20,13 @@

class QgsMapRendererCustomPainterJob;

/** job implementation that renders everything sequentially in one thread */
/** Job implementation that renders everything sequentially in one thread.
*
* The resulting map image can be retrieved with renderedImage() function.
* It is safe to call that function while rendering is active to see preview of the map.
*
* @note added in 2.4
*/
class CORE_EXPORT QgsMapRendererSequentialJob : public QgsMapRendererQImageJob
{
Q_OBJECT

0 comments on commit 2fedba0

Please sign in to comment.