portersky
5b4743ff8f
- Added comprehensive "Pipeline Abstraction" section to README.md (for dummies, with step-by-step examples, render-to-texture, and post-processing). - Added "Documentation (Markdown)" section to AGENTS.md with the max-80-cols rule (exceptions for tables/code blocks). - Applied consistent Markdown styling to AGENTS.md and README.md (wrapped text at 80 cols, bold, code spans, cleaned duplicates). - Moved scenes libraries to (cleaned main CMakeLists.txt significantly). No behavior change. All follows AGENTS.md conventions.
152 lines
4.9 KiB
Markdown
152 lines
4.9 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Overview
|
|
|
|
`cuber` is an OpenGL 3D renderer with multiple scenes.
|
|
|
|
## Build System
|
|
|
|
- **Generator:** Ninja
|
|
- **CMake minimum:** 3.21
|
|
- **C++ standard:** C++23
|
|
|
|
### Commands
|
|
|
|
```sh
|
|
cmake -S . -B build -GNinja
|
|
ninja -C build
|
|
./build/cuber
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
Dependencies are managed via custom `Find*.cmake` scripts in `deps/`.
|
|
These scripts use `FetchContent` under the hood to download and build
|
|
libraries automatically.
|
|
|
|
To add a new dependency:
|
|
|
|
1. Add the corresponding `Find<name>.cmake` to `deps/`
|
|
2. Add `find_package(<name> REQUIRED)` to `CMakeLists.txt`
|
|
3. Link with `<name>::<name>` in `target_link_libraries()`
|
|
|
|
### Static Libraries
|
|
|
|
The project is split into static libraries:
|
|
|
|
- **`cbt_opengl`** — OpenGL abstraction and window management (window,
|
|
context, buffer, texture, vao, shader, descriptor)
|
|
- **`cbt_scene`** — Base scene class
|
|
- **`scenes_cube`** — Spinning cube scene implementation
|
|
- **`scenes_sphere`** — Cube-to-sphere mapped mesh with diffuse lighting
|
|
|
|
### CMake Module Path
|
|
|
|
`deps/` is added to `CMAKE_MODULE_PATH` so `find_package()` resolves
|
|
to the custom scripts instead of system-installed packages.
|
|
|
|
## Coding Conventions
|
|
|
|
- **Language:** C++23
|
|
- **Trailing return type** for function signatures (e.g. `auto fn() -> void`)
|
|
- **4-space indentation**
|
|
- **No semicolons after closing braces** for namespaces/classes
|
|
- `auto` for obvious types (e.g. `auto main(...) -> int`)
|
|
- **East const** (e.g. `char const*` not `const char*`)
|
|
- **Trailing return type** for all function definitions, including
|
|
operators (e.g. `auto operator=(T&&) noexcept -> T&`)
|
|
- **Public members first** in class declarations, private members at the
|
|
bottom
|
|
- `<>` includes only for system headers (std, OS, etc.)
|
|
- `""` includes for third-party dependencies (e.g. `fmt`,
|
|
`nlohmann/json`)
|
|
- **Naming:** `snake_case` for variables, functions, and classes
|
|
- **Naming:** `SCREAMING_SNAKE_CASE` only for macros and constants
|
|
- Include order:
|
|
1. C++ standard library headers (`<chrono>`, `<vector>`, etc.)
|
|
2. *(blank line)*
|
|
3. C standard library headers (`<stdlib.h>`, `<string.h>`, etc.)
|
|
4. *(blank line)*
|
|
5. OS-specific headers (Windows API, POSIX, etc.)
|
|
6. *(blank line)*
|
|
7. Third-party dependencies (`"fmt/core.h"`, etc.)
|
|
8. *(blank line)*
|
|
9. Local/project headers
|
|
|
|
## Shell Scripts
|
|
|
|
- Always use `#!/bin/sh` shebang for shell scripts
|
|
- Scripts must be POSIX compliant (no bashisms)
|
|
- When providing commands to users:
|
|
- Windows/PowerShell: use `` ` `` for line continuation
|
|
- Unix/Linux/macOS: use `\` for line continuation
|
|
|
|
## Commit Messages
|
|
|
|
- Follow the 50/72 rule:
|
|
- Subject line: max 50 characters
|
|
- Body lines: wrapped at 72 characters
|
|
- Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `chore:`,
|
|
etc.)
|
|
- Separate subject from body with a blank line
|
|
|
|
Example:
|
|
|
|
```
|
|
feat: add stopwatch timer
|
|
|
|
Replace Hello World with a live stopwatch that prints elapsed time
|
|
in HH:MM:SS.mmm format, updating every 10ms with color output.
|
|
```
|
|
|
|
## Documentation (Markdown)
|
|
|
|
- Wrap normal text and lists at **max 80 columns** (for readability in
|
|
terminals and editors).
|
|
- **Exceptions**: Tables and code blocks (```` ``` ````) can exceed 80
|
|
columns when formatting requires it (e.g. trees, alignment).
|
|
- Use standard Markdown: `**bold**`, `` `inline code` ``, `##` headings,
|
|
`-` or numbered lists, fenced code blocks with language hints
|
|
(```` ```cpp ````, ```` ```sh ````).
|
|
- Keep examples concise, up-to-date, and self-documenting.
|
|
- This file (`AGENTS.md`) follows its own rules.
|
|
|
|
## Source Layout
|
|
|
|
```text
|
|
cuber/
|
|
CMakeLists.txt # Build configuration
|
|
cuber.cpp # Entry point
|
|
cbt/ # Project namespace (utilities)
|
|
scene.hpp # Base scene class
|
|
scene.cpp # Scene implementation
|
|
window.hpp # GLFW window RAII wrapper
|
|
window.cpp # Window implementation
|
|
opengl/ # OpenGL abstraction layer
|
|
context.hpp # OpenGL context RAII wrapper (GLAD setup)
|
|
context.cpp # Context implementation
|
|
buffer.hpp # Buffer resource (VBO, EBO, UBO, SSBO)
|
|
buffer.cpp # Buffer implementation
|
|
texture.hpp # Texture resource
|
|
texture.cpp # Texture implementation
|
|
descriptor.hpp # Descriptor set (Vulkan-style binding)
|
|
descriptor.cpp # Descriptor implementation
|
|
shader.hpp # Shader program
|
|
shader.cpp # Shader implementation
|
|
vao.hpp # Vertex array object
|
|
vao.cpp # VAO implementation
|
|
scenes/ # Application scenes
|
|
cube.hpp # Spinning cube scene
|
|
cube.cpp # Cube scene implementation
|
|
sphere.hpp # Cube-to-sphere mapped mesh
|
|
sphere.cpp # Sphere scene implementation
|
|
deps/ # Custom Find*.cmake scripts
|
|
Findfmt.cmake # fmt library
|
|
```
|
|
|
|
## Platform Support
|
|
|
|
The project supports Windows, Linux, Emscripten, and Android via
|
|
`Platform.cmake` and `Flags.cmake` in `deps/`.
|
|
|