Building Guide

This page guides you through the process of creating a custom build of the LiteFX engine, its samples and tests.

Building Guide

In order for the project to be built, there are a few prerequisites that need to be present on your environment:

• C++23 compatible compiler †
• CMake (version 3.20 or higher). ‡
• Optional: LunarG Vulkan SDK 1.3.204.1 or later (required to build the Vulkan backend).
• Optional: Windows 10 SDK 10.0.19041.0 or later (required to build DirectX backend).

† At the moment only MSVC 17.5 fully supports the required features.

‡ CMake 3.20 is part of Visual Studio 2019 version 16.10 and above. When using other compilers, CMake may have to be installed manually.

Choosing a Shader Compiler

Depending on which backends you want to support, you have to choose a shading language and shader compiler. Refer to the following table for mature differences:

	HLSL	GLSL	HLSL Validation	Target DXIL ❎	Target SPIR-V 🌋
DXC	✔	❌	✔	✔	✔
GLSLC	✔	✔	❌	❌	✔

If you are only ever targeting Vulkan and want to author shaders in GLSL, you can use glslc, which is included in the LunarG Vulkan SDK. Switching to HLSL and DXC allows you to re-use the same shader to target both backends. DXC is also included (since version 1.2.141.0) with support for both, DXIL and SPIR-V code generation and thus should be favored over the DXC binary shipped with the Windows SDK, which only supports targeting DXIL.

Cloning the Repository

Create a new directory from where you want to build the sources. Then open your shell and clone the repository:

git clone --recursive https://github.com/crud89/LiteFX.git .

Building under Windows

If you want to use the engine in your own projects, you can directly include the LiteFX registry to install it using vcpkg or build if from the command line as described below. If you want to customize the engine itself, you can also open it using Visual Studio directly.

Command Line Builds

Building from command line is the most straightforward way and is typically sufficient, if you only want to consume a fresh build.

cmake src/ --preset windows-x64-release
cmake --build out/build/windows-x64-release/ --target install

Using Visual Studio

From Visual Studio open the folder where you just checked out the contents of the repository. In the Project Explorer change the view to CMake Targets. Right click LiteFX and select Install.

Building under Linux

⚠ Please note that Linux support is currently experimental and under active development. The compatible changes are pushed to the linux branch.

Building under Linux only supports the Vulkan backend. Before attempting a build, there are some prerequisites that need to be installed:

sudo apt update && sudo apt upgrade
sudo apt install g++ gdb make cmake ninja-build zip pkg-config libxinerama-dev libxcursor-dev xorg-dev libglu1-mesa-dev

Additionally, the Vulkan SDK needs to be installed as described in this guide. It is important to use the tarball version of the SDK.

Next, create a new directory and clone the repository into it:

mkdir ~/repos/litefx/
cd ~/repos/litefx/
git clone --recursive -b linux https://github.com/crud89/LiteFX.git .

Finally, you can build the source as usual:

cmake src/ --preset linux-x64-debug
cmake --build out/build/linux-x64-debug/

Build Customization

You can customize the engine build, according to your specific needs. The most straightforward way is to use CMake presets. Create a file called CMakeUserPresets.json inside the src/ directory and add the following content to it:

{
  "version": 2,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 20,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "win-x64-custom-preset",
      "inherits": "windows-x64-release",
      "cacheVariables": {
      }
    }
  ]
}

Within the cache variables, you can override the build options, LiteFX exports. All customizable options have the BUILD_ prefix and are described in detail below:

• BUILD_VULKAN_BACKEND (default: ON): builds the Vulkan 🌋 backend (requires LunarG Vulkan SDK 1.3.204.1 or later to be installed on your system).
• BUILD_DX12_BACKEND (default: ON): builds the DirectX 12 ❎ backend.
• BUILD_DEFINE_BUILDERS (default: ON): enables the builder architecture for backends.
• BUILD_WITH_GLM (default: ON): adds glm converters to math types. †
• BUILD_WITH_DIRECTX_MATH (default: ON): adds DirectX Math converters to math types. †
• BUILD_HLSL_SHADER_MODEL (default: 6_3): specifies the default HLSL shader model.
• BUILD_EXAMPLES (default: ON): builds the examples. Depending on which backends are built, some may be omitted.
• BUILD_EXAMPLES_DX12_PIX_LOADER (default: ON): enables code that attempts to load the latest version of the PIX GPU capturer in the DirectX 12 samples, if available (and if the command line argument --load-pix=true is specified).
• BUILD_EXAMPLES_RENDERDOC_LOADER (default: OFF): enables code in the samples, that loads the RenderDoc runtime API, if the application is launched from within RenderDoc (and if the command line argument --load-render-doc=true is specified).
• BUILD_TESTS (default: OFF): builds tests for the project.

For example, if you only want to build the Vulkan backend and samples and don't want to use DirectX Math, a preset would look like this:

{
  "version": 2,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 20,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "win-x64-vulkan-only",
      "inherits": "windows-x64-release",
      "cacheVariables": {
        "BUILD_DX12_BACKEND": "OFF",
        "BUILD_WITH_DIRECTX_MATH": "OFF"
      }
    }
  ]
}

You can build using this preset from command line like so:

cmake src/ --preset win-x64-vulkan-only
cmake --build out/build/win-x64-vulkan-only/ --target install --config Release

† Note that glm and DirectX Math are installed using vcpkg automatically. If one of those options gets disabled, no converters will be generated and the dependency will not be exported. Note that both can be used for DirectX 12 and Vulkan.