lv_draw.h

API reference for lv_draw.h

Summary

Functions

public/draw/lv_draw.h:274function

lv_draw_get_available_task

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.

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

Name	Type	Description
`layer`	`lv_layer_t *`	the draw layer to search in
`t_prev`	`lv_draw_task_t *`	continue searching from this task May be `NULL`.
`draw_unit_id`	`uint8_t`	check the task where `preferred_draw_unit_id` equals this value or `LV_DRAW_UNIT_NONE`

Returns: lv_draw_task_t * — an available draw task or NULL if there is not any

public/draw/lv_draw.h:293function

lv_draw_get_next_available_task

Find and available draw task

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)

Name	Type	Description
`layer`	`lv_layer_t *`	the draw layer to search in
`t_prev`	`lv_draw_task_t *`	continue searching from this task May be `NULL`.
`draw_unit_id`	`uint8_t`	check the task where `preferred_draw_unit_id` equals this value or `LV_DRAW_UNIT_NONE`

Returns: lv_draw_task_t * — an available draw task or NULL if there is not any

public/draw/lv_draw.h:303function

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

uint32_t lv_draw_get_dependent_count(lv_draw_task_t *t_check)

Name	Type	Description
`t_check`	`lv_draw_task_t *`	the task whose dependent tasks shall be counted May be `NULL`.

Returns: uint32_t — number of tasks depending on t_check

public/draw/lv_draw.h:367function

lv_draw_task_get_type

Get the type of a draw task

lv_draw_task_type_t lv_draw_task_get_type(const lv_draw_task_t *t)

Name	Type	Description
`t`	`const lv_draw_task_t *`	the draw task to get the type of

Returns: lv_draw_task_type_t — the draw task type

public/draw/lv_draw.h:374function

lv_draw_task_get_draw_dsc

Get the draw descriptor of a draw task

void * lv_draw_task_get_draw_dsc(const lv_draw_task_t *t)

Name	Type	Description
`t`	`const lv_draw_task_t *`	the draw task to get the draw descriptor of

Returns: void * — a void pointer to the draw descriptor

public/draw/lv_draw.h:381function

lv_draw_task_get_area

Get the draw area of a draw task

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

Name	Type	Description
`t`	`const lv_draw_task_t *`	the draw task to get the draw area of
`area`	`lv_area_t *`	the destination where the draw area will be stored

public/draw/lv_draw.h:207function

lv_draw_init

Used internally to initialize the drawing module

void lv_draw_init(void)

public/draw/lv_draw.h:212function

lv_draw_deinit

Deinitialize the drawing module

void lv_draw_deinit(void)

public/draw/lv_draw.h:219function

lv_draw_create_unit

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

void * lv_draw_create_unit(size_t size)

