Abdelrahman Said
135 lines
4.4 KiB
Markdown
135 lines
4.4 KiB
Markdown
# AGENTS.md — Prism
|
|
|
|
## Project Identity
|
|
|
|
**Prism** is a node-based image compositing tool. Images flow through a directed
|
|
acyclic graph (DAG) of processing nodes (read, blend, colour-grade, etc.) and
|
|
are rendered via GPU shaders.
|
|
|
|
- **Language**: C11 / C++11 (dual-mode, like `src/wapp/`)
|
|
- **GPU API**: Vulkan, abstracted behind a Rendering Hardware Interface (RHI)
|
|
- **Shading language**: Slang, stored in external `.slang` files under `src/shaders/`
|
|
- **Build**: TBD — either a standalone shell build script or a `justfile` (Just)
|
|
- **Dependencies**: `src/wapp/` (local utility library, already vendored)
|
|
|
|
## Coding Conventions
|
|
|
|
All code follows the patterns established in `src/wapp/`. The project prefix is
|
|
`pr` (functions/macros) / `Pr` (types).
|
|
|
|
### Naming
|
|
|
|
| Category | Convention | Examples |
|
|
|-----------------------|------------------------|---------------------------------|
|
|
| Types | `Pr` + PascalCase | `PrNode`, `PrGraph`, `PrImage` |
|
|
| Functions | `pr` + PascalCase | `prGraphCreate`, `prNodeEval` |
|
|
| Macros | `pr` + PascalCase | `prArrayOf`, `prNodeType` |
|
|
| Enum constants | `PR_` + SCREAMING_SNAKE| `PR_NODE_BLEND`, `PR_OK` |
|
|
| Internal/static funcs | `_` + camelCase | `_resolveTopology`, `_execCmd` |
|
|
| File-scope globals | `_` + camelCase | `_default_allocator` |
|
|
| File-scope constants | SCREAMING_SNAKE | `MAX_NODE_NAME` |
|
|
|
|
### Storage qualifiers
|
|
|
|
Use the `wp_extern` / `wp_intern` / `wp_persist` aliases from wapp:
|
|
|
|
```c
|
|
wp_extern void prGraphInit(PrGraph *g); // extern linkage
|
|
wp_intern void _helper(void); // static (file-scope)
|
|
wp_persist u32 _counter; // static (file-scope, mutable)
|
|
```
|
|
|
|
### Structs
|
|
|
|
POD structs with typedef, following `wapp/base/` patterns. Functions operate
|
|
on structs by pointer rather than through vtables:
|
|
|
|
```c
|
|
typedef struct PrNode PrNode;
|
|
struct PrNode {
|
|
PrNodeType type;
|
|
u32 input_count;
|
|
PrNode **inputs;
|
|
// ...
|
|
};
|
|
|
|
void prNodeInit(PrNode *n, PrAllocator *alloc);
|
|
void prNodeEval(PrNode *n, PrRhiCmdList *cl);
|
|
void prNodeDestroy(PrNode *n, PrAllocator *alloc);
|
|
```
|
|
|
|
### Memory management
|
|
|
|
Use wapp allocators (`WpAllocator`, arena-based). Stack-allocate where
|
|
possible; pass allocators explicitly.
|
|
|
|
```c
|
|
PrGraph *prGraphCreate(PrAllocator *alloc);
|
|
void prGraphDestroy(PrGraph *g, PrAllocator *alloc);
|
|
```
|
|
|
|
### File organisation
|
|
|
|
One `.h` / `.c` pair per module, grouped in subdirectories by subsystem.
|
|
A top-level umbrella header re-exports everything (see `src/wapp/wapp.h`).
|
|
|
|
```
|
|
src/prism/prism.h ← umbrella include
|
|
src/prism/core/ ← graph, node types, DAG
|
|
src/prism/rhi/ ← rendering hardware interface
|
|
src/prism/node/ ← node implementations
|
|
src/prism/app/ ← entry point, window, main loop
|
|
```
|
|
|
|
Shaders live in a flat-ish `src/shaders/` tree:
|
|
|
|
```
|
|
src/shaders/blit.slang
|
|
src/shaders/blend.slang
|
|
src/shaders/common/ ← shared include files
|
|
```
|
|
|
|
### Data-oriented design
|
|
|
|
For hot paths (per-frame graph evaluation, image transfers, shader dispatch)
|
|
prefer SoA layouts, batch processing, and minimise pointer chasing. Keep
|
|
the DAG in contiguous arrays (e.g. adjacency lists packed in flat buffers)
|
|
rather than individually allocated linked structures.
|
|
|
|
## Documentation
|
|
|
|
Save research notes and implementation plans as markdown in `documents/`:
|
|
|
|
```
|
|
documents/
|
|
├── ARCHITECTURE.md
|
|
├── RENDERING_HARDWARE_INTERFACE.md
|
|
├── NODE_SYSTEM.md
|
|
├── ROADMAP.md
|
|
└── research/
|
|
└── vulkan-baseline.md
|
|
```
|
|
|
|
## Workflows for AI agents
|
|
|
|
### Research / planning
|
|
|
|
1. Save findings to `documents/research/<topic>.md`.
|
|
2. When asked for a plan, write it to `documents/<PLAN_NAME>.md` and present
|
|
a summary; iterate on the plan before writing any code.
|
|
3. Only start implementing after the plan is approved.
|
|
|
|
### Learning from edits
|
|
|
|
The user may edit code produced by AI agents. When this happens, infer the
|
|
reason for the change and update AGENTS.md with any new conventions, patterns,
|
|
or constraints that the edit reveals. This keeps the guide aligned with the
|
|
user's evolving preferences.
|
|
|
|
### Committing
|
|
|
|
Only commit when explicitly asked. When asked:
|
|
- Stage only intended files.
|
|
- Write a short, conventional commit message in present tense.
|
|
- Never amend, force-push, or create PRs without a request.
|