Auto-Vk-Toolkit v0.99

Auto-Vk-Toolkit (formerly "Gears-Vk") is a framework for the Vulkan graphics API, implemented in modern C++. It aims to hit the sweet spot between programmer-convenience and efficiency while still supporting full Vulkan functionality. To achieve this goal, this framework uses Auto-Vk, a convenience and productivity layer atop Vulkan-Hpp.

Auto-Vk-Toolkit has been successfully used for rapid prototyping, research (e.g., Conservative Meshlet Bounds for Robust Culling of Skinned Meshes), and teaching (e.g., Algorithms for Real-Time Rendering).

This image showcases some work that has been developed using Auto-Vk-Toolkit (from left to right): Usage in an advanced graphics course for teaching modern low-level GPU concepts; post-processing graphics effects; division of meshes into meshlets and rendering them with fine-grained view-frustum and backface culling in task and mesh shaders; ray traced shadows and reflections using the hardware-accelerated real-time ray tracing device extensions.

Some of its highlight-features (besides the awesome features of Auto-Vk) include:

• Window management and input handling through GLFW.
• Render loop framework with update() and render() callbacks at varying or fixed update times.
• Powerful Auto-Vk-avk::root implementation, with swap chain handling and automatic resource lifetime management.
• Versatile updater which enables swapchain recreation.
• In combination with a powerful Post Build Helper tool (Windows-only), the updater enables shader hot reloading.
• Model loading of a variety of 3D scenes with the help of assimp.
• Loading of .fscene files from the ORCA: Open Research Content Archive.
• Loading of a multitude of image formats, including cube maps.
• Versatile serializer support which allows to serialize Vulkan resources such as avk:buffer or avk::image instances, and also custom types; based on cereal.
• User interface support through ImGui with support for displaying textures in the UI.
• Support for real-time ray tracing (RTX) and convenient building of acceleration structures from triangle meshes or AABBs.
• Support for dividing meshes into meshlets which can be rendered with task and mesh shaders.
• Handling of bone hierarchies, supporting animation of skinned meshes.

Table of Contents

• Installation
  • Visual Studio 2022
    • Requirements
    • Setup and build instructions
    • Set up your own project
  • CMake
• Examples
• Creating a New Project
• Resource Mangement and the Post Build Helper
• What's the difference between Auto-Vk-Toolkit and Auto-Vk?
• Documentation
• FAQs, Known Issues, Troubleshooting

Installation

Auto-Vk-Toolkit is ready to go with Visual Studio or CMake. If your system meets the system requirements, everything is set up to build an run right out of the box. E.g., for Visual Studio, open visual_studio/auto_vk_toolkit.sln, set one of the example projects as startup project, build and run!

Hint: The version on the development branch might be more up-to-date and contain additional features and fixes. Please consider using that version, especially if you encounter problems.

Note: At the first run, the Post Build Helper tool is being built. Watch Visual Studio's "Output" tab for status messages and possible instructions.

Visual Studio 2022

A preconfigured project setup is provided for Visual Studio 2022 on Windows.

Requirements

• Windows 10 or 11
• Visual Studio 2022 with a Windows 10 or 11 SDK installed (For detailed information about project setup and resource management please refer to visual_studio/README.md.)
• A Vulkan SDK from LunarG, optimally Vulkan SDK 1.3.250.0 or newer.

Setup and build instructions

• Clone or download this repository
• Execute git submodule update --init to pull the Auto-Vk framework which is added as a submodule under auto_vk
• Download and install one of the latest Vulkan SDKs for Windows! (At time of writing, the most recent version is 1.3.250.0.)
  • Select the Vulkan Memory Allocator header. option so that the Vulkan Memory Allocator (VMA) library is installed.
  • Note: VMA can be installed through the Vulkan installer or its maintenance tool (e.g., maintenancetool.exe on Windows) by selecting the Vulkan Memory Allocator header. option.
