# Draw Pipeline (/main-modules/draw/draw_pipeline)



What is Drawing? [#what-is-drawing]

Drawing (also known as :dfn:`rendering`) is writing pixel colors into a buffer from
where they will be delivered to a display panel as pixels. It can mean filling areas
with a color, blending images, or using complex algorithms to, for example, calculate rounded
corners or rotate images.

The following sections cover how LVGL's drawing logic works and how to use it.

Draw-Pipeline Overview [#draw-pipeline-overview]

Modern embedded devices come with a wide variety of solutions to speed up rendering:

* 2D GPUs fill areas and blend images
* 2.5D (Vector graphics) GPUs
* 3D GPUs (e.g. for OpenGL)
* SIMD assembly-level acceleration
* multi-core CPUs
* Software libraries
* and more

To make it possible to utilize such facilities in the most efficient fashion, LVGL
implements a :dfn:`Drawing Pipeline`, like an assembly line, where decisions are
made as to which drawing tasks (Draw Tasks) are given to which Draw Units
(rendering engines) in order to be carried out.

This Pipeline is designed so that it is both flexible and extensible. You can use it
to perform custom rendering with a GPU or replace parts of the built-in software
rendering logic to any extent desired.

Using events, it's also possible to modify [Draw Tasks](/main-modules/draw/draw_pipeline) or insert new ones as
LVGL renders Widgets.

The following sections describe the basic terminology and concepts of rendering.

Draw Tasks [#draw-tasks]

A "Draw Task" (<ApiLink name="lv_draw_task_t" />) is a package of information that is
created at the beginning of the Drawing Pipeline when a request to draw is made.
Functions such as <ApiLink name="lv_draw_rect" /> and <ApiLink name="lv_draw_label" /> create
one or more Draw Tasks and pass them down the Drawing Pipeline. Each Draw Task
carries all the information required to:

* compute which [Draw Unit](/main-modules/draw/draw_pipeline) should receive this task, and
* give the Draw Unit all the information required to accomplish the drawing task.

A Draw Task carries the following information:

:type:                    defines the drawing algorithm involved (e.g. line, fill,
border, image, label, arc, triangle, etc.)

| Field                    | Description                                                                                               |
| ------------------------ | --------------------------------------------------------------------------------------------------------- |
| `area`                   | defines the rectangle in which drawing will occur                                                         |
| `transformation matrix`  | if <ApiLink name="LV_DRAW_TRANSFORM_USE_MATRIX" /> is configured to '1'                                   |
| `state`                  | waiting, queued, in progress, completed                                                                   |
| `drawing descriptor`     | carries details of the drawing to be performed                                                            |
| `preferred Draw Unit ID` | identifier of the Draw Unit that should carry out this task                                               |
| `preference score`       | value describing the speed of the specified Draw Unit relative to software rendering (more on this below) |
| `next`                   | a link to the next Draw Task in the list.                                                                 |

Draw Tasks are collected in a list and periodically dispatched to Draw Units.

Draw Units [#draw-units]

A "Draw Unit" (based on <ApiLink name="lv_draw_unit_t" />) is any "logic entity" that can
generate the output required by a [Draw Task](/main-modules/draw/draw_pipeline). This can be a CPU
core, a GPU, a custom rendering library for specific Draw Tasks, or any entity
capable of performing rendering.

For a reference implementation of a draw unit, see
[lv\_draw\_sw.c](https://github.com/lvgl/lvgl/blob/master/src/draw/sw/lv_draw_sw.c).

Learn more about [Draw Units](/main-modules/draw/draw_pipeline)

Creating Draw Units [#creating-draw-units]

During LVGL's initialization (in <ApiLink name="lv_init" />), a list of Draw Units is created
from the enabled built-in draw units. For example, if <ApiLink name="LV_USE_DRAW_SW" /> is
enabled, it will be automatically initialized and used for rendering. The same applies for
<ApiLink name="LV_USE_DRAW_OPENGLES" />, <ApiLink name="LV_USE_PXP" />, <ApiLink name="LV_USE_DRAW_SDL" />, or
<ApiLink name="LV_USE_DRAW_VG_LITE" />.

You can also add your own Draw Unit(s) after <ApiLink name="lv_init" /> by calling
<ApiLink name="lv_draw_create_unit" display="lv_draw_create_unit(sizeof(your_draw_unit_t))" />. You also need to
add custom `evaluate_cb` and `dispatch_cb` callbacks (mentioned later)
to the new draw unit.

For an example of how draw-unit creation and initialization is done, see
<ApiLink name="lv_draw_sw_init" /> in lv\_draw\_sw\.c\_ or the other draw units whose `init`
functions are in <ApiLink name="lv_init" />.

Thread Priority [#thread-priority]

If <ApiLink name="LV_USE_OS" /> is set to something other than <ApiLink name="LV_OS_NONE" />, draw units might use a thread to
allow waiting for the completion of rendering in a non-blocking way.

The thread priority can be set using the <ApiLink name="LV_DRAW_THREAD_PRIO" />
(<ApiLink name="LV_THREAD_PRIO_HIGH" /> by default) configuration option in `lv_conf.h`.
This allows you to fine-tune the priority level for rendering in general.

Clip Area [#clip-area]

LVGL clips the children widgets to the parent's boundary. To do that, it needs to know
the current clip area when creating a draw task. The current clip area is the smallest
intersection of all parent clip areas and the widget to be rendered. So, if a widget is
out of its parent at the bottom and only its top part is visible, the clip area will be
that small top part.

As the current clip area always changes as LVGL traverses the widget tree, the clip
area is saved in each draw task. This clip area should be considered by the draw units
too, for example, to mask out only a smaller part of an image to be blended.

Draw Task Evaluation [#draw-task-evaluation]

When each [Draw Task](/main-modules/draw/draw_pipeline) is created, each existing Draw Unit is
"consulted" as to its "appropriateness" for the task. It does this through
an "evaluation callback" function pointer (a.k.a. `evaluate_cb`), which each Draw
Unit sets (for itself) during its initialization. Normally, that evaluation:

* optionally examines the existing "preference score" for the task mentioned above,
* if it can accomplish that type of task (e.g. line drawing) faster than other
  Draw Units that have already reported, it writes its own "preference score" and
  "preferred Draw Unit ID" to the respective fields in the task.

In this way, by the time the evaluation sequence is complete, the task will contain
the score and the ID of the Draw Unit that will be used to perform that task when
it is [dispatched](/main-modules/draw/draw_pipeline).

This ensures that the same Draw Unit will be selected
consistently, depending on the type (and nature) of the drawing task, avoiding any
possible screen jitter in case more than one Draw Unit is capable of performing a
given task type.

Dispatching [#dispatching]

While collecting Draw Tasks, LVGL frequently dispatches the collected Draw Tasks to
their assigned Draw Units. This is handled via the `dispatch_cb` of the Draw Units.

If a Draw Unit is busy with another Draw Task, it just returns. However, if it is
available, it can take a Draw Task.

<ApiLink name="lv_draw_get_next_available_task" display="lv_draw_get_next_available_task(layer, previous_task, draw_unit_id)" /> is a
useful helper function which is used by the `dispatch_cb` to get the next Draw Task
it should act on. If it handled the task, it sets the Draw Task's `state` field to
<ApiLink name="LV_DRAW_TASK_STATE_FINISHED" />.

Hierarchy Summary [#hierarchy-summary]

All of the above have this relationship:

* LVGL (global)

  * list of Draw Units
  * list of [Display(s)](/main-modules/display/overview)

    * Layer(s): Each [Display object](/main-modules/display/overview) has its own list of [Draw Layers](/main-modules/draw/draw_layers)

      * Draw Tasks: Each Layer has its own list of Draw Tasks

API [#api]