LuciadCPillar provides a
Map as the central component for visualizing geospatial data.
You can’t show the Map on screen instantly: you need to make a graphics environment available first. The graphics environment
is provided by a UI framework of your choice.
Because different UI frameworks have different threading models, the Map enforces some rules to help make sure that things
happen on the right thread.
Many UI frameworks are entirely single-threaded: interacting with graphical components and rendering them happen on the same thread. If your framework falls into this category, all interaction with the Map and its renderer must happen on that thread.
Some frameworks, however, separate component interaction from component rendering. An example is Qt Quick with the threaded render loop enabled. In these frameworks, it’s important to do things on the appropriate thread.
When component interaction and component rendering happen on distinct threads, we use these designations:
- UI thread
The thread you use to interact with the GUI components, handling input events, or modifying component state, for example.
- Render thread
The thread that renders GUI components: it reads or copies the state from the component when it’s safe to do so. The actual rendering happens in parallel with input event handling.
For frameworks that don’t make this distinction, both names refer to the single thread used by the framework.
The API offers guidance about the thread expected for the interaction of your code with
To get the renderer from a Map, use
You must call this function, and any of the renderer’s functions, on the render thread.
It’s impossible to explicitly communicate which threads are the UI and render threads, so the Map implicitly detects them.
It assumes that the thread on which the Map object is created is the UI thread, and that the thread with the first call to
getRenderer is the render thread.
Any later function calls verify that they’re happening on the expected thread.
Most functions on the Map are synchronous. The effect or result is produced immediately in the current thread. You can call all these functions safely even if there is no renderer yet. This makes it easy to set up the Map as required, its size and layers for example, without having to worry about threads yet.
Some functions on Map are asynchronous. These functions compute their result on a different thread, the render thread typically. Then, they provide that result through a callback passed to the function. The callback is always invoked on the UI thread, so that you can use the result to update the application state.
For this to work, you must first invoke the renderer on the render thread, so that the necessary computations can be performed. Then, you must invoke the Map on the UI thread, so that any callbacks can be called with the result. Usually, this just means that the UI framework’s event loop needs to do its job.