Gears-Vk + Auto-Vk

Gears-Vk rendering framework for the Vulkan 1.2 API, implemented in modern C++, using C++17 and C++20 features.
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.

Gears-Vk is ready to go. If your system meets the system requirements (see section Installation below), everything is set up to build an run right out of the box. Just open visual_studio/gears-vk.sln, set one of the example projects as startup project, build and run.

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.

Installation

Currently, only Windows is supported as a development platform. The project setup is provided for Visual Studio 2019.

Requirements:

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

Setup and build instructions:

• Clone this repository
• Execute a git submodule update --init to pull the Auto-Vk framework which is added as a submodule under auto_vk
• Open the Visual Studio solution file visual_studio/gears-vk.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 Gears-Vk 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/Gears-Vk.git gears_vk to add Gears-Vk as submodule in directory gears_vk.
• Execute git submodule update --init --recursive in order to pull both, Gears-Vk and the Auto-Vk framework.
• The steps described under section Creating a New Project might be helpful for setting up a custom Visual Studio project that links agains Gears-Vk.

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 Gears-Vk library project gears-vk.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 <gvk.hpp> to use Gears-Vk.
• After these steps, you should be able to successfully link against Gears-Vk build your newly created project.

A good strategy is to add Gears-Vk 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 Gears-Vk's master branch to get the latest updates.

Resource Mangement and the Post Build Helper

Gears-Vk'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:

• 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 Gears-Vk and Auto-Vk?

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

Gears-Vk establishes the missing link to the operating system -- in this case Windows 10 -- and adds further functionality:

• Rendering environment configuration, such as enabling Vulkan extensions (e.g. if VK_KHR_raytracing 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 gvk::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: gvk::transform
• A ready to use user-controllable camera class gvk::quake_camera (which is derived from both, gvk::transform and gvk::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 (gvk::material and gvk::material_gpu_data)
• Lightsource loading and conversion into a GPU-suitable format (gvk::lightsource and gvk::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.

Automatic Resource-Updates

See: Automatic Resource-Updates

FAQs, Known Issues, Troubleshooting

Q: Can Gears-Vk be used on Linux?
A: Not yet. Auto-Vk, however, can.

Q: Can Gears-Vk 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

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