# AGENTS.md - Aurora Rendering Engine

## Project Overview
Aurora Rendering Engine (ARE) is a high-performance path tracing library in C++ developed by NanoEra Studio. It provides a rendering framework using OpenGL 4.3 with GPU-accelerated ray tracing, BVH acceleration, and denoising.

## Build Commands

### Standard Build
```bash
mkdir build && cd build
cmake ..
cmake --build .
```

### Build Types
- **Debug**: `cmake -DCMAKE_BUILD_TYPE=Debug ..`
- **Release**: `cmake -DCMAKE_BUILD_TYPE=Release ..` (default)

### Running Examples
The main example is the Cornell Box demo:
```bash
./build/examples/cornell_box
```

### Testing
This project has **no built-in unit tests**. Testing is performed manually by running the example executables. There are no test-specific build targets or test frameworks configured.

### Linting/Code Formatting
- **Format**: Use `.clang-format` configuration (tabs, attach braces, unlimited line length)
  ```bash
  clang-format -i src/*.cpp include/**/*.h examples/*.cpp
  ```
- **Clangd**: IDE integration via `.clangd` file (C++20, includes paths configured)

## Code Style Guidelines

### General Conventions
- **C++ Standard**: C++17 (project CMake), C++20 (clangd for IDE)
- **Indentation**: Tabs (not spaces)
- **Line Length**: Unlimited
- **Brace Style**: Attach (opening brace on same line)

### File Organization
- **Headers**: `include/` - Public API
- **Source**: `src/` - Implementation
- **Examples**: `examples/` - Demo applications
- **Include format**: `#include "path/to/header.h"` (quotes for project headers)

### Naming Conventions
- **Classes**: `PascalCase` (e.g., `Renderer`, `Scene`, `RayTracer`)
- **Functions**: `PascalCase` (e.g., `initialize()`, `render()`, `set_config()`)
- **Member variables**: `snake_case_` with trailing underscore (e.g., `config_`, `frame_count_`)
- **Types (aliases)**: `PascalCase` (e.g., `Vec3`, `Mat4`, `TextureHandle`)
- **Enums**: `PascalCase` with `ARE_LOG_` prefix for values (e.g., `LogLevel::ARE_LOG_INFO`)
- **Constants**: `SCREAMING_SNAKE_CASE` (e.g., `INVALID_HANDLE`)

### Header Guards
```cpp
#ifndef ARE_INCLUDE_PATH_TO_FILENAME_H
#define ARE_INCLUDE_PATH_TO_FILENAME_H
// ... content ...
#endif // ARE_INCLUDE_PATH_TO_FILENAME_H
```

### Namespace
- All code lives in `are` namespace
- Namespace closing comment: `} // namespace are`

### Imports/Includes Order
1. Corresponding header (for .cpp files)
2. Project headers (alphabetically within group)
3. External library headers (e.g., `<glm/glm.hpp>`, `<glad/glad.h>`)
4. Standard library headers

### Comments
- Use `/* */` for function documentation with `@brief`, `@param`, `@return`
- Brief descriptions in header files, implementation details in .cpp
- Avoid unnecessary inline comments

### Error Handling
- Use `ARE_LOG_ERROR()`, `ARE_LOG_WARN()`, `ARE_LOG_CRITICAL()` macros
- Return `false` on failure, `true` on success
- Check initialization states before operations
- Log with context: `"Failed to initialize X"`

### Smart Pointers
- Use `std::unique_ptr` for exclusive ownership
- Use `std::shared_ptr` for shared ownership
- Avoid raw `new`/`delete`

### GLM Types
Use GLM for all math types:
```cpp
using Vec2 = glm::vec2;
using Vec3 = glm::vec3;
using Vec4 = glm::vec4;
using Mat3 = glm::mat3;
using Mat4 = glm::mat4;
```

### OpenGL Resources
- Follow OpenGL best practices
- Check OpenGL errors during development (debug builds)
- Clean up resources in destructors or `shutdown()` methods

## Project Structure
```
ARE/
├── include/          # Public headers
│   ├── basic/        # Types, constants, math
│   ├── core/         # Renderer, raytracer, BVH
│   ├── scene/        # Scene objects (mesh, material, camera)
│   ├── resource/     # GPU resources (shader, texture, buffer)
│   └── utils/        # Utilities (logger, config)
├── src/              # Implementation files
├── examples/         # Example applications
├── shaders/          # GLSL shaders
├── lib/              # External libraries (glad, stb, spdlog)
└── build/            # Build output (generated)
```

## Key Classes
- `Renderer` - Main rendering engine interface
- `Scene` - Scene container (meshes, materials, lights, camera)
- `RayTracer` - GPU ray tracing implementation
- `BVH` - Acceleration structure
- `GBuffer` - Geometry buffer for deferred rendering

## Dependencies
- OpenGL 4.3
- GLFW 3
- GLAD (OpenGL loader)
- GLM (math library)
- stb-image (image loading)
- spdlog (logging)