Skip to main content

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:

KindWhat it isHow many
Device (IMcMapDevice)The engine instance and its GPU back-endOne, normally for the whole process
Viewport (IMcMapViewport)One rendered view, with its camerasAs many as you need
Terrain (IMcMapTerrain)A coordinate system plus a set of map layersShareable between viewports
Layer (IMcMapLayer)One source of map dataMany per terrain, shareable between terrains
Overlay (IMcOverlayManager)Your own graphics, drawn above the mapIndependent 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 (NULL takes 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.

note

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 of EPendingUpdateType, defaulting to EPUT_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.

Verified against MapCore 12.5.0

Written from Map/IMcMapDevice.h, Map/IMcMapViewport.h, Map/IMcMapTerrain.h, Map/IMcMapLayer.h