Skip to main content

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​

ConceptC++C#JavaJS/TS
InterfaceIMcMapViewportIDNMcMapViewportIMcMapViewport (interface) and McMapViewport (class)IMcMapViewport
StructSMcVector3DDNSMcVector3DSMcVector3DSMcVector3D
EnumEMapTypeDNEMapTypeEMapTypeEMapType
MethodSetCameraScale()SetCameraScale()SetCameraScale()SetCameraScale()

Method names never change. Only type names do, and only in C#:

  • C# prefixes everything — IDNMc for interfaces, DNS for structs, DNE for enums.
  • Java keeps the native names, in the com.elbit.mapcore package. It splits each interface in two: an interface and a class that implements it — IMcMapViewport and McMapViewport. You declare variables as the interface and receive instances of the class.
  • JavaScript/TypeScript keeps the native names, inside a global MapCore namespace. Nested types live in a namespace named after their interface, so IMcMapCamera::EMapType in C++ is MapCore.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:

SurfaceCreating a device
C++IMcMapDevice::Create(&pDevice, initParams) — out-parameter
C#DNMcMapDevice.Create(initParams) — a separate DNMc* static class returns the IDNMc* interface
JavaIMcMapDevice.Static.Create(initParams) — statics sit in a nested Static class
JS/TSMapCore.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:

SurfaceHow
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()
JavaObjectRef<T> holder objects
JS/TSA 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:

const yaw: any = {}, pitch: any = {}, roll: any = {};
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:

SurfaceTaking a referenceDropping one
C++AddRef()Release()
JavaScript / TypeScriptAddRef(), as in C++Release()
Javanot available — no AddRef() in the surface at allRelease()
C#not neededDispose()

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 each Render().
  • DisposeAll() must be the last MapCore call on the thread that used MapCore — for a desktop application, the last line of Program.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​

SurfaceRuns onTypical use
C++Windows, Linux, AndroidDesktop applications, servers, batch tools, native Android code; the full API
C#WindowsWPF and WinForms applications
JavaAndroidAndroid applications
JavaScript / TypeScriptBrowsers, Node.jsWeb 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 returns IMcErrors::INVALID_PARAMETERS.
  • Initialization is asynchronous on the web and nowhere else. McStartMapCore() returns a promise, and the MapCore namespace 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.

Verified against MapCore 12.5.0

Written from MapCore/Emscripten/Wasm/MapCore.d.ts, Map/IMcMapViewport.h, Map/IMcMapDevice.h, Map/IMcPrintMap.h