lv_draw.h¶

Defines

LV_DRAW_UNIT_NONE¶: Modified by NXP in 2024

LV_DRAW_UNIT_IDLE¶: The draw unit is idle, new dispatching might be requested to try again

Enums

enum lv_draw_task_type_t¶

Values:

enumerator LV_DRAW_TASK_TYPE_NONE¶

enumerator LV_DRAW_TASK_TYPE_FILL¶

enumerator LV_DRAW_TASK_TYPE_BORDER¶

enumerator LV_DRAW_TASK_TYPE_BOX_SHADOW¶

enumerator LV_DRAW_TASK_TYPE_LETTER¶

enumerator LV_DRAW_TASK_TYPE_LABEL¶

enumerator LV_DRAW_TASK_TYPE_IMAGE¶

enumerator LV_DRAW_TASK_TYPE_LAYER¶

enumerator LV_DRAW_TASK_TYPE_LINE¶

enumerator LV_DRAW_TASK_TYPE_ARC¶

enumerator LV_DRAW_TASK_TYPE_TRIANGLE¶

enumerator LV_DRAW_TASK_TYPE_MASK_RECTANGLE¶

enumerator LV_DRAW_TASK_TYPE_MASK_BITMAP¶

enumerator LV_DRAW_TASK_TYPE_VECTOR¶

enumerator LV_DRAW_TASK_TYPE_3D¶

enum lv_draw_task_state_t¶

Values:

enumerator LV_DRAW_TASK_STATE_BLOCKED¶: Waiting for an other task to be finished. For example in case of LV_DRAW_TASK_TYPE_LAYER (used to blend a layer) is blocked until all the draw tasks of the layer is rendered.

enumerator LV_DRAW_TASK_STATE_WAITING¶: The draw task is added to the layers list and waits to be rendered.

enumerator LV_DRAW_TASK_STATE_QUEUED¶: The draw task is added to the command queue of the draw unit. As the queued task are executed in order it's possible to queue multiple draw task (for the same draw unit) even if they are depending on each other. Therefore lv_draw_get_available_task and lv_draw_get_next_available_task can return draw task for the same draw unit even if a dependent draw task is not finished ready yet.

enumerator LV_DRAW_TASK_STATE_IN_PROGRESS¶: The draw task is being rendered. This draw task needs to be finished before lv_draw_get_available_task and lv_draw_get_next_available_task would return any depending draw tasks.

enumerator LV_DRAW_TASK_STATE_FINISHED¶: The draw task is rendered. It will be removed from the draw task list of the layer and freed automatically.

Functions

void lv_draw_init(void)¶: Used internally to initialize the drawing module

void lv_draw_deinit(void)¶: Deinitialize the drawing module

void *lv_draw_create_unit(size_t size)¶

Allocate a new draw unit with the given size and appends it to the list of draw units

Parameters:: size – the size to allocate. E.g. sizeof(my_draw_unit_t), where the first element of my_draw_unit_t is lv_draw_unit_t.

lv_draw_task_t *lv_draw_add_task(lv_layer_t *layer, const lv_area_t *coords, lv_draw_task_type_t type)¶

Add an empty draw task to the draw task list of a layer.

Parameters:

layer – pointer to a layer
coords – the coordinates of the draw task

Returns:

the created draw task which needs to be further configured e.g. by added a draw descriptor

void lv_draw_finalize_task_creation(lv_layer_t *layer, lv_draw_task_t *t)¶

Needs to be called when a draw task is created and configured. It will send an event about the new draw task to the widget and assign it to a draw unit.

Parameters:

layer – pointer to a layer
t – pointer to a draw task

void lv_draw_dispatch(void)¶: Try dispatching draw tasks to draw units

bool lv_draw_dispatch_layer(lv_display_t *disp, lv_layer_t *layer)¶

Used internally to try dispatching draw tasks of a specific layer

Parameters:

disp – pointer to a display on which the dispatching was requested
layer – pointer to a layer

Returns:

at least one draw task is being rendered (maybe it was taken earlier)

void lv_draw_dispatch_wait_for_request(void)¶: Wait for a new dispatch request. It's blocking if LV_USE_OS == 0 else it yields

void lv_draw_wait_for_finish(void)¶: Wait for draw finish in case of asynchronous task execution. If LV_USE_OS == 0 it just return.

void lv_draw_dispatch_request(void)¶: When a draw unit finished a draw task it needs to request dispatching to let LVGL assign a new draw task to it

uint32_t lv_draw_get_unit_count(void)¶: Get the total number of draw units.

lv_draw_task_t *lv_draw_get_available_task(lv_layer_t *layer, lv_draw_task_t *t_prev, uint8_t draw_unit_id)¶

If there is only one draw unit check the first draw task if it's available. If there are multiple draw units call lv_draw_get_next_available_task to find a task.

Parameters:

layer – the draw layer to search in
t_prev – continue searching from this task
draw_unit_id – check the task where preferred_draw_unit_id equals this value or LV_DRAW_UNIT_NONE

Returns:

an available draw task or NULL if there is not any

