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:

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:

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.

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

Save findings to documents/research/<topic>.md.
When asked for a plan, write it to documents/<PLAN_NAME>.md and present a summary; iterate on the plan before writing any code.
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.

4.4 KiB Raw Blame History