Project Island is an experimental Vulkan renderer/proto-engine for Linux and Windows, written in C/C++.
Island is written for rapid protoyping and tweaking. That's why it allows hot-reloading wherever possible: for C/C++ application code, GLSL or HLSL shader code, even the renderer's own core modules.
Each module aims to be strictly isolated, which makes the codebase fast to compile, especially in parallel.
Hot-reloading: An Island project is made from isolated c/cpp modules, each of which can be tweaked, re-compiled at runtime, and automatically hot-reloaded.
Shader Hot-reloading: Island supports shader code hot-reloading for HLSL, GLSL, or SPIR-V shader source files. Shader files are automatically watched, and any change triggers a recompile, with (Vulkan) pipelines automatically rebuilt if needed. HLSL/GLSL Shaders may use
#includedirectives. Error messages (if any) will point at shader file and line number, and include a brief listing with problematic lines highlighted in context.
Fast compile times: Because of Island's modular architecture, a recompilation & reload cycle typically takes less than 1 second, while the application keeps running. Compiling the whole codebase from scratch should take less than 5 seconds when using LLVM on an average multi-core machine.
Code tweaks: Near-instant in-code parameter tweaks for Debug builds (no need to recompile) by using a special
Vulkan backend: Island has a Vulkan rendering backend, which, on Linux, allows access to new and experimental GPU features soon after they are released. The renderer takes care of most of the bureaucracy which comes with modern APIs: Vulkan resources are automatically synchronised, and only allocated when needed. Most resource properties are inferred automatically based on the context of how the resource is being used. Pipelines are compiled and recompiled on demand. When compiled in Debug mode, Vulkan validation layers are loaded by default.
Rendergraph- based Architecture: Rendering is structured using renderpasses. Renderpasses are executed on-demand and synchronised automatically by evaluating a rendergraph. If a renderpass is detected to have no effect on the final image, it is automatically pruned. For Debug targets, the rendergraph generates
.dotfiles, which can be drawn using graphviz.
Static release binaries: While Island is highly modular and dynamic when compiled for Debug, it can compile into a single, optimised static binary for Release.
Multi-Window Island allows you to hook up multiple swapchains to a single application. This is particularly useful for multi-window scenarios. See example
Straight to video: Island can render straight to screen using the direct rendering swapchain, or use any number of available options for a window-based vulkan swapchain. It's also easy to render straight to an mp4 file, or an image sequence without showing a window, by selecting the appropriate
Helpers: minimal effort to enable multisampling, import images, fonts
2d drawing context: Draw thick lines and curves using
le_paths, which specialises in 2d meshes. This module implements a useful subset of the SVG command palette, and includes some extras like for example a command to smoothen open or closed Bézier curves by applying the Hobby algorithm. Thick Bézier curves are drawn using an algorithm outlined by T. F. Hain.
glTF Island wraps cgltf for gltf file import, and the
le_stagemodule can display and render most features found in gltf 2.0 files: pbrt materials, vertex animations, morph target animations, and skinning animations.
Job-system: Cooperatively parallel workloads can be implemented using the
le_jobsmodule, which implements a job system using coroutine-like fibers. Both backend and render modules are designed to minimise resource contention.
GPU ray tracing Island supports RTX via the Khronos Vulkan raytracing extensions. Creating acceleration structures and shader binding tables is automated and simplified as much as possible. Ray tracing shaders can be hot-reloaded.
GPU mesh shaders gives you - optional - access to Nvidia-specific extensions for mesh and task shaders. These can be used in regular graphics pipelines.
- Project generator: Generates scaffolding for new apps, based on project templates
- Module generator: Generates scaffolding for new modules.
A full list of examples can be found here. More examples to come.
Island projects can be built by combining any number of island modules. Each module aims to do one thing well, and to play nice with others. Modules are automatically hot-reloaded, if a change is detected and hot-reloading is active. Some modules provide their functionality by wrapping well-known external libraries, some are written entirely from scratch. Some of the most useful modules are listed here:
||-||interactive, mouse controlled camera|
||-||draw svg-style paths, parse simplified SVG-style path command lists|
||earcut, libtess||tessellation; dynamic choice of tessellation backend|
||imgui||graphical user interface|
||stb image||load image files|
||stb truetype||truetype glyph sdf, geometry and texture atlas based typesetting|
||-||build graphics, and compute pipelines|
||-||build Khronos RTX raytracing pipelines|
||-||simplified 2d drawing context|
||cgltf||load and parse glTF 2.0 files|
||-||render 3d scenes, display animations|
||-||timekeeping, canonical clock for animations|
||-||fiber-based job system|
||shaderc||compile glsl shaders to SPIR-V|
||glfw||window i/o system|
||-||windowed, direct, or straight-to-video output|
||-||record command buffers, evaluate rendergraphs|
||-||interact with GPU via Vulkan, manage GPU resources|
To use a module, name it as a dependency in your applidation module's
CMakeLists.txt file; modules may depend on other modules, and the build system will automatically include these dependencies. You can write your own modules - and there is a module template generator which provides you with a scaffold to start from.
Island should run out of the box on a modern Linux system with the current Vulkan SDK and build tools installed. For Windows, build instructions are collected in a separate readme.
Island depends on a few common development tools: CMake, gcc, git, ninja. These are commonly found on a development machine. Island also depends on the Vulkan SDK.
Install Vulkan SDK
Vulkan SDK >=
I recommend to install the latest Vulkan SDK via a package manager. Follow the installation instructions via: https://vulkan.lunarg.com/sdk/home#linux.
Arch Linux (Manjaro)
On Arch Linux, I recommend installing the following packages via pacman:
shaderc vulkan-devel ninja cmake.
Building an Island project
git submodule init git submodule update --depth=1
Then move to the directory of the Island project which you want to compile:
Build using CMake:
mkdir build cd build cmake -G Ninja .. ninja
Run your new Island Application:
Note: The CMAKE parameter
PLUGINS_DYNAMIC lets you choose whether to compile Island as a static binary, or as a thin module with dynamic plugins. Unless you change this parameter, Debug builds will be built thin/dynamic with hot-reloading enabled, and Release builds will produce a single static binary with hot-reloading disabled.
I recommend using the freely available QT Creator IDE, it allows you to directly open CMake project files, and integrates pretty seamlessly with the Island workflow: running, hot-reloading, then setting a breakpoint, and then stepping whilst inspecting state in the debugger just works. Alternative IDEs are of course available, and as long as they support CMake project files, should work. When running an Island app with the debugger in Qt Creator, it's important to check that
Run in terminal is disabled - this can be specified in the Run Settings dialog.
Auto-recompilation on save using
If you prefer to work without an IDE, but wish a setup where apps get recompiled as soon as a source file changes, the following Linux-based setup is pretty nice:
cd apps/examples/hello_triangle mkdir build cd build cmake -G Ninja .. # and then git ls-files ../.. | entr ninja &
entr(1) is a great utility, which runs a command on file change. The last line of the above script causes
ninja to run as soon as any of the files checked into the github repo at
Windows 10 support
Island can compile and run natively on Microsoft Windows - with some caveats. Progress of the Windows port and Windows-specific build instructions etc. are tracked in a separate readme.
Note The API is under active development, expect lots of change. As such, there are no promises that it might be ready or fit for any purpose, and the code here is released in the hope that you might find it interesting.
The initial motivation for writing Island was to experiment with a modern rendering API (Vulkan), to learn by trying out ideas around modern realtime-rendering, and to have a framework to create visual experiments with.