Auto-Vk-Toolkit v1.0.1

Auto-Vk-Toolkit 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, Fast Rendering of Parametric Objects on Modern GPUs), 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; visualization of 19,600 spherical harmonics glyphs from a brain scan; 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; rendering of 358k parametrically-defined fiber curves in real time.

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 1.3 or 1.4 SDK from LunarG

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!
  • 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 c