A fast real-time 3D rendering engine built with modern C++.
Gleam is a lightweight, high-performance 3D rendering engine written in modern C++. It follows a clean, scene-oriented architecture that provides fine-grained control over rendering, lighting, and assets through a minimal and expressive API. Built for native performance and modularity, Gleam is ideal for interactive tools, visualization applications, and real-time rendering workflows that don't need the weight of a full game engine.
Features
- Real-time forward renderer – Cameras, meshes, lighting, and materials supported out of the box.
- Cross-platform – Runs on Windows, macOS, and Linux with consistent behavior.
- Modern C++ architecture – Written in C++23 with strong typing and minimal overhead.
- Windowing and event system – Built-in support for input and context management.
- Flexible lighting system – Directional, point, and spot lights with attenuation support.
- Rich material system – Supports multiple shading models and user-defined shaders.
- Precompiled asset pipeline – Converts raw assets into optimized GPU-ready formats.
- Constexpr-first math – Header-only types and math utilities designed for compile-time use.
- Strong API boundaries – Internal symbols are hidden; public interface is clearly scoped.
- Comprehensive documentation – Grouped, consistent, and cross-linked via Doxygen.
Getting Started
This section covers how to build Gleam, install it, and integrate it into your own project. Gleam is easy to consume: all dependencies are vendored, and no global packages are required.
Requirements
Gleam requires a C++23-compatible toolchain, CMake 3.20 or newer, and an OpenGL 4.1+ context. It is actively tested on:
24.04 and GCC 11.3.0
macOS 14 and Clang 15.0.0
Windows 10 and MSVC 19.44
Dependencies
Gleam vendors all required libraries directly into the repository. The only runtime dependencies are:
| Dependency | Version | Location | Description |
|---|---|---|---|
| Glad | 0.1.36 | vendor/glad | OpenGL function loader generated from glad.dav1d.de. |
| GLFW | 3.5.0 | vendor/glfw | Cross-platform window/input/context management (with minor internal modifications). |
| ImGui | 1.92.1 | vendor/imgui | Optional immediate-mode UI library for in-engine tools and examples. |
Each dependency includes license information in its respective vendor/ folder. Additional libraries may be used in asset tooling but are not part of the engine runtime.
Building Gleam
Gleam uses CMake to configure and build the project. You can toggle build components using options or presets.
CMake Options
The following options control which components are built:
| Option | Description |
|---|---|
GLEAM_BUILD_DOCS | Build Doxygen documentation. |
GLEAM_BUILD_EXAMPLES | Build example applications. |
GLEAM_BUILD_IMGUI | Enable ImGui support for debug UI/tools. |
GLEAM_BUILD_TESTS | Build unit tests. |
GLEAM_BUILD_TOOLS | Build command-line. |
Defaults are preset-dependent.
CMake Presets
To streamline the build process, Gleam provides a set of CMake presets with common configurations:
dev-debug– Debug build with all features enabled.dev-release– Optimized build with tools and examples.install-debug– Debug build for install (used by MSVC).install-release– Optimized release build for install.
Build Instructions
If examples are enabled, you can run them to verify that everything is working as expected.
Installation and Usage
Gleam can be installed via the provided script and integrated into your project using CMake’s standard find_package and target_link_libraries pattern. Alternatively, you can link Gleam manually by including headers and linking the compiled library directly.
Install Script
- macOS/Linux:
sudo scripts/install.sh - Windows (PowerShell as Admin):
scripts\install.bat
The script uses the install-release preset on Unix. On MSVC, both install-debug and install-release are installed due to ABI differences. Elevated privileges are required in both cases. By default, Gleam is installed as a shared library. This enforces a clean API boundary and hides internal symbols using platform-specific visibility controls.
CMake Integration
CMake automatically selects the correct configuration (Debug/Release) based on your project settings.
Platform Notes
- Gleam disables RTTI by default. You can match this in your project: target_compile_options(MyApp PRIVATE$<$<CXX_COMPILER_ID:GNU>:-fno-rtti>$<$<CXX_COMPILER_ID:Clang>:-fno-rtti>$<$<CXX_COMPILER_ID:AppleClang>:-fno-rtti>$<$<CXX_COMPILER_ID:MSVC>:/GR->)
- On MSVC: You may need to copy the Gleam DLL next to your executable. Automate this with: if(WIN32)add_custom_command(TARGET MyApp POST_BUILDCOMMAND ${CMAKE_COMMAND} -E copy_if_different$<TARGET_FILE:gleam::gleam>$<TARGET_FILE_DIR:MyApp>)endif()
Asset Generation Pipeline
Gleam does not parse raw assets at runtime. Instead, assets are preprocessed using asset_builder, a command-line tool built with GLEAM_BUILD_TOOLS. It converts raw asset formats into compact, runtime-ready formats.
Supported Formats
| Input | Output | Type | Description |
|---|---|---|---|
.png, .jpg | .tex | Texture | Converts 2D images into a GPU-ready format |
.obj | .msh | Mesh | Converts geometry and material files for runtime loading |
Usage
Building <tt>asset_builder</tt>
asset_builder is built by default with any CMake preset. If installed with Gleam, it will be available on the system PATH by default on Unix systems. On Windows, you may need to add it manually, for example: $env:PATH += ";C:\path\to\gleam\bin" in PowerShell.
