Miscellaneous cleanup

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-2025 Double Buffer SRL
+Copyright (c) 2023-2026 Double Buffer SRL
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

samples/Demos/01-Renderer/README.md

@@ -0,0 +1,82 @@
+# Renderer Demo
+
+This is Elemental's main renderer laboratory and stress test.
+
+Unlike the progressive `Elemental/*` samples, Renderer is intentionally not minimal. It combines several systems to expose real API friction, synchronization problems, resource-lifetime questions and performance costs while the library evolves.
+
+## What it exercises
+
+- compiled scene loading and GPU scene creation;
+- meshlet rendering with mesh shaders;
+- bindless buffers, textures and samplers;
+- depth rendering into an HDR floating-point target;
+- ray-tracing acceleration structures;
+- compute-based path tracing using inline ray queries;
+- resource barriers between compute, graphics and presentation work;
+- path-tracing accumulation;
+- tonemapping and UI composition;
+- GPU timestamps for major rendering phases;
+- an in-engine debug UI;
+- camera-state persistence.
+
+The default scene is `Sponza/sponza.scene`. A different compiled `.scene` file can be passed as the final command-line argument.
+
+## Rendering flow
+
+Renderer can switch between two main paths:
+
+```text
+raster
+    -> mesh-shader scene rendering
+    -> HDR render target
+
+path tracing
+    -> compute dispatch
+    -> HDR render target
+
+HDR result + debug UI
+    -> barriers
+    -> tonemap/composite
+    -> swap chain
+```
+
+Scene GPU data and ray-tracing structures are also used to stress loading and synchronization behavior rather than hiding it behind a finished engine abstraction.
+
+## Controls
+
+| Input | Action |
+|:--|:--|
+| `W` / `A` / `S` / `D` | Move camera |
+| Arrow keys | Rotate camera |
+| Right mouse drag | Rotate camera |
+| `Space` | Toggle raster / path tracing |
+| `Enter` | Toggle path-tracing accumulation |
+| `F1` | Toggle cursor visibility |
+
+Gamepad camera controls are also available.
+
+## Command-line options
+
+- `--vulkan` — prefer the Vulkan backend.
+- `--fullscreen` — start fullscreen.
+- `--gpu-debug` — enable the graphics debug layer.
+- `<path>.scene` — use another compiled scene instead of Sponza.
+
+## Key files
+
+- [`main.c`](main.c) — renderer setup and frame graph written explicitly as command recording.
+- [`DebugUI.c`](DebugUI.c) / [`DebugUI.h`](DebugUI.h) — renderer debug overlay and statistics.
+- [`ElementalArt.c`](ElementalArt.c) / [`ElementalArt.h`](ElementalArt.h) — renderer-specific drawing helpers.
+- [`UnityBuild.c`](UnityBuild.c) — unity-build entry point for the demo implementation.
+- [`Data`](Data) — renderer shaders.
+
+## Build
+
+```bash
+cmake --build --preset default --target Renderer
+```
+
+> [!WARNING]
+> Renderer is active R&D code. TODO, HACK and BUG comments are expected here. Treat it as a place where Elemental is stressed and new requirements are discovered, not as a reference engine architecture.
+
+[Back to samples](../../README.md)

samples/Demos/02-AITraining/README.md

@@ -0,0 +1,51 @@
+# AI Training Demo
+
+A small neural-network and automatic-differentiation experiment written in C.
+
+This demo is currently a **CPU baseline**. It does not run training or tensor operations on the GPU yet. Its role is to keep the learning experiment small and understandable before exploring how the same kind of workload could use Elemental compute and future GPU linear-algebra capabilities.
+
+## NeuralNetV0
+
+`NeuralNetV0.c` implements a tiny scalar automatic-differentiation engine from scratch:
+
+- values stored behind small integer handles;
+- an operation graph with parent dependencies;
+- reverse-mode gradient propagation;
+- addition, multiplication, subtraction, division, power, exponential and `tanh` operations;
+- neurons, layers and a small multilayer neural network;
+- forward pass, squared-error loss, backward pass and parameter updates.
+
+The current network is:
+
+```text
+3 inputs
+    -> 4 neurons
+    -> 4 neurons
+    -> 1 output
+```
+
+It trains for 20 steps on four small input/output examples and prints the loss and final predictions to the console.
+
+## NeuralNetV1
+
+`NeuralNetV1.c` is currently only a skeleton for the next iteration. The forward, backward and parameter-update stages are intentionally unfinished.
+
+## Why this is in Elemental
+
+The interesting future experiment is not to turn Elemental into a machine-learning framework. It is to start from code this small and ask what the minimal GPU programming path should look like when selected tensor or neural-network operations move to modern GPU hardware.
+
+That GPU version does not exist in this sample yet.
+
+## Key files
+
+- [`NeuralNetV0.c`](NeuralNetV0.c) — working CPU autodiff and neural-network experiment.
+- [`NeuralNetV1.c`](NeuralNetV1.c) — next-iteration placeholder.
+- [`main.c`](main.c) — sample application entry point.
+
+## Build
+
+```bash
+cmake --build --preset default --target AITraining
+```
+
+[Back to samples](../../README.md)

