1# Add custom GPU
2LVGL has a flexible and extendable draw pipeline. You can hook it to do some rendering with a GPU or even completely replace the built-in software renderer.
3
4## Draw context
5The core structure of drawing is `lv_draw_ctx_t`.
6It contains a pointer to a buffer where drawing should happen and a couple of callbacks to draw rectangles, texts, and other primitives.
7
8### Fields
9`lv_draw_ctx_t` has the following fields:
10- `void * buf` Pointer to a buffer to draw into
11- `lv_area_t * buf_area` The position and size of `buf` (absolute coordinates)
12- `const lv_area_t * clip_area` The current clip area with absolute coordinates, always the same or smaller than `buf_area`. All drawings should be clipped to this area.
13- `void (*draw_rect)()` Draw a rectangle with shadow, gradient, border, etc.
14- `void (*draw_arc)()` Draw an arc
15- `void (*draw_img_decoded)()` Draw an (A)RGB image that is already decoded by LVGL.
16- `lv_res_t (*draw_img)()` Draw an image before decoding it (it bypasses LVGL's internal image decoders)
17- `void (*draw_letter)()` Draw a letter
18- `void (*draw_line)()` Draw a line
19- `void (*draw_polygon)()` Draw a polygon
20- `void (*draw_bg)()` Replace the buffer with a rect without decoration like radius or borders.
21- `void (*wait_for_finish)()` Wait until all background operation are finished. (E.g. GPU operations)
22- `void * user_data` Custom user data for arbitrary purpose
23
24(For the sake of simplicity the parameters of the callbacks are not shown here.)
25
26All `draw_*` callbacks receive a pointer to the current `draw_ctx` as their first parameter. Among the other parameters there is a descriptor that tells what to draw,
27e.g. for `draw_rect` it's called [lv_draw_rect_dsc_t](https://github.com/lvgl/lvgl/blob/master/src/draw/lv_draw_rect.h),
28for `lv_draw_line` it's called [lv_draw_line_dsc_t](https://github.com/lvgl/lvgl/blob/master/src/draw/lv_draw_line.h), etc.
29
30To correctly render according to a `draw_dsc` you need to be familiar with the [Boxing model](https://docs.lvgl.io/master/overview/coords.html#boxing-model) of LVGL and the meanings of the fields. The name and meaning of the fields are identical to name and meaning of the [Style properties](https://docs.lvgl.io/master/overview/style-props.html).
31
32### Initialization
33The `lv_disp_drv_t` has 4 fields related to the draw context:
34- `lv_draw_ctx_t * draw_ctx` Pointer to the `draw_ctx` of this display
35- `void (*draw_ctx_init)(struct _lv_disp_drv_t * disp_drv, lv_draw_ctx_t * draw_ctx)` Callback to initialize a `draw_ctx`
36- `void (*draw_ctx_deinit)(struct _lv_disp_drv_t * disp_drv, lv_draw_ctx_t * draw_ctx)` Callback to de-initialize a `draw_ctx`
37- `size_t draw_ctx_size` Size of the draw context structure. E.g. `sizeof(lv_draw_sw_ctx_t)`
38
39When you ignore these fields, LVGL will set default values for callbacks and size in `lv_disp_drv_init()` based on the configuration in `lv_conf.h`.
40`lv_disp_drv_register()` will allocate a `draw_ctx` based on `draw_ctx_size` and call `draw_ctx_init()` on it.
41
42However, you can overwrite the callbacks and the size values before calling `lv_disp_drv_register()`.
43It makes it possible to use your own `draw_ctx` with your own callbacks.
44
45
46## Software renderer
47LVGL's built in software renderer extends the basic `lv_draw_ctx_t` structure and sets the draw callbacks. It looks like this:
48```c
49typedef struct {
50   /** Include the basic draw_ctx type*/
51    lv_draw_ctx_t base_draw;
52
53    /** Blend a color or image to an area*/
54    void (*blend)(lv_draw_ctx_t * draw_ctx, const lv_draw_sw_blend_dsc_t * dsc);
55} lv_draw_sw_ctx_t;
56```
57
58Set the draw callbacks in `draw_ctx_init()` like:
59```c
60draw_sw_ctx->base_draw.draw_rect = lv_draw_sw_rect;
61draw_sw_ctx->base_draw.draw_letter = lv_draw_sw_letter;
62...
63```
64
65### Blend callback
66As you saw above the software renderer adds the `blend` callback field. It's a special callback related to how the software renderer works.
67All draw operations end up in the `blend` callback which can either fill an area or copy an image to an area by considering an optional mask.
68
69The `lv_draw_sw_blend_dsc_t` parameter describes what and how to blend. It has the following fields:
70- `const lv_area_t * blend_area` The area with absolute coordinates to draw on `draw_ctx->buf`. If `src_buf` is set, it's the coordinates of the image to blend.
71- `const lv_color_t * src_buf` Pointer to an image to blend. If set, `color` is ignored. If not set fill `blend_area` with `color`
72- `lv_color_t color` Fill color. Used only if `src_buf == NULL`
73- `lv_opa_t * mask_buf` NULL if ignored, or an alpha mask to apply on `blend_area`
74- `lv_draw_mask_res_t mask_res` The result of the previous mask operation. (`LV_DRAW_MASK_RES_...`)
75- `const lv_area_t * mask_area` The area of `mask_buf` with absolute coordinates
76- `lv_opa_t opa` The overall opacity
77- `lv_blend_mode_t blend_mode` E.g. `LV_BLEND_MODE_ADDITIVE`
78
79
80## Extend the software renderer
81
82### New blend callback
83
84Let's take a practical example: you would like to use your MCUs GPU for color fill operations only.
85
86As all draw callbacks call `blend` callback to fill an area in the end only the `blend` callback needs to be overwritten.
87
88First extend `lv_draw_sw_ctx_t`:
89```c
90
91/*We don't add new fields, so just for clarity add new type*/
92typedef lv_draw_sw_ctx_t my_draw_ctx_t;
93
94void my_draw_ctx_init(lv_disp_drv_t * drv, lv_draw_ctx_t * draw_ctx)
95{
96    /*Initialize the parent type first */
97    lv_draw_sw_init_ctx(drv, draw_ctx);
98
99    /*Change some callbacks*/
100    my_draw_ctx_t * my_draw_ctx = (my_draw_ctx_t *)draw_ctx;
101
102    my_draw_ctx->blend = my_draw_blend;
103    my_draw_ctx->base_draw.wait_for_finish = my_gpu_wait;
104}
105```
106
107After calling `lv_disp_draw_init(&drv)` you can assign the new `draw_ctx_init` callback and set `draw_ctx_size` to overwrite the defaults:
108```c
109static lv_disp_drv_t drv;
110lv_disp_draw_init(&drv);
111drv->hor_res = my_hor_res;
112drv->ver_res = my_ver_res;
113drv->flush_cb = my_flush_cb;
114
115/*New draw ctx settings*/
116drv->draw_ctx_init = my_draw_ctx_init;
117drv->draw_ctx_size = sizeof(my_draw_ctx_t);
118
119lv_disp_drv_register(&drv);
120```
121
122This way when LVGL calls `blend` it will call `my_draw_blend` and we can do custom GPU operations. Here is a complete example:
123```c
124void my_draw_blend(lv_draw_ctx_t * draw_ctx, const lv_draw_sw_blend_dsc_t * dsc)
125{
126    /*Let's get the blend area which is the intersection of the area to fill and the clip area.*/
127    lv_area_t blend_area;
128    if(!_lv_area_intersect(&blend_area, dsc->blend_area, draw_ctx->clip_area)) return;  /*Fully clipped, nothing to do*/
129
130    /*Fill only non masked, fully opaque, normal blended and not too small areas*/
131    if(dsc->src_buf == NULL && dsc->mask == NULL && dsc->opa >= LV_OPA_MAX &&
132       dsc->blend_mode == LV_BLEND_MODE_NORMAL && lv_area_get_size(&blend_area) > 100) {
133
134        /*Got the first pixel on the buffer*/
135        lv_coord_t dest_stride = lv_area_get_width(draw_ctx->buf_area); /*Width of the destination buffer*/
136        lv_color_t * dest_buf = draw_ctx->buf;
137        dest_buf += dest_stride * (blend_area.y1 - draw_ctx->buf_area->y1) + (blend_area.x1 - draw_ctx->buf_area->x1);
138
139        /*Make the blend area relative to the buffer*/      
140        lv_area_move(&blend_area, -draw_ctx->buf_area->x1, -draw_ctx->buf_area->y1);
141       
142        /*Call your custom gou fill function to fill blend_area, on dest_buf with dsc->color*/  
143        my_gpu_fill(dest_buf, dest_stride, &blend_area, dsc->color);
144    }
145    /*Fallback: the GPU doesn't support these settings. Call the SW renderer.*/
146    else {
147      lv_draw_sw_blend_basic(draw_ctx, dsc);
148    }
149}
150```
151
152The implementation of wait callback is much simpler:
153```c
154void my_gpu_wait(lv_draw_ctx_t * draw_ctx)
155{
156    while(my_gpu_is_working());
157   
158    /*Call SW renderer's wait callback too*/
159    lv_draw_sw_wait_for_finish(draw_ctx);
160}
161```
162
163### New rectangle drawer
164If your MCU has a more powerful GPU that can draw e.g. rounded rectangles you can replace the original software drawer too.
165A custom `draw_rect` callback might look like this:
166```c
167void my_draw_rect(lv_draw_ctx_t * draw_ctx, const lv_draw_rect_dsc_t * dsc, const lv_area_t * coords)
168{
169  if(lv_draw_mask_is_any(coords) == false && dsc->grad == NULL && dsc->bg_img_src == NULL &&
170     dsc->shadow_width == 0 && dsc->blend_mode = LV_BLEND_MODE_NORMAL)
171  {
172    /*Draw the background*/
173    my_bg_drawer(draw_ctx, coords, dsc->bg_color, dsc->radius);
174   
175    /*Draw the border if any*/
176    if(dsc->border_width) {
177      my_border_drawer(draw_ctx, coords, dsc->border_width, dsc->border_color, dsc->border_opa)
178    }
179   
180    /*Draw the outline if any*/
181    if(dsc->outline_width) {
182      my_outline_drawer(draw_ctx, coords, dsc->outline_width, dsc->outline_color, dsc->outline_opa, dsc->outline_pad)
183    }
184  }
185  /*Fallback*/
186  else {
187    lv_draw_sw_rect(draw_ctx, dsc, coords);
188  }
189}
190```
191
192`my_draw_rect` can fully bypass the use of `blend` callback if needed.
193
194## Fully custom draw engine
195
196For example if your MCU/MPU supports a powerful vector graphics engine you might use only that instead of LVGL's SW renderer.
197In this case, you need to base the renderer on the basic `lv_draw_ctx_t` (instead of `lv_draw_sw_ctx_t`) and extend/initialize it as you wish.
198
199