Architecture
MapCore is an engine you embed in your own application, not a framework your application lives inside. You create it, you own the objects you put into it, and you decide when each frame is drawn. Everything else follows from that.
There are five kinds of object, and they nest:
| Kind | What it is | How many |
|---|---|---|
Device (IMcMapDevice) | The engine instance and its GPU back-end | One, normally for the whole process |
Viewport (IMcMapViewport) | One rendered view, with its cameras | As many as you need |
Terrain (IMcMapTerrain) | A coordinate system plus a set of map layers | Shareable between viewports |
Layer (IMcMapLayer) | One source of map data | Many per terrain, shareable between terrains |
Overlay (IMcOverlayManager) | Your own graphics, drawn above the map | Independent of the terrain |
The device is the root: nothing else can be created before it exists, and releasing the last one shuts the engine down. Terrains and layers are the data side; viewports and cameras are the view side. The two meet when you add a terrain to a viewport, which is why the same terrain can appear in several views at once without being loaded twice.
The map device
Interface for a rendering device (video adapter) used to create map viewports.
A device represents an instance of the MapCore engine, normally together with the rendering system (GPU back-end) that map viewports (see IMcMapViewport) and GPU-based spatial queries run on. A device created with ERS_NONE has no rendering system: viewports cannot be created and GPU-based queries cannot run, but other queries and calculations can. Almost all members are static factory or utility functions; the device pointer itself is an opaque, reference-counted handle (see IMcBase), and one device normally serves the whole process.
Used for:
- Starting and stopping the engine: Create() once at start-up, IMcBase::AddRef() to own the device, and IMcBase::Release() when it is no longer needed; releasing the last device tears the engine down.
- Keeping it running: PerformPendingCalculations() on the main thread, and AddLostDeviceCallback() / RemoveLostDeviceCallback() to be told through ILostDeviceCallback when the GPU device is lost and restored.
- Resources shared by all viewports: LoadResourceGroup() / UnloadResourceGroup().
- Discovering what a web server offers before creating layers: GetWebServerLayers() and Get3DModelSmartRealityData().
- Administering the map layers local cache: RemoveMapLayersLocalCache(), RemoveMapLayerFromLocalCache(), SetMapLayersLocalCacheSize() and GetMapLayersLocalCacheParams().
- Diagnostics: GetVersion(), GetGpuInfo() and the logging level in SInitParams.
- JavaScript API only: heap sizing and web-worker limits, fetching optional components, and the virtual file system (GetMemorySize() through DoesFileSystemPathExist()).
The engine is configured by the SInitParams passed to the first Create(); those passed with later devices are ignored. Its fields select the rendering system and window mode, trade visual quality for performance and memory (anti-aliasing, terrain-object quality, visibility-query precision, DTM precision, render targets, raster mipmaps), tune object batching and texture atlases, set the number of background loading threads, the logging level, the configuration, log and device-caps directories and the resource-path prefix, enable the map layers local cache, and bound web requests. Every field has a default, so a default-constructed SInitParams is a valid start.
Threads: the thread that creates the first device becomes MapCore's main (render) thread; creating a viewport re-binds the main thread to the creating thread, so it is effectively the thread that created the last viewport. PerformPendingCalculations() must be called regularly on that thread, so that GPU work redirected from worker threads completes and asynchronous results (e.g. of GetWebServerLayers()) are delivered to their callbacks.
See also: IMcMapViewport::Create(), IMcMapTerrain::Create(), IMcSpatialQueries::Create()
— from Map/IMcMapDevice.h
The thread rules in that description are the ones most likely to bite, and Threading and lifecycle covers them in full.
Viewports
A viewport is one rendered view of the world. It owns its cameras, holds the terrains you have added to it, and decides which layers and overlays are visible in it — two viewports can show the same terrain with different layers switched on, different image processing, and cameras pointing in different directions.
Several viewports can share a single window. SetRelativePositionInWindow() places them and
Render() draws them together, in Z-order, with one buffer swap for the window.
IMcMapViewport is more than the view itself. It inherits five interfaces, which is why querying
the terrain, printing, image processing and the overview-inset role are all methods on a viewport
rather than separate objects you create: IMcMapCamera, IMcSpatialQueries, IMcImageProcessing,
IMcPrintMap and IMcGlobalMap. The camera is the one with a twist — the viewport forwards every
camera method to whichever camera is currently active, so for the common single-camera case you can
ignore cameras entirely and drive the viewport directly.
Rendering and cameras covers the camera model, the two specialized
viewport types (IMcHeatMapViewport and IMcSectionMapViewport) and the global-map role.
All viewport geometry is in the world coordinate system, with separate screen and window pixel frames — see Coordinate systems.
Terrains and layers
Interface for a terrain: a set of map layers of different kinds, shown by viewports and queried by spatial queries.
A terrain is the unit of map content shown by a viewport (see IMcMapViewport::Create() and IMcMapViewport::AddTerrain()) or queried by a standalone spatial-queries interface (see IMcSpatialQueries::Create()). It holds a reference to its coordinate system and to each of its layers: a layer can belong to several terrains, and a terrain can be used by several viewports. A terrain is created by Create() from existing layers (or by Load() from a saved definition) and released with IMcBase::Release(). A map device must have been created (see IMcMapDevice::Create()) before any terrain or layer is created.
Used for:
- Creation: Create() from an array of layers and an optional coordinate system (
NULLtakes it from the first layer that has one). - Terrain parameters: SetCoordinateSystem() and GetCoordinateSystem(); GetBoundingBox() (the union of the loaded layers' boxes); SetVisibility() and GetVisibility(), in all viewports or in one of them.
- Terrain ID and user data: SetID() and GetID() (the ID looks the terrain up in IMcMapViewport::GetTerrainByID()); SetUserData() and GetUserData(); GetDisplayItemsAttachedTo3DModelWithoutDtm().
- Layers: AddLayer() and RemoveLayer(); the per-terrain display parameters of a layer (scale range, draw priority, transparency, visibility) with SetLayerParams() and GetLayerParams() (see SLayerParams); GetLayers(), GetLayerByID() (by the ID set with IMcMapLayer::SetID()) and GetDtmLayer().
- Saving and loading: Save() writes the terrain definition (its layers and their parameters, not the map data) to a file or a memory buffer, and Load() creates a terrain from it; the user data is saved only when bSaveUserData is
true.
A terrain has at most one DTM layer, and all its layers must share its coordinate system and tiling scheme (see AddLayer() for the complete list of rules). Layers not yet initialized (see IMcMapLayer::IsInitialized()) are members of the terrain nevertheless: GetLayers() and GetDtmLayer() return them, SetLayerParams() accepts them, and GetBoundingBox() returns IMcErrors::NOT_INITIALIZED (with the box of the already initialized layers) until all of them are initialized.
See also: IMcMapLayer, IMcMapViewport::AddTerrain(), IMcSpatialQueries::Create()
— from Map/IMcMapTerrain.h
A terrain is the unit you hand to a viewport, and a layer is the unit that actually reads data.
The main layer kinds are the six that IMcMapLayer::ELayerKind enumerates: elevation, raster,
vector, heat map, static objects, and code maps (material and traversability). 3D models and
extruded buildings are variants within the static-objects kind rather than kinds of their own. A
terrain normally combines several: elevation to give the ground its shape, raster to give it a
surface, vector and object layers on top.
Layers and terrain covers the layer kinds, the ownership rules and the asynchronous loading contract.
Overlays
Overlays are where your application's own graphics go: tracks, symbols, annotations, routes,
anything you draw rather than load. They live in an overlay manager, independent of any terrain,
and are made visible per viewport with SetOverlaysVisibilityOption() and reported by
GetVisibleOverlays().
An overlay manager has its own world coordinate system, which need not be the viewport's.
ViewportToOverlayManagerWorld() and OverlayManagerToViewportWorld() convert between them —
relevant whenever you place an overlay item at a position you obtained from the map, or the
reverse.
The overlay model itself — items, objects, schemes, collections and conditional selectors — is a large API whose documentation is being written as part of an in-progress API review, and is not included in this release of the documentation.
How a frame is drawn
Nothing renders unless you ask it to. There is no internal timer and no hidden render thread: your application owns the loop.
A frame is Render(). Call it on one viewport, or use the static
Render(apViewports, uNumViewports) for a specific list, or RenderAll() for every viewport that
exists. Viewports sharing a window must be drawn in the same call to get a single buffer swap.
Between frames, two calls matter:
HasPendingUpdates()answers whether anything has changed that a redraw would show — new terrain tiles arriving, objects moving, the camera having been moved. Applications that redraw only when needed rather than continuously use this as the trigger. It takes a bit field ofEPendingUpdateType, defaulting toEPUT_ANY_UPDATE; note that window-resize and viewport-change updates are reported for any requested type, not only for a matching one.IMcMapDevice::PerformPendingCalculations()is the only thing that executes GPU-based calculations that were issued from other threads and redirected to the main thread.Render()handles communication and dispatches asynchronous results as well, so in an application that renders continuously and issues no GPU calculations off-thread you may never need it — but if either of those is untrue, it has to be called regularly on the main thread or that work never finishes. Threading and lifecycle has the specifics.
PerformPendingUpdates() looks like it belongs in that list and does not. It performs pending
updates without rendering, handles only EPUT_TERRAIN and EPUT_OBJECTS whatever else you pass,
can be slow, and is meant for application or scene start-up — bringing terrain in before the first
frame rather than letting the user watch it stream in. It is not part of a steady-state loop.
Rendering can fail for one reason worth handling: Render() returns
IMcErrors::RENDERING_DEVICE_LOST when the GPU device has been lost, which on DirectX happens
when a full-screen application loses keyboard focus or the machine is locked. Register an
IMcMapDevice::ILostDeviceCallback to be told: OnDeviceLost() warns you that user-created
memory-buffer textures with dynamic or render-target usage have been discarded, and
OnDeviceRestored() tells you MapCore has recreated them — empty, with new underlying pointers,
so their contents must be filled again.