• Download and install Visual Studio Community 2022, or a newer version.
  • Select the Desktop development with C++ workload in the installer!
• Recommended: Install the GLSL language integration extension for syntax highlighting in shader files!
  • Hint: Go to Tools -> Options -> GLSL language integration. For Vulkan shader development, either set Live compiling to False (syntax highlighting only), or set the External compiler executable file to, e.g., the path to glslangValidator.exe!
• Open the Visual Studio solution file visual_studio/auto_vk_toolkit.sln, and build the solution
• During building, you'll recognize messages from the Post Build Helper tool in Visual Studio's Output-tab, some popup messages, and an icon in the system tray. Please have a look at section Resource Mangement and the Post Build Helper for additional information.
• Several example applications are available in the solution file. Set one of them as startup project, and run.

Set up your own project

• To add Auto-Vk-Toolkit to one of your custom repositories, you might want to add it as a GIT submodule. You could execute git submodule add https://github.com/cg-tuwien/Auto-Vk-Toolkit.git auto_vk_toolkit to add Auto-Vk-Toolkit as submodule in directory auto_vk_toolkit.
• Execute git submodule update --init --recursive in order to pull both, Auto-Vk-Toolkit and Auto-Vk.
• The steps described under section Creating a New Project might be helpful for setting up a custom Visual Studio project that links against Auto-Vk-Toolkit.
• The most convenient way to set up you own project might be one of the starter templates:
  • Starter template for Visual Studio-based projects: Auto-Vk-Toolkit-VS-Starter
  • Starter template for CMake-based projects: Auto-Vk-Toolkit-Starter

CMake

Please see docs/cmake.md!

Examples

Hello World	Multiple Queues	Compute Image Processing	ORCA Loader

Several example applications are included in this repository:

• Hello World: How to render one single triangle
• Vertex Buffers: How to use vertex buffers with graphics pipelines
• Framebuffer: How to create and use framebuffers
• Multi Invokee Rendering: How to use multiple invokees, how your application could be structured
• Multiple Qeues: How to utilize multiple queues (two transfer and one graphics queue)
• Compute Image Processing: How to use compute shaders for some image processing
• Present From Compute: How to present to the swap chain from a compute queue
• Model Loader: How to load 3D models from file and render them
• ORCA Loader: How to load ORCA .fscene files and render them; also how to use the serializer
• Static Meshlets: How to divide a 3D model into small meshlets and render them using task and mesh shaders
• Skinned Meshlets: How to divide an animated, skinned 3D model into small meshlets and how to animate and render that using task and mesh shaders
• Ray Tracing With Shadows and AO: How to build acceleration structures from triangle meshes and create a ray-traced image. Additionally adds ray traced shadows and a very simple (and ugly) version of ambient occlusion to the rendered result by recursive ray tracing from closest hit shaders.
• Ray Query in Ray Tracing Shaders: Similar to the "Ray Tracing With Shadows and AO" Example, but instead of recursive ray tracing with a shader binding table etc., it simply uses ray queries from closest hit shaders to achieve the same result.
• Ray Tracing Custom Intersection: How to build acceleration structures from AABBs and from triangle meshes.
• Texture Cubemap: How to load and use cube maps.

Skinned Meshlets	Ray Query and Ray Tracing	RTX Custom Intersection	Texture Cubemap

Creating a New Project

For Visual Studio projects, there is a convenience tool under visual_studio/tools/executables/ that can help to quickly set up a new project by copying an existing one (e.g. one of the example applications): create_new_project.exe

Use it like follows to create a copy of an existing project:

• Open create_new_project.exe and either select one of the example applications or enter the path to the project to be copied manually.
• Enter the target location, the target project name, and hit the [Create it!]-button.
• The project is copied to the target folder and all relative paths are adapted to the new location if the target folder is on the same drive as the source project. (If it is not, absolute paths are set.)
• Asset references and shader references are retained and their paths are adapted.
  Attention: Make sure to remove the existing references if you are going to modify the referenced assets/shaders! You'll have to create copies of these files manually and add references to the copies instead. If you fail to do so, you'll end up modifying the stock assets or the examples' shader files.
