Requirements
isolen ui builds on Windows and macOS with CMake, either inside the isolen app or on its own. Windows runs the Vulkan backend and macOS runs a native Metal backend. Both also carry a CPU backend that needs no GPU. Every other platform is refused at configure time.
Getting the source
The library and its engines are separate private repositories joined by submodules, so clone with --recursive, or run git submodule update --init --recursive in a clone made without it. Project layout shows the tree, the include prefix and how to build isolenui alone.
Language
- C++20 for all engine and app code, and C11 for the few C units.
- Objective-C++ 20 on macOS, for the Metal backend and for any level two code that includes
gfx_metal.h.
Windows
- Windows 10 or 11.
- Visual Studio 2022 or newer, with the C++ toolset.
- The Vulkan SDK 1.4 or newer. It ships volk and glslc, and the build uses both directly.
- CMake 3.24 or newer, and Ninja.
- Optionally sccache and LLVM's lld-link, see faster builds:
winget install Mozilla.sccacheandwinget install LLVM.LLVM.
macOS
- The Xcode command line tools and CMake 3.24 or newer.
- The full Xcode is optional. Its offline metal shader compiler lets the build bake the shaders. Without it, the MSL is compiled at boot instead.
- No Vulkan loader is linked on macOS. MoltenVK is not used.
- Optionally sccache and ld64.lld, see faster builds:
brew install sccache lld.
Faster builds
cmake/fast_tools.cmake speeds up rebuilds with two optional tools. The ISOLEN_FAST_TOOLS option turns them on and is on by default. Each tool is used only when it is found. A missing one logs one line at configure and the build carries on with the default. -DISOLEN_FAST_TOOLS=OFF turns both off.
| Tool | What it does | Where |
|---|---|---|
| sccache | The compiler launcher for C, C++ and Objective C++, so an unchanged file comes from the cache instead of the compiler. With MSVC, debug info is embedded in each object (/Z7) while it is cached, since a shared PDB cannot be cached. | macOS and Windows |
| ld64.lld | Links instead of Apple's ld. | macOS, every preset |
| lld-link | Links instead of link.exe. Only the debug preset asks for it, through ISOLEN_LLD. Release keeps link.exe with link time code generation, which lld cannot read. | Windows debug |
The linker switch needs CMake 3.29 or newer. On an older CMake the default linker is kept. Configure logs what it picked, for example isolen compiler cache /opt/homebrew/bin/sccache and isolen linker apple ld, ld64.lld not found. The binaries are the same either way.
Hardware
The Windows event build is tuned for one target: an NVIDIA RTX 2050 laptop GPU with 4 GB of VRAM. gfx_stats reports the resident bytes of every asset, so you can watch that budget. The macOS build has no VRAM budget and simply runs as fast as it can. On x86, ISOLEN_AVX2 (on by default) builds with AVX2 and FMA.
Capacities
The solver and the device registry use fixed tables. The draw lists allocate once from their caps and, once warm, a frame allocates nothing. A frame that outgrows them flushes through a sink or grows, and growth is logged. These are the limits you can hit:
| Limit | Value | What happens past it |
|---|---|---|
ISOLEN_LAY_MAX_NODES | 2048 boxes | The tree still solves. Later nodes are dropped and lay_ctx::overflowed is set. |
ISOLEN_LAY_MAX_DEPTH | 32 levels | The same, counted in lay_ctx::skipped. |
gfx_list_caps | 1024 rects, 2048 glyphs, 2048 curves, 32 art, 64 runs by default | The list flushes through its sink or grows, up to 1,048,576 records of a kind. Only a failed allocation refuses records, counted in gfx_list::dropped. |
GFX_RUN_LIMIT, GFX_ART_LIMIT | 1024, 256 | The most runs of a kind and art records one draw carries. The list flushes before it passes them. |
GFX_LAYERS | 32 | The layers one draw holds. Higher layers slide the window up through the sink. |
GFX_MAX_DEVICES | 4 | gfx_open refuses a fifth device. |
GFX_MAX_IMAGES, GFX_MAX_SVGS, GFX_MAX_FONTS | 256, 64, 4 | The load returns GFX_NONE and logs an error. |
TEXT_MAX_FACES | 8 | A face index past the atlas is clamped. |
lay_ctx is 730,016 bytes, most of the 1 MB default stack on Windows, so keep it static or on the heap, never as a local. gfx_list is only 256 bytes with its records on the heap.Header hygiene
No graphics api type crosses gfx.h, gfx_list.h, ui.h or layout2.h. gfx_vulkan.h pulls in the Vulkan SDK, so include it only from a Windows level two unit. An isolation unit in the engine fails the build if a neutral header includes it. The level two page shows both native headers in use.