# kdrv_compose

The driver of the ESP32-P4's pixel accelerator on the Kode Dot: fill, scale and blend on RGB565 pictures, the alignment an output needs, and who may call it.

## What it is

The ESP32-P4 has a pixel accelerator, the PPA, that moves pictures without the CPU. **kdrv_compose** is the Kode Dot's driver for it. It runs three kinds of pass on RGB565 pictures in memory:

- A **fill**: a block of a picture painted one colour.
- A **scale**: a block of one picture copied into another, scaled and turned by quarter turns.
- A **blend**: a block of one picture laid over another at an opacity.

Each call is one blocking pass. The driver keeps no picture of its own: the caller owns every buffer.

## How it is connected

```mermaid
flowchart LR
  ks["kscreen<br/>an app's renderer"] -- "display_compose_run()" --> ao["AO_Display"]
  row["AO_Autotest<br/>test component=compose"] -- "display_compose_run()" --> ao
  mir["kdrv_ppa<br/>the mirror"] --> drv
  ao -- "kdrv_compose_fill / scale / blend" --> drv["kdrv_compose"]
  drv -- "driver/ppa.h" --> ppa["PPA"]
  class ao ao
  class ppa chip
```

*Who asks the accelerator for a pass*

**AO_Display owns the accelerator** and is the only caller. It claims `KBSP_RES_PPA` when the mirror or `CONFIG_KODE_COMPOSE` is built, and runs every pass in its own step. A renderer, the self-test row or a worker task asks it for a pass with `display_compose_run()` (`sdk/kaos/display`), and an app's renderer reaches that through kscreen (`sdk/kscreen`). The mirror's half-size copy of the glass goes through the same driver (`kdrv_ppa`, `sdk/kdrv/mirror`), so the mirror and a renderer share one set of accelerator clients on AO_Display's thread.

The scale is always built, for the mirror. The fill and the blend are built only with `CONFIG_KODE_COMPOSE`, which is off by default in the SDK and off in KodeOS.

Each kind of pass registers its own accelerator client the first time it is asked for. `kdrv_compose_init()` registers the scale's at start and takes no picture memory.

## Specifications

### Pictures

A picture (`kdrv_compose_pic_t`) is RGB565, row after row from the top, `w` times 2 bytes a row:

| Field | What it holds |
| --- | --- |
| `px` | The pixels |
| `bytes` | The size of the allocation, at least `w` × `h` × 2 |
| `w`, `h` | Width and height in pixels |

A block (`kdrv_compose_rect_t`: `x`, `y`, `w`, `h`) is a part of a picture, in pixels from its top left.

| Constant | Value | Meaning |
| --- | --- | --- |
| `KDRV_COMPOSE_ALIGN` | 64 | An output picture's address and `bytes` are multiples of this, one cache line |
| `KDRV_COMPOSE_PX_BYTES` | 2 | RGB565 |
| `KDRV_COMPOSE_SIDE_MAX` | 502 | The longest side of a picture, the glass's longer side. A picture is then at most 1.23 times the glass, so the largest pass is about one pass over a full frame |
| `KDRV_COMPOSE_SCALE_ONE` | 16 | The same size, in sixteenths |
| `KDRV_COMPOSE_SCALE_MIN`, `_MAX` | 1, 256 | One sixteenth to sixteen times |
| `KDRV_COMPOSE_OPA_MAX` | 255 | A foreground that covers what is under it |
| `KDRV_COMPOSE_TURNS` | 4 | Quarter turns in a whole one: a turn is 0 to 3 |

### Calls

| Call | What it does |
| --- | --- |
| `kdrv_compose_init()` | Registers the scale's client. Idempotent. `KODE_NO_RESOURCES` when the accelerator gave no client |
| `kdrv_compose_fill(dst, at, argb8888)` | Paints the block `at` of `dst` one colour, `0xAARRGGBB`. The alpha is not used. With `CONFIG_KODE_COMPOSE` |
| `kdrv_compose_scale(dst, x, y, src, from, sx, sy, turns)` | Copies the block `from` of `src` into `dst` at `x`, `y`, scaled by `sx` and `sy` sixteenths along the block's own width and height, and turned `turns` quarter turns counter-clockwise. An odd turn lands the block as tall as it was wide. `dst` is never `src` |
| `kdrv_compose_blend(dst, x, y, fg, from, opa)` | Lays the block `from` of `fg` over `dst` at `x`, `y`: each pixel is `fg` at `opa` over what `dst` held, written in place. 0 leaves `dst` as it is. With `CONFIG_KODE_COMPOSE` |

Every pass answers the same way:

- `KODE_OK`: the pixels are there.
- `KODE_DENIED`: a NULL, malformed or oversized picture, a block that does not fit, a scale or a turn out of range, or a result that is empty or does not fit `dst`. The check is plain arithmetic (`kdrv_compose_check.c`), with no accelerator, so the host tests run it.
- `KODE_NO_RESOURCES`: no accelerator client.
- `KODE_ERROR`: the accelerator refused the pass. The log names its size.

### The caches

The accelerator reads and writes memory behind the CPU's caches. For a fill and a blend, ESP-IDF's PPA driver writes the output's rows back before the pass. For a scale it only drops the cache's copy of the rows its output block touches, so kdrv_compose first writes those rows back itself: pixels the CPU drew beside the block survive the pass. This is why an output picture starts on a cache line and spans whole cache lines.

## Gotchas

> **WARNING**
>
> **`KODE_DENIED` for a picture that looks right.** An output picture's address or its `bytes` is not a multiple of 64. Allocate it with the cache-aligned capability and round its size up to whole 64-byte lines.

> **NOTE**
>
> **`kdrv_compose_fill()` and `kdrv_compose_blend()` do not link.** They exist only with `CONFIG_KODE_COMPOSE=y`. The scale is always there.

> **NOTE**
>
> **Call it from AO_Display alone.** The driver has no lock of its own: AO_Display's step is what keeps one pass at a time. An app asks for a pass through kscreen or `display_compose_run()`.

## In the SDK

- [`components/kdrv/compose`](https://github.com/kodediy/kode-sdk/tree/main/components/kdrv/compose): `kdrv_compose.c`, the passes, and `kdrv_compose_check.c`, the arithmetic that judges them.
- [`components/kaos/display`](https://github.com/kodediy/kode-sdk/tree/main/components/kaos/display): AO_Display, which runs the passes (`sdk/kaos/display`).