• Precompiled headers are disabled in the newly created project copy. If you'd like to use this feature, you'll have to manually enable it in Visual Studio's project settings.
• Manually add a reference to the Auto-Vk-Toolkit library project auto_vk_toolkit.vxcproj to your Visual Studio solution and ensure that the newly created project copy references it.
• All source and include file references are removed from the newly created project copy. You'll have to add at least a .cpp file containing a main() function.
• Add #include <auto_vk_toolkit.hpp> to use Auto-Vk-Toolkit.
• After these steps, you should be able to successfully link against Auto-Vk-Toolkit build your newly created project.

A good strategy is to add Auto-Vk-Toolkit as a git submodule to your repository and use create_new_project.exe and the steps above to create a properly configured project in a directory outside of the submodule. Make sure to frequently update the submodule by pulling from Auto-Vk-Toolkit's master branch to get the latest updates.

Resource Mangement and the Post Build Helper

Auto-Vk-Toolkit's Visual Studio projects are configured so that Visual Studio itself can be elegantly used for resource management. That means, required assets (3D models, images, ORCA scene files) and shader files can just be added to Visual Studio's filters in the "Solution Explorer" view and a smart Post Build Helper tool ensures that those resources are deployed to the application's target directory.

In short/TL;DR:

• Add required 3D models, images, and ORCA scenes to the assets filter, and
• add required shader files to the shaders filter directly in Visual Studio. Then build the application, wait for the Post Build Helper to deploy these resources to the target directory, and run your application!

This can look like follows, where the filters assets and shaders have special meaning, as hinted above:

A more detailed explanation and further instructions are given in visual_studio/README.md.

You will notice Post Build Helper activity through its tray icon: . The tool will remain active after deployment has finished for two main reasons:

• It allows to investigate logs from previous build events, and also change settings.
• It continues to monitor resource files which is especially important to enable shader hot reloading.

For more information about the Post Build Helper, please refer to the Post Build Helper section, and for more information about shader hot reloading, please refer to the Automatic Resource-Updates section below.

What's the difference between Auto-Vk-Toolkit and Auto-Vk?

Auto-Vk is a platform-agnostic convenience and productivity layer atop Vulkan-Hpp.

Auto-Vk-Toolkit establishes the missing link to the operating system, like window handling, and adds further functionality:

• Rendering environment configuration, such as enabling Vulkan extensions (e.g. if VK_KHR_ray_tracing_pipeline shall be used, it selects an appropriate physical device and enables required flags and extensions)
• Window management (through GLFW)
• Game-loop/render-loop handling with convenient to use callback methods via the avk::invokee interface (such as initialize(), update(), render(), where the former is called only once and the latter two are invoked each frame)
• User input handling
• A ready to use base class for object hierarchies: avk::transform
• Ready to use user-controllable camera classes avk::quake_camera and avk::orbit_camera (derived from both, avk::transform and avk::invokee)
• Resource loading support for:
  • Images
  • 3D Models
  • Scenes in the ORCA format, see: ORCA: Open Research Content Archive
• Material loading and conversion into a GPU-suitable format (avk::material and a vk::material_gpu_data)
• Lightsource loading and conversion into a GPU-suitable format (avk::lightsource and avk::lightsource_gpu_data)
• Resource handling via Visual Studio's filters, i.e. just drag and drop assets and shaders that you'd like to use directly into Visual Studio's filter hierarchy and get them deployed to the target directory.
• A powerful Post Build Helper tool which is invoked as a custom build step.
  • It deploys assets and shaders to the target directory
  • Shaders are compiled into SPIR-V
  • If shader files contain errors, popup messages are created displaying the error, and providing a [->VS] button to navigate to the line that contains the error within Visual Studio.
  • By default, "Debug" and "Release" build configurations symlink resources to save space, but "Publish" build configurations deploy all required files into the target directory so that a built program can easily be transfered to another PC. No more tedious resource gathering is required in such situations since that is all handled by the Post Build Helper.

