For now, Illusion is a convenience layer on top of Vulkan, similar in spirit to V-EZ. However, I plan to add more features as I progress in learning. Since everybody loves badges, here are some describing Illusion:
Illusion uses C++17 and can be build on Linux (gcc or clang), Windows (msvc) and OS X (xcode). Nearly all dependencies are included as git submodules, please refer to the section Building Illusion in order to get started.
I try to add as many comments to the source code as possible. The number of source code lines and comment lines above is computed with the script cloc.sh. This script only counts real comments. Any dumb comments (such as copy-right headers or stuff like /////////) are not included in this number.
- Vulkan convenience layer
- Automatic Vulkan object lifetime management using reference counting
- Automatic resource re-creation on swapchain changes
- Very readable validation error messages since Illusion forces you to assign descriptive names to each and every Vulkan object (using
PFN_vkSetDebugUtilsObjectNameEXT) - Explicit graphics state per command buffer
- Explicit binding state per command buffer
- Explicit specialization constants state per command buffer
- A ring-buffer for per-frame resources
- Per-frame resource count is independent from swapchain image count
- Automatic image layout transitions
- ...
- Frame graph
- Automatically create render passes and subpasses with dependencies
- Automatically create framebuffer attachments
- Automatic image layout transitions of the framebuffer attachments
- Texture input support
- Async compute
- Parallel render pass recording
- Parallel subpass recording
- In-depth testing 😬
- ...
- Window creation using glfw
- Mouse and joystick input using glfw
- Shader support
- Loading from Spir-V, GLSL and HLSL using glslang - if you feel adventurous you can even mix GLSL and HLSL modules in one shader program 😬
- Shader includes using
#extension GL_GOOGLE_include_directive - Automatic reloading of shaders when source file changed on disc
- Automatic shader program reflection using spirv-cross
- Automatic creation of pipeline layouts
- Automatic allocation and updates of descriptor sets
- Texture support
- LDR and HDR texture loading using stb (hdr, jpg, png, tga, bmp, ...)
- DDS texture loading using gli
- Automatic mipmap generation
- Conversion of equirectangular panoramas to cubemaps using compute shaders
- Creation of prefiltered irradiance and reflectance maps for physically based shading using compute shaders
- Creation of the BRDFLuT for physically based shading using compute shaders
- Saving textures to files
- glTF loading using tinygltf
- Metallic-roughness materials
- Specular-glossiness materials
- Animations
- Skins
- Morph targets
- Sparse accessors
- Multiple texture coordinates
- Multiple scenes
- Signal-Slot implementation using only C++ standard library
- Command line parsing using only C++ standard library
When compiled with the commands below, the examples will be located in illusion/build/install/bin. You can run them either by double-clicking or from the command line. For Linux, there is a shell script to start each example which sets the environment variables required for Vulkan.
The list below is roughly sorted by complexity. So if you want to learn features of Illusion step-by-step you can have a look at the example's code in that order.
| Link | Core Utility Examples | Screenshot |
|---|---|---|
| Signal Slot | This very small example shows some basic usage of Illusion's Signals and Properties. You can read some information on the implementation on my blog. |  |
| Command Line | This small example shows how to use Illusion's very basic command line parser. Use CommandLine --help to see the options. |
 |
| Link | Low-level Vulkan Examples | Screenshot |
| GPU Info | This minimal example creates a Vulkan instance and prints a very verbose list of your Vulkan implementation's hardware and software capabilities. |  |
| Headless | This rather simple example renders an image and save it to a file. This is done in headless-mode - no window or swapchain is created. |  |
| Triangle | A simple triangle without vertex or index buffers that uses a pre-recorded command buffer and no per-frame resources. |  |
| Specialization Constants | Similar to the Triangle example, but here three triangles are drawn with one shader program. For each triangle some specialization constants are set to different values. |  |
| Textured Quad | Similar to the triangle, in addition a texture is loaded and bound as fragment shader input. This example can either use GLSL or HLSL shaders. Use TexturedQuad --help to see the options. |
 |
| Shader Sandbox | An example similar to ShaderToy. You can specify a fragment shader on the command line and it will be automatically reloaded when it changes on disc. Use ShaderSandbox --help to see the options. |
 |
| Textured Cube | A more complex example using vertex buffers and an index buffer. Camera information is uploaded as uniform buffer, the cube's transformation is set via push constants. The command buffer is re-recorded every frame. The uniform buffer and the command buffer are per-frame resources. |  |
| glTF-Viewer | A viewer for glTF files. There are several command line options; have a look at GltfViewer --help. Most glTFSample Models are supported, including those with skinned animations. |
 |
| Deferred Rendering | A small test application for the frame graph implementation. It's still work-in-progress and will evolve as the frame graph gets more mature. You can adjust the number of light sources; have a look at DeferredRendering --help. |
 |
Illusion uses CMake for project file generation. Below are some exemplary instructions for Linux and Windows (here Visual Studio 2017) which you should adapt to your system.
Nearly all dependencies are included as git submodules. Additionally you will need a C++ compiler, python3 and CMake. The following submodules are included in this repository and automatically build together with Illusion:
| Submodule | Description |
|---|---|
| glfw | Used for window creation. |
| gli | Used for loading of dds textures. |
| glm | Used as math library. |
| stb | Used for loading of LDR and HDR textures. |
| glslang | Used to compile GLSL to Spir-V |
| spirv-cross | Used for shader program reflection. |
| tinygltf | Used for loading of gLTF models. |
| vulkan-headers | This is usually part of the Vulkan SDK. In Illusion the Vulkan SDK is basically included in the submodules. This simplifies continuous integration. |
| vulkan-loader | Same as above. |
| vulkan-validation-layers | Same as above. |
| spirv-tools | Dependency of vulkan-validation-layers. |
| spirv-headers | Dependency of vulkan-validation-layers. |
git clone https://github.com/schneegans/illusion.git
cd illusion
git submodule update --init
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install ..
make -j installThen you can execute an example with:
install/bin/Triangle.shgit clone https://github.com/schneegans/illusion.git
cd illusion
git submodule update --init
mkdir build
cd build
cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_INSTALL_PREFIX=install ..
cmake --build . --target installThen you can execute an example with:
cd install\bin
Triangle.exeFor now, there is no documentation in addition to the example applications and the inline code comments. This will change once the API is more or less stable. Right now, entire classes may change completely in one commit.
Here are some resources I am using while developing this software.
- Vulkan Tutorial: A great starting point for learning Vulkan.
- Tutorials by Sascha Willems: In particular the glTF example was very useful to understand some concepts.
- V-EZ: Especially the shader reflection of Illusion is based on code of V-EZ.
- Granite: I learned a lot from this great Vulkan engine.
- glTF sample models: These are very usefulf!
- HDRI Haven: Thank you Greg Zaal for your awesome work!
- icons8.com: Some great icons!
- shields.io: Some great badges!
Copyright (c) 2018-2019 Simon Schneegans
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.