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:

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
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:

FieldWhat it holds
pxThe pixels
bytesThe size of the allocation, at least w × h × 2
w, hWidth 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.

ConstantValueMeaning
KDRV_COMPOSE_ALIGN64An output picture's address and bytes are multiples of this, one cache line
KDRV_COMPOSE_PX_BYTES2RGB565
KDRV_COMPOSE_SIDE_MAX502The 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_ONE16The same size, in sixteenths
KDRV_COMPOSE_SCALE_MIN, _MAX1, 256One sixteenth to sixteen times
KDRV_COMPOSE_OPA_MAX255A foreground that covers what is under it
KDRV_COMPOSE_TURNS4Quarter turns in a whole one: a turn is 0 to 3

Calls

CallWhat 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:

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