If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/JoeyDeVries/LearnOpenGL shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 10 active contributors
• Other licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live JoeyDeVries/LearnOpenGL repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JoeyDeVries/LearnOpenGL.

What it runs against: a local clone of JoeyDeVries/LearnOpenGL — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in JoeyDeVries/LearnOpenGL | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 671 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JoeyDeVries/LearnOpenGL. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JoeyDeVries/LearnOpenGL.git
#   cd LearnOpenGL
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of JoeyDeVries/LearnOpenGL and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "JoeyDeVries/LearnOpenGL(\\.git)?\\b" \\
  && ok "origin remote is JoeyDeVries/LearnOpenGL" \\
  || miss "origin remote is not JoeyDeVries/LearnOpenGL (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "configuration/root_directory.h.in" \\
  && ok "configuration/root_directory.h.in" \\
  || miss "missing critical file: configuration/root_directory.h.in"
test -f "includes/GL/glew.h" \\
  && ok "includes/GL/glew.h" \\
  || miss "missing critical file: includes/GL/glew.h"
test -f "includes/GLFW/glfw3.h" \\
  && ok "includes/GLFW/glfw3.h" \\
  || miss "missing critical file: includes/GLFW/glfw3.h"
test -f "includes/assimp/Importer.hpp" \\
  && ok "includes/assimp/Importer.hpp" \\
  || miss "missing critical file: includes/assimp/Importer.hpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 671 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~641d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/JoeyDeVries/LearnOpenGL"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

LearnOpenGL is a comprehensive educational codebase containing 100+ runnable C++ tutorials demonstrating OpenGL graphics programming from fundamentals through advanced techniques (shaders, lighting, materials, normal mapping, parallax mapping, deferred rendering). It pairs with learnopengl.com and provides chapter-by-chapter sample code with embedded GLSL shader files, 3D model assets, and textures for teaching modern OpenGL (3.3+) rendering pipelines. Monolithic educational codebase: root CMakeLists.txt discovers all chapter folders (src/[ChapterName]/) as independent executable targets. Each chapter contains standalone .cpp files with embedded shader code or paired .vs/.fs files in resources/. Shared includes live in /includes/ (GLEW, GLFW, ASSIMP headers bundled), pre-compiled libs in /libs/, and DLLs in /dlls/. Configuration templates in /configuration/ (root_directory.h.in injects the repo root path at build time for asset lookup).

Computer science students and self-taught graphics programmers learning OpenGL who want working, copy-paste-friendly code examples organized by concept; also useful for game developers ramping up on shader programming and graphics APIs before moving to engines like Unreal or Unity.

