RenderEngine

Since: BlackBerry 10.0.0

#include <bb/cascades/maps/RenderEngine>

To link against this class, add the following line to your .pro file: LIBS += -lbbcascadesmaps

The common interface for all rendering engine implementations.

Communication Between MapView and RenderEngine

The only object that directly talks to a render engine instance is the MapView class. A majority of the operations triggered by MapView are synchronous in nature, and thus are blocking. Some of these calls could be executed on the main GUI event thread (for example, RenderEngine::windowToWorld). The exception to this is slot operations. These are executed asynchronously using Qt's queued messaging system.

Synchronous methods need to return very promptly. If they require longer, a separate thread should be spawned to turn it into an asynchronous operation.

Render Engine Timeline

Creation and Metadata: The render engine instance will be created using the default, empty constructor. At that point, the framework can query the properties of the engine. At this point, the engine should not be consuming any significant portion of memory.

Configuration: Once it has been determined that the engine is going to be used, its initialize() operation is called to set up the engine. At this point, the engine can set itself up, ready to perform renders.

Render Cycle: While an engine is in use, its render() operation will be executed in a separate thread. It is at this point that the engine needs to convert geographic data into OpenGL calls. Once a single render cycle has completed, the renderCompleted() signal has to be emitted so that the framework is notified.

The render cycle needs to complete in a timely fashion. If a long-term process needs to be performed (such as downloading data), then the action should be initiated off-thread and the render() operation completed. Once the long-term process has completed, the render can resume, and then the renderCompleted() signal can be emitted.

Closure: Once the framework has finished with the engine (but before destruction), the teardown() operation will be executed. At this point, the engine instance should clean up as much as possible. However, it may be reconfigured / re-initiated again using the initialize() operation. (The teardown() operation will be executed on the thread with MapView affinity: the GUI thread.)

Destruction: The engine's destructor is only called once the framework is, itself, destructed.

Note: Due to the fact that the engine may be in memory, but not in use, it is important that the engine be as memory efficient as possible. Thus, only between the initialize() and teardown() states should the engine consider itself "actively rendering".

Memory Management

When an instance of this class is handed to a MapView instance, the MapView claims ownership of the render engine. Thus, MapView is responsible for the destruction of the RenderEngine when it has been given to the MapView.

Reference Data and Thread Safety

RenderEngine implementations need to be aware that the MapData object is not thread safe. As such, care needs to be taken with dangling pointers to Geographic and DataProvider objects.

How to Make a RenderEngine a Plug-in

RenderEngine instances can be automatically discovered and used by MapView if they follow a plug-in format. To do this:

  • Declare it as an implementation of the RenderEngine interface by using the Q_INTERFACES macro, which gets placed under the Q_OBJECT macro in the engine's header file:
    Q_INTERFACES( bb::cascades::maps::RenderEngine )
    
  • Export the engine as a plug-in using the Q_EXPORT_PLUGIN2 macro, where project_target is the name of the project's TARGET value in the .pro file, and plugin_classname is the name of the class extending RenderEngine:
    Q_EXPORT_PLUGIN2( project_target, plugin_classname )
    
    The macro gets placed at the bottom of the engine's CPP implementation file.
  • Build the engine as a plugin, and bundle it as a shared library by adding the following to the project's .pro file:
    CONFIG += shared plugin
    
  • Deploy the plugin library to one of the following locations:
    • /usr/lib/qt4/plugins/mapview-renderengine - for system-wide plugins

    • [application root]/app/native/lib/mapview-renderengine - for application specific plugins.

Target Audience

This class is designed for clients wishing to extend MapView only.


Overview

Inheritance

bb::cascades::maps::RenderEngine
bb::cascades::maps::BlankRenderEngine

Public Functions Index

RenderEngine (QObject *parent=0)
virtual ~RenderEngine ()
bb::platform::geo::BoundingBoxcalculateBoundingBox (const bb::cascades::maps::ViewProperties &view) const =0
bb::cascades::maps::RenderEngineInfocharacteristics () const =0
intcoveragePriority () const =0
boolcoverageSupported (const bb::cascades::maps::ViewProperties &region) const =0
QStringelementIdAt (const QPoint &windowCoord) const =0
bb::ImageDatagenerateMapImage () const =0
voidinitialize (bb::cascades::maps::RenderEngineConfiguration config)=0
boolisBaseMapVisible () const =0
boolisInlineTrafficAvailable ()
boolisInlineTrafficEnabled ()
bb::cascades::maps::RenderEngine *newInstance () const =0
voidsetBaseMapVisible (bool visible)=0
voidsetInlineTrafficAvailable (bool available)
voidsetInlineTrafficEnabled (bool enabled)
voidsetMapData (bb::cascades::maps::MapData *data)=0
voidsetViewport (const bb::cascades::maps::ViewProperties &view)=0
voidteardown ()=0
bb::platform::geo::PointwindowToWorld (const QPoint &windowCoord) const =0
QPointworldToWindow (const bb::platform::geo::Point &worldCoord) const =0

Public Slots Index

voidrender ()=0

Signals Index

Public Functions

