https://github.com/shlomnissan/vglx
✨ A fast cross-platform 3D rendering engine for modern C++
https://github.com/shlomnissan/vglx
3d cpp opengl rendering vulkan
Last synced: 8 months ago
JSON representation
✨ A fast cross-platform 3D rendering engine for modern C++
- Host: GitHub
- URL: https://github.com/shlomnissan/vglx
- Owner: shlomnissan
- License: mit
- Created: 2024-08-04T21:10:45.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-10-06T14:59:20.000Z (8 months ago)
- Last Synced: 2025-10-06T16:29:50.972Z (8 months ago)
- Topics: 3d, cpp, opengl, rendering, vulkan
- Language: C++
- Homepage: https://vglx.org
- Size: 17.7 MB
- Stars: 15
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# VGLX
A fast cross-platform 3D rendering engine for modern C++.
[](https://shlomnissan.github.io/vglx/)
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Getting Started](#getting-started)
- [Requirements](#requirements)
- [Dependencies](#dependencies)
- [Building VGLX](#building-vglx)
- [Installation and Usage](#installation-and-usage)
- [Documentation](https://shlomnissan.github.io/vglx/)
- [Asset Generation Pipeline](#asset-generation-pipeline)
- [License](#license)
---
## Overview
VGLX 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, VGLX 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](https://doxygen.nl/).
## Getting Started
This section covers how to build VGLX, install it, and integrate it into your own project. VGLX is easy to consume: all dependencies are vendored, and no global packages are required.
### Requirements
VGLX 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
VGLX 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](https://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 VGLX
VGLX uses [CMake](https://cmake.org/download/) 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 |
|------------------------|----------------------------------------------------------|
| `VGLX_BUILD_DOCS` | Build Doxygen documentation. |
| `VGLX_BUILD_EXAMPLES` | Build example applications. |
| `VGLX_BUILD_IMGUI` | Enable ImGui support for debug UI/tools. |
| `VGLX_BUILD_TESTS` | Build unit tests. |
| `VGLX_BUILD_TOOLS` | Build command-line tools. |
Defaults are preset-dependent.
#### CMake Presets
To streamline the build process, VGLX provides a set of [CMake presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) 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
```bash
# Clone the repository
git clone --recursive https://github.com/shlomnissan/vglx.git
cd vglx
# Create output directory
mkdir build
cd build
# Configure with a preset
cmake .. --preset dev-debug --config Debug
# Build the engine
cmake --build . --config Debug
```
If examples are enabled, you can run them to verify that everything is working as expected.
### Installation and Usage
VGLX 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 VGLX 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, VGLX is installed as a **shared library**. This enforces a clean API boundary and hides internal symbols using platform-specific visibility controls.
#### CMake Integration
```cmake
find_package(vglx REQUIRED)
target_link_libraries(MyApp PRIVATE vglx::vglx)
```
CMake automatically selects the correct configuration (Debug/Release) based on your project settings.
#### Platform Notes
- VGLX disables RTTI by default. You can match this in your project:
```cmake
target_compile_options(MyApp PRIVATE
$<$:-fno-rtti>
$<$:-fno-rtti>
$<$:-fno-rtti>
$<$:/GR->
)
```
- On MSVC: You may need to copy the VGLX DLL next to your executable. Automate this with:
```cmake
if(WIN32)
add_custom_command(TARGET MyApp POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy_if_different
$
$
)
endif()
```
## Asset Generation Pipeline
VGLX does not parse raw assets at runtime. Instead, assets are preprocessed using asset_builder, a command-line tool built with `VGLX_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
```bash
asset_builder --input model.obj
asset_builder --input texture.png --output texture.tex
```
#### Building `asset_builder`
`asset_builder` is built by default with any CMake preset. If installed with VGLX, 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\vglx\bin"` in PowerShell.
## License
```
________ ___ ________ ___ ___
|\ ____\|\ \ |\_____ \ |\ \ / /|
\ \ \___|\ \ \ \|____|\ /_ \ \ \/ / /
\ \ \ __\ \ \ \|\ \ \ \ / /
\ \ \|\ \ \ \____ __\_\ \ / \/
\ \_______\ \_______\\_______\/ /\ \
\|_______|\|_______\|_______/__/ /\ __\
|__|/ \|__|
Copyright (c) 2024–present Shlomi Nissan
The MIT License (MIT)
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
```