Vulkan Launchpad Starter 🚀

Starter template for a project based on Vulkan Launchpad

Sections:

• Setup Instructions
• Documentation

Setup Instructions

Note: These setup instructions are an extended edition of Vulkan Launchpad's.

Vulkan Launchpad runs on Windows, macOS, and Linux. For building you'll need Git, the Vulkan SDK, a C++ compiler, CMake, and optimally an integrated development environment (IDE). In the following, we describe setup instructions for common operating systems and editors/IDEs (click the links in the table of contents to jump to the sections that are relevant to your chosen setup):

• Operating Systems
  • Windows
  • macOS
  • Linux
    • Ubuntu and Linux Mint
    • Fedora Workstation
    • Manjaro
• Editors and IDEs
  • Visual Studio Code (VS Code)
  • Visual Studio 2022 Community
  • Xcode
  • Other IDEs
• Troubleshooting
  • Submodule Updates Take a Long Time
  • On macOS: CMake cannot find C/CXX compiler
  • On macOS: CMake cannot find Vulkan
  • ERROR: No GLFW window created

Operating Systems

Windows

• Download and install Git for Windows!
  • Add Git to your PATH! This can be done through the installer, selecting the Git from the command line and also from 3rd-party software option.
• Download and install one of the latest Vulkan SDKs for Windows! (At time of writing, the most recent version is 1.3.243.0.)
  • Note: It is not required to install any optional components, if you make only x64 builds.
• Download and install the Microsoft Visual C++ compiler (MSVC) by installing the Build Tools for Visual Studio 2022 or a newer version!
  • Select the Desktop development with C++ workload in the installer!
  • Note: Should you decide to install Visual Studio Community 2022 (as described below), you don't have to install the Build Tools for Visual Studio 2022 separately. Also in this case of using the Visual Studio Community 2022 installer, ensure to select the Desktop development with C++ workload!
• Download and install CMake through its Windows x64 Installer!
  • Select an option to Add CMake to the system PATH ... during installation!
  • Important: Ensure to get CMake version 3.22 or newer!

macOS

• Download and install Xcode from the Mac App Store!
  • Install the Xcode Command Line Tools by executing xcode-select --install from command line. This will install Git on your system.
• Download and install one of the latest Vulkan SDKs for macOS! (At time of writing, the most recent version is 1.3.243.0.)
  • Note: If you are using a Mac which runs on Apple silicon, it could happen that a popup asks you to install Rosetta. Please confirm, even though we are going to use native Apple silicon libraries.
  • Important: Make sure to tick the box called System Global Installation during installation so the Vulkan SDK can be found by the build system.
• Download and install CMake through its macOS universal Installer or through a package manager like Homebrew!
  • Note: The official website installer will not automatically add CMake to the system PATH. If you are planning to use CMake from the command line, you need to open the CMake app, go to Tools -> How to Install For Command Line Use and execute one of the three instructions listed.
  • Important: Ensure to get CMake version 3.22 or newer!

Linux

Requirements: C++ Compiler, Git, CMake, Vulkan SDK, X.Org and Vulkan compatible driver.

In case you want to use Ninja or other development tools please install them separately. The instructions below are the minimum dependencies to build Vulkan Launchpad.

Ubuntu and Linux Mint

# Jammy Jellyfish (Ubuntu 22.04/22.10 and Linux Mint 21.0/21.1)
# Add LunarG public key
wget -qO- https://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo tee /etc/apt/trusted.gpg.d/lunarg.asc
# Add Vulkan package
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-jammy.list http://packages.lunarg.com/vulkan/lunarg-vulkan-jammy.list
# Focal Fossa (Ubuntu 20.04/20.10 and Linux Mint 20.0/20.1/20.2/20.3)
# Add LunarG public key
wget -qO - http://packages.lunarg.com/lunarg-signing-key-pub.asc | sudo apt-key add -
# Add Vulkan package
sudo wget -qO /etc/apt/sources.list.d/lunarg-vulkan-focal.list http://packages.lunarg.com/vulkan/lunarg-vulkan-focal.list

# Update package manager
sudo apt update
# Install dependencies
sudo apt install git cmake build-essential xorg-dev libvulkan-dev vulkan-headers vulkan-validationlayers