Very mature and stable. The repo shows 7.8M lines of well-organized C++ code across 4,100+ files, no visible CI/CD pipeline in the file list (no .github/workflows), but comprehensive CMake build system with multi-platform support (Windows/Linux/macOS). Last commit age is unknown from provided metadata, but the README documents production-ready build instructions and widespread adoption (Glitter boilerplate exists partly because of this repo's popularity).

Low risk for learning; moderate risk for production use. Dependencies are heavy (GLFW, GLEW, ASSIMP, GLM, SOIL, irrKlang) and bundled pre-compiled DLLs for Windows may mismatch your compiler version (explicitly warned in README). Single maintainer (JoeyDeVries) with no visible multi-contributor history. No automated tests visible in file structure. Library versions are pinned and potentially outdated (ASSIMP headers frozen in time).

Unable to determine from provided metadata (no commit log, PR list, or issue backlog included). The repo structure suggests maintenance mode: build system is stable, but no active refactoring visible. Presence of Objective-C files (5.6KB) hints at legacy macOS support that may not be actively updated.

Check README for instructions.

Daily commands: After build: Executables land in build/[ChapterName]/ (e.g., ./build/1.GettingStarted/HelloTriangle or ./build/2.Lighting/BasicLighting). Set LOGL_ROOT_PATH=/path/to/LearnOpenGL environment variable if running from IDE or alternate directory (so shaders and assets resolve). Each tutorial runs until window close; most have keyboard controls (documented in source comments).

• CMakeLists.txt — Primary build configuration that orchestrates compilation for all chapters and manages dependency discovery (GLFW, GLM, ASSIMP, GLEW, FreeType)
• configuration/root_directory.h.in — CMake template that injects the project root path at compile time, enabling asset loading across all example projects
• includes/GL/glew.h — OpenGL extension loader header that every example depends on for accessing modern OpenGL functions
• includes/GLFW/glfw3.h — Window and input management library header used as the foundation for all OpenGL window creation and event handling
• includes/assimp/Importer.hpp — Asset importer interface used throughout advanced chapters for loading 3D models in multiple formats
• includes/glm — Mathematics library headers providing vector/matrix operations essential to all shader-based rendering code
• includes/freetype/freetype.h — Text rendering library header used in advanced chapters for font rasterization and glyph management

Add a New OpenGL Chapter Example

1. Create a new source directory following the pattern src/[chapter]/[example] (CMakeLists.txt (add target via add_executable, link libraries))
2. Write main C++ source file that initializes GLFW window and OpenGL context (src/[chapter]/[example]/main.cpp)
3. Create vertex and fragment shader files in the resources subdirectory (resources/shaders/[example].vs and [example].fs)
4. Register the new target in CMakeLists.txt with add_executable() and target_link_libraries() for GLFW, GLEW, GLM (CMakeLists.txt)
5. If loading models, add #include <assimp/Importer.hpp> and place .obj/.fbx files in resources/objects/ (src/[chapter]/[example]/main.cpp)

Add Texture Loading to an Example

1. Place image file (PNG, JPG, TGA) in resources/textures/ (resources/textures/[texture_name].[ext])
2. Include SOIL header and call SOIL_load_OGL_texture() to load texture (includes/SOIL.h)
3. Bind texture to shader uniform and update fragment shader to sample from texture (src/[chapter]/[example]/main.cpp and resources/shaders/[example].fs)

Add 3D Model Loading to an Example

1. Place model file (OBJ, DAE, FBX) in resources/objects/ (resources/objects/[model_name].[ext])
2. Include ASSIMP headers and create Importer instance to load and parse model (includes/assimp/Importer.hpp)
3. Iterate scene meshes via aiScene*, extract vertices/indices, create VAO/VBO buffers (src/[chapter]/[example]/main.cpp)
4. Update vertex shader to accept transformed vertex positions and normals from mesh data (resources/shaders/[example].vs)

• CMake — Cross-platform build generation supporting Windows (Visual Studio), Linux (GCC/Clang), and macOS; manages dependency discovery and library linking
• GLFW3 — Lightweight, cross-platform windowing and input library; minimal boilerplate for OpenGL context creation
• GLEW — Extension wrangler simplifying access to modern OpenGL functions across platform-specific driver variations
• GLM — Header-only math library with GLSL-like syntax for vectors, matrices, and transformations; no external dependencies
• ASSIMP — Unified API for loading 3D models in 40+ formats (OBJ, DAE, FBX, BLEND); handles format diversity in educational examples
• FreeType — Industry-standard TrueType/OpenType font rasterizer enabling text rendering directly from font files
• SOIL — Simple image loading library handling common texture formats (PNG, JPG, TGA, DDS) with direct OpenGL texture upload

• Precompiled Windows DLLs bundled in /dlls

  • Why: Eliminates build-time dependency compilation for Windows users; reduces setup friction for learners
  • Consequence: Platform-specific binary distribution; users on other platforms or compiler versions must rebuild libraries; DLL load failures if linked against incompatible compiler versions

• CMake over Makefile/build.py

  • Why: Native IDE integration (Visual Studio, Xcode, VS Code); platform abstraction; widely taught in graphics courses
  • Consequence: Adds intermediate build generation step; CMake syntax steeper learning curve than simple Makefile

• Header-only GLM + system package GLFW/ASSIMP on Linux vs. bundled Windows libs

  • Why: Linux distributions package GLFW/ASSIMP consistently; reduces repo size; follows OS distribution norms
  • Consequence: Requires apt install for Linux; version mismatches possible if system libs outdated; Windows gets convenience, Linux gets package management discipline

• No runtime asset embedding; asset paths resolved via compile-time injected root_directory.h

  • Why: Assets (shaders, textures, models) remain editable at runtime; learners can iterate shader code without recompiling
  • Consequence: Asset search paths must be correct; executable location relative to resources/ matters; easy to break with misplaced binaries

• Does not provide a game engine; examples are minimal, single-file or thin wrapper applications
• Does not abstract shader compilation; learners write raw GLSL—no intermediate language or shader cross-compilation
• Does not include macOS binaries or official macOS build documentation; assumes GCC/Clang on Linux or MSVC on Windows
• Does not provide network, AI, or physics simulation libraries; focus is purely graphics API instruction
• Does not include unit tests or automated validation; examples are demonstration code with manual visual inspection

Critical: (1) Windows DLL mismatch — prebuilt dlls/ are VC140 (VS 2015); if you use newer MSVC, link errors occur; rebuild ASSIMP/GLEW from source as documented. (2) Asset path resolution — executables must be run from build/ root or LOGL_ROOT_PATH env var must be set, else shader/texture files silently fail to load (no error message in many cases). (3) Shader compilation failures are runtime, not compile-time; a typo in shader source appears at window launch. (4) Linux: libfreetype-dev required but not always obvious; modern tutorials use it for text rendering. (5) macOS irrKlang audio library (dlls/irrKlang.dll) is Windows-only; audio chapters may fail silently on Mac unless handled with #ifdef guards.

• Immediate-Mode Rendering — LearnOpenGL teaches the traditional OpenGL pipeline (glBegin/glEnd evolved to VAO/VBO/shader) which is foundational to understanding modern graphics APIs; understanding what immediate mode was helps appreciate why we use shaders and buffers today.
• Vertex Attribute Objects (VAO) and Vertex Buffer Objects (VBO) — Core GPU memory layout pattern used in every chapter; VAOs define vertex shader input layouts, VBOs store geometry on GPU—misunderstanding either breaks rendering.
• Phong Reflection Model — Industry-standard lighting equation taught in chapters 2-3; combines ambient, diffuse, and specular terms—essential for understanding how to write effective fragment shaders.
• Normal Mapping — Advanced texturing technique in chapter 5 that simulates surface detail without extra geometry; critical for achieving realistic visuals in games and 3D applications at reasonable performance.
• Parallax Occlusion Mapping (POM) — Heightmap-based surface detail technique beyond normal mapping; teaches how to manipulate UV coordinates in fragment shaders to create depth illusion, used in modern game engines.
• Deferred Rendering — Alternative to forward rendering that decouples lighting from geometry passes via G-Buffer; chapter 5 teaches this for handling many lights efficiently, directly applicable to game engine design.
• Frame Buffer Objects (FBO) and Render-to-Texture — Advanced rendering technique enabling post-processing, shadows, and deferred rendering; offscreen rendering to textures is required for modern visual effects in any graphics application.

• Polytonic/Glitter — Boilerplate fork of LearnOpenGL that bundles a single chapter into a standalone project; useful for learners who want to isolate and extend one tutorial without the full monorepo.
• g-truc/glm — Pure C++ vector/matrix math library used extensively in LearnOpenGL tutorials; standalone repo where contributors can report math-related bugs or feature requests.
• glfw/glfw — OpenGL window and input library that LearnOpenGL wraps; directly relevant if extending multi-window or advanced input tutorials.
• assimp/assimp — 3D model loading library used in LearnOpenGL's model-loading chapters; upstream repo for bug fixes and format support beyond what's bundled.
• TheCherno/Hazel — Modern C++ game engine with OpenGL backend that applies LearnOpenGL graphics concepts at production scale; next step for learners building larger projects.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI workflow for cross-platform CMake builds

The repo has build scripts (build_windows.sh) and CMakeLists.txt but no CI pipeline to validate builds on Windows, Linux, and macOS. This would catch breaking changes early and ensure the CMake configuration works across platforms. Currently, contributors have no automated feedback when modifying CMakeLists.txt or adding new chapters.

• [ ] Create .github/workflows/build.yml with matrix strategy for Windows (MSVC), Linux (GCC), and macOS (Clang)
• [ ] Test CMake configuration step with the existing cmake/modules/*.cmake find modules
• [ ] Validate that precompiled libs in /libs and /dlls work on Windows, and system packages resolve on Linux
• [ ] Add workflow status badge to README.md

Create a chapter validation script and CI check for missing/orphaned source files

The repo contains many chapters (evidenced by the LearnOpenGL book structure) but there's no inventory or validation that all chapter code exists and is referenced. Adding a script to audit which chapter directories exist, which are built by CMakeLists.txt, and which may be orphaned or incomplete would help maintainers catch missing chapters and keep the repo organized.

• [ ] Create a Python or Bash script (e.g., scripts/validate_chapters.sh) that scans src/ directory structure and extracts all chapter references from CMakeLists.txt
• [ ] Report discrepancies (chapters with no CMake target, CMake targets with no source files)
• [ ] Add this as a CI check in the GitHub Actions workflow to run on every PR
• [ ] Document the script in README.md under a 'Repository Structure' section

Add platform-specific build documentation for Linux with missing dependency details

The README.md Linux section is incomplete (cuts off mid-sentence at 'Build through CMake-gui: The'). More critically, the apt-get packages listed may vary by distribution and don't include build instructions for assimp from source (which the README mentions contributors may need). Adding a complete Linux build guide with troubleshooting for common linker issues would reduce friction.

• [ ] Complete the truncated 'Build through CMake-gui' section in README.md
• [ ] Add a new 'Building Dependencies from Source' subsection with specific steps for compiling assimp, GLEW, and GLFW on Linux
• [ ] Include a 'Troubleshooting' section addressing common link errors (e.g., missing libGL.so, GLFW version mismatches)
• [ ] Add Debian/Ubuntu, Fedora, and Arch Linux specific package manager commands
• [ ] Reference the cmake/modules/Find*.cmake scripts to explain how CMake locates custom-built libraries

• Add unit tests for shader compilation: create a tests/ folder with a small CMake target that programmatically loads and compiles all .vs/.fs pairs in resources/ across all chapters, catching shader syntax errors before tutorials run.
• Document per-chapter learning outcomes: create CHAPTERS.md listing each tutorial's prerequisites, key concepts taught (e.g., 'Phong lighting', 'Normal mapping'), and time-to-completion; currently learners must infer this from file names.
• Add CMake option for GLFW static/dynamic linking: Windows users hitting DLL load failures have no escape hatch; add set(GLFW_STATIC ON/OFF) to CMakeLists.txt and document when to use static mode to reduce runtime dependencies.

• High · Outdated and Potentially Vulnerable Pre-compiled DLLs — /dlls/ directory. The repository contains pre-compiled Windows DLLs (assimp-vc140-mt.dll, ikpMP3.dll, irrKlang.dll) that appear to be built with Visual Studio 2015 (vc140). These binaries are not version-controlled for updates and may contain known security vulnerabilities. The vc140 compiler is significantly outdated and no longer receives security patches. Fix: 1. Replace pre-compiled DLLs with dynamically sourced versions from official repositories. 2. Implement a dependency management system (vcpkg, Conan) to automatically fetch and update libraries. 3. Document the build versions and dates of all DLLs. 4. Add a security scanning process for binary dependencies.
• High · Bundled Third-Party Libraries Without Version Pinning — /includes/ directory. The /includes directory contains multiple third-party libraries (ASSIMP, FreeType, GLFW, GLM, GLEW) bundled directly in the repository. Without explicit version pinning or checksums, users cannot verify authenticity or identify which versions are included. This increases supply chain attack risk. Fix: 1. Remove bundled headers and use official package managers instead. 2. If bundling is necessary, create a VERSION.md file documenting exact versions and upstream sources. 3. Implement checksum verification for all included libraries. 4. Consider using git submodules with pinned tags for third-party code.
• High · SOIL Library Source Code Included Directly — /includes/SOIL.c and /includes/SOIL.h. The SOIL.c source file is included directly in the repository (/includes/SOIL.c). SOIL (Simple OpenGL Image Library) is a legacy library with known security issues. Bundling its source code directly presents maintenance and security patching challenges. Fix: 1. Replace SOIL with modern alternatives like stb_image or SDL_image which are actively maintained. 2. If SOIL must be used, build it as an external dependency rather than bundling source. 3. Apply known security patches from the SOIL community or use a patched fork.
• Medium · Missing Security Headers in Build Configuration — /CMakeLists.txt and /cmake/ directory. The CMakeLists.txt and build configuration files do not appear to implement security compiler flags (e.g., -fPIE, -fstack-protector-strong, -D_FORTIFY_SOURCE=2 on Linux, or /GS, /SafeSEH on Windows) based on the partial file structure provided. Fix: 1. Add platform-specific security flags to CMake configuration. 2. Enable compiler warnings as errors (-Werror). 3. Implement Control Flow Guard (CFG) and Address Space Layout Randomization (ASLR). 4. Use CMake's built-in security features like CMAKE_CXX_FLAGS_SECURITY.
• Medium · No Dependency Integrity Verification — /CMakeLists.txt, /cmake/modules/. The build process lacks cryptographic verification of downloaded dependencies. The README mentions building libraries from source but provides no guidance on verifying checksums or signatures of third-party code. Fix: 1. Implement checksum verification (SHA256) for all downloaded dependencies. 2. Use GPG signatures if available from upstream projects. 3. Document the verification process in README.md. 4. Create a script to validate all third-party sources before compilation.
• Medium · Unclear License Compliance for Bundled Libraries — /LICENSE.md and /includes/ directory. While a LICENSE.md file exists, it's unclear if all bundled third-party libraries (ASSIMP, FreeType, GLFW, etc.) are properly attributed and their licenses respected, especially for commercial use cases. This creates legal and security audit risks. Fix: 1. Create a THIRD_PARTY_LICENSES.md file documenting all dependencies with their licenses. 2. Ensure compatibility of all licenses (e.g., GPL with proprietary code). 3. Implement SBOM (Software Bill of Materials) generation using tools like SPDX. 4. Add license scanning to CI/CD pipeline.
• Low · No Security Policy or Vulnerability Disclosure Process — undefined. The repository does not contain a SECURITY.md file or vulnerability Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.