RenderEngine (

Base Constructor.

Parameters
parent

The parent object to this object.

Since:

BlackBerry 10.0.0

virtual~RenderEngine ()

Destructor.

Since:

BlackBerry 10.0.0

bb::platform::geo::BoundingBox calculateBoundingBox (

Calculates a new bounding box based on the view properties provided.

Parameters
view

The properties of the view to base the calculation on.

Return:

A bounding box that matches the limits of the view.

Since:

BlackBerry 10.0.0

bb::cascades::maps::RenderEngineInfo characteristics ()

Gets the characteristics of this engine.

Return:

The information concerning the characteristics of this engine.

Since:

BlackBerry 10.0.0

int coveragePriority ()

Indicates the priority for which this engine should be used when two engines have coverage over the same area.

Thus, if render engine A and B both have coverage over the current viewport, the render engine with the higher priority will be used.

Current priorities include:
  • 5: Reserved for Application-provided plug-in

  • 4: 3D System Render Engine

  • 3: 2D System Render Engine

  • 0: Blank Render Engine (no memory consumption)

Return:

The priority for this render engine. A higher number equals a higher priority. Numbers range from 0 to 5. 5 indicates an RE should absolutely be used, while 3 indicates a "normal" priority.

Since:

BlackBerry 10.0.0

bool coverageSupported (

Indicates whether this render engine has code coverage for the given region.

Note: Important factors to be considered are center, altitude and bounding box.

Parameters
region

The region in question.

Return:

true if this engine has map coverage for the entire region, false if partial coverage or no coverage.

Since:

BlackBerry 10.0.0

QString elementIdAt (

Gets the element ID of the interactable element at the given window coordinates.

Parameters
windowCoord

the location of the point of interest.

Return:

The ID of the element available, or an empty string if no element exists.

Since:

BlackBerry 10.0.0

bb::ImageData generateMapImage ()

Converts the current map into an image.

Return:

The viewport's content as an image.

Since:

BlackBerry 10.0.0

void initialize (

Initializes the engine.

Since:

BlackBerry 10.0.0

bool isBaseMapVisible ()

Indicates whether base map data is included in the rendered output.

Base map data includes items such as ground information, roads, and so on.

Return:

true if the base map is included.

Since:

BlackBerry 10.0.0

bool isInlineTrafficAvailable ()

Indicates whether there is inline traffic available for the current map view.

Return:

true if traffic data is available for the current view, false if no traffic data is available.

Since:

BlackBerry 10.2.0

bool isInlineTrafficEnabled ()

Indicates whether inline traffic has been enabled within this RenderEngine.

Return:

true to enable, false to disable inline traffic.

Since:

BlackBerry 10.2.0

bb::cascades::maps::RenderEngine * newInstance ()

Creates a new instance of this render engine.

This factory method is only used through the plug-in system.

Return:

The new instance of the RenderEngine, never null.

Since:

BlackBerry 10.0.0

void setBaseMapVisible (
  • boolvisible)

Sets whether or not the base map should be included in the rendered output.

Parameters
visible

true if the base map should be included.

Since:

BlackBerry 10.0.0

void setInlineTrafficAvailable (
  • boolavailable)

Sets the flag indicating if inline traffic is available within the current map view.

It is the RenderEngine's responsibility to call this operation whenever the availability state changes.

Parameters
available

true if traffic data is available for the current view, false if no traffic data is available.

Since:

BlackBerry 10.2.0

void setInlineTrafficEnabled (
  • boolenabled)

Enables the inclusion of inline traffic within the map.

Note: If the render engine doesn't support inline traffic, setting this value will have no effect.

Parameters
enabled

true to enable, false to disable inline traffic.

Since:

BlackBerry 10.2.0

void setMapData (

Gives the render engine the mapping data container holding non-atlas data.

Parameters
data

The container for mapping data. This parameter is owned by the parent MapView instance.

Since:

BlackBerry 10.0.0

void setViewport (

Changes the properties of the view.

This call is not an explicit request to initiate a new render. To initiate a new render use RenderEngine::render.

This is a blocking call (synchronous). See the class level comment titled "Communication Between MapView and RenderEngine".

Parameters
view

The new view properties.

Since:

BlackBerry 10.0.0

void teardown ()

Provides an opportunity for the engine to perform any shutdown work.

Since:

BlackBerry 10.0.0

bb::platform::geo::Point windowToWorld (

Converts the screen coordinates to world coordinates.

This is a blocking call (synchronous). See the class level comment titled "Communication Between MapView and RenderEngine".

Parameters
windowCoord

The coordinates within the viewport's window to convert.

Return:

The coordinates representing the window's coordinates.

Since:

BlackBerry 10.0.0

QPoint worldToWindow (

Converts a world coordinate into a screen/window coordinate.

This is a blocking call.

Parameters
worldCoord

The world (lat/lon) coordinates to convert.

Return:

The window coordinates representing the world coordinates. The returned coordinates may not be within the current window's view.

Since:

BlackBerry 10.0.0

Public Slots

void render ()

Initiates a render cycle using the location information previously provided.

Note: This operation will not be called again until it has returned. Thus, there might be a backlog of render requests. It is important that this operation return in a timely fashion so that other messages in the messaging queue can be delivered.

Since:

BlackBerry 10.0.0

Signals

void coverageUnavailable ()

Emitted when the RenderEngine cannot fully render the current map viewing area.

Since:

BlackBerry 10.0.0

void inlineTrafficAvailableChanged (
  • boolavailable)

Emitted when the "inline traffic available" state has changed.

Parameters
available

The availability state for the inline traffic flag.

Since:

BlackBerry 10.2.0

void inlineTrafficEnabledChanged (
  • boolenabled)

Emitted when the "enable inline traffic" state has changed.

Parameters
enabled

The new state for inline traffic being enabled / disabled.

Since:

BlackBerry 10.2.0

void renderCompleted ()

Indicates to observers that a render cycle has been completed.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus