The maiden project is a GPU accelerated 3D rendering engine built with C++ based on the Vulkan API for an emphasis on optimization and performance. The engine is intended to:

be usable cross platform
use minimal external libraries
be configurable
be performance profilable

Getting Started

Clone Repository

$ git clone https://git.vxbard.net/homeburger/maiden.git

# If there's any necessary submodules then:
$ git clone --recurse-submodules https://git.vxbard.net/homeburger/maiden.git

# If you have already cloned the repository and you need its submodules:
$ git submodule update --init --recursive

Installation Prequisites

LunarG's Vulkan SDK is used for almost every Vulkan project, including this one. Installation instructions here are for Ubuntu 24, further instructions can be found here: https://vulkan.lunarg.com/doc/sdk/1.4.341.1/linux/getting_started.html

$ cd ~/Downloads
$ wget "https://sdk.lunarg.com/sdk/download/1.4.341.1/linux/vulkansdk-linux-x86_64-1.4.341.1.tar.xz" # or the latest version on https://vulkan.lunarg.com/sdk/home
$ mkdir /opt/vulkan-sdk
$ cd /opt/vulkan-sdk
$ tar -xvf ~/Downloads/vulkansdk-linux-x86_64-1.4.341.1.tar.xz
$ sudo apt install libxcb-xinput0 libxcb-xinerama0 libxcb-cursor-dev # vulkan prerequeisites

Then to setup your current session:

$ source /opt/vulkan-sdk/1.4.341.1/setup-env.sh # or whichever version you have

Note: sourcing only affects your current shell session. Add to your .bashrc script if you wish for it to persist.

Verify your installation by using the the command:

$ vulkaninfo

Build

This app uses CMake and C++20, so a compatible compiler (gcc8, clang9, msvc16) are necessary.

Most library prerequisites are handled within CMake. Any others that need to be manually installed will be described below as the project grows.

To build the project (using default build directory "build"):

# configure
$ cmake -S . -B build # + any extra options

# build
$ cmake --build build -j

# execute
$ cd build
$ ./maiden

Testing

This app uses GoogleTest for building unit tests. The below instructions use ctest and gcovr for test execution and code coverage:

# execute unit tests
$ ctest -T Test # + filter options

# analyze code coverage
$ cd build
$ gcovr -r .. --filter "../src"

App Troubleshooting

Basically these are some tricky situations that I encountered when trying to execute this app throughout this development phase. If you are running on WSL Ubuntu 26.04 like me, then you mightr run into these too, hopefully my steps help fix. note: I am running an x86_64 system with an Nvidia GPU so some things may be slightly different if your system doesn't match.

Development Roadmap

lots of todo here

See CONTRIBUTING.md for design and more specific development plans.