Skip to main content

Build your first Native Lens

Write a native library that exports a hello() function to a Lens, cross-compile it with the SPECS NDK Clang toolchain, and load it from a Lens script.

This page takes you from an empty folder to a native library for a Lens on SPECS: an aarch64 shared library, built with the SPECS NDK, that exports a hello() function to the Lens's scripts. Before you start, set up your host: Host Setup on macOS or Host Setup on Windows.

Step 1: Write the native library

A native library for a Lens has no main(). Instead, it exports functions that the Lens's scripts call, through the CoreJS ABI. Its C++ headers ship in the NDK under snap/corejs_abi/, and the ABI is header-only, so there's no library to link. When the Lens loads your library, the runtime calls your CoreJsOnLoad function, and each property you set on its moduleObject becomes an export.

This binding.cpp exports one function, hello(), which returns a string to JavaScript:

#include <span>

#include <snap/corejs_abi/cpp/abi.hpp>

using namespace snap::corejs_abi;

namespace {

// hello() in JavaScript. Returns a greeting.
Value hello(Runtime runtime, const Value& /*thisValue*/, std::span<const Value> /*args*/) {
return runtime.createStringFromUtf8("Hello from SPECS");
}

} // namespace

extern "C" {

// Called when the Lens loads the library. Each property you set on
// moduleObject becomes an export of the library.
void CoreJsOnLoad(CoreJsAbiRuntime* runtime, CoreJsAbiObject* moduleObject, void** /*context*/) {
Runtime rt{runtime};
ObjectView exports{*moduleObject};
exports.setProperty(rt, "hello", rt.createFunction(&hello));
}

// Called when the Lens unloads the library. Release per-load state here.
void CoreJsOnUnload(CoreJsAbiRuntime* /*runtime*/, void* /*context*/) {}

}

Next to it, a CMakeLists.txt builds binding.cpp as a shared library. The CoreJS ABI headers need C++20:

cmake_minimum_required(VERSION 3.15)
project(MyNativeLens CXX)

add_library(hello SHARED binding.cpp)
target_compile_features(hello PRIVATE cxx_std_20)

To call SPECS APIs from an export, link their libraries; see Link multiple SPECS libraries.

Step 2: Configure with CMake

Pass the Clang toolchain file via -DCMAKE_TOOLCHAIN_FILE. Use an absolute path to the NDK root:

NDK=/path/to/specsndk-armv8-1.3.0

cmake -B build \
-DCMAKE_TOOLCHAIN_FILE="${NDK}/SpecsNDK-Toolchain-Clang.cmake" \
-DCMAKE_BUILD_TYPE=Release

CMake configures the sysroot, compiler, and linker automatically. You do not need to set CMAKE_CXX_COMPILER or CMAKE_SYSROOT manually.

Step 3: Build

cmake --build build

Step 4: Verify the output

The add_library(hello SHARED …) target builds build/libhello.so. Confirm it targets aarch64:

file build/libhello.so
# build/libhello.so: ELF 64-bit LSB shared object, ARM aarch64, version 1 (SYSV), dynamically linked, ...

The build output also shows specs-perm-embed embedding the .snap.permissions manifest into libhello.so; see Permission Annotations and Manifest Embedding.

The library is ready to add to a Lens.

Deployment Steps

A native library ships inside a Lens: add the .so to your Lens Studio project, and a script loads it as a NativeLibraryAsset and calls its exports.

Step 5: Add the library to your Lens Studio project

Copy build/libhello.so into your Lens Studio project, under Assets/NativeModules/.

Step 6: Load the library and call its exports

In a script under Assets/Scripts/, load the library when the Lens starts. requireAsset takes the path to the .so, relative to the script, and load() resolves to the library's exports, the functions that CoreJsOnLoad registered:

async function loadNativeLibrary() {
try {
const library = requireAsset('../NativeModules/libhello.so');
const exports = await library.load();
if (!exports) {
print('Native library did not load here');
return;
}
print(exports.hello()); // Hello from SPECS
} catch (err) {
print(`Error loading native library: ${err}`);
}
}

loadNativeLibrary();

Write the path to requireAsset as a string literal. Lens Studio finds the libraries to package by scanning for requireAsset('…') calls, so a path built at runtime leaves the library out of the Lens.

Calling load() again returns the same exports until you call unload(). When the library can't load, for example a device .so in Lens Studio's preview, load() can resolve to null instead of failing, so check the exports before you call them.

Step 7: Run the Lens on device

The .so runs only on a SPECS device, so run the Lens on your SPECS:

  1. Log in to Lens Studio: select SPECS Dev Portal > Login in the menu bar. Use the same SPECS account as the SPECS App.
  2. Connect your SPECS to Lens Studio. See Connect Lens Studio to SPECS.
  3. Select Preview in the toolbar. Lens Studio sends the Lens to the connected SPECS, and the Lens starts on the device.

When the Lens starts, the script loads libhello.so and calls hello(), and the Logger shows its result:

Hello from SPECS

For more ways to send a Lens and debug it on the device, see Send a Lens to SPECS.

Only link what you use. Each API has its own library:

target_link_libraries(hello PRIVATE
specs_player # SpecsPlayer.h
specs_media # SpecsMediaCodec.h, SpecsMediaExtractor.h, SpecsMediaPresenter.h, SpecsMediaBuffer.h, SpecsMediaGLTexture.h, SpecsRecorder.h, SpecsCapture.h
specs_audio_playback # SpecsAudioPlayback.h
specs_audio_record # SpecsAudioRecord.h
specs_camera # SpecsCameraManager.h
specs_location # SpecsLocationProvider.h
)
# SpecsFs.h is header-only on the device: include it, no library to link.

For every header-to-library mapping, see Linking and pkg-config.