samples/Elemental/01-HelloTriangle/README.md

@@ -0,0 +1,51 @@
+# Hello Triangle
+
+The smallest graphics sample and the recommended first look at Elemental's runtime API.
+
+It creates a window, graphics device, command queue and swap chain, then renders a rotating triangle with a mesh shader.
+
+## What it demonstrates
+
+- application and window lifetime;
+- graphics-device creation;
+- a graphics command queue and command list;
+- swap-chain rendering and presentation;
+- shader-library loading and graphics-pipeline creation;
+- push constants;
+- a render pass;
+- mesh-shader dispatch.
+
+The triangle is generated entirely inside the shader, so there is no vertex buffer or asset loading to distract from the basic GPU execution path.
+
+## Frame flow
+
+```text
+get command list
+    -> begin render pass
+    -> bind graphics pipeline
+    -> push aspect ratio + rotation
+    -> dispatch mesh shader
+    -> end render pass
+    -> commit + execute
+    -> present
+```
+
+`Data/Triangle.hlsl` emits three vertices and one triangle from `MeshMain`, then `PixelMain` outputs the interpolated vertex color.
+
+## Key files
+
+- [`main.c`](main.c) — application setup and per-frame command recording.
+- [`Data/Triangle.hlsl`](Data/Triangle.hlsl) — procedural triangle mesh and pixel shaders.
+
+## Build
+
+From the repository root:
+
+```bash
+cmake --preset default
+cmake --build --preset default --target HelloTriangle
+```
+
+The sample also accepts `--vulkan`, primarily to select Vulkan instead of the default Direct3D 12 backend on Windows.
+
+[Back to samples](../../README.md)

samples/Elemental/02-HelloInputs/README.md

@@ -0,0 +1,48 @@
+# Hello Inputs
+
+This sample keeps the simple triangle from Hello Triangle and adds cross-platform input handling.
+
+The important part is not the triangle itself: it is the path from Elemental's raw input event stream to application actions that can be shared across keyboard, mouse, gamepad and touch input.
+
+## What it demonstrates
+
+- reading `ElemInputStream` every frame;
+- consuming `ElemInputEvent` values;
+- mapping several physical inputs to the same logical action;
+- keyboard, mouse, gamepad and touch input;
+- press/release, toggle and double-release behavior;
+- cursor visibility and application exit;
+- driving shader parameters from input.
+
+The small action-binding layer in `main.c` belongs to this sample. It is an example of how application code can consume Elemental input events, not a required high-level input model imposed by Elemental.
+
+## Controls
+
+| Input | Action |
+|:--|:--|
+| `W` / `S` | Rotate up / down |
+| `A` / `D` | Rotate left / right |
+| `Q` / `E` | Roll |
+| `Z` / `X` | Zoom |
+| `Space` | Change triangle color |
+| `F1` | Toggle cursor visibility |
+| `Escape` | Exit |
+| Mouse drag / wheel | Rotate / zoom |
+| Mouse double-click | Change triangle color |
+
+Gamepad and touch bindings provide equivalent rotation, zoom and action controls. Two-finger touch input is used for pinch/rotation gestures.
+
+## Key files
+
+- [`main.c`](main.c) — input bindings, action updates and triangle rendering.
+- [`Data/Triangle.hlsl`](Data/Triangle.hlsl) — mesh and pixel shaders driven by the current input state.
+
+## Build
+
+```bash
+cmake --build --preset default --target HelloInputs
+```
+
+The sample also accepts `--vulkan`, primarily to select Vulkan instead of the default Direct3D 12 backend on Windows.
+
+[Back to samples](../../README.md)

samples/Elemental/03-HelloCompute/README.md

@@ -0,0 +1,58 @@
+# Hello Compute
+
+This sample introduces general-purpose GPU compute by rendering an interactive Julia fractal into a texture and then displaying that texture through the graphics pipeline.
+
+It is also the first sample where resource descriptors and barriers become an important part of the frame.
+
+## What it demonstrates
+
+- creating a GPU heap and texture resource;
+- creating separate bindless read and write descriptors for the same texture;
+- compiling and dispatching a compute pipeline;
+- writing an `RWTexture2D` through `ResourceDescriptorHeap`;
+- transitioning the texture from compute-write access to graphics-read access;
+- displaying a compute result with a fullscreen graphics pass;
+- recreating GPU resources when the swap chain changes size.
+
+## Frame flow
+
+```text
+bind compute pipeline
+    -> barrier for texture write
+    -> dispatch 16x16 compute groups
+    -> barrier for texture read
+    -> begin render pass
+    -> draw fullscreen mesh
+    -> end render pass
+    -> commit + execute
+    -> present
+```
+
+`Data/Fractal.hlsl` currently renders a Julia set. A Mandelbrot implementation is also present in the shader as an alternate experiment.
+
+## Controls
+
+| Input | Action |
+|:--|:--|
+| `W` / `A` / `S` / `D` | Move around the fractal |
+| `Q` / `E` | Rotate |
+| `Z` / `X` | Zoom |
+| `F1` | Toggle cursor visibility |
+| `Escape` | Exit |
+| Mouse / touch / gamepad | Equivalent navigation controls |
+
+## Key files
+
+- [`main.c`](main.c) — texture allocation, descriptors, barriers, compute dispatch and presentation.
+- [`Data/Fractal.hlsl`](Data/Fractal.hlsl) — 16x16 compute shader that generates the fractal.
+- [`Data/Tonemap.hlsl`](Data/Tonemap.hlsl) — fullscreen pass used to display the generated texture.
+
+## Build
+
+```bash
+cmake --build --preset default --target HelloCompute
+```
+
+The sample also accepts `--vulkan`, primarily to select Vulkan instead of the default Direct3D 12 backend on Windows.
+
+[Back to samples](../../README.md)

samples/Elemental/04-HelloMesh/README.md

@@ -0,0 +1,50 @@
+# Hello Mesh
+
+Hello Mesh moves from procedural geometry to compiled mesh data and meshlets.
+
+The sample loads a small scene, creates a depth buffer and dispatches a mesh shader using the meshlet data for the first mesh primitive. It is intentionally a focused mesh-rendering sample rather than a general scene renderer.
+
+## What it demonstrates
+
+- loading the sample `.scene` format;
+- using mesh and meshlet data produced by the Scene Compiler sample;
+- allocating GPU memory for scene data;
+- creating and resizing a depth buffer;
+- configuring depth testing;
+- passing mesh-buffer offsets to a mesh shader;
+- dispatching one mesh-shader workgroup per meshlet;
+- interactive model-viewer controls.
+
+The sample currently renders the first primitive from `kitten.scene`. The surrounding scene/GPU-memory helpers are shared sample code and are still evolving.
+
+## Controls
+
+| Input | Action |
+|:--|:--|
+| `W` / `S` | Rotate up / down |
+| `A` / `D` | Rotate left / right |
+| `Q` / `E` | Roll |
+| `Z` / `X` | Zoom |
+| `Space` | Toggle meshlet visualization |
+| `F1` | Toggle cursor visibility |
+| `Escape` | Exit |
+| Mouse / touch / gamepad | Equivalent model-viewer controls |
+
+## Key files
+
+- [`main.c`](main.c) — scene loading, GPU resources, depth buffer and mesh dispatch.
+- [`Data/RenderMesh.hlsl`](Data/RenderMesh.hlsl) — meshlet-based mesh and pixel shaders.
+- [`../../ElementalTools/02-SceneCompiler`](../../ElementalTools/02-SceneCompiler) — creates the sample scene data consumed here.
+
+## Build
+
+```bash
+cmake --build --preset default --target HelloMesh
+```
+
+Supported sample flags include `--vulkan`, `--fullscreen` and `--gpu-debug`.
+
+> [!NOTE]
+> This sample deliberately contains some shared helper code and temporary memory/scene-loading choices. It demonstrates the mesh-shader path; it is not intended to define a final renderer architecture.
+
+[Back to samples](../../README.md)