Skip to main content
Version: 14 May 2024

Running Your App (C-API)

Running Your App (C-API)​

This section walks through environment setup and building and running C-API apps on the Application Simulator.

C/C++ Apps​

Overview​

The Application Simulator supports running programs on hosts which use the Magic Leap C SDK.

Magic Leap 2 (ML2) is built on Android (where standalone native graphical applications are not supported), this section assumes your goal is to start from an Android-style project which builds for device and adapt it for usage with the Application Simulator.

A key point is that Application Simulator only covers the C/C++ side of such projects; it does not support Java APIs. Thus, Android projects suitable for the Application Simulator should be native activities which invoke C/C++ logic in a shared library through the help of native_app_glue (see Android's Native Activity documentation for more information).

The Application Simulator can load a host build of this native library and invoke its android_main entry point. Any callbacks to JNI code either need to be stubbed out or replaced with the Application Simulator C APIs.

note

The permissions system in ml_zi_permissions.h should be used to make permission requests under the Application Simulator instead of their JNI equivalents on device.

Graphics Compatibility for C-API Apps​

The following graphics APIs are compatible with the Magic Leap Application Simulator. You can use these with your Native/C++ applications.

OpenGLVulkanMetal
Windows 10/11✓✓
macOS (Intel)✓
macOS (M1)✓

Application Simulator Environment Setup​

Some of your environment variables have to be set in order to run your application with Application Simulator.

All of these steps may be performed by starting a command line prompt from the Magic Leap Hub, which you can open by pressing F8 or by clicking the terminal icon on the bottom left.

To open a terminal with a command line prompt from the Magic Leap Hub, do the following:

  1. Open the Magic Leap Hub.

  2. Open the sidebar menu on the left.

    Magic Leap Hub Sidebar Menu

  3. Click the command line icon at the bottom to instantly open a terminal window.

    Command Line Icon

For advanced users - Manual steps to set up a command line interface for Application Simulator development are to run the following scripts:

source $USER/MagicLeap/mlsdk/<your-os-version>/envsetup.sh
source $USER/MagicLeap/tools/zi/<latest-app-sim-version>/mlvdsetup.sh

Building C API Apps​

tip

Reference the C-API Building Guide for more building instructions to supplement the information below.

An Android app is built for device using gradlew, which (for our purposes) can be split into "native build" and "Android build" parts. The Application Simulator only requires the “native build” parts.

Typically, Android projects contain an app/build.gradle file which contains an "externalNativeBuild { cmake { … } }" section that targets app/src/main/cpp/CMakeLists.txt. The Application Simulator can share the cmake project used to build the native activity code, if the same is built as a shared library for the host.

The C-API samples ship with a build.py script that automates the building of the shared library. The build process places the shared library, the manifest, and the assets into sample specific folders within the out/samples_host_samples folder of the root samples directory.

All samples can be built for the host using python3 build.py --build host on the terminal. If you want to build just one sample, use python3 build.py --build host --project <project_name>.

For example, the shared library and the assets for the controller sample can be found under: <path_to_samples>/out/sdk_host_samples/com.magicleap.capi.sample.controller.

The next section covers launching the shared library.

Launching C API Apps​

Now let's launch the app you built in the previous sections.

  1. Launch ZILauncher by specifying the full path to the shared library from Building for Application Simulator.
ZILauncher /path/to/shared_lib
  1. The running Application Simulator instance in the Magic Leap Hub (ML Hub) should report ZILauncher as connected. Then the app rendered frames should be visible in the Device View if you are running a Simulator target or in the headset if you are running a Device target.