portersky
98673b57ff
Updated project description from 'cube timer' to 'OpenGL 3D renderer with multiple scenes'. Added usage section with CLI flags and key bindings. Listed both available scenes. Updated AGENTS.md to include the sphere scene in static libraries and source layout. Normalized run command to ./build/cuber for cross-platform consistency.
135 lines
4.4 KiB
Markdown
135 lines
4.4 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.
|
|
```
|
|
|
|
## Source Layout
|
|
|
|
```
|
|
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/`.
|
|
|