Draw Pipeline¶

What is Drawing?¶

Drawing (also known as 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¶

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 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 or insert new ones as LVGL renders Widgets.

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

Draw Tasks¶

A "Draw Task" (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 lv_draw_rect() and 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 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.)
area:: defines the rectangle in which drawing will occur
transformation matrix:: if 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¶

A "Draw Unit" (based on lv_draw_unit_t) is any "logic entity" that can generate the output required by a Draw Task. 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.

Creating Draw Units¶

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

You can also add your own Draw Unit(s) after lv_init() by calling 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 lv_draw_sw_init() in lv_draw_sw.c or the other draw units whose init functions are in lv_init().

Thread Priority¶

If LV_USE_OS is set to something other than 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 LV_DRAW_THREAD_PRIO (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¶

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¶

When each Draw Task 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.

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¶

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.

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 LV_DRAW_TASK_STATE_FINISHED.

Hierarchy Summary¶

All of the above have this relationship:

LVGL (global)
- list of Draw Units
- list of Display(s)
  - Layer(s): Each Display object has its own list of Draw Layers
    - Draw Tasks: Each Layer has its own list of Draw Tasks

API¶