SDK
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
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
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 fitdst. 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
In the SDK
components/kdrv/compose:kdrv_compose.c, the passes, andkdrv_compose_check.c, the arithmetic that judges them.components/kaos/display: AO_Display, which runs the passes (sdk/kaos/display).