1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
@page page_device_graphic_logo Boot Logo
# Boot Logo (PPM)
Implementation: **`components/drivers/graphic/logo/logo.c`**. Build converts a **PPM** asset into **`logo.inc`** (RGB triplets) at compile time. At runtime **`rt_graphic_logo_render()`** draws the logo centered on the framebuffer when a **`rt_graphic_device`** registers.
Graphic stack overview: @ref page_device_graphic_dm.
---
## Kconfig
| Option | Role |
| --- | --- |
| **`RT_GRAPHIC_LOGO`** | Enable logo subsystem; selects **`RT_GRAPHIC_FB`** |
| **`RT_GRAPHIC_LOGO_NONE`** | No built-in image — use **`rt_graphic_logo_change()`** at runtime |
| **`RT_GRAPHIC_LOGO_RT_THREAD_CLUT224`** | Embed **`logo-rt-thread-clut224.ppm`** (default) |
| **`RT_GRAPHIC_LOGO_RT_THREAD_WHITE_CLUT224`** | White variant PPM |
| **`SOC_DM_GRAPHIC_LOGO_DIR`** | BSP adds custom logo choices via **`Kconfig`** / **`Kconfig.path`** |
Custom BSP logos: define **`RT_GRAPHIC_LOGO_<NAME>`** in Kconfig and **`RT_GRAPHIC_LOGO_<NAME>_PATH`** (string, path to `.ppm`). **`logo/SConscript`** parses the file and generates **`logo.inc`**.
---
## When the logo is drawn
```
rt_graphic_device_register(gdev)
|
v
rt_graphic_logo_render(gdev) /* graphic.c; errors logged at DBG only */
|
+-- open fb device, GET_INFO, POWERON
+-- blit PPM RGB -> framebuffer (centered)
+-- RTGRAPHIC_CTRL_RECT_UPDATE + WAIT_VSYNC
+-- startup_logo = NULL (one-shot; frees built-in use)
```
- Runs when a graphic device successfully **registers** (see **`graphic.c`**).
- Requires **`RT_GRAPHIC_LOGO`** and non-empty **`startup_logo`** (built-in or **`rt_graphic_logo_change`**).
- If logo is larger than **`var.xres` / `var.yres`**, render fails with **`-RT_EINVAL`**.
---
## Runtime API (`graphic.h`)
### `rt_graphic_logo_change`
```c
rt_err_t rt_graphic_logo_change(void *data, int width, int height, int color_max);
```
| Arguments | Meaning |
| --- | --- |
| **`data`** | Pointer to **packed RGB** bytes (`width * height * 3`), same order as PPM pixmap data |
| **`width` / `height`** | Logo size in pixels |
| **`color_max`** | Max channel value in **`data`** (PPM **max pixel value**, e.g. **255** or **15**) |
| Call pattern | Effect |
| --- | --- |
| **`data == NULL` && all sizes 0** | Disable logo (**`startup_logo = NULL`**) |
| Valid **`data` + dimensions** | Replace logo used on next **`rt_graphic_logo_render`** |
| Otherwise | **`-RT_EINVAL`** |
Use with **`RT_GRAPHIC_LOGO_NONE`** or to override the built-in clut224 asset before the first **`register`**.
### `rt_graphic_logo_render`
```c
rt_err_t rt_graphic_logo_render(struct rt_graphic_device *gdev);
```
Normally called from **`rt_graphic_device_register()`** — drivers rarely invoke it directly. Steps:
1. **`rt_device_open`** on the graphic **`rt_device`**
2. **`FBIOGET_VSCREENINFO`** — grayscale vs RGB bitfield layout
3. **`RTGRAPHIC_CTRL_GET_INFO`** — framebuffer base + pitch
4. **`RTGRAPHIC_CTRL_POWERON`**
5. Center logo: **`rect.x/y = (screen - logo) / 2`**
6. Per-pixel color remap into **`bits_per_pixel`**
7. **`RTGRAPHIC_CTRL_RECT_UPDATE`** + **`RTGRAPHIC_CTRL_WAIT_VSYNC`**
8. Clears **`startup_logo`** (one-shot)
Without **`RT_GRAPHIC_LOGO`**, both APIs compile to inline no-ops returning **`RT_EOK`**.
---
## Build-time PPM → `logo.inc`
**`logo/SConscript`** (when a logo path is selected):
1. Read PPM header (**P1–P3** ASCII path in script).
2. Parse **`width height`**, **`max_pixel_value`**, pixel stream.
3. Emit **`logo.inc`**: rows of **`R,G,B`** byte triplets.
4. Define **`__STARTUP_LOGO_WIDTH__`**, **`__STARTUP_LOGO_HEIGHT__`**, **`__STARTUP_LOGO_COLOR_MAX__`**.
**`logo.c`** includes **`logo.inc`** into **`builtin_logo[]`** when all three macros are non-zero.
---
## Supported PPM variants
| Magic | Kind | Encoding | Notes |
| --- | --- | --- | --- |
| P1 | Bitmap | ASCII | Build script ASCII path |
| P2 | Graymap | ASCII | Build script ASCII path |
| P3 | Pixmap | ASCII | Typical for clut224 logos |
| P4 | Bitmap | Binary | Convert to P3 for embed |
| P5 | Graymap | Binary | Convert to P3 for embed |
| P6 | Pixmap | Binary | Use **`pnmnoraw`** → P3 for SConscript |
Runtime rendering always uses **RGB triplets** in memory.
---
## ASCII PPM layout
```text
# <magic>: P1 / P2 / P3 …
# <comment>
<width> <height>
<max_pixel_value>
<data…>
```
### Example (P3, 4×4)
```text
P3
# Standard 15-color test logo
4 4
15
0 0 0 0 0 0 0 0 0 15 0 15
0 0 0 0 15 7 0 0 0 0 0 0
0 0 0 0 0 0 0 15 7 0 0 0
15 0 15 0 0 0 0 0 0 0 0 0
```
| | Col 0 | Col 1 | Col 2 | Col 3 |
| --- | --- | --- | --- | --- |
| **Row 0** | 0,0,0 | 0,0,0 | 0,0,0 | 15,0,15 |
| **Row 1** | 0,0,0 | 0,15,7 | 0,0,0 | 0,0,0 |
| **Row 2** | 0,0,0 | 0,0,0 | 0,15,7 | 0,0,0 |
| **Row 3** | 15,0,15 | 0,0,0 | 0,0,0 | 0,0,0 |
---
## Generating a logo file
1. Convert source image to PPM:
```bash
magick <input>.png <output>.ppm
```
2. Reduce to **224** colors (clut224 path):
```bash
ppmquant 224 <input>.ppm > <tmp>_224.ppm
```
3. ASCII PPM for SConscript:
```bash
pnmnoraw <tmp>_224.ppm > logo-<name>-clut224.ppm
```
4. Point BSP **`RT_GRAPHIC_LOGO_<NAME>_PATH`** at the file, or replace in-tree **`logo-rt-thread-clut224.ppm`**.
---
## Offline preview
Open **`components/drivers/graphic/logo/logo.html`** in a browser to preview a PPM before building.
---
## BSP / integration quick notes
| Topic | Guidance |
| --- | --- |
| **Asset size** | Large PPM bloats **`logo.inc`** and slows boot — keep resolution modest. |
| **Display readiness** | Logo runs at **`register`** — enable backlight after first frame if needed (@ref page_device_graphic_backlight). |
| **Format** | Invalid PPM fails SConscript at build time; validate in CI. |
| **One-shot** | After first render, **`startup_logo`** is cleared — call **`rt_graphic_logo_change`** again for another splash. |
---
## Pitfalls
- **Logo bigger than mode**: **`-RT_EINVAL`** — match PPM to panel resolution.
- **`RT_GRAPHIC_LOGO_NONE` without `logo_change`**: no logo (by design).
- **Binary P6 without conversion**: SConscript may not parse — use **`pnmnoraw`**.
---
## See also
- @ref page_device_graphic_dm
- @ref page_device_graphic_framebuffer
- `components/drivers/graphic/logo/logo.c`, `logo/SConscript`
- `components/drivers/include/drivers/graphic.h`
|
