concepts overview
Before you start, we highly recommend to take a look at the minimal application example.
Dependency graph of most important classes:
Map class is the foundation of the whole application. It keeps track of current mapconfig and maintains all resources.
Camera defines where on the planet is the viewer, in which direction is it looking and what loading method is used.
Based on the view, it instructs the map what resources should be downloaded.
It provides the application (or the rendering library) with commands to render.
You may have multiple cameras on one map - eg. for split screen views.
Use Map::createCamera to create a new one.
Navigation provides panning, zooming and rotation operations to the camera.
It is based on simple inputs such as relative mouse movement.
It is also capable of smooth and perceptually invariant fly overs to potentially distant points.
You may have at most one navigation per camera.
Use Camera::createNavigation to create a new one.
To create the Map, you have to pass MapCreateOptions structure, which contains immutable configuration for the map, such as client-id or disk cache options.
You may also pass custom content fetcher instance or nullptr to let the map create a default one. See fetcher for more details.
Next, you need to configure callbacks through which the Map provides the application with downloaded resources.
Lastly a call to Map::setMapconfigPath configures an url to a mapconfig and, optionally, an url to authentication token.
In the main loop, the map is kept updated by calling Map::dataUpdate and Map::renderUpdate.
The camera and its associated navigation, if any, are updated with Camera::renderUpdate.
The Map::dataUpdate will, in turn, call the load* callbacks, which are used to pass necessary resources to the application.
The Map::renderUpdate is used for some internal maintenance and cleaning.
The Camera::renderUpdate will renew the render commands for the application.
Finally, before the map can be destroyed, it is deinitialized by a call to Map::dataFinalize and Map::renderFinalize.
Note: All of the update and finalize methods are in pairs to allow for use of a secondary thread to maintain the data in a lag-free manner.