On this page

Project layout

isolen ui lives in its own repository, and each of its engines has one too. The presentation app pulls the library in as a submodule, and the library pulls in the engines the same way.

The repositories

All of them are private repositories in the xyoda organisation, so cloning needs access to each one.

RepositoryWhat it holds
isolenuiThe library: core, gfx, the shared GPU code, platform, text, ui, the kit, the app shell, audio and compat, plus the gallery, the atlas and svg tools, the shared assets and the CMake modules.
elbaThe vector engine, see elba.
dogaThe GIF decoder behind gif.
capriThe Lottie engine behind lottie.
corfuThe glTF model engine behind model view.
isolenThe presentation app: the deck language and its baker in tools/deck, the Bluetooth remote, the show and visualizer apps, the boot and deck assets, and the fetched cache.

The submodule tree

Every repository keeps its sources under src/. isolen holds isolenui at third_party/isolenui, and isolenui holds each engine under third_party:

tree
isolen               deck, remote, show and visualizer
  tools/deck
  third_party/isolenui
    src/core  src/gfx  src/gpu  src/platform  src/text
    src/ui  src/kit  src/app  src/audio  src/compat
    assets/          icons, avatars, models, test, atlases
    apps/gallery  apps/eq  apps/graph  apps/overlay
    tools/atlas  tools/svg
    kit.conf  cmake/
    third_party/elba     src/
    third_party/doga     src/
    third_party/capri    src/
    third_party/corfu    src/

Cloning

The tree is two levels deep, so clone with --recursive. A plain clone leaves the submodule folders empty and the build cannot find the engines.

clone
git clone --recursive https://git.meowda.xyz/xyoda/isolenui
cd isolenui

For a clone made without it, or after a pull that moves a submodule, fetch the rest in place:

update
git submodule update --init --recursive

The include prefix

Every include names its repository first. Configure links include/isolenui in the build folder to isolenui's src, and each engine links include/elba, include/doga, include/capri or include/corfu to its own src. On Windows the links are junctions, so no admin rights are needed. Library headers start with isolenui/ and engine headers with the engine's name. The GIF decoder that was media/doga.h is now doga/doga.h. Shaders keep their bare #include "isolen_common.glsl".

includes
#include "isolenui/core/log.h"
#include "isolenui/gfx/gfx.h"
#include "isolenui/ui/ui.h"

#include "elba/elba.h"
#include "doga/doga.h"
#include "capri/capri.h"
#include "corfu/corfu.h"

Libraries

isolenui defines isolenui::core, isolenui::gfx, isolenui::ui, isolenui::kit, isolenui::audio and isolenui::app. The app shell is its own library, above the kit. isolenui/ui/ui.h no longer includes the kit: include isolenui/kit/kit.h wherever you use a kit component. The draw, curve and art headers that sat in ui now live in isolenui/gfx, and dashboard.h in isolenui/kit.

isolenui_app(target) in cmake/apps.cmake turns a target into an app: the shared flags, the kit, the libraries and the assets beside it. The gallery, eq, graph and overlay apps live in apps, and -DISOLENUI_BUILD_APPS=OFF leaves them out.

Engines as peer dependencies

The engines use the library's targets and carry no copy of it. Inside isolenui they link the targets the parent already defined: elba and corfu link isolenui::gfx, doga links isolenui::core, and capri links elba and isolenui::core. Each engine is the static library named after it, also reachable as elba::elba, doga::doga, capri::capri and corfu::corfu.

Built on its own, an engine looks for isolenui in -DISOLENUI_DIR, then the ISOLENUI_DIR environment variable, then an isolenui folder beside it, and stops configure with an error if none is there.

an engine alone
cmake -S . -B build -DISOLENUI_DIR=/path/to/isolenui

Building isolenui alone

isolenui builds without isolen, with its own presets: release and debug on Windows, macos and macos-debug on macOS. Each builds with Ninja into build/<preset>. build.sh and build.bat take the preset first, defaulting to macos on a mac and release on Windows, and an optional target second that builds only that target. build.bat finds Visual Studio through vswhere and puts LLVM's lld-link on the path when it is installed. The toolchain is listed in requirements.

macOS
./build.sh
./build.sh macos-debug
./build.sh macos isolen_gallery
Windows
build.bat
build.bat debug
build.bat release isolen_gallery

Raw input for the remote

The Bluetooth remote stays in isolen and listens through the window's raw hook in isolenui/platform/window.h. window_set_raw_sink(w, fn, user) hands the host every device event before the ui sees it. On macOS the payload is a window_raw_key for every press and release, with vk as a Win32 virtual key, plus down and repeat. On Windows the payload is the raw input lparam.

remote.cpp
#include "isolenui/platform/window.h"

static void on_raw(void* user, void* payload) {
#if defined(__APPLE__)
    const window_raw_key* k = static_cast<const window_raw_key*>(payload);
    if (k->down && !k->repeat) {
        // k->vk is a win32 virtual key
    }
#else
    // payload is the raw input lparam
#endif
    (void)user;
}

void hook_remote(window* w, void* state) {
    window_set_raw_sink(w, on_raw, state);
}

Last updated 6 October 2026