Documentation

There are some documentation pages containing further information:

• Usage of ImGui for User Interfaces, describing how to use Dear ImGui in an Auto-Vk-Toolkit project
• CMake setup and build instructions
• Meshlets-specfic functionality for dividing geometry into small clusters and using them for rendering in graphics mesh pipelines (those with task and mesh shaders)
• Serializer functionality for storing and loading resources to/from file, such as 3D models, images, or custom structs
• Automatic Resource-Updates through the avk::updater class, enabling shwapchain recreation and shader hot reloading

FAQs, Known Issues, Troubleshooting

Q: Can Auto-Vk-Toolkit be used on Linux?
A: Yes. Please see the CMake documentation at docs/cmake.md!

Q: Can Auto-Vk-Toolkit be used without the Post Build Helper?
A: Yes. The Post Build Helper is a convenience tool that handles resource deployment, asset dependencies, and also file updates (useful for shader hot reloading, depending on the project structure). If you're not using it, you'll have to manage deployment of resources, and compilation of shader files into SPIR-V manually.

Q: I have troubles with asset management in Visual Studio. Any advice?
A: Check out Known Issues and Troubleshooting w.r.t. Asset Handling, which offers guidelines for the following cases:

• Build errors when adding assets
• Asset is not deployed because it is not saved in the Visual Studio's filters-file

Q: More resources have been deployed than I have added to Visual Studio's filters. What's going on?
A: Some assets reference other assets internally. For example, 3D models often reference images or material files (in case of .obj models). These "dependent assets" are also deployed to the target directory by the Post Build Helper. Please see Deployment of Dependent Assets for more details.

Q: What are the differences between Debug, Release, and Publish build configurations?
A: In terms of compilation settings, Release and Publish configurations are the same. They link against Release builds of libraries. Debug configuration has classical debug settings configured for the Visual Studio projects and links against Debug builds of libraries. There is, however, a difference between Publish builds and non-Publish builds w.r.t. the deployment of resources. Please see Symbolic Links/Copies depending on Build Configuration for more details.

Q: I have troubles with the Post Build Helper. What to do?
A: Check out Post Build Helper, which offers guidelines for the following cases:

• Build is stuck at "Going to invoke[...]MSBuild.exe" step, displayed in Visual Studio's Output tab
• Post Build Helper can't be built automatically/via MSBuild.exe
• Too few resources are being deployed
• Application could not start at first try (maybe due to missing assets or DLLs)
• Error message about denied access to DLL files (DLLs are not re-deployed)
• Slow performance when showing lists within the Post Build Helper
• Error message in the UI of Post Build Helper: "Could not find part of the path '...'"
• Error message in the console: can't fopen, or !RUNTIME ERROR! Couldn't load image from '...' or similar

Q: The application takes a long time to load assets like 3D models and images. Can it be accelerated?
A: If you are referring to Debug builds, you can configure Post Build Helper so that it deploys Release DLLs of some external dependencies even for Debug builds. They should accelerate asset loading a lot. To enable deployment of Release DLLs, please open Post Build Helper's settings and enable the option "Always deploy Release DLLs".

Q: Getting cereal::Exception in cereal::loadBinary, or Unhandled exception at 0x00007FFE82204FD9 in ...exe: Microsoft C++ exception: cereal::Exception at memory location ...
A: Your serialized cache file (e.g., for sponza_and_terrain.fscene this could be sponza_and_terrain.fscene.cache) has become corrupt (maybe because it was not fully written due to a previously occured error in the application, or because execution was aborted). Delete the cache file (e.g., sponza_and_terrain.fscene.cache) and let a new one be generated!