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:

• Model loading, using libassimp
• Internal thread pool
• Shader program caching
• Keyboard and mouse input handling

Requirements:

• A c++23 compatible compiler (g++ 12+ / clang 17+)
  • 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
  • Build with FAST=true to enable these, if supported
• 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:

• make library
• sudo make install

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

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 and thread demo
  • make library - Builds build/libammonite.so
  • make install - Installs libammonite.so to system directories
    • The install path can be configured, by setting the environment variable INSTALL_DIR
  • make headers - Installs Ammonite headers to the system
    • The install path can be configured, by setting the environment variable HEADER_DIR
  • make uninstall - Removes installed library
    • Custom install locations can be removed using the environment variable INSTALL_DIR
  • make clean - Cleans the build area (build/) and default runtime cache (cache/)
• All targets and optional flags are documented here

Dependencies:

• Package names are correct for Debian, other distros may vary
• make
• pkg-config
• coreutils
• g++ OR clang
  • If using clang, use CXX="clang++" make [TARGET]
  • When swapping between different compilers, run make clean

• Libraries:

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

• Linting:

  • clang-tidy

• Icons:

  • inkscape optipng

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 :)

Usage:

• Some very basic usage information can be found in docs/USAGE.md
• Better documentation is planned in the future

Screenshots:

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

License

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