Ammonite Engine

• A simple OpenGL based graphics engine, built to learn C++ and graphics programming
  • This isn't a serious, production-quality engine, please don't treat it as one
• Despite the project being for learning, any contributions are still welcome
  • See docs/CONTRIBUTING.md to get started
  • If you found this project interesting, any donations are greatly appreciated :)

Features:

• Multi-threaded model loading, using libtangle and libassimp
  • Includes support for raw mesh and material uploads, demoed with a torus
• Shader program caching with a custom hash
• Key binding and mouse input support
• Camera path support
• Command prompt for engine control
• Miscellaneous utilities (thread pool, thread-safe logging, timers, random number generation)

Requirements:

• A c++23 compatible compiler (g++ (16+) / clang++ (19+))
  • Toolchain support for thread-local variables
  • All build and runtime dependencies installed
• A 64-bit Linux system
  • Some functions may have AVX-512 / VAES accelerated versions
• An OpenGL 4.5+ compatible driver
• Alternatively, an OpenGL 3.2+ driver supporting the following extensions can be used
  • ARB_direct_state_access
  • ARB_shader_storage_buffer_object
  • ARB_texture_storage
  • ARB_texture_cube_map_array
• OpenGL debugging is supported with KHR_debug
• Program caching is supported with ARB_get_program_binary
• No error contexts are supported with KHR_no_error

Building + installing libammonite:

• Set up libtangle, optionally using the submodule
• make library
• sudo make install
• Optionally, run sudo make headers to install the headers

Running a demo:

• make build will compile the library and all demos on the current branch
• Demos can be listed with ./launch.sh --demo
• Run a specific demo with ./launch.sh --demo [DEMO]
  • For example: ./launch.sh --demo object-field
  • Running the binary directly will only work if libammonite is installed to the system
• make clean will clean the build area, to start from fresh
• Screenshots of some demos can be found at the end of the README
• The sponza demo requires some Intel assets
  • Download the Sponza base scene, then extract it to assets-experimental/intel-assets/main_sponza/
  • The Curtains and Ivy packages are also supported
    • Extract these to assets-experimental/intel-assets/pkg_a_curtains/ and assets-experimental/intel-assets/pkg_b_ivy/
• All demos support the following keybinds:
  • W, A, S and D for movement
  • Left control to 'sprint'
  • Scroll to adjust zoom
  • Middle-click to reset zoom
  • B to switch camera
  • G to record a camera path, replayable through commands
  • C to release input
  • ESC to close the demo
  • V to open the command prompt
  • F11 to toggle fullscreen
  • P to toggle model (torus) placement mode
    • Left-click to confirm placement
    • Scroll to adjust distance
    • Middle-click to reset distance
  • Up or down arrow to adjust the framerate limit
  • Z to toggle focal depth
  • [ or ] to adjust focal depth
• The object-field demo additionally supports the following keybinds:
  • F to place a new cube at the camera's position
  • R to shuffle placed cubes

Options:

• Compiled demos have a few arguments supported:
  • --help: Displays a help menu
  • --benchmark: Start a benchmark
  • --demo: List available demos
  • --demo [DEMO]: Launch a specific demo
  • --vsync: Enable / disable VSync (true / false)

Build system:

• Targets:

  • build and library support -j[CORE COUNT]
  • make build - Builds the demo
  • make library - Builds build/libammonite.so
  • make install - Installs libammonite.so to the system
  • make headers - Installs Ammonite headers and ammonite.pc to the system
  • make uninstall - Removes installed library and headers
    • Custom install locations must be specified the same way as they were installed
  • make clean - Cleans the build area (build/) and default runtime cache (cache/)
• All targets and optional flags are documented here
• Set the environment variable PREFIX_DIR to configure the base install path
  • The install, headers and uninstall targets have additional path options

Dependencies:

• Package names are correct for Debian, other distros may vary
• make
• pkgconf
• coreutils
• sed
• python3
• libtangle
  • This can be provided by the system or used in-place
  • The submodule can be used to provide both options
• g++ OR clang++
  • If using clang++, use CXX="clang++" make [TARGET]
    • USE_LLVM_CPP=true might be useful for systems without (a new enough) GCC
  • When swapping between different compilers, run make clean

• Libraries:

  • libglm-dev libglfw3-dev libepoxy-dev libstb-dev libassimp-dev
  • libdecor-0-0 libdecor-0-plugin-1-gtk are required for Wayland window decorations

• Linting:

  • clang-tidy (22+)

• Icons:

  • inkscape optipng

libtangle:

• Run git submodule update --init to clone the libtangle submodule
  • Alternatively, pass --recurse-submodules when cloning this repository
• Run make -C libtangle build -j$(nproc) to build libtangle
• To use libtangle as part of the system instead of in-place:
  • Run sudo make -C libtangle install headers
  • Pass USE_SYSTEM=true to any make commands to use the system copy of libtangle
    • For client code compilation recipes, this will also attempt to use the system copy of Ammonite
    • Make sure Ammonite is installed to the system before using USE_SYSTEM=true make build
    • The library can be built separately using make library, then installed with sudo make install headers

Issues:

• Due to the small size of this project, only a small range of hardware can be tested
  • If you hardware / driver meets the requirements listed here, but the engine doesn't work, please file a bug report
• Issues, feature requests and bug reports can be filed here
• Feel free to work on any issues / feature ideas, suggestions are welcome :)

Screenshots:

Related projects

• Bad Hash Museum: Tools and hashes written for the shader cache hash used here
• Crystal Assembly Viewer: A tool to locally inspect compiler output, written to optimise the maths functions
• libtangle: A C++ thread pool created from the thread pool written for this project

Credits:

• Some models in assets/ may have been created by third parties, attribution can be found in docs/CREDITS.md
• Reference materials:
  • OpenGL Tutorial
  • Learn OpenGL

Licence:

• This project is available under the terms of the MIT License
  • These terms can be found in LICENCE.txt