Fedora Workstation

sudo dnf install cmake gcc-c++ libXinerama-devel vulkan-loader-devel vulkan-headers vulkan-validation-layers-devel
sudo dnf -y groupinstall "X Software Development"

Manjaro

sudo pacman -Sy cmake base-devel vulkan-validation-layers

Editors and IDEs

Visual Studio Code (VS Code)

• Download and install Visual Studio Code!
  • Select the option Add "Open with Code" action to Widows Explorer directory context menu for more convenience.
• Install the following extensions (navigate to View -> Extensions):
  • CMake Tools (which will also install the CMake extension)
  • C/C++
  • Recommended: Shader languages support for VS Code
  • Restart VS Code, or execute the comand Developer: Reload Window!
• Open the folder containing the CMakeLists.txt file (the root folder of this repository)!
  • This can be accomplished through File -> Open Folder..., you might also get the option to Open with Code from a folder's context menu in Windows Explorer.
• Execute the following commands (either through Show All Commands, which can be activated by default via Ctrl+Shift+P or Cmd+Shift+P (macOS), or you'll also find buttons for these actions at the bottom of the VS Code window):
  • CMake: Select a Kit then select, e.g., Visual Studio Build Tools 2022 Release - amd64 (if you are using Windows and have installed the Build Tools for Visual Studio 2022).
  • CMake: Select Variant and select Debug for a build with debug information, or Release for one without.
  • The above command should also trigger CMake's configuration step. If it doesn't, execute CMake: Configure!
  • CMake: Build Target, then select VulkanLaunchpadStarter EXECUTABLE to build Vulkan Launchpad Starter as an executable. Alternatively, just build everything by selecting ALL_BUILD.
  • CMake: Debug to start debugging the the selected target (default shortcut: Ctrl+F5).
  • CMake: Run to start debugging the the selected target (default shortcut: Shift+F5).

Note: Vulkan Launchpad Starter comes with a .vscode/settings.json file which configures the current working directory to be the workspace root folder, which can be especially helpful when loading files from paths relative to the workspace root (like shader files). Furthermore, configures an external console window to be shown, which might allow to focus better on messages printed to the console.

Visual Studio 2022 Community

• Download and install Visual Studio Community 2022, or a newer version.
  • Select the Desktop development with C++ workload in the installer!
  • Should you encounter CMake-related problems, install one of the latest versions of CMake after installing Visual Studio Community 2022 using the Windows x64 Installer.
    • Ensure to select an option to Add CMake to the system PATH ... during installation!
    • Important: Ensure to get CMake version 3.22 or newer!
• 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 folder containing the CMakeLists.txt file (the root folder of this repository)!
  • This can be accomplished through File -> Open -> Folder..., you might also get the option to Open with Visual Studio from a folder's context menu in Windows Explorer.
  • You should be able to observe in the Output tab that CMake generation started.
    • If not, check if the Show output from: combobox is set to the option CMake!
    • Wait a bit until you see the message CMake generation finished..
  • Execute Build -> Build All (default shortcut: Ctrl+Shift+B) to build Vulkan Launchpad Starter as an executable (and also builds all the other targets).
• To debug or run the executable, please select the VulkanLaunchpadStarter.exe (in workspaceRoot) item from the Select Startup Item combobox. F5 starts debugging the selected item, Ctrl+F5 runs the selected item without debugging.
  Note: The difference to the VulkanLaunchpadStarter.exe item (i.e., without "(in workspaceRoot)") is that the suggested item VulkanLaunchpadStarter.exe (in workspaceRoot) configures the current working directory to be the workspace root folder, which can be especially helpful when loading files from paths relative to the workspace root (like shader files).
  This is configured via the .vs/launch.vs.json config file.

Xcode

• Download and install Xcode from the Mac App Store!
• Generate the Xcode project files:
  • Command line option:
    • Open a terminal window at the workspace root directory. This can be done by right clicking the folder and selecting New Terminal at Folder.
    • Option 1: Execute make from the terminal. This uses the included makefile located in the workspace root directory. Project files can be found in _project afterwards.
    • Option 2: Execute cmake -H. -B_project -G "Xcode" -DCMAKE_INSTALL_PREFIX="_install" from the terminal.
  • CMake Gui option:
    • Open the CMake Gui and specify the workspace root directory as the source directory. Specify a folder into which the generated project files should be stored. Click Configure, select Xcode as the Generator and press Done. After completion, press Generate.
• Open VulkanLaunchpadStarter.xcodeproj with Xcode. The file should be located in the folder into which the project files were generated.

Other IDEs

Other IDEs (such as CLion or Qt Creator) are usable too as long as they support CMake. Please consider the following remarks for the setup process:

• Make sure to set the working directory to the workspace directory.

Troubleshooting

Submodule Updates Take a Long Time

In case you experience problems concerning the submodule checkout, i.e. the cloning of the submodules (GLFW, GLM or glslang) takes a long time or seems to be stuck, please try the following approach:

• Please clone the repo manually in a terminal in a new location using the following git commands:

  git clone --recurse-submodules https://github.com/cg-tuwien/VulkanLaunchpadStarter.git

On macOS: CMake cannot find C/CXX compiler

In case you had an existing XCode Command Line Tools installation, this error may occur during cmake generation. You can try: bash xcode-select --reset

On macOS: CMake cannot find Vulkan

This may be the case, if you forgot to select System Global Installation during the Vulkan SDK installation, leading to errors during cmake generation, as the location of the Vulkan libraries cannot be found. You can install it retroactively by executing the MaintenanceTool.app in the VulkanSDK folder and selecting System Global Installation as a component to add.

ERROR: No GLFW window created

You have followed the setup instructions, you have built the executable, you run it and you receive an error message which says:

ERROR:   No GLFW window created.

This is exactly what you should see if you haven't already implemented anything, but just built&run Vulkan Launchpad Starter as-is.
Look for // TODO: comments in the code to get an idea what is requiried next in order to finish setup, like creating a GLFW window, creating a Vulkan instance, selecting a physical device, etc.

Documentation

Vulkan Launchpad Starter represents a project setup for an executable that links the Vulkan Launchpad framework. Therefore, all of Vulkan Launchpad's functionality is provided here. Please have a look at Vulkan Launchpad's Documentation to get an overview of its functionality!

Vulkan Launchpad Starter adds the following functionality:

Vulkan Helpers:

• struct HlpGeometryHandles: Struct intended for storing a bunch of geometry buffers.
• hlpIsInstanceExtensionSupported: Test if a given extension is supported by the Vulkan instance.
• hlpIsInstanceLayerSupported: Test if a given layer is supported by the Vulkan instance.
• hlpSelectPhysicalDeviceIndex: Select a physical device index that supports graphics and presentation.
• hlpGetPhysicalDeviceSurfaceCapabilities: Gets a given physical device's surface capabilities.
• hlpGetSurfaceImageFormat: Get a suitable image format for a surface.
• hlpGetSurfaceTransform: Get a surface's current transform.
• hlpRecordPipelineBarrierWithImageLayoutTransition: Record a pipeline barrier with some default parameter and an image layout transition into a command buffer.
• hlpRecordCopyBufferToImage: Copy a buffer's contents into the first mip level and first layer of an image.
• hlpCreateImageView: Creates a VkImageView for the first mip level and first layer of a VkImage.
• hlpDestroyImageView: Corresponding 👆 destruction function.
• hlpCreateSampler: Create a VkSampler with some default parameters.
• hlpDestroySampler: Corresponding 👆 destruction function.

Teapot Functionality:

• teapotCreateGeometryAndBuffers: Create the geometry of a teapot model and stores it internally.
• teapotDestroyBuffers: Corresponding 👆 destruction function.
• teapotDraw: Draws a teapot into the (Vulkan Launchpad-internally handled) current command buffer. There are multiple overloads:
  • One that takes no parameters
  • One that takes a custom VkPipeline and uses that for drawing.
  • One that takes a custom VkPipeline and a VkDescriptorSet as parameters. The VkDescriptorSet is bound before the teapot is drawn with the VkPipeline.
• teapotGetPositionsBuffer: Gets a VkBuffer handle containing the teapot's positions.
• teapotGetIndicesBuffer: Gets a VkBuffer handle containing the teapot's indices.
• teapotGetNumIndices: Gets the number of indices contained in the buffer returned by 👆 teapotGetIndicesBuffer.