![]() |
LuciadCPillar 2023.0.03
|
A map for showing geo-spatial data. More...
#include <luciad/maps/Map.h>
Classes | |
class | Builder |
class | FeatureQuery |
A query specifies which features you are interested in. More... | |
class | HeightProvider |
A height provider based on the map layers order and visibility. More... | |
class | IRendererCallback |
This callback can be used to execute tasks on the render thread right before or right after the Map is painted by Map::Renderer . More... | |
class | Renderer |
The Map renderer. More... | |
class | ViewMapTransformation |
This class allows to transform between view (pixel coordinates on the screen) and map coordinates. More... | |
Public Types | |
enum class | LocationMode { ClosestSurface , Terrain } |
Used to determine how the Map::getViewToMapTransformation method determines the point in Map coordinates that corresponds to a given view location. More... | |
Public Member Functions | |
virtual | ~Map ()=default |
virtual void | addRendererCallback (std::shared_ptr< IRendererCallback > rendererCallback)=0 |
Adds the given callback to the Map. More... | |
virtual void | deliverNotifications ()=0 |
Delivers any pending notifications. More... | |
virtual void | destroy ()=0 |
Disposes the Map. More... | |
virtual const AnimationManager & | getAnimationManager () const =0 |
virtual AnimationManager & | getAnimationManager ()=0 |
virtual Color | getBackgroundColor () const =0 |
Returns the background color of the map. More... | |
virtual std::shared_ptr< Camera > | getCamera () const =0 |
Returns the camera that is currently used. More... | |
virtual std::shared_ptr< IController > | getController () const =0 |
Returns the current active controller of the map. More... | |
virtual MouseCursor | getCursor ()=0 |
Returns the current cursor of the map. More... | |
virtual double | getDisplayScale () const =0 |
Gets the display scale currently used to render the map. More... | |
virtual double | getDpi () const =0 |
Gets the DPI value used to calculate map scales. More... | |
virtual const GraphicsEffects & | getEffects () const =0 |
virtual GraphicsEffects & | getEffects ()=0 |
virtual const FeatureStateManager & | getFeatureStateManager () const =0 |
Returns the FeatureStateManager that keeps track of the feature state (for example selection) for this map. More... | |
virtual FeatureStateManager & | getFeatureStateManager ()=0 |
virtual uint32_t | getHeight () const =0 |
virtual const Map::HeightProvider & | getHeightProvider () const =0 |
virtual std::shared_ptr< LayerList > | getLayerList () const =0 |
virtual MapNavigator & | getMapNavigator () const =0 |
virtual std::shared_ptr< CoordinateReference > | getReference () const =0 |
Returns the reference of this Map. More... | |
virtual Renderer & | getRenderer () const =0 |
Retrieves the Renderer for this Map. More... | |
virtual const ViewMapTransformation & | getViewMapTransformation () const =0 |
Returns a transformation that can transform view coordinates to map coordinates and vice-versa. More... | |
virtual uint32_t | getWidth () const =0 |
virtual bool | is3D () const =0 |
Returns whether this Map is visualized in 3D. More... | |
virtual void | queryFeatures (const Map::FeatureQuery &query, const std::shared_ptr< IMapQueryFeaturesCallback > &callback) const =0 |
Queries the features under the given pixel bounds, and passes the result to the given callback. More... | |
virtual void | removeRendererCallback (const std::shared_ptr< IRendererCallback > &rendererCallback)=0 |
Removes the given callback from the Map. More... | |
virtual void | resize (uint32_t width, uint32_t height)=0 |
To be called when the host widget resizes, so that the map can adapt its camera, and graphics related resources. More... | |
virtual void | setBackgroundColor (luciad::Color color)=0 |
Sets the background color of the map. More... | |
virtual void | setCamera (const std::shared_ptr< Camera > &camera)=0 |
Set the camera that is used by the renderer. More... | |
virtual void | setController (std::shared_ptr< IController > controller)=0 |
Activate a controller, so that it can interact with the map. More... | |
virtual void | setCursor (MouseCursor cursor)=0 |
Change the map's cursor. More... | |
virtual void | setDisplayScale (double displayScale)=0 |
Specifies the display scale to allow the renderer to scale the graphics on high DPI displays. More... | |
virtual void | setDpi (double dpi)=0 |
Sets the DPI value that will be used to calculate map scales. More... | |
virtual void | setMapInvalidationCallback (std::shared_ptr< IInvalidationCallback > mapInvalidationCallback)=0 |
Sets the given IInvalidationCallback. More... | |
virtual void | setMouseCursorCallback (std::shared_ptr< IMouseCursorCallback > mouseCursorCallback)=0 |
Sets the given IMouseCursorCallback. More... | |
Static Public Member Functions | |
static Builder | newBuilder () |
A map for showing geo-spatial data.
Data can be added to the map using its LayerList
. For rendering, all data is transformed to a common coordinate reference for display. As a consequence, many different types of data can be visualized at the same time: raster data (imagery and elevation) and vector data (Feature instances).
The following article shows, among others, how you can add data to the map: Create your first map application
You can navigate the map using MapNavigator
. If you want to fully customize map navigation, you can set the Camera
directly.
Related articles:
To support interaction with Feature data, it is possible to query which features are present in a given pixel bounds. Feature states, such as selection, can be tracked by the Map's FeatureStateManager .
Note that Map and its Map::Renderer track on which thread they are constructed. This is done so that, in subsequent calls, they can verify that the same threads are used consistently. When an inconsistency is detected, an assertion is triggered. This means that:
Related article: Threading rules for the Map
To make sure the Map can be rendered on screens with different DPI's, it is possible to configure:
Map#setDpi
Map#setDisplayScale
Related article: Support high-resolution (HiDPI) displays
The map can only be made visible on the screen when integrating it with a UI toolkit. The samples show how this can be done. Next to that, the following article demonstrates how this is done for Qt: Integrate with Qt.
|
strong |
Used to determine how the Map::getViewToMapTransformation method determines the point in Map coordinates that corresponds to a given view location.
Enumerator | |
---|---|
ClosestSurface | Defines the view-to-map transformation mode where, for a given view point (pixels), a corresponding position (in Map coordinates) on a closest surface is provided. |
Terrain | Defines the view-to-map transformation mode where, for a given view point (pixels) a corresponding position (in Map coordinates) on the terrain is provided. |
|
virtualdefault |
|
pure virtual |
Adds the given callback to the Map.
After calling this method, the Map::Renderer::paint
will start calling the given callback instance.
rendererCallback | a renderer callback instance. Cannot be nullptr . |
NullArgumentException | when the renderer call back is nullptr . |
|
pure virtual |
Delivers any pending notifications.
The map buffers up notifications for delivery to the user on the UI thread. However, as the map does not have a way to schedule any actions on the UI thread, the user himself should call this function on the appropriate thread. For example, this could be done when the UI toolkit or framework indicates that the widget containing this map should be updated.
|
pure virtual |
|
pure virtual |
AnimationManager
attached to this map.Important notice regarding multi-threading:
IAnimation
will be invoked from the render thread. Because of this, animations are for example suitable to animate and update the map's camera.See the related article: Threading rules for the Map
|
pure virtual |
|
pure virtual |
Returns the background color of the map.
|
pure virtual |
Returns the camera that is currently used.
You can call this method on any thread.
See also setCamera
for more information.
Warning: this method will return the camera instance that was last used by the map renderer. This means that if you call setCamera
on a different thread than the render thread, a call to getCamera immediately after will not necessarily result in the same camera. See the threading article for a more detailed explanation.
|
pure virtual |
Returns the current active controller of the map.
No default behavior is
nullptr
if no controller has been set.
|
pure virtual |
Returns the current cursor of the map.
The default value is MouseCursor::defaultCursor
.
Map::setCursor
|
pure virtual |
Gets the display scale currently used to render the map.
setDisplayScale
has never been called
|
pure virtual |
Gets the DPI value used to calculate map scales.
|
pure virtual |
|
pure virtual |
GraphicsEffects
instance that can apply graphics effects on this map. Have a look at GraphicsEffects
for a list of effects that are available.
|
pure virtual |
Returns the FeatureStateManager that keeps track of the feature state (for example selection) for this map.
Apart from inspecting the feature state, you can use the returned object to change the feature state.
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
MapNavigator
instance that can manipulate the Camera
of this map
|
pure virtual |
Returns the reference of this Map.
This reference determines how the Map is visualized. When a projected (2D) reference is used, all data on the map is painted in this reference. When a (3D) geocentric reference is used, the Map is painted in 3D, and all data is pointed on the globe.
|
pure virtual |
|
pure virtual |
Returns a transformation that can transform view coordinates to map coordinates and vice-versa.
|
pure virtual |
|
pure virtual |
Returns whether this Map is visualized in 3D.
Currently, this will only be true if the map reference
is geocentric.
Having a 2D map limits the navigation, for example the camera can not be tilted and will always be top-down.
Currently, 3D maps always use a perspective camera
and 2D maps always use an orthographic camera
.
|
static |
|
pure virtual |
Queries the features under the given pixel bounds, and passes the result to the given callback.
All visible layers are taken into account. The features are sorted using the following criteria:
3D:
2D:
It is possible that the same feature appears multiple times in the result list, once for each part of the feature. When a feature is for example painted
using 2 draw calls, all 2 parts of the feature can be returned if they are hit. A typical example is a feature is painted using both a geometry on the map and a label. It is up to the caller of this method to filter out duplicate feature hits if needed.
query | the feature query containing the parameters to use to query the visible features |
callback | a callback which can handle the result of the query operation. Cannot be nullptr . |
NullArgumentException | when the call back is nullptr . |
|
pure virtual |
Removes the given callback from the Map.
After calling this method, the Map::Renderer::paint
will stop calling the given callback instance.
rendererCallback | a renderer callback instance. Cannot be nullptr . |
NullArgumentException | when the renderer call back is nullptr . |
|
pure virtual |
To be called when the host widget resizes, so that the map can adapt its camera, and graphics related resources.
width | The new map's width expressed in device independent pixels. |
height | The new map's height expressed in device independent pixels. |
|
pure virtual |
Sets the background color of the map.
color | the new background color. |
|
pure virtual |
Set the camera that is used by the renderer.
This method is only needed when you want to navigate in a different way than using MapNavigator
.
You can call this method on any thread, but its behavior is slightly different:
See the threading article for a more detailed explanation on the threading behavior.
camera | the new camera. Cannot be nullptr . |
NullArgumentException | when the camera is nullptr . |
|
pure virtual |
Activate a controller, so that it can interact with the map.
When a controller is set, the map will call luciad::IController::onActivate
to let the controller know it is activated. The previous controller if present will first receive a call to luciad::IController::onDeactivate
.
controller | The new active controller. If nullptr is given, that will only deactivate the previous one. Given that, no further interaction will be possible on the map until a controller is set again. |
|
pure virtual |
Change the map's cursor.
Changing the cursor triggers a call to the mouse cursor callback if set.
cursor | the new cursor. |
Map::setMouseCursorCallback
|
pure virtual |
Specifies the display scale to allow the renderer to scale the graphics on high DPI displays.
When a feature is scaled by the display scale, it means that pixel distances are scale. For example:
This method must be called every time the display or its display scale changes to ensure proper rendering.
You can call this method on any thread, but its behavior is slightly different:
See the threading article for a more detailed explanation on the threading behavior.
The default is 1.0;
displayScale | the display scale. A value of 1.0 corresponds with a display scale of 100%. |
|
pure virtual |
Sets the DPI value that will be used to calculate map scales.
By default, the map uses the default DPI of your platform (96 on Windows/Linux, 72 on MacOS, 160 on Android). The DPI value should be set to the physical DPI value of the display to get accurate results.
You can call this method on any thread, but its behavior is slightly different:
See the threading article for a more detailed explanation on the threading behavior.
dpi | the dpi value |
|
pure virtual |
Sets the given IInvalidationCallback.
This callback is called when the map has changed, and needs to be repainted. Can be nullptr
. The callback is owned by the calling code, i.e. typically code that integrates the Map in a UI framework. Beware that this callback should not call (directly or indirectly) the map (for example Map::paint) because it can be called on any thread.
mapInvalidationCallback | a callback that is called when the map has changed. |
|
pure virtual |
Sets the given IMouseCursorCallback.
This callback is called when the map's cursor has changed. Can be nullptr
. The callback is owned by the calling code, i.e. typically code that integrates the Map in a UI framework. Beware that this callback should not call (directly or indirectly) the map (for example Map::paint) because it can be called on any thread.
mouseCursorCallback | a callback that is called when the map has changed. |