Threading and lifecycle
Two questions account for most of the surprises in a first MapCore integration: which thread am I allowed to call this from, and who releases this object. Neither has a complicated answer, but both have answers that differ from the obvious guess.
Start-up and shutdown
IMcMapDevice::Create() initializes the engine and hands back a device. Everything else —
terrains, layers, viewports, queries — requires one to exist first.
IMcBase::Release() on the device is the shutdown. Releasing the last device tears the engine
down, so this is not a call to make speculatively at the end of a subsystem's life; it ends
MapCore for the process.
A device created with ERS_NONE as its rendering system has no rendering system at all. It cannot
create viewports and cannot perform GPU-based queries, but non-GPU queries and calculations work
normally. This is the configuration for a server or a batch tool that needs MapCore's geometry and
data handling without a display.
Thread affinity
On the web every MapCore call you make runs on the one JavaScript thread (see Web and web workers), so the rules about which thread may call what apply to the desktop and Android builds only. Dispatching asynchronous results applies everywhere, the web included — see PerformPendingCalculations, precisely.
MapCore has a main thread, and it is not necessarily the one you would expect:
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 the main thread is effectively the thread that created the last viewport. If your application creates its device during start-up on one thread and later creates a viewport on another, the main thread has moved. The practical advice is to create the device and all viewports on the same thread, deliberately, and then leave it alone.
What must happen on that thread:
IMcMapViewport::Render()and the other rendering entry points.IMcMapDevice::PerformPendingCalculations(). Called from any other thread it does nothing in multi-threaded builds, and the header documentsIMcErrors::INVALID_PARAMETERSas the result of calling it off-thread — either way, the work does not get done.
Two creation-time choices that set the threading
Both are fields of IMcMapDevice::SInitParams, the parameter block the header describes so:
MapCore rendering and spatial queries engine initialization parameters; considered only when creating the first device.
— from Map/IMcMapDevice.h
uNumBackgroundThreads— how many background threads load map layers. The default,UINT_MAX, means the number of hardware thread contexts minus one;0loads layers on the main thread instead. Layer loading is the work that leaves the main thread by default, so a host that cannot tolerate MapCore working off its own thread passes0and accepts that loading then competes with rendering.bMultiThreadedDevice— whether the rendering device is initialised multi-threaded. It must betruein WPF mode, and in any case where a texture MapCore returns is used from a thread other than the main one; otherwisefalseis recommended, for performance. Decide it up front: the parameters are read only for the first device.
PerformPendingCalculations, precisely
This one is worth being exact about, because both over- and under-calling it cause problems.
It does three things: it executes GPU-based calculations that were issued from other threads and
redirected to the main thread, it performs communication-related work, and it dispatches
asynchronous results — for example those from IMcMapDevice::GetWebServerLayers() — to their
callbacks.
Render() also performs the communication and asynchronous-results processing. The redirected
GPU-based calculations are executed only here. That gives a clear rule:
| Your application | What it needs |
|---|---|
| Renders every frame, issues no GPU calculations off-thread | Render() alone is enough |
| Issues GPU-based calculations from worker threads | PerformPendingCalculations() regularly, on the main thread |
Renders only when HasPendingUpdates() says so | PerformPendingCalculations() regularly, or asynchronous results stall while nothing is being drawn |
The timeout parameter bounds how long one call may spend, in milliseconds; at least one
calculation is always performed, and the default of 0 means exactly one. The optional output
flag tells you whether calculations remain, so you can decide whether to come back sooner.
Who owns what
MapCore objects are reference-counted through IMcBase, but the initial count is the part that
catches people out. The header states the rules every interface follows:
Base interface of MapCore's reference-counted interfaces: an instance is destroyed when its last reference is released (a map layer, or a resource such as a texture, that MapCore still uses internally is destroyed once MapCore stops using it).
Nothing MapCore retrieves comes with a reference for the caller: not an instance a function creates (Create(), Clone(), Load()...), one a getter or a C++ cast such as IMcObjectSchemeNode::CastToLineItem() retrieves, or a callback's argument. So you must hold a reference of your own to every instance you keep a pointer to, including one you create: call AddRef() when you get the pointer, and Release() when you no longer use it. MapCore holds its own references the same way: an interface that holds another, such as a terrain its layers, a viewport its terrains or an item its texture, keeps it alive while it holds it.
The exception is an instance created inside its container, which holds its only reference: overlays, objects, collections and animation states, which leave their container by their Remove(); object locations, removed by IMcObjectScheme::RemoveObjectLocation(); cameras, destroyed by IMcMapViewport::DestroyCamera(); and map environments, which go with their viewport. Never call AddRef() or Release() on them; a pointer to one is valid until it leaves its container or the container is destroyed.
— from IMcBase.h
Those are the rules in C++ and on the web. In C# and Java the wrappers take the reference
themselves when they create the managed object, so holding the managed object already owns it: you
call no AddRef() (Java has none), and you release by disposing the object or calling Release()
— see Language surfaces.
A terrain adds a reference to its coordinate system and to each of its layers, which is what makes sharing safe: the same layer in three terrains, or the same terrain in three viewports, stays alive as long as any of them holds it.
A device and a standalone IMcSpatialQueries object are always stored, so AddRef() each after
creating it. Release the device last, after every other MapCore object you own.
Cameras are among the instances a container holds. The viewport's initial camera comes from
IMcMapViewport::Create() and further ones from CreateCamera(); the active camera cannot be
destroyed, so activate another one first.
Asynchronous work
Creating a layer does not mean the layer is ready. Loading continues in the background, and
IsInitialized() reports whether it has finished. To be told rather than to poll, supply an
IMcMapLayer::IReadCallback:
| Callback | Meaning |
|---|---|
OnInitialized() | Loading finished. Check the status argument — this fires on failure too, and the layer pointer can be NULL if the failure happened during creation |
OnReadError() | A read or communication error occurred |
OnRemoved() | RemoveLayerAsync() has removed the layer from all its terrains, just before it is deleted |
OnReplaced() | ReplaceNativeServerLayerAsync() has swapped the layer for a new one everywhere |
Every one of these carries an additional data string naming what actually went wrong — the file that could not be read, the request that failed. It is the first thing to log.
The asymmetry to remember: layer removal is asynchronous too. RemoveLayerAsync() returns
before the layer is gone, and OnRemoved() is your signal that it is safe to consider the layer
finished with. It can also refuse up front — a terrain's elevation layer cannot be removed while a
3D-model layer depends on it (IMcErrors::DTM_LAYER_CANT_BE_REMOVED), so check the synchronous
return before waiting for a callback that will never arrive.
Removing a layer can take a terrain out of your viewports. Any terrain left empty by the removal is itself removed from all its viewports. So dropping the last layer of a terrain does not leave you with a blank terrain still mounted — it silently unmounts the terrain everywhere it was shown. If you intend to swap the only layer, add the replacement before removing the original.
Web and web workers
The web build uses no Emscripten pthreads and no shared memory, so everything you call runs on the
one JavaScript thread. In a browser, the work other platforms move to background threads runs
concurrently in web workers instead — each with a heap of its own and no memory shared with the
page, which is why heap accounting becomes visible in the API.
IMcMapDevice::SetWebWorkersHeapLimits() bounds those heaps: a per-worker maximum (default
200 MB, and it should be above 50 MB) and a total across the main thread and all workers (default
10 GB for Wasm64, 6 GB for Wasm32). Under Node.js MapCore creates no workers: the background work
runs on the same thread, and the per-worker limit has nothing to bound. To stay inside those
limits MapCore deletes workers with large heaps, recreating them later with a minimal heap if they
are needed again — so a tight total limit trades memory for the cost of that churn.
GetHeapSize() reports the current heap and takes a flag to include the workers;
GetMaxMemoryUsage() and GetMemorySize() complete the picture. These are the numbers to watch
when a web application grows slowly unresponsive rather than failing outright.