Name	Type	Description
`size`	`size_t`	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`.

public/draw/lv_draw.h:229function

lv_draw_add_task

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

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

Name	Type	Description
`layer`	`lv_layer_t *`	pointer to a layer
`coords`	`const lv_area_t *`	the coordinates of the draw task
`type`	`lv_draw_task_type_t`	the draw task type

Returns: lv_draw_task_t * — the created draw task which needs to be further configured e.g. by added a draw descriptor

public/draw/lv_draw.h:238function

lv_draw_finalize_task_creation

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.

void lv_draw_finalize_task_creation(lv_layer_t *layer, lv_draw_task_t *t)

Name	Type	Description
`layer`	`lv_layer_t *`	pointer to a layer
`t`	`lv_draw_task_t *`	pointer to a draw task

public/draw/lv_draw.h:243function

lv_draw_dispatch

Try dispatching draw tasks to draw units

void lv_draw_dispatch(void)

public/draw/lv_draw.h:251function

lv_draw_dispatch_layer

Used internally to try dispatching draw tasks of a specific layer

bool lv_draw_dispatch_layer(lv_display_t *disp, lv_layer_t *layer)

Name	Type	Description
`disp`	`lv_display_t *`	pointer to a display on which the dispatching was requested May be `NULL`.
`layer`	`lv_layer_t *`	pointer to a layer

Returns: bool — at least one draw task is being rendered (maybe it was taken earlier)

public/draw/lv_draw.h:257function

lv_draw_dispatch_wait_for_request

Wait for a new dispatch request. It's blocking if LV_USE_OS == 0 else it yields

void lv_draw_dispatch_wait_for_request(void)

public/draw/lv_draw.h:263function

lv_draw_wait_for_finish

Wait for draw finish in case of asynchronous task execution. If LV_USE_OS == 0 it just return.

void lv_draw_wait_for_finish(void)

public/draw/lv_draw.h:269function

lv_draw_dispatch_request

When a draw unit finished a draw task it needs to request dispatching to let LVGL assign a new draw task to it

void lv_draw_dispatch_request(void)

public/draw/lv_draw.h:313function

lv_draw_unit_send_event

Send an event to the draw units

void lv_draw_unit_send_event(const char *name, lv_event_code_t code, void *param)

Name	Type	Description
`name`	`const char *`	the name of the draw unit to send the event to May be `NULL`.. When NULL the event is sent to all draw units
`code`	`lv_event_code_t`	the event code
`param`	`void *`	the event parameter May be `NULL`.

public/draw/lv_draw.h:319function

lv_layer_init

Initialize a layer

void lv_layer_init(lv_layer_t *layer)

Name	Type	Description
`layer`	`lv_layer_t *`	pointer to a layer to initialize

public/draw/lv_draw.h:325function

lv_layer_reset

Reset the layer to a drawable state

void lv_layer_reset(lv_layer_t *layer)

Name	Type	Description
`layer`	`lv_layer_t *`	pointer to a layer to reset

public/draw/lv_draw.h:334function

lv_draw_layer_create

Create (allocate) a new layer on a parent layer

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

Name	Type	Description
`parent_layer`	`lv_layer_t *`	the parent layer to which the layer will be merged when it's rendered May be `NULL`.
`color_format`	`lv_color_format_t`	the color format of the layer
`area`	`const lv_area_t *`	the areas of the layer (absolute coordinates)

Returns: lv_layer_t * — the new target_layer or NULL on error

public/draw/lv_draw.h:343function

lv_draw_layer_init

Initialize a layer which is allocated by the user

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)

Name	Type	Description
`layer`	`lv_layer_t *`	pointer the layer to initialize (its lifetime needs to be managed by the user)
`parent_layer`	`lv_layer_t *`	the parent layer to which the layer will be merged when it's rendered May be `NULL`.
`color_format`	`lv_color_format_t`	the color format of the layer
`area`	`const lv_area_t *`	the areas of the layer (absolute coordinates)

public/draw/lv_draw.h:351function

lv_draw_layer_alloc_buf

Try to allocate a buffer for the layer.

void * lv_draw_layer_alloc_buf(lv_layer_t *layer)

Name	Type	Description
`layer`	`lv_layer_t *`	pointer to a layer

Returns: void * — pointer to the allocated aligned buffer or NULL on failure

public/draw/lv_draw.h:360function

lv_draw_layer_go_to_xy

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

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

Name	Type	Description
`layer`	`lv_layer_t *`	pointer to a layer
`x`	`int32_t`	the target X coordinate
`y`	`int32_t`	the target X coordinate

Returns: void * — buf offset to point to the given X and Y coordinate

public/draw/lv_draw.h:385function

lv_draw_layer_create_drop_shadow

lv_layer_t * lv_draw_layer_create_drop_shadow(lv_layer_t *parent_layer, const lv_draw_dsc_base_t *base, const lv_area_t *area)

Name	Type
`parent_layer`	`lv_layer_t *`
`base`	`const lv_draw_dsc_base_t *`
`area`	`const lv_area_t *`

public/draw/lv_draw.h:388function

lv_draw_layer_finish_drop_shadow

void lv_draw_layer_finish_drop_shadow(lv_layer_t *drop_shadow_layer, const lv_draw_dsc_base_t *base)

Name	Type
`drop_shadow_layer`	`lv_layer_t *`
`base`	`const lv_draw_dsc_base_t *`

public/draw/lv_draw.h:396function

lv_draw_layer_dealloc_buf

Deallocate a buffer attached to this layer.

void lv_draw_layer_dealloc_buf(lv_layer_t *layer)

Name	Type	Description
`layer`	`lv_layer_t *`	pointer to a layer

public/draw/lv_draw.h:402function

lv_draw_layer_deinit

Deinitialize a layer, reverse operation of lv_draw_layer_init

void lv_draw_layer_deinit(lv_layer_t *layer)

Name	Type	Description
`layer`	`lv_layer_t *`	pointer the layer to deinitialize May be `NULL`.

public/draw/lv_draw.h:408function

lv_draw_layer_delete

Delete a layer, reverse operation of lv_draw_layer_create

void lv_draw_layer_delete(lv_layer_t *layer)

Name	Type	Description
`layer`	`lv_layer_t *`	pointer the layer to delete May be `NULL`.

Enums

public/draw/lv_draw.h:46enum

lv_draw_task_type_t

Name	Value
`LV_DRAW_TASK_TYPE_NONE`	`0`
`LV_DRAW_TASK_TYPE_FILL`
`LV_DRAW_TASK_TYPE_BORDER`
`LV_DRAW_TASK_TYPE_BOX_SHADOW`
`LV_DRAW_TASK_TYPE_LETTER`
`LV_DRAW_TASK_TYPE_LABEL`
`LV_DRAW_TASK_TYPE_IMAGE`
`LV_DRAW_TASK_TYPE_LAYER`
`LV_DRAW_TASK_TYPE_LINE`
`LV_DRAW_TASK_TYPE_ARC`
`LV_DRAW_TASK_TYPE_TRIANGLE`
`LV_DRAW_TASK_TYPE_MASK_RECTANGLE`
`LV_DRAW_TASK_TYPE_MASK_BITMAP`
`LV_DRAW_TASK_TYPE_BLUR`
`LV_DRAW_TASK_TYPE_VECTOR`
`LV_DRAW_TASK_TYPE_3D`

Used by 1 function

lv_draw_add_task — param type

public/draw/lv_draw.h:69enum

lv_draw_task_state_t

Name	Description
`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.
`LV_DRAW_TASK_STATE_WAITING`	The draw task is added to the layers list and waits to be rendered.
`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.
`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.
`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.
`LV_DRAW_TASK_STATE_FAILED`

Structs

struct

_lv_layer_t

Member	Type	Description
`draw_buf`	`lv_draw_buf_t *`	Target draw buffer of the layer
`draw_task_head`	`lv_draw_task_t *`	Linked list of draw tasks
`display`	`lv_display_t *`	The display assigned to this layer
`parent`	`lv_layer_t *`	Parent layer
`next`	`lv_layer_t *`	Next layer
`user_data`	`void *`	User data
`buf_area`	`lv_area_t`	The absolute coordinates of the buffer
`phy_clip_area`	`lv_area_t`	The physical clipping area relative to the display
`_clip_area`	`lv_area_t`	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.
`partial_y_offset`	`int32_t`	Partial y offset
`recolor`	`lv_color32_t`	Recolor of the layer
`color_format`	`lv_color_format_t`	The color format of the layer. LV_COLOR_FORMAT_...
`all_tasks_added`	`bool`	Flag indicating all tasks are added
`opa`	`lv_opa_t`	Opacity of the layer
`buffer_owned`	`bool`	true if LVGL is responsible for freeing `draw_buf`

struct

lv_draw_dsc_base_t

Member	Type	Description
`obj`	`lv_obj_t *`	The widget for which draw descriptor was created
`part`	`uint32_t`	The widget part for which draw descriptor was created
`id1`	`uint32_t`	A widget type specific ID (e.g. table row index). See the docs of the given widget.
`id2`	`uint32_t`	A widget type specific ID (e.g. table column index). See the docs of the given widget.
`layer`	`lv_layer_t *`	The target layer
`drop_shadow_ofs_x`	`int16_t`	Drop shadow offset in X
`drop_shadow_ofs_y`	`int16_t`	Drop shadow offset in Y
`drop_shadow_color`	`lv_color_t`	Drop shadow color
`drop_shadow_opa`	`lv_opa_t`	Drop shadow opacity
`drop_shadow_blur_radius`	`int32_t`	Drop shadow blur radius
`drop_shadow_quality`	`lv_blur_quality_t`	Drop shadow blur quality
`dsc_size`	`size_t`	Size of the specific draw descriptor into which this base descriptor is embedded
`user_data`	`void *`	Any custom user data

Used by 2 functions

lv_draw_layer_create_drop_shadow — param base
lv_draw_layer_finish_drop_shadow — param base

Macros

public/draw/lv_draw.h:33macro

LV_DRAW_UNIT_NONE

#define LV_DRAW_UNIT_NONE 0

Modified by NXP in 2024

public/draw/lv_draw.h:34macro

LV_DRAW_UNIT_IDLE

#define LV_DRAW_UNIT_IDLE -1

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

lv_draw.h

On this page