lv_draw_task_t *lv_draw_get_next_available_task(lv_layer_t *layer, lv_draw_task_t *t_prev, uint8_t draw_unit_id)¶

Find and available draw task

Parameters:

layer – the draw layer to search in
t_prev – continue searching from this task
draw_unit_id – check the task where preferred_draw_unit_id equals this value or LV_DRAW_UNIT_NONE

Returns:

an available draw task or NULL if there is not any

uint32_t lv_draw_get_dependent_count(lv_draw_task_t *t_check)¶

Tell how many draw task are waiting to be drawn on the area of t_check. It can be used to determine if a GPU shall combine many draw tasks into one or not. If a lot of tasks are waiting for the current ones it makes sense to draw them one-by-one to not block the dependent tasks' rendering

Parameters:: t_check – the task whose dependent tasks shall be counted
Returns:: number of tasks depending on t_check

void lv_layer_init(lv_layer_t *layer)¶

Initialize a layer

Parameters:: layer – pointer to a layer to initialize

void lv_layer_reset(lv_layer_t *layer)¶

Reset the layer to a drawable state

Parameters:: layer – pointer to a layer to reset

lv_layer_t *lv_draw_layer_create(lv_layer_t *parent_layer, lv_color_format_t color_format, const lv_area_t *area)¶

Create (allocate) a new layer on a parent layer

Parameters:

parent_layer – the parent layer to which the layer will be merged when it's rendered
color_format – the color format of the layer
area – the areas of the layer (absolute coordinates)

Returns:

the new target_layer or NULL on error

void lv_draw_layer_init(lv_layer_t *layer, lv_layer_t *parent_layer, lv_color_format_t color_format, const lv_area_t *area)¶

Initialize a layer which is allocated by the user

Parameters:

layer – pointer the layer to initialize (its lifetime needs to be managed by the user)
parent_layer – the parent layer to which the layer will be merged when it's rendered
color_format – the color format of the layer
area – the areas of the layer (absolute coordinates)

Returns:

the new target_layer or NULL on error

void *lv_draw_layer_alloc_buf(lv_layer_t *layer)¶

Try to allocate a buffer for the layer.

Parameters:: layer – pointer to a layer
Returns:: pointer to the allocated aligned buffer or NULL on failure

void *lv_draw_layer_go_to_xy(lv_layer_t *layer, int32_t x, int32_t y)¶

Got to a pixel at X and Y coordinate on a layer

Parameters:

layer – pointer to a layer
x – the target X coordinate
y – the target X coordinate

Returns:

buf offset to point to the given X and Y coordinate

lv_draw_task_type_t lv_draw_task_get_type(const lv_draw_task_t *t)¶

Get the type of a draw task

Parameters:: t – the draw task to get the type of
Returns:: the draw task type

void *lv_draw_task_get_draw_dsc(const lv_draw_task_t *t)¶

Get the draw descriptor of a draw task

Parameters:: t – the draw task to get the draw descriptor of
Returns:: a void pointer to the draw descriptor

void lv_draw_task_get_area(const lv_draw_task_t *t, lv_area_t *area)¶

Get the draw area of a draw task

Parameters:

t – the draw task to get the draw area of
area – the destination where the draw area will be stored

struct _lv_layer_t¶

Public Members

lv_draw_buf_t *draw_buf¶: Target draw buffer of the layer

lv_draw_task_t *draw_task_head¶: Linked list of draw tasks

lv_layer_t *parent¶: Parent layer

lv_layer_t *next¶: Next layer

void *user_data¶: User data

lv_area_t buf_area¶: The absolute coordinates of the buffer

lv_area_t phy_clip_area¶: The physical clipping area relative to the display

lv_area_t _clip_area¶: NEVER USE IT DRAW UNITS. USED INTERNALLY DURING DRAW TASK CREATION. The current clip area with absolute coordinates, always the same or smaller than buf_area Can be set before new draw tasks are added to indicate the clip area of the draw tasks. Therefore lv_draw_add_task() always saves it in the new draw task to know the clip area when the draw task was added. During drawing the draw units also sees the saved clip_area and should use it during drawing. During drawing the layer's clip area shouldn't be used as it might be already changed for other draw tasks.

int32_t partial_y_offset¶: Partial y offset

lv_color32_t recolor¶: Recolor of the layer

lv_color_format_t color_format¶: The color format of the layer. LV_COLOR_FORMAT_...

bool all_tasks_added¶: Flag indicating all tasks are added

lv_opa_t opa¶: Opacity of the layer

struct lv_draw_dsc_base_t¶

Public Members

lv_obj_t *obj¶: The widget for which draw descriptor was created

uint32_t part¶: The widget part for which draw descriptor was created

uint32_t id1¶: A widget type specific ID (e.g. table row index). See the docs of the given widget.

uint32_t id2¶: A widget type specific ID (e.g. table column index). See the docs of the given widget.

lv_layer_t *layer¶: The target layer

size_t dsc_size¶: Size of the specific draw descriptor into which this base descriptor is embedded

void *user_data¶: Any custom user data