{"id":15039460,"url":"https://github.com/tgfrerer/island","last_synced_at":"2025-05-14T20:04:14.528Z","repository":{"id":38191398,"uuid":"150248562","full_name":"tgfrerer/island","owner":"tgfrerer","description":"🌋🐎 Project Island is an experimental, hot-reloading Vulkan Renderer for Linux and Windows, written in C/C++.","archived":false,"fork":false,"pushed_at":"2025-03-25T09:32:27.000Z","size":11183,"stargazers_count":1168,"open_issues_count":2,"forks_count":44,"subscribers_count":15,"default_branch":"wip","last_synced_at":"2025-04-13T14:04:29.317Z","etag":null,"topics":["3d-engine","c","cpp","engine","experimental","hot-reload","rendergraph","research-and-development","shader-glsl","shader-hlsl","vulkan","vulkan-backend"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tgfrerer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-25T10:36:37.000Z","updated_at":"2025-04-13T11:30:02.000Z","dependencies_parsed_at":"2023-11-20T10:38:19.704Z","dependency_job_id":"ab94af1c-17d3-433f-a2dd-6f26a405093b","html_url":"https://github.com/tgfrerer/island","commit_stats":{"total_commits":3565,"total_committers":11,"mean_commits":"324.09090909090907","dds":0.006451612903225823,"last_synced_commit":"c465edb26b188626b1df2b89f656bd9cc8b96cfe"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgfrerer%2Fisland","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgfrerer%2Fisland/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgfrerer%2Fisland/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgfrerer%2Fisland/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tgfrerer","download_url":"https://codeload.github.com/tgfrerer/island/tar.gz/refs/heads/wip","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724639,"owners_count":21151561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-engine","c","cpp","engine","experimental","hot-reload","rendergraph","research-and-development","shader-glsl","shader-hlsl","vulkan","vulkan-backend"],"created_at":"2024-09-24T20:42:54.591Z","updated_at":"2025-04-13T14:04:58.741Z","avatar_url":"https://github.com/tgfrerer.png","language":"C++","readme":"\u003cimg width=\"100%\" src=\"resources/readme/title.png\" /\u003e\n\n# Project Island 🌋🐎 \n\nProject Island is an experimental **Vulkan** Renderer for Linux (Desktop, [Raspberry Pi 5](README_RPI5.md)) and Windows, written in C/C++. \n\nIsland is written for **rapid protoyping and tweaking**. That's why it\nallows **hot-reloading** wherever possible: for **C/C++** application\ncode, **GLSL** or **HLSL** shader code, **image assets**, and even the renderer's own core modules. \n\nIsland is **fast to compile**. A full rebuild should take \u003c 5s on\na moderate multicore machine, and incremental builds often take \u003c 1s. \n\nTo achieve this, Island is structured into strictly separated modules,\nwhich can be dropped in or out during Debug, while for Release, you\ncan build a single, statically linked and optimised binary.\n\n\n[![C/C++ CI](https://github.com/tgfrerer/island/actions/workflows/c-cpp.yml/badge.svg)](https://github.com/tgfrerer/island/actions/workflows/c-cpp.yml)\n\n\n## Main Features:\n\n* **Hot-reloading**: An Island project is made from isolated c/cpp\n  modules, each of which can be tweaked, re-compiled at runtime, and\n  automatically hot-reloaded.\n\n* **Shader hot-reloading**: Island supports shader code hot-reloading\n  for HLSL, GLSL, or SPIR-V shader source files. Shader files are\n  automatically watched, and any change triggers a recompile, with\n  (Vulkan) pipelines automatically rebuilt if needed. HLSL/GLSL\n  Shaders may use `#include` directives. Error messages (if any) will\n  point at shader file and line number, and include a brief listing\n  with problematic lines highlighted in context.\n\n\u003cimg width=\"350\" src=\"https://github.com/tgfrerer/island/assets/423509/b97ef461-42b1-4fbd-b3a0-c4051bb6e8d7\" align=\"right\" /\u003e\n\n* **Image hot-reloading**: If importing images via\n  `le_resource_manager` (it's simple, and recommended) - any image\n  resource may automatically hot-reload when its source file changes.\n\n* **Fast compile times**:  Because of Island's modular architecture,\n  a recompilation \u0026 reload cycle typically takes less than 1 second,\n  while the application keeps running. Compiling the whole codebase\n  from scratch should take less than 5 seconds when using LLVM on an\n  average multi-core machine. And on Raspberry Pi 5, a typical project takes about 27s of wall-clock-time to compile from scratch.\n\n* **Code tweaks**: Near-instant in-code parameter tweaks for Debug\n  builds (no need to recompile) by using a special `LE_TWEAK()` macro.\n\n* **Vulkan backend**: Island has a Vulkan rendering backend, which, on\n  Linux, allows access to new and experimental GPU features soon after\n  they are released. The renderer takes care of most of the\n  bureaucracy which comes with modern APIs: Vulkan **resources are\n  automatically synchronised**, and only allocated when needed. Most\n  resource properties are *inferred* automatically based on the\n  context of how the resource is being used. Pipelines are compiled\n  and recompiled on demand. When compiled in Debug mode, Vulkan\n  validation layers are loaded by default.\n\n* **Rendergraph based architecture**: Rendering is structured using\n  passes. Passes are executed on-demand and synchronised\n  automatically by evaluating a rendergraph. If a renderpass is\n  detected to have no effect on the final image, it is automatically\n  pruned. When requested, the rendergraph generates `.dot` files,\n  which can be drawn using graphviz. More about how Island builds its\n  rendergraph in [this blog post][rendergraph_blog].\n\n  \u003cimg width=\"350\" src=\"resources/readme/graph_screenshot.png\" align=\"right\" /\u003e\n  \n* **Automatic GPU multiqueue**: renderpasses are automatically\n  distributed onto any avaliable render queues - if resources need to\n  be transferred between queue families, this happens automatically.\n  More about how Island distributes workloads across renderqueues and\n  synchronises them in [this blog post][rendergraph_sync_blog].\n\n* **Vulkan Video Decode** hardware accelerated video decode using just\n  the new Vulkan Video api, and no external decoding dependencies,\n  synchronising video images implicitly and simply.  \n\n* **Static release binaries**: While Island is highly modular and\n  dynamic when compiled for Debug, it can compile into a single,\n  optimised static binary for Release. \n\n* **Interactive Console** if you add the `le_console` module to your\n  app, it will listen on localhost port 3535 and, if you connect to it\n  via telnet or similar, if will provide you with an interactive\n  console. You can use this to change settings on a running\n  application, and to filter and monitor log messages. Use\n  reverse-ssh or similar to forward localhost::3535 and you can\n  remotely connect to a running app from all over the world.\n\n* **Gamepad** support: the default camera can be steered with\n  a gamepad-just connect your gamepad and you are set; application\n  windows can decide whether they want to subscribe to gamepad events- \n  and to which gamepads to subscribe to. \n\n  \u003cimg width=\"350\" src=\"modules/le_tracy/tracy.png\" align=\"right\" /\u003e\n\n* **Tracy intergation** nano-second-resolution profiling via \n  [Tracy](https://github.com/wolfpld/tracy) - enable this by \n  [uncommenting a single line](modules/le_tracy/README.md) in the \n  app CMakeLists file. Profiling works with both hot-reloading and \n  optimised static builds.\n\n* **Multi-Window** Island allows you to hook up multiple swapchains to\n  a single application. You can dynamically add and remove swapchains\n  while your Island application is running. This is particularly useful\n  for multi-window scenarios. See [example][example-multiwindow]\n  \n* **Straight to video**: Island can render straight to screen using\n  the direct rendering swapchain, or use any number of available\n  options for a window-based vulkan swapchain. It's also easy to\n  render straight to an mp4 file (via ffmpeg), or an image sequence\n  without showing a window, by selecting the appropriate\n  `le_swapchain` specialisation.\n\n* **Helpers**: minimal effort to enable multisampling, import images,\n  import, display and use fonts\n\n* Load and Save **OpenEXR** images, in 16bit float, 32bit float\n  variants via the core `le_exr` module\n\n* **2D drawing context**: Draw thick lines and curves using\n  `le_path`, which specialises in 2D meshes. This module implements\n  a useful subset of the SVG command palette, and includes some extras\n  like for example a command to smoothen open or closed Bézier curves\n  by applying the [Hobby algorithm][hobby]. Thick Bézier curves are\n  drawn using [an algorithm after T. F. Hain][hain].\n\n* **Job-system**: Cooperatively parallel workloads can be implemented\n  using the `le_jobs` module, which implements a job system using\n  coroutine-like fibers. Both backend and render modules are designed\n  to minimise resource contention.\n\n* **GPU ray tracing** Island supports RTX via the *Khronos Vulkan\n  raytracing extensions*. Creating acceleration structures and shader\n  binding tables is automated and simplified as much as possible. Ray\n  tracing shaders can be hot-reloaded.\n\n* **Debug print to screen** print-to-screen that is fast, textureless\n  and simple to use with `le_debug_print_text`\n\n[hain]: https://doi.org/10.1016/j.cag.2005.08.002\n[hobby]: http://weitz.de/hobby/\n[cgltf-link]: https://github.com/jkuhlmann/cgltf\n[example-multiwindow]: apps/examples/multi_window_example/\n[rendergraph_blog]: https://poniesandlight.co.uk/reflect/island_rendergraph_1/\n[rendergraph_sync_blog]: https://poniesandlight.co.uk/reflect/island_rendergraph_2/\n\n\n## Examples ([more examples](apps/examples/))\n\nIsland comes with a number of examples. No collection of examples\nwould be complete without a \n\n| [Hello Triangle](apps/examples/hello_triangle/) | and a [Hello World](apps/examples/hello_world/) example |\n| --- | --- | \n|\u003cimg width=\"350\" src=\"apps/examples/hello_triangle/screenshot.png\" /\u003e|\u003cimg width=\"350\" align=\"right\" src=\"apps/examples/hello_world/screenshot.jpg\" /\u003e|\n\n\u003e [!TIP]\n\u003e \n\u003e A full list of examples can be found [here](apps/examples/). Examples\n\u003e can be used as starting point for new projects by using the project\n\u003e generator.\n\n## Tools\n\n+ [Project generator][project-generator]: Generates scaffolding for new\n  projects, based on project templates\n+ [Module generator][module-generator]: Generates scaffolding for new\n  modules.\n+ [Vulkan Struct Scaffold generator][struct-generator] Generates\n  scaffolding for Vulkan structs, so you don't ever have to type\n  `VK_STRUCTURE_TYPE...` ever again.\n\n## Project Generator\n\nIsland projects can be scaffolded from templates (or from other,\nexisting projects) by invoking the project generator python script.\nThis script lives in the `scripts` folder, but can be invoked from\nanywhere. \n\n```bash\n# say myapps is where I want to place a new island project\ncd island/apps/myapps\n\n# this will create a new project based on the \"hello triangle\" template\n../../scripts/create_project.py mynewproject\n\n# this will create a new project based on the \"full screen quad\" template\n../../scripts/create_project.py mynewquadproject -t quad_template\n\n# this will create a new project based on the project \"myoldproject\", if it can be found in the current directory\n../../scripts/create_project.py anotherproject -T . -t myoldproject\n```\n```bash\n# print options and help for project generator via \n../../scripts/create_project.py -h\n```\n```txt\nusage: create_project.py [-h] [-T TEMPLATE_DIR] [-t TEMPLATE_NAME]\n                         project_name\n\nCreate a new Island project based on a template / or an existing\nproject.\n\npositional arguments:\n  project_name          Specify the name for new project to create\n                        from template.\n\noptions:\n  -h, --help            show this help message and exit\n  -T TEMPLATE_DIR, --template-dir TEMPLATE_DIR\n                        Specify a path *relative to the current\n                        directory* in which to look for project\n                        template directories. Use dot (\".\") to search\n                        for project directories within the current\n                        directory - for example if you wish to\n                        duplicate an existing project as a starting\n                        point for a new project.\n  -t TEMPLATE_NAME, --template-name TEMPLATE_NAME\n                        Specify the name for template. This can be\n                        the name of any project directory within\n                        TEMPLATE_DIR.\n```\n\n## Modules\n\nIsland projects can be built by combining any number of island\nmodules. Each module aims to do **one thing well**, and to play nice\nwith others. Modules are automatically hot-reloaded, if a change is\ndetected and hot-reloading is active. Some modules provide their\nfunctionality by wrapping well-known external libraries, some are\nwritten entirely from scratch. Some of the most useful modules are\nlisted here:\n\n| Module | Wraps | Description | \n| --- | :---: | --- | \n| `le_camera` | - | interactive, mouse controlled camera |\n| `le_path` | - | draw svg-style paths, parse simplified SVG-style path command lists | \n| `le_imgui` | [imgui][link-imgui] | graphical user interface |\n| `le_pixels` | [stb image][link-stb_image] | load image files |\n| `le_png` | [lodepng][link-lodepeng] | image codec: load and store png files, supports fpnge on linux |\n| `le_exr` | [openEXR][link-openexr] | image codec: load and store exr files, support for f16 f32 images |\n| `le_font` | [stb truetype][link-stb_truetype] | truetype glyph sdf, geometry and texture atlas based typesetting |\n| `le_pipeline_builder` | - | build graphics, and compute pipelines | \n| `le_rtx_pipeline_builder` | - | build Khronos RTX raytracing pipelines | \n| `le_2d` | - | simplified 2d drawing context |\n| `le_timebase` | - | timekeeping, canonical clock for animations | \n| `le_jobs` | - | fiber-based job system | \n| `le_ecs` | - | entity-component-system | \n| `le_shader_compiler` | [shaderc][link-shaderc] | compile GLSL, and HLSL shader source to SPIR-V | \n| `le_window` | [glfw][glfw] | window i/o system | \n| `le_swapchain` | - | windowed, direct, or straight-to-video output | \n| `le_renderer` | - | record command buffers, evaluate rendergraphs |\n| `le_video_decoder` | - | hardware accelerated video decoding using Vulkan Video API |\n| `le_backend` | - | interact with GPU via Vulkan, manage GPU resources |\n| `le_screenshot` | - | save renderpass images to disk, supports image sequences, and any file format for which there is an image encoder, notably exr, png |\n\n\u003e [!TIP]\n\u003e\n\u003e To use a module, name it as a dependency in your applidation module's\n\u003e `CMakeLists.txt` file; modules may depend on other modules, and the build\n\u003e system will automatically include these dependencies. You can write your own\n\u003e modules - and there is a [module template generator][module-generator] which\n\u003e provides you with a scaffold to start from.\n\n[link-imgui]: https://github.com/ocornut/imgui\n[link-earcut]: https://github.com/mapbox/earcut.hpp\n[link-lodepeng]: https://github.com/lvandeve/lodepng\n[link-libtess]: https://github.com/memononen/libtess2\n[link-stb_image]: https://github.com/nothings/stb/blob/master/stb_image.h\n[link-stb_truetype]: https://github.com/nothings/stb/blob/master/stb_truetype.h\n[link-cgltf]: https://github.com/nothings/stb/blob/master/stb_truetype.h\n[module-generator]: scripts/create_module.py\n[project-generator]: scripts/create_project.py\n[link-shaderc]: https://github.com/google/shaderc/\n[glfw]: https://github.com/glfw/glfw\n[link-openexr]: https://github.com/AcademySoftwareFoundation/openexr\n\n# Setup instructions\n\nIsland should run out of the box on a modern Linux system with the\ncurrent Vulkan SDK and build tools installed. For Windows, build\ninstructions are collected in a [separate readme][readme-win].\n\n## Dependencies\n\nIsland depends on a few common development tools: CMake, gcc, git,\nninja. These are commonly found on a development machine. Island also\ndepends on the Vulkan SDK.\n\n## Install Vulkan SDK \n\n### Vulkan SDK \u003e= `1.3.211`\n\nI recommend to install the latest Vulkan SDK via a package manager.\nFollow the installation instructions via:\n\u003chttps://vulkan.lunarg.com/sdk/home#linux\u003e.\n\n### Arch Linux (Manjaro)\n\nOn Arch Linux, I recommend installing the following packages via\npacman: `shaderc vulkan-devel ninja cmake`.\n\n### Fedora Linux \n\nOn Fedora, I recommend installing these packages:\n\n```bash\ndnf install -y wayland-scanner libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel libdrm-devel ninja-build cmake \n```\n\n## Building an Island project\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e If you freshly cloned the Island repository, remember to update\n\u003e submodules before proceeding.\n\n    git submodule init\n    git submodule update --depth=1\n\nThen move to the directory of the Island project which you want to\ncompile:\n\n    cd apps/examples/hello_triangle/\n\nBuild using CMake:\n\n    mkdir build\n    cd build\n    cmake -G Ninja ..\n    ninja\n\nRun your new Island Application: \n\n    ./Island-HelloTriangle\n\n\u003e [!NOTE] \n\u003e\n\u003e The CMAKE parameter `PLUGINS_DYNAMIC` lets you choose\n\u003e whether to compile Island as a static binary, or as a thin module with\n\u003e dynamic plugins. Unless you change this parameter, Debug builds will\n\u003e be built thin/dynamic with hot-reloading enabled, and Release builds\n\u003e will produce a single static binary with hot-reloading disabled. \n\n## IDE support\n\nI recommend using the freely available [QT Creator][qt_creator] IDE,\nit allows you to directly open CMake project files, and integrates\npretty seamlessly with the Island workflow: running, hot-reloading,\nthen setting a breakpoint, and then stepping whilst inspecting state\nin the debugger just works. Alternative IDEs are of course available,\nand as long as they support CMake project files, should work. When\nrunning an Island app with the debugger in Qt Creator, it's important\nto check that `Run in terminal` is **disabled** - this can be\nspecified in the Run Settings dialog.\n\n[qt_creator]: https://download.qt.io/official_releases/qtcreator/ \n\n## Auto-recompilation on save using `entr`\n\nIf you prefer to work without an IDE, but wish a setup where apps get\nrecompiled as soon as a source file changes, the following Linux-based\nsetup is pretty nice: \n\n```bash\n    cd apps/examples/hello_triangle\n    mkdir build\n    cd build\n    cmake -G Ninja ..\n    # and then \n    git ls-files ../.. | entr ninja \u0026\n```\n\n`entr(1)` is a great utility, which runs a command on file change. The\nlast line of the above script causes `ninja` to run as soon as any of\nthe files checked into the github repo at `hello_triangle` change.\n\n## Windows 11 support\n\nIsland can compile and run natively on Microsoft Windows - with some\ncaveats. Progress of the Windows port and Windows-specific build\ninstructions etc. are tracked in a [separate readme][readme-win].\n\n## Caveats\n\n\u003e [!CAUTION]\n\u003e \n\u003e Island's API is under active development, expect lots of\n\u003e change. As such, there are no promises that it might be ready or fit\n\u003e for any purpose, and the code here is released in the hope that you\n\u003e might find it interesting. \n\nThe initial motivation for writing Island was to experiment with\na modern rendering API (Vulkan), to learn by trying out ideas around\nmodern realtime-rendering, and to have a framework to create [visual\nexperiments](http://instagram.com/tgfrerer) with.\n\n[readme-win]: README_WINDOWS.md \n[struct-generator]: scripts/codegen/gen_vk_structs.py\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgfrerer%2Fisland","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftgfrerer%2Fisland","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgfrerer%2Fisland/lists"}