Remarks

A Carmenta Engine MapControl is used to integrate a map view into the UI of an application. Carmenta Engine provides several different MapControl classes, for different API:s and UI platforms.

All MapControl classes

Using the C++ MapControl base class

This MapControl is the abstract base class of all other C++ map control classes. It cannot be used by itself, an application needs to subclass it to intregrate it with whatever UI framework it is using, or use one of the provided subclasses.

A subclass must override the GetWindow (not available in C#) method and return the WindowHandle of the window the control should draw into. The application or subclass must also "feed" the control with events/messages received from the UI system, typically by just passing all Windows messages to the control.

Examples of how this can be subclassed can be found in Sample application using C++ and Windows API (Win32) and Sample application using C++ and Microsoft Foundation Class Library.

Even though the class has limited functionality, it still serves an important purpose: it makes it possible to use built-in tools like StandardTool, or to write new tools which can be reused in other applications, using other UI frameworks. See the ITool interface for more information about writing tools.

Using the Qt Widget MapControl

The C++ API provides the class QtMapControl which is a MapControl implementation for use in a Qt Widgets application. It must be included explicitly (it is not included through the Core.hpp header file). You must also add the QtMapControl.hpp header file to your project to make the Qt tools extract the necessary metadata and include in the build,otherwise you will see some unresolved symbols when you link your application.

#include <Carmenta/Engine/Controls/QtMapControl.hpp>

For more information on how to use it see Sample application using C++ and the Qt class library.

Using the Qt Quick MapControl

The C++ API also provides the class QtQuickMapControl which is a MapControl implementation for use in a Qt Quick application. It must be included explicitly (it is not included through the Core.hpp header file). You must also add the QtQuickMapControl.hpp header file to your project to make the Qt tools extract the necessary metadata and include in the build, otherwise you will see some unresolved symbols when you link your application.

#include <Carmenta/Engine/Controls/QtQuickMapControl.hpp>

For more information on how to use it see Sample application using C++ and QtQuick.

Using the X11 MapControl

For use on Linux the C++ API also provides the class X11MapControl which is a MapControl implementation using X11. Like the QtMapControl it must also be included explicitly:

#include <Carmenta/Engine/Controls/X11MapControl.hpp>

For an example on how it can be used see Sample application using C++ and low-level X11 calls.

Using the Windows Forms MapControl

The Windows Forms MapControl inherits from System.Windows.Forms.UserControl, see Microsoft Developer Network article for more information.

Limitations

The 64-bit version of the MapControl cannot be loaded and used in the Visual Studio designer, in Visual Studio 2019 and earlier, because Visual Studio runs as a 32-bit process. As an alternative, you can instantiate and initialize a MapControl at runtime instead, for example when the form that should contain the MapControl is being initialized. The Basic Map Application Tutorial shows how this can be done in a Windows Forms application.

Using the WPF MapControl

The WPF (Windows Presentation Foundation) MapControl inherits from System.Windows.Controls.Control, see Microsoft Developer Network article for more information.

This control works almost exactly like the Windows Forms MapControl, except it can only use a DirectX renderer, which is hardware accelerated, or a Software renderer. It will automatically replace the renderer of a connected view according to the following table:

Remote Desktop

The WPF MapControl works over Remote Desktop connections and the remote machine will render frames into a memory buffer using hardware acceleration, including for example a 3D GlobeView. Each frame that is rendered is copied into a WPF element (this happens internally in the WPF MapControl class) to be composed with the rest of the application GUI but since the WPF MapControl must make an extra copy of each frame when it runs remotely it will always be slower than a non-WPF application rendering the same map with OpenGL or DirectX over the same Remote Desktop connection.

Limitations

The 64-bit version of the MapControl cannot be loaded and used in the Visual Studio designer, in Visual Studio 2019 and earlier, because it runs as a 32-bit process. As an alternative, you can instantiate and initialize a MapControl at runtime instead, for example when the form that should contain the MapControl is being initialized.

Using the Maui MapControl

This control is used to integrate Carmenta Engine with a NET MAUI application. It inherits from Microsoft.Maui.Controls.View.

On Windows this control can only use a DirectX renderer, which is hardware accelerated, or a Software renderer. It will automatically replace the renderer of a connected view according to the following table:

Limitations

On Windows the Carmenta Engine MAUI MapControl will render frames into a memory buffer using hardware acceleration, including for example a 3D GlobeView. Each frame that is rendered is copied into a MAUI element (this happens internally in the MAUI MapControl class) to be composed with the rest of the application GUI but since the MAUI MapControl must make an extra copy of each frame when it runs it will always be slower than a non-MAUI application rendering the same map with OpenGL or DirectX on the same computer.

Using the Android .NET MapControl

This class is the Android/.NET version of the MapControl class. It inherits from Android.Views.SurfaceView, see SurfaceView reference documentation for more information.

It can be used like any other Android widget class. The MapControl can be added directly in a .AXML file for native Android GUI.

Using the Java AWT MapControl

The Windows and Linux version of the Java MapControl extends java.awt.Canvas, see the Java AWT Canvas documentation for more information.

The MapControl class can used like any other AWT control. It can also be used together with light-weight Swing components.

Using the Android Java MapControl

This class is a replacement for the MapControl class found in the Java API on Windows and Linux, modified to work on Android devices. Instead of inheriting from java.awt.Canvas, this class inherits from the android.view.SurfaceView class, see SurfaceView reference documentation for more information. It can be used like any other Android view class.