Project Island �� ��

Project Island is an experimental Vulkan renderer/proto-engine forLinux and Windows, written in C/C++.

Island is written for rapid protoyping and tweaking. That's why itallows hot-reloading wherever possible: for C/C++ applicationcode, GLSL or HLSL shader code, even the renderer's own coremodules.

Each module aims to be strictly isolated, which makes the codebasefast to compile, especially in parallel.

Main Features:

• Hot-reloading: An Island project is made from isolated c/cppmodules, each of which can be tweaked, re-compiled at runtime, andautomatically hot-reloaded.

• Shader Hot-reloading: Island supports shader code hot-reloadingfor HLSL, GLSL, or SPIR-V shader source files. Shader files areautomatically watched, and any change triggers a recompile, with(Vulkan) pipelines automatically rebuilt if needed. HLSL/GLSLShaders may use #include directives. Error messages (if any) willpoint at shader file and line number, and include a brief listingwith 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 codebasefrom scratch should take less than 5 seconds when using LLVM on anaverage multi-core machine.

• Code tweaks: Near-instant in-code parameter tweaks for Debugbuilds (no need to recompile) by using a special TWEAK() macro.

• Vulkan backend: Island has a Vulkan rendering backend, which, onLinux, allows access to new and experimental GPU features soon afterthey are released. The renderer takes care of most of thebureaucracy which comes with modern APIs: Vulkan resources areautomatically synchronised, and only allocated when needed. Mostresource properties are inferred automatically based on thecontext of how the resource is being used. Pipelines are compiledand recompiled on demand. When compiled in Debug mode, Vulkanvalidation layers are loaded by default.

• Rendergraph- based Architecture: Rendering is structured usingrenderpasses. Renderpasses are executed on-demand and synchronisedautomatically by evaluating a rendergraph. If a renderpass isdetected to have no effect on the final image, it is automaticallypruned. For Debug targets, the rendergraph generates .dot files,which can be drawn using graphviz.

• Static release binaries: While Island is highly modular anddynamic 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 toa single application. This is particularly useful for multi-windowscenarios. See example

• Straight to video: Island can render straight to screen usingthe direct rendering swapchain, or use any number of availableoptions for a window-based vulkan swapchain. It's also easy torender straight to an mp4 file, or an image sequence without showinga window, by selecting the appropriate le_swapchainspecialisation.

• Helpers: minimal effort to enable multisampling, import images,fonts

• 2d drawing context: Draw thick lines and curves usingle_paths, which specialises in 2d meshes. This module implementsa useful subset of the SVG command palette, and includes some extraslike for example a command to smoothen open or closed Bézier curvesby applying the Hobby algorithm. Thick Bézier curves aredrawn using an algorithm outlined by T. F. Hain.

• glTF Island wraps cgltf for gltf file import, andthe le_stage module can display and render most features found ingltf 2.0 files: pbrt materials, vertex animations, morph targetanimations, and skinning animations.

• Job-system: Cooperatively parallel workloads can be implementedusing the le_jobs module, which implements a job system usingcoroutine-like fibers. Both backend and render modules are designedto minimise resource contention.

• GPU ray tracing Island supports RTX via the Khronos Vulkanraytracing extensions. Creating acceleration structures and shaderbinding tables is automated and simplified as much as possible. Raytracing shaders can be hot-reloaded.

• GPU mesh shaders gives you - optional - access toNvidia-specific extensions for mesh and task shaders. These can beused in regular graphics pipelines.

Tools

• Project generator: Generates scaffolding for newapps, based on project templates
• Module generator: Generates scaffolding for newmodules.

Examples (more examples)

Island comes with a number of examples. No collection of exampleswould be complete without a hellotriangle example, and a helloworld example.

A full list of examples can be found here. More examples to come.

Modules

Island projects can be built by combining any number of islandmodules. Each module aims to do one thing well, and to play nicewith others. Modules are automatically hot-reloaded, if a change isdetected and hot-reloading is active. Some modules provide theirfunctionality by wrapping well-known external libraries, some arewritten entirely from scratch. Some of the most useful modules arelisted here:

To use a module, name it as a dependency in your applidation module'sCMakeLists.txt file; modules may depend on other modules, and the buildsystem will automatically include these dependencies. You can write your ownmodules - and there is a module template generator whichprovides you with a scaffold to start from.

Installation instructions

Island should run out of the box on a modern Linux system with thecurrent Vulkan SDK and build tools installed. For Windows, buildinstructions are collected in a separate readme.

Depencencies

Island depends on a few common development tools: CMake, gcc, git,ninja. These are commonly found on a development machine. Island alsodepends on the Vulkan SDK.

Install Vulkan SDK

Vulkan SDK >= 1.2.175

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 viapacman: shaderc vulkan-devel ninja cmake.

Building an Island project

�� If you freshly cloned the Island repository, remember to updatesubmodules before proceeding. ��

git submodule init
git submodule update --depth=1

Then move to the directory of the Island project which you want tocompile:

cd apps/examples/hello_triangle/

Build using CMake:

mkdir build
cd build
cmake -G Ninja ..
ninja

Run your new Island Application:

./Island-HelloTriangle

Note: The CMAKE parameter PLUGINS_DYNAMIC lets you choose whether tocompile 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 withhot-reloading enabled, and Release builds will produce a single static binarywith hot-reloading disabled.

IDE support

I recommend using the freely available QT Creator IDE, it allowsyou to directly open CMake project files, and integrates pretty seamlessly withthe Island workflow: running, hot-reloading, then setting a breakpoint, andthen stepping whilst inspecting state in the debugger just works. AlternativeIDEs 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'simportant to check that Run in terminal is disabled - this can bespecified in the Run Settings dialog.

Auto-recompilation on save using entr

If you prefer to work without an IDE, but wish a setup where apps getrecompiled as soon as a source file changes, the following Linux-basedsetup 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. Thelast line of the above script causes ninja to run as soon as any ofthe files checked into the github repo at hello_triangle change.

Windows 10 support

Island can compile and run natively on Microsoft Windows - with somecaveats. Progress of the Windows port and Windows-specific buildinstructions etc. are tracked in a separate readme.

Caveats

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 anypurpose, and the code here is released in the hope that you might findit interesting.

The initial motivation for writing Island was to experiment witha modern rendering API (Vulkan), to learn by trying out ideas aroundmodern realtime-rendering, and to have a framework to create visualexperiments with.

Acknowledgements

I would like to thank the folks at our machinery fortheir wonderful blog posts on engine architecture and hotreloading, these were a big initial inspiration for this project.