Getting Started

discord

If you have any trouble, please open a ticket on GitHub or join our Discord server

Required Hardware

  • You need a graphics card with support for Vulkan API 1.3 for both development and also for just running the engine.

  • Use Vulkan Hardware Database to get extensive information about a graphics card’s Vulkan API support.

  • We will stick to Vulkan API 1.3 for a long time to come and we want to implement all desired features from Vulkan 1.3 before updating to a newer version.

  • Older versions of Vulkan API (1.0, 1.1, and 1.2) are no longer supported and will not be supported again in the future.

  • We do not support other graphics APIs such as DirectX or OpenGL and we will not support them in the future.

Supported Platforms

  • We support Windows 11 and Linux distributions for which Vulkan drivers exist.

  • We do not support macOS or iOS and we will not support it in the future because it would require us to use MoltenVK abstraction layer for Apple’s Metal API to get Vulkan running on those devices.

  • We do not yet support Android because this will likely require fundamental changes to the engine, but maybe we will support it in the future.

Required Software for Development

Tip

Update your graphics drivers and also your Vulkan SDK as frequently as possible! Updates contain bug fixes, new features, and performance improvements. Both your gaming experience and your game development experience will benefit from this.

This project uses out-of-source builds with gcc and clang on Linux as well as Microsoft Visual Studio 2022 and Clang/LLVM for Visual Studio on Windows. Our Continuous Integration (CI) on GitHub uses all four of those compilers to build both debug and release configuration in our nightly build.

In addition to one of these compilers, the following software is required for building the code:

Vulkan SDK

The Vulkan SDK contains the libraries and tools which are required to work with Vulkan API.

CMake

The build system to generate the project files for building the engine, shaders, and documentation.

Git

Git version control is used to download (clone) the source code from GitHub.

If you also want to build the documentation, you’ll need the following software in addition to the software required for building the code:

Python with pip

Generates the documentation of the project with Sphinx

Doxygen

Generates the C++ documentation based on the comments in the source code.

Optional Software

Visual Studio Code

A powerful, free, and open-source text editor.

GitHub Desktop

An open source Git user interface which is easy to use.

Ninja Build System

A build system that works with CMake to improve speed.

RenderDoc

A powerful, free, and open-source graphics debugger.

CMake Build Targets

List of CMake build targets.

Build Target

Description

Comment

inexor-vulkan-renderer-core-lib

The core engine library

inexor-vulkan-renderer-example

The main executable

Requires inexor-vulkan-renderer-core-lib

inexor-vulkan-renderer-tests

Google Test

Requires inexor-vulkan-renderer-core-lib

inexor-vulkan-renderer-benchmark

Google Benchmark

Requires inexor-vulkan-renderer-core-lib

inexor-vulkan-renderer-documentation

Builds the documentation with Sphinx

inexor-vulkan-renderer-documentation-linkcheck

Sphinx linkcheck feature

Search for broken links

CMake Build Options

List of CMake options.

CMake Option

Description

Default Value

INEXOR_BUILD_EXAMPLE

Build inexor-renderer-example

OFF

INEXOR_BUILD_TESTS

Build inexor-renderer-tests

OFF

INEXOR_BUILD_BENCHMARKS

Build inexor-renderer-benchmarks

OFF

INEXOR_BUILD_DOCUMENTATION

Build the documentation with Sphinx

OFF

INEXOR_BUILD_DOCUMENTATION_USE_VENV

Generate and use a Python virtual environment for the documentation dependencies.

ON

INEXOR_FORCE_COLORED_OUTPUT

Always produce ANSI-colored output (GNU/Clang only).

OFF

Building on Windows

STEP 1: Install Microsoft Visual Studio 2022, Git, CMake, Python, Doxygen, and the Vulkan SDK.

STEP 2: Clone the source code from GitHub into any folder (in our example it will be V:/INEXOR/):

$ git clone https://github.com/inexorgame/vulkan-renderer

Alternatively, download the source code from the GitHub repository directly.

STEP 3: Open CMake:

_images/cmake-win-1.png

STEP 4: Click “Browse Source…” to select the folder that contains the source code. In this example, the path is V:/INEXOR/vulkan-renderer:

_images/cmake-win-2.png

STEP 5: Click “Browse Build…” to select a build folder, usually we pick a sub-folder named build:

_images/cmake-win-3.png

STEP 6: Click “Configure”. If the build directory does not exist already, you will see the following dialog. Click “Yes”:

_images/cmake-win-4.png

STEP 7: Now you can specify the generator for the project and some more options. Because we are using Visual Studio 17 2022, just click “Finish”:

_images/cmake-win-5.png

STEP 8: Let CMake configuration finish its work. CMake will download all dependencies automatically, which might take some minutes. If everything completed, the console log prints “Configuring done”:

_images/cmake-win-6.png

STEP 9: We now can configure the CMake build options of this project. You can enter “INEXOR” into the search field to find the options more easily. As you can see, only the INEXOR_BUILD_EXAMPLE option is enabled by default:

_images/cmake-win-7.png

STEP 10: In this example, let’s enable building benchmarks, tests, and the documentation as well. To do so, set the checkboxes for INEXOR_BUILD_BENCHMARKS, INEXOR_BUILD_TESTS, and INEXOR_BUILD_DOCUMENTATION:

_images/cmake-win-8.png

