---
title: "GPU2D Layer Compose"
description: "Compose ARGB8888 layers through the portable `` surface and check the result — on the RZ/V2N's Mali-G31 when the image carries the Renesas graphics stack, on the CPU otherwise. The source does not change between the two. A Linux/Yocto user-space app on the Cortex-A55 cluster."
source: https://docs.alplab.ai/sdk/examples/v2n/v2n-gpu2d-compose
---

# `v2n-gpu2d-compose`

Compose ARGB8888 layers through the portable [`<alp/gpu2d.h>`](https://docs.alplab.ai/sdk/api/gpu2d) surface and check the result — on the RZ/V2N's **Mali-G31** when the image carries the Renesas graphics stack, on the CPU otherwise. The source does not change between the two. A Linux/Yocto user-space app on the Cortex-A55 cluster.

Source: [`examples/v2n/v2n-gpu2d-compose/`](https://github.com/alplabai/alp-sdk/tree/main/examples/v2n/v2n-gpu2d-compose). New in alp-sdk v0.17.0.

:::warning[`[UNTESTED on silicon]`]
The Mali-G31 GLES backend has not run on a board. The CPU path it falls back to is the same software fallback that is unit-tested on `native_sim`. The HIL spec exists but has not been bench-run.
:::

## What it shows

1. `alp_gpu2d_open()` plus the three ops — `fill_rect`, `blit` and `blend` — on caller-owned memory. No EGL, no GLES, no vendor header in the app.
2. How to see which engine served the ops: `alp_gpu2d_capabilities()` carries `ALP_INSTANCE_CAP_DMA` for a hardware backend. That is for diagnostics only — never branch drawing code on it.
3. Why the surface is 640×360: the GPU path uploads, draws and reads back, so small rects are cheaper on the CPU, and the SDK sends them there op by op.

## `board.yaml`

```yaml
som:
  sku: E1M-V2N101

preset: e1m-x-evk

cores:
  a55_cluster:
    app: ./src                   # Linux userspace app -- <alp/gpu2d.h> only
    recipe: alp-gpu2d-compose    # meta-alp-sdk/recipes-examples/alp-gpu2d-compose
  m33_sm:
    os: "off"                    # the GPU is A55/Linux-owned; no M33 app here.

diagnostics:
  log_level: info
```

The Mali-G31 is present on every E1M-V2N / E1M-V2M SKU; only the base `E1M-V2N101` is declared and built here.

## Build and run

`alp-image-edge` installs the `alp-gpu2d-compose` recipe on every Mali-family machine. For the GPU engine to be selected, the image also needs the Renesas `meta-rz-graphics` layer (the alp-sdk recipe then turns its GLES `PACKAGECONFIG` on by itself) and a running weston (`IMAGE_FEATURES += "alp-display"`). Without the GPU stack, the same binary runs on the CPU fallback and says so. Run `v2n-gpu2d-compose` on the target.

## Expected output

```
[gpu2d] engine: GPU context up (EGL/GLES)      # or "CPU fallback"
[gpu2d] centre pixel 0x... expected ~0xFF881018 # within 1 per channel of the formula
[gpu2d] 20 x blend 640x360: ... ms total
[gpu2d] PASS
```

The `engine:` line only shows that a GPU context came up. The GPU backend also writes `[gpu2d/gles] ...` lines to stderr — one on the first GL-error fallback, and at close the totals (`N op(s) ran on the GPU, M fell back`) — and **those** show which engine really ran.

## See also

- [`<alp/gpu2d.h>` reference](https://docs.alplab.ai/sdk/api/gpu2d)
- [`aen-gpu2d-bench`](https://docs.alplab.ai/sdk/examples/aen/aen-bench-tools#npu--inference) — the software-fallback bench on the AEN M55
- [LVGL Dashboard (E1M-X EVK)](https://docs.alplab.ai/sdk/examples/lvgl-dashboard-x-evk)
- [Examples overview](https://docs.alplab.ai/sdk/examples/overview)
