LiteFX

An extensible, descriptive, modern computer graphics and rendering engine, written in C++20.

About

LiteFX is a computer graphics engine, that can be used to quick-start developing applications using Vulkan 🌋 and/or DirectX 12 ❎ rendering APIs. It provides a flexible abstraction layer over modern graphics pipelines. Furthermore, it can easily be build and integrated using CMake. It naturally extents build scripts with functions that can be used to handle assets and compile shaders † and model dependencies to both.

The engine design follows an descriptive approach, which means that an application focuses on configuring what it needs and the engine then takes care of handling those requirements. To support this, the API also provides a fluent builder interface. Here is an example of how to easily setup a render pass graphics pipeline with a few lines of code:

UniquePtr<RenderPass> renderPass = device->buildRenderPass("Geometry")
    .renderTarget(RenderTargetType::Present, Format::B8G8R8A8_UNORM, MultiSamplingLevel::x1, { 0.f, 0.f, 0.f, 1.f }, true, false)
    .renderTarget(RenderTargetType::DepthStencil, Format::D32_SFLOAT, MultiSamplingLevel::x1, { 1.f, 0.f, 0.f, 0.f }, true, false);
 
UniquePtr<RenderPipeline> renderPipeline = device->buildRenderPipeline(*renderPass, "Geometry")
    .viewport(viewport)
    .scissor(scissor)
    .inputAssembler(inputAssembler)
    .rasterizer(device->buildRasterizer()
        .polygonMode(PolygonMode::Solid)
        .cullMode(CullMode::BackFaces)
        .cullOrder(CullOrder::ClockWise)
        .lineWidth(1.f))
    .layout(device->buildPipelineLayout()
        .descriptorSet(DescriptorSets::Constant, ShaderStage::Vertex | ShaderStage::Fragment)
            .withUniform(0, sizeof(CameraBuffer))
            .add()
        .descriptorSet(DescriptorSets::PerFrame, ShaderStage::Vertex)
            .withUniform(0, sizeof(TransformBuffer))
            .add())
    .shaderProgram(device->buildShaderProgram()
        .withVertexShaderModule("shaders/basic_vs." + FileExtensions<TRenderBackend>::SHADER)
        .withFragmentShaderModule("shaders/basic_fs." + FileExtensions<TRenderBackend>::SHADER));

LiteFX is written in modern C++20, following established design patterns to make it easy to learn and adapt. Its focus is make the performance of modern graphics APIs easily accessible, whilst retaining full flexibility.

† Shaders can be built using glslc or DXC. glslc can be used to compile HLSL and GLSL shaders into SPIR-V for the Vulkan backend. DXC can only compile HLSL, but can target SPIR-V and DXIL, that's why it is preferred over glslc.

Key Features

• Fluent Builders: the fluent vuilder API can help you to organize creation of your render context. Instances, render passes and pipeline states typically require a lot of code to set them up. LiteFX hides this code behind a flexible builder architecture. However, if you don't like it, you can still create all objects on your own.
• Runtime Backend Switching: Switch between DirectX 12 and Vulkan at runtime without re-creating the window. The engine's app model supports flexible configuration and all domain types are abstracted in a way, that make it easy to provide different render paths.
• State of the Art: the engine makes use of some of the most recent techniques introduced to the supported APIs in order to help you to fully utilize the latest hardware. For example it implements support for DirectX 12 render passes or Vulkan timeline semaphores for improved thread synchronization.
• Multi-Threading Support: LiteFX comes with support for multi-threaded render passes in order to maximize throughput and prevent GPU stalls. It takes care of the necessary synchronization between threads and exposes interfaces for manual synchronization.
• Descriptor and Memory Management: descriptors and buffers can be hard to get around. LiteFX abstracts them away in a way that is both efficient and easy to adapt.
• CMake Integration: you can use CMake to integrate the engine into your project. Furthermore, it exports scripts that allow you to integrate assets and shaders into your build process. It can be installed using vcpkg, making project setup quick and painless.
• Much More: If you want to learn what else you can do, check out the guides and wiki.

Installation

If you just want to start using LiteFX, you can acquire binaries of the latest version from the releases page and follow the project setup and quick start guides.

Using vcpkg

If you are using vcpkg, you can use the registry to install the engine directly.

Manual Builds

You can also build the sources on your own. Currently only MSVC builds under Windows are officially supported. However, the engine does use CMake and (besides the DirectX 12 backend) no Windows-specific features, so porting the Vulkan backend and engine architecture should be absolutely possible (pull requests are much appreciated!).

Prerequisites

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

• CMake (version 3.20 or higher). †
• Optional: LunarG Vulkan SDK 1.2.148.0 or later (required to build the Vulkan backend).
• Optional: Custom DXC build (required to build shaders for DirectX backend). ‡
• Optional: Windows 10 SDK 10.0.19041.0 or later (required to build DirectX backend).

† CMake 3.20 is part of Visual Studio 2019 version 16.10 and above. When using older Visual Studio versions, consider installing CMake manually.

‡ Note that the LunarG Vulkan SDK (1.2.141.0 and above) ships with a pre-built DXC binary, that supports DXIL and SPIR-V code generation and thus should be favored over the DXC binary shipped with the Windows SDK, which only supports 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 https://github.com/crud89/LiteFX.git . --recurse-submodules

Performing a Build

There are multiple ways of creating a build from scratch. In general, all CMake-based build systems are supported.

From Command Line

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
cmake --build out/build/windows-x64/ --target install --config Release

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.

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",
      "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.2.148.0 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).

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

Troubleshooting

If you are having problems building the project, you may find answers in the wiki. Otherwise, feel free to start a discussion or open an issue.

Dependencies

All dependencies are automatically installed using vcpkg, when performing a manual build. The engine only has two hard dependencies:

• spdlog: Lightweight logging library.
• {fmt}: String formatting library and implicit dependency of spdlog.

Depending on which rendering backends are build, the following dependencies are required:

• Vulkan SDK: Required by the Vulkan backend
• Vulkan Memory Allocator: Required by the Vulkan backend. Handles memory allocations.
• DirectX Headers: Required by the DirectX 12 backend.
• D3D12 Memory Allocator: Required by the DirectX 12 backend. Handles memory allocations.

The math module can optionally be built with converters for the following math and linear algebra libraries:

• glm: Cross-platform math library.
• DirectX Math: Windows-specific math library.

Furthermore, the samples also use some libraries for convenience. Those dependencies are not exported and are not required by your application. You can use whatever replacement suits you best instead.

• CLI11: Command line parser.
• glfw3: Cross-platform window manager.
• stb: Lightweight image loading and processing library.

Getting Started

For a quick-start guide, a collection of tutorials and more in-depth information on how to use the engine and work with the code base, take a look at the documentation and the project wiki.

Contribute

If you are having trouble using the engine, found a bug or have suggestions, just drop an issue. Keep in mind that this project is developed in my free time and I might not be able to provide any advanced support. If you want to, feel free to provide improvements by creating a pull request.

Projects using LiteFX

Want to add yours? Feel free to contact me!

License

LiteFX is licensed under the permissive MIT license. The documentation (i.e. the contents of the docs folder of this repository, especially the LiteFX logo, banner and icon) is licensed under CC-BY 4.0.

If you want to use LiteFX in your projects, linking to project website and/or putting the logo in your project description is much appreciated.