STEP 11: Click “Generate” and wait for CMake to complete its work. If everything completed, the console log will print “Generating done”:

_images/cmake-win-9.png

STEP 12: CMake successfully generated the Visual Studio project file. Click “Open Project” to open it in directly in Visual Studio:

_images/cmake-win-10.png

STEP 13: You can see that inexor-vulkan-renderer-example is set as start-up project by default. To build it, right click on it and select “Build”.

_images/cmake-win-11.png

This will also build the core library and the shaders as well. It might take some time to build the project.

_images/cmake-win-12.png

STEP 14: To start debugging the currently selected project, you can either press F5 or click “Start Debugging”:

_images/cmake-win-13.png

Running inexor-vulkan-renderer-example on Windows currently looks like this:

_images/example-app-1.png

Running inexor-vulkan-renderer-tests on Windows currently gives this console output:

_images/tests.png

Running inexor-vulkan-renderer-benchmarks on Windows currently gives this console output:

_images/benchmarks.png

Building on Linux

Note

Of all the Linux distributions listed here, only the build instructions for Ubuntu are continuously tested. Please open a ticket on GitHub if you have any trouble setting it up for distributions which are not tested as frequently or if you want to add build instructions for other Linux distributions!

STEP 1: Install dependencies and tools:

Ubuntu

Follow the Install the SDK-instructions on the vulkan-sdk page.

Install the required packages:

# apt install -y \
    pkg-config \
    libglm-dev \
    libxcb-dri3-0 \
    libxcb-present0 \
    libpciaccess0 \
    libpng-dev \
    libxcb-keysyms1-dev \
    libxcb-dri3-dev \
    libx11-dev  \
    libmirclient-dev \
    libwayland-dev \
    libxrandr-dev \
    libxcb-ewmh-dev
# apt install -y \
    cmake \
    ninja-build \
    clang-tidy \
    vulkan-sdk \
    python3 \
    python3-pip
$ pip3 install \
    wheel \
    setuptools \

Gentoo

 
# emerge \
   dev-util/cmake \
   dev-util/vulkan-headers \
   dev-util/vulkan-tools \
   dev-vcs/git \
   media-libs/vulkan-layers \
   media-libs/vulkan-loader

Install ninja build tool (optional):

# emerge dev-util/ninja

Debian

Follow the Install the SDK-instructions on the vulkan-sdk page.

Install the required packages:

# apt install -y \
    libvulkan-dev \
    glslang-dev \
    glslang-tools \
    vulkan-tools \
    vulkan-validationlayers-dev \
    spirv-tools \
    pkg-config \
    libglm-dev \
    libxcb-dri3-0 \
    libxcb-present0 \
    libpciaccess0 \
    libpng-dev \
    libxcb-keysyms1-dev \
    libxcb-dri3-dev \
    libx11-dev \
    libmirclient-dev \
    libwayland-dev \
    libxrandr-dev \
    libxcb-ewmh-dev
# apt install -y \
    cmake \
    ninja-build \
    clang-tidy \
    vulkan-sdk \
    python3 \
    python3-pip
$ pip3 install \
    wheel \
    setuptools \

Arch

Follow the Install the SDK-instructions on the vulkan-sdk page.

Install the required packages:

# pacman -S --noconfirm \
    pkg-config \
    glslang \
    spirv-tools \
    glm \
    libice \
    libpciaccess \
    libpng \
    libx11 \
    libxres \
    xkeyboard-config \
    libxrandr \
    libxcb \
    libxaw \
    xcb-util \
    xtrans \
    libxvmc
# pacman -S --noconfirm \
    cmake \
    ninja \
    vulkan-headers \
    vulkan-tools \
    vulkan-validation-layers \
    python3 \
    python-pip
$ pip3 install \
    wheel \
    setuptools \

Fedora

Install the required packages:

# dnf install -y \
    git \
    cmake \
    gcc \
    gcc-c++ \
    ninja-build \
    vulkan \
    libvkd3d \
    vulkan-loader-devel \
    python3-pip \
    libglvnd-devel \
    libfontenc-devel \
    libXaw-devel \
    libXcomposite-devel \
    libXcursor-devel \
    libXdmcp-devel \
    libXtst-devel \
    libXinerama-devel \
    libxkbfile-devel \
    libXrandr-devel \
    libXres-devel \
    libXScrnSaver-devel \
    libXvMC-devel \
    xorg-x11-xtrans-devel \
    xcb-util-wm-devel \
    xcb-util-image-devel \
    xcb-util-keysyms-devel \
    xcb-util-renderutil-devel \
    libXdamage-devel \
    libXxf86vm-devel \
    libXv-devel \
    xcb-util-devel \
    libuuid-devel \
    xkeyboard-config-devel \
    glslang-devel

Other?

Open a ticket on GitHub

STEP 2: Clone the repository:

$ git clone https://github.com/inexorgame/vulkan-renderer
$ cd vulkan-renderer

STEP 3: Configure CMake:

$ cmake . --Bbuild --DCMAKE_BUILD_TYPE=Debug

You can pass --GNinja if Ninja build system is installed:

$ cmake . --Bbuild --GNinja --DCMAKE_BUILD_TYPE=Debug

STEP 4: Build and run:

$ cmake --build build --target inexor-vulkan-renderer-example
$ ./build/example/inexor-vulkan-renderer-example