# Rendering

> A PBR renderer on Metal, D3D12, Vulkan and WebGPU that picks its own quality level for the hardware.

Kaigen has one renderer, the same on every platform: a PBR renderer with clustered lights, over Metal (macOS and iOS), D3D12 (Windows), Vulkan (Linux, Android, and Windows if you ask for it) and WebGPU (the web). Shaders are written once in GLSL and cooked for each.

It records and submits on every lane, so the CPU cost of rendering spreads over all your cores.

## Using it

You don't call the renderer per object. Entities with a model, a transform and `EcsVisibility` are drawn, and the ECS bridge keeps the renderer in sync with them. Your frame does three things:

The renderer in a frame:

```
// app_init, main lane
ecs_renderer_init(world, &(RendererInitDesc){.shadows_enabled = true,
                                             .bloom_enabled = true});

// app_update_and_render, inside the scope
ecs_renderer_schedule(world);

// app_update_and_render, after the scope, every lane
renderer_update(renderer, &(RendererBeginFrameDesc){.camera = cam,
                                                    .time = memory->total_time});
```

## What's in the box

- **Lights**: a sun with cascaded shadows, and point, spot and rect (area) lights, all as components (`EcsDirectionalLight`, `EcsPointLight`, ...).
- **Environment**: image-based lighting from an `.hdr`, a physical sky and atmosphere or a stylized one, clouds, height fog, reflection probes, water.
- **Post**: bloom, auto-exposure, tonemapping and color grading, ambient occlusion, depth of field, screen-space reflections, god rays, TAA and upscaling.
- **World**: GPU particles, decals, trails, grass, terrain, Gaussian splats, GPU skinning and blendshapes.
- **Debug**: unlit, normals, wireframe, overdraw and LOD views, and debug shapes (`gizmos`) you can draw from any lane.

Scene-wide settings (ambient light, environment, fog, shadow distance) are the `EcsSceneSettings` component on one entity in your scene, so you tune them in the editor.

## Quality

The renderer has four quality levels, from `RENDERER_QUALITY_LOW` to `_ULTRA`. By default it starts at a level that fits the hardware it's on, and then moves up or down by how long the GPU actually takes, so a game runs on a phone and on a desktop GPU without you shipping two versions. Use `RENDERER_QUALITY_FIXED` if you want to pick it yourself.

## Materials and shaders

A material is an `.hzt` file that names a shader and sets its properties. Models bring their own materials when they're cooked, and most games never write a shader.

When you do, a shader is a plain `.glsl` file in your project's `shaders/` folder. The properties it declares in an `@material` block become the material's properties, which you can set per material file, or per object with a material instance:

A different color per object:

```
HzHandleT(RendererMaterial) mat =
    renderer_create_material_instance(r, base_material);
material_set_color4(r, mat, "color", (ColorF32){1, 0.2f, 0.1f, 1});
```

The starting template's floor (`st_grid.glsl`) is a short, complete example of a custom lit shader.

## Worth knowing

- `--commands "2:screenshot;3:quit"` saves a screenshot to `out/`, which is the quickest way to check what you changed.
- `hz/hzbuild shaders` rebuilds only the shaders.

The renderer is `hz/src/engine/rendering/renderer.h`, and its ECS side `hz/src/engine/ecs/renderer/ecs_renderer.h`.
