Skip to content

Suckless-OGL

CI/CD Pipeline Coverage Report Latest Release License: MIT

High-performance C11 PBR Renderer

Suckless-OGL Reference Image

Suckless-OGL is a minimalist 3D rendering engine written in C. Faithful to the "suckless" philosophy, it prioritizes a compact codebase, rigorous resource management, and an absence of unnecessary dependencies. It implements a modern pipeline based on OpenGL 4.4 Core Profile.

🚀 Features

  • Minimalism: Lightweight architecture focused on performance and readability.
  • Modern Rendering: Support for Skyboxes, IcoSpheres, textures, and Phong lighting.
  • Dynamic Shaders: Loading and compilation of GLSL files (vertex/fragment).
  • Shader Optimization: Static (Release) or dynamic (Debug) compilation to balance flexibility and performance. See Documentation.
  • Stencil Buffer Masking: Post-processing optimization to differentiate skybox from objects. See Documentation.
  • Performance Mode: Adaptive optimization (GameMode/Native) for maximum frame stability. See Documentation.
  • Isolated Environment: Native distrobox support to guarantee a reproducible build environment.
  • Quality & Testing: Unit testing suite, code coverage, static analysis, and Standalone Mocking.
  • Interactive Keyboard Overlay: Modern Cyberpunk UI with Responsive Scaling and Visual Parameter Reference.
  • Post-Processing Pipeline: Advanced stack including Auto-Exposure, Bloom, Bloom Debugging, Debug Histograms, and 3D LUT / Gamut Mapping.
  • Cinematic Rendering: High-fidelity photographic simulation with brand-specific profiles like the Sony Alpha 7S III.

🛠️ Compilation and Usage

The project uses a Makefile wrapper that drives CMake to simplify interactions. For a modern alternative, seeing Justfile Documentation.

Compilation Flags & Environment

The build is configured with the following settings:

  • Optimization: -Wall -Wextra -O2 for clean and performant code.
  • POSIX Standard: -D_POSIX_C_SOURCE=199309L for clock_gettime support.
  • Static Analysis: clang-tidy integration with strict header filters.
  • Containerization: Default use of distrobox with the clang-dev image to isolate dependencies.

Main Commands

Command Action
make all Compiles the project (generates GLAD and the app binary).
make debug Compiles in DEBUG mode (dynamic shaders, ideal for dev).
make release Compiles in RELEASE mode (statically optimized shaders).
make run Launches the DEBUG version.
make run-release Launches the RELEASE version.
make test Runs the unit test suite via ctest.
make test-apitrace Automated lightweight performance check.
make test-integration-apitrace Automated full app integration scenario check.
make format Applies clang-format formatting on src, include, and tests.
make lint Runs clang-tidy static analysis on source files.
make coverage Generates a complete HTML report via llvm-cov in build-coverage/.

🤖 CI/CD Workflow (GitHub Actions)

The pipeline is structured to optimize the build while guaranteeing maximum quality. It handles Testing, Quality Assurance, Documentation, and Automated Releases.

> Read the full CI/CD Pipeline Documentation

Quick Summary

  1. Test & Coverage: Instrumented compilation and test execution under Xvfb.
  2. Lint & Format: Enforces styling (clang-format) and static analysis (clang-tidy).
  3. Automated Releases:
  4. Nightly: Built every night at 01:00 UTC and on every push to master.
  5. Stable: Triggered by version tags (v*).

📁 Project Structure

  • src/ & include/: Engine core (Log, App, Shader, Texture, Icosphere).
  • shaders/: GLSL sources (Phong, Background/Skybox).
  • assets/: HDR resources and textures.
  • tests/: Unit tests (Icosphere, Shader, Skybox, Texture, Log).
  • docs/: In-depth technical documentation.

📦 Docker / Podman

To test the application in a container with X11 forwarding:

make docker-build
make docker-run

(Requires a local X server and configured xhost permissions).

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.