Language surfaces
MapCore is a C++ library with wrappers for C#, Java, and JavaScript/TypeScript. There is one API: the same interfaces, the same methods, in the same order, with the same semantics. What changes between surfaces is naming, how a method returns more than one value, and how errors arrive.
One qualification, because it is real and easy to be caught by: the C++ API is not quite identical
on Windows and Linux. IMcPrintMap — which IMcMapViewport inherits — gates eight methods behind
#ifdef _WIN32: SetPrintedPageSettings(), GetPrintedPageSettings(), SetPrinterSettings(),
GetPrinterSettings(), CalcPrintScreenPages(), PrintScreen(), CalcPrintRectPages2D() and
PrintRect2D(). These are the ones that drive a printer through a print dialog, so they do not
exist in a Linux build, and they are absent from the web surface too. The
render-to-raster equivalents — PrintScreenToRawRasterData(), PrintRect2DToRawRasterData() and
CancelAsyncPrint() — are available everywhere. Nothing else in the public C++ API differs by
platform.
That has a practical consequence worth stating up front: documentation and examples written for one language transfer to the others. When a page shows C++, the sequence of calls is the sequence you make in C#, Java or JavaScript/TypeScript — you only have to map the names. The Quickstart shows the same seven steps in all four.
JavaScript and TypeScript are one surface, not two. The wrapper is the Emscripten/WebAssembly
build; TypeScript adds the type declarations in MapCore.d.ts. Every TypeScript example in this
documentation is valid JavaScript once the annotations are removed.
Naming
| Concept | C++ | C# | Java | JS/TS |
|---|---|---|---|---|
| Interface | IMcMapViewport | IDNMcMapViewport | IMcMapViewport (interface) and McMapViewport (class) | IMcMapViewport |
| Struct | SMcVector3D | DNSMcVector3D | SMcVector3D | SMcVector3D |
| Enum | EMapType | DNEMapType | EMapType | EMapType |
| Method | SetCameraScale() | SetCameraScale() | SetCameraScale() | SetCameraScale() |
Method names never change. Only type names do, and only in C#:
- C# prefixes everything —
IDNMcfor interfaces,DNSfor structs,DNEfor enums. - Java keeps the native names, in the
com.elbit.mapcorepackage. It splits each interface in two: an interface and a class that implements it —IMcMapViewportandMcMapViewport. You declare variables as the interface and receive instances of the class. - JavaScript/TypeScript keeps the native names, inside a global
MapCorenamespace. Nested types live in a namespace named after their interface, soIMcMapCamera::EMapTypein C++ isMapCore.IMcMapCamera.EMapType.
Where the static factories live
Create() is a static, and each surface puts statics somewhere different. This is the detail most
likely to stop a first port from compiling:
| Surface | Creating a device |
|---|---|
| C++ | IMcMapDevice::Create(&pDevice, initParams) — out-parameter |
| C# | DNMcMapDevice.Create(initParams) — a separate DNMc* static class returns the IDNMc* interface |
| Java | IMcMapDevice.Static.Create(initParams) — statics sit in a nested Static class |
| JS/TS | MapCore.IMcMapDevice.Create(initParams) — a namespace function |
So in C# the interface you hold (IDNMcMapDevice) and the class you call Create() on
(DNMcMapDevice) are two different names, and in Java the statics are one level deeper than the
instance methods.
The C# enum-member trap
C# enum members gain a leading underscore, because the native names are not valid where C# wants to put them:
C++: EMcLineStyle::ELS_SOLID
C#: DNELineStyle._ELS_SOLID
This catches everyone once. The type is renamed by prefix, the member by underscore.
Struct field names are not guaranteed identical
Mostly they are, but not always. In the viewport's creation parameters the coordinate-system field
is pCoordinateSystem in C++, Java and JS/TS — and CoordinateSystem, with no prefix, in C#.
When a field assignment does not compile, check the name before assuming the field is missing.
The C# enum-member trap
C# enum members gain a leading underscore, because the native names are not valid where C# wants to put them:
C++: EMcLineStyle::ELS_SOLID
C#: DNELineStyle._ELS_SOLID
This catches everyone once. The type is renamed by prefix, the member by underscore.
Errors: returned in C++, thrown everywhere else
This is the single largest difference between the surfaces, and the one that most changes how code is shaped.
C++ returns an error code. Every method returns IMcErrors::ECode, and you check it:
float fScale = 0;
IMcErrors::ECode res = pViewport->GetCameraScale(&fScale);
if (res != IMcErrors::SUCCESS)
return res;
All three wrappers throw instead. C# and Java throw MapCoreException; the web surface throws
too. A wrapper method's return type is therefore the result, not a status — which is why
DNMcMapDevice.Create() hands back the device directly where C++ writes it to an out-parameter.
Structure wrapper code with try/catch around a block of calls rather than checking each one:
try
{
IDNMcMapDevice device = DNMcMapDevice.Create(initParams);
IDNMcMapTerrain terrain = DNMcMapTerrain.Create(coordSys, layers);
}
catch (MapCoreException ex)
{
// ex carries the underlying MapCore error
}
Porting C++ examples to a wrapper therefore means deleting the error checks, not translating them.
A void return in a wrapper signature is not a method that cannot fail — it is a method whose
failure arrives as an exception.
Returning more than one value
C++ writes extra results through pointer parameters. Each wrapper needs its own equivalent:
| Surface | How |
|---|---|
| C++ | Pointer out-parameters: GetCameraScale(&fScale) |
| C# | out and ref parameters; DNMcNullableOut<T> for the optional ones; getter/setter pairs become properties — terrain.BoundingBox, not GetBoundingBox() |
| Java | ObjectRef<T> holder objects |
| JS/TS | A single output is returned; additional outputs use an object whose .Value field receives the result |
The JS/TS rule is worth stating precisely, because both halves of it surprise people. Since errors are exceptions, the return value is free — so a method with one output simply returns it:
const scale = viewport.GetCameraScale(); // number
const position = viewport.GetCameraPosition(); // SMcVector3D
const box = terrain.GetBoundingBox(); // SMcBox
When that one output is a list — a CMcDataArray in C++ — it is returned as a plain JavaScript
array:
const cameras = viewport.GetCameras(); // IMcMapCamera[]
const layers = terrain.GetLayers(); // IMcMapLayer[]
Only when there is more than one output do the .Value objects appear:
- TypeScript
- JavaScript
const yaw: any = {}, pitch: any = {}, roll: any = {};
viewport.GetCameraOrientation(yaw, pitch, roll);
// yaw.Value, pitch.Value, roll.Value
const yaw = {}, pitch = {}, roll = {};
viewport.GetCameraOrientation(yaw, pitch, roll);
// yaw.Value, pitch.Value, roll.Value
Those parameters are typed any in MapCore.d.ts, with the real type of .Value documented in
the JSDoc above each method. A list output arrives in one of two ways, which the method's declaration
tells: in .Value, as a JavaScript array or a typed array such as Uint32Array, or in an array you pass,
which the call fills in place — GetLayerDataSources() does both, filling the names array you pass and
setting the IDs as a Uint32Array in .Value. Optional parameters use TypeScript's ?, so you can omit them.
Memory
C++ callers manage lifetime explicitly: reference counts, and the zero-initial-count rule for devices, terrains, layers and spatial-queries objects. See Threading and lifecycle — those rules are the authority, and the wrappers implement them rather than replacing them.
What each surface actually asks of you differs more than the shared IMcBase suggests:
| Surface | Taking a reference | Dropping one |
|---|---|---|
| C++ | AddRef() | Release() |
| JavaScript / TypeScript | AddRef(), as in C++ | Release() |
| Java | not available — no AddRef() in the surface at all | Release() |
| C# | not needed | Dispose() |
The two managed wrappers take the reference themselves, when they create the managed object that
wraps the MapCore one — which is why Java has no AddRef() to call and does not miss it: holding
the managed object is holding the MapCore object. The zero-initial-count rule is therefore
invisible from C# and Java, and unavoidable from C++ and the web. Release() and Dispose() drop
that reference early rather than waiting for finalization.
What does not vary is the ownership structure: a terrain still owns its layers, a viewport still owns its cameras and terrains, and objects still become invalid when their last owner releases them. A garbage collector decides when your reference is dropped, not whether the ownership graph holds.
The practical rule is the same in every language: release or dispose in the reverse order of creation, and do not hold a reference to something whose owner you have released.
C# and Java: the bridge needs driving
Both managed bridges — between MapCore's reference counts and the runtime's collector — need
driving, and both expose the same pair of static calls: DNMcGarbageCollector in C#,
McGarbageCollector in Java.
Collect()releases the native objects behind managed objects the runtime has already collected. It should be called frequently; the documented place is immediately before eachRender().DisposeAll()must be the last MapCore call on the thread that used MapCore — for a desktop application, the last line ofProgram.Main(). It disposes what remains while the correct thread is still alive. Without it, finalizers run on the runtime's own threads and dispose MapCore objects from a thread that is not MapCore's main thread. Nothing calls it for you, in either language.
Collect() is the one that varies, because some wrappers call it for you inside Render(): the
legacy C++/CLI wrapper (DNMapCoreWrapper) and the JNI wrapper both do, and the current P/Invoke
wrapper (DNPIMapCoreWrapper) does not. So a C# application on the current wrapper is the one
that has to call it per frame.
Neither call has an equivalent on the C++ or web surfaces, where lifetime is explicit anyway.
What each surface is for
| Surface | Runs on | Typical use |
|---|---|---|
| C++ | Windows, Linux, Android | Desktop applications, servers, batch tools, native Android code; the full API |
| C# | Windows | WPF and WinForms applications |
| Java | Android | Android applications |
| JavaScript / TypeScript | Browsers, Node.js | Web applications, via WebAssembly |
Divergences to expect
The wrappers mirror the C++ API, but not every part of it is exposed everywhere, and a few things exist only on one surface:
- Platform-specific API is only on platforms that have it. The Direct3D rendering systems are
Windows-only.
SetWebWorkersHeapLimits()and the virtual file-system methods are on the JavaScript/TypeScript surface only, because nothing else has web workers or a virtual file system. - The same method can take different arguments per platform.
ViewportResized()is the one to know: on Android you must pass the new width and height, because MapCore cannot obtain them from the window; on every other platform both arguments must be left at their defaults, and passing a size returnsIMcErrors::INVALID_PARAMETERS. - Initialization is asynchronous on the web and nowhere else.
McStartMapCore()returns a promise, and theMapCorenamespace does not exist until it resolves. Every other surface can call MapCore on the line after the import. - A wrapper can lag a C++ addition. Every wrapper is updated in the same change as the C++ API it exposes, but if a method you can see in the headers is missing from your surface, that is the explanation — the generated reference for your language is the authority on what is available, not the C++ headers.
- Callbacks are idiomatic per language. The same events arrive, delivered the way that language delivers events.
When a surface genuinely behaves differently rather than just looking different, the release notes record it against the release that changed it.