Skip to content

For now, Illusion is a convenience layer on top of Vulkan. However, I plan to add more features as I progress in learning.

License

Notifications You must be signed in to change notification settings

Schneegans/illusion

Repository files navigation

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:

Build Status Coverage Status license c++17 source loc example loc test loc comments gitter

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.

Features

  • 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

Included Examples

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. screenshot
Command Line This small example shows how to use Illusion's very basic command line parser. Use CommandLine --help to see the options. screenshot
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. screenshot
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. screenshot
Triangle A simple triangle without vertex or index buffers that uses a pre-recorded command buffer and no per-frame resources. screenshot
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. screenshot
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. screenshot
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. screenshot
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. screenshot
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. screenshot
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. screenshot

Building Illusion

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.

Dependencies

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.

Linux

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 install

Then you can execute an example with:

install/bin/Triangle.sh

Windows

git 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 install

Then you can execute an example with:

cd install\bin
Triangle.exe

Documentation

For 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.

Credits

Here are some resources I am using while developing this software.

MIT License

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.

About

For now, Illusion is a convenience layer on top of Vulkan. However, I plan to add more features as I progress in learning.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published