# lv_draw.h (/api/draw/lv_draw_h) Functions [#functions] lv_draw_get_unit_count [#lv_draw_get_unit_count] Get the total number of draw units. ```c title=" " lineNumbers=1 uint32_t lv_draw_get_unit_count(void) ``` lv_draw_get_available_task [#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. ```c title=" " lineNumbers=1 lv_draw_task_t * lv_draw_get_available_task(lv_layer_t *layer, lv_draw_task_t *t_prev, uint8_t draw_unit_id) ``` Parameters | Name | Type | Description | | -------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `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_get_next_available_task [#lv_draw_get_next_available_task] Find and available draw task ```c title=" " lineNumbers=1 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) ``` Parameters | Name | Type | Description | | -------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `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_get_dependent_count [#lv_draw_get_dependent_count] 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 ```c title=" " lineNumbers=1 uint32_t lv_draw_get_dependent_count(lv_draw_task_t *t_check) ``` Parameters | Name | Type | Description | | --------- | ------------------------------------------------------------ | ----------------------------------------------- | | `t_check` | | the task whose dependent tasks shall be counted | **Returns:** — number of tasks depending on `t_check` lv_draw_task_get_type [#lv_draw_task_get_type] Get the type of a draw task ```c title=" " lineNumbers=1 lv_draw_task_type_t lv_draw_task_get_type(const lv_draw_task_t *t) ``` Parameters | Name | Type | Description | | ---- | ------------------------------------------------------------------ | -------------------------------- | | `t` | | the draw task to get the type of | **Returns:** — the draw task type lv_draw_task_get_draw_dsc [#lv_draw_task_get_draw_dsc] Get the draw descriptor of a draw task ```c title=" " lineNumbers=1 void * lv_draw_task_get_draw_dsc(const lv_draw_task_t *t) ``` Parameters | Name | Type | Description | | ---- | ------------------------------------------------------------------ | ------------------------------------------- | | `t` | | the draw task to get the draw descriptor of | **Returns:** `void *` — a void pointer to the draw descriptor lv_draw_task_get_area [#lv_draw_task_get_area] Get the draw area of a draw task ```c title=" " lineNumbers=1 void lv_draw_task_get_area(const lv_draw_task_t *t, lv_area_t *area) ``` Parameters | Name | Type | Description | | ------ | ------------------------------------------------------------------ | -------------------------------------------------- | | `t` | | the draw task to get the draw area of | | `area` | | the destination where the draw area will be stored | lv_draw_init [#lv_draw_init] Used internally to initialize the drawing module ```c title=" " lineNumbers=1 void lv_draw_init(void) ``` lv_draw_deinit [#lv_draw_deinit] Deinitialize the drawing module ```c title=" " lineNumbers=1 void lv_draw_deinit(void) ``` lv_draw_create_unit [#lv_draw_create_unit] Allocate a new draw unit with the given size and appends it to the list of draw units ```c title=" " lineNumbers=1 void * lv_draw_create_unit(size_t size) ``` Parameters | Name | Type | Description | | ------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `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_add_task [#lv_draw_add_task] Add an empty draw task to the draw task list of a layer. ```c title=" " lineNumbers=1 lv_draw_task_t * lv_draw_add_task(lv_layer_t *layer, const lv_area_t *coords, lv_draw_task_type_t type) ``` Parameters | Name | Type | Description | | -------- | -------------------------------------------------------- | -------------------------------- | | `layer` | | pointer to a layer | | `coords` | | the coordinates of the draw task | | `type` | | | **Returns:** — the created draw task which needs to be further configured e.g. by added a draw descriptor lv_draw_finalize_task_creation [#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. ```c title=" " lineNumbers=1 void lv_draw_finalize_task_creation(lv_layer_t *layer, lv_draw_task_t *t) ``` Parameters | Name | Type | Description | | ------- | ------------------------------------------------------------ | ---------------------- | | `layer` | | pointer to a layer | | `t` | | pointer to a draw task | lv_draw_dispatch [#lv_draw_dispatch] Try dispatching draw tasks to draw units ```c title=" " lineNumbers=1 void lv_draw_dispatch(void) ``` lv_draw_dispatch_layer [#lv_draw_dispatch_layer] Used internally to try dispatching draw tasks of a specific layer ```c title=" " lineNumbers=1 bool lv_draw_dispatch_layer(lv_display_t *disp, lv_layer_t *layer) ``` Parameters | Name | Type | Description | | ------- | -------------------------------------------------------- | ----------------------------------------------------------- | | `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) lv_draw_dispatch_wait_for_request [#lv_draw_dispatch_wait_for_request] Wait for a new dispatch request. It's blocking if `LV_USE_OS == 0` else it yields ```c title=" " lineNumbers=1 void lv_draw_dispatch_wait_for_request(void) ``` lv_draw_wait_for_finish [#lv_draw_wait_for_finish] Wait for draw finish in case of asynchronous task execution. If `LV_USE_OS == 0` it just return. ```c title=" " lineNumbers=1 void lv_draw_wait_for_finish(void) ``` lv_draw_dispatch_request [#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 ```c title=" " lineNumbers=1 void lv_draw_dispatch_request(void) ``` lv_draw_unit_send_event [#lv_draw_unit_send_event] Send an event to the draw units ```c title=" " lineNumbers=1 void lv_draw_unit_send_event(const char *name, lv_event_code_t code, void *param) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------- | ---------------------------------------------- | | `name` | `const char *` | the name of the draw unit to send the event to | | `code` | | the event code | | `param` | `void *` | the event parameter | lv_layer_init [#lv_layer_init] Initialize a layer ```c title=" " lineNumbers=1 void lv_layer_init(lv_layer_t *layer) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | -------------------------------- | | `layer` | | pointer to a layer to initialize | lv_layer_reset [#lv_layer_reset] Reset the layer to a drawable state ```c title=" " lineNumbers=1 void lv_layer_reset(lv_layer_t *layer) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | --------------------------- | | `layer` | | pointer to a layer to reset | lv_draw_layer_create [#lv_draw_layer_create] Create (allocate) a new layer on a parent layer ```c title=" " lineNumbers=1 lv_layer_t * lv_draw_layer_create(lv_layer_t *parent_layer, lv_color_format_t color_format, const lv_area_t *area) ``` Parameters | Name | Type | Description | | -------------- | -------------------------------------------------------- | --------------------------------------------------------------------- | | `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 lv_draw_layer_init [#lv_draw_layer_init] Initialize a layer which is allocated by the user ```c title=" " lineNumbers=1 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) ``` Parameters | Name | Type | Description | | -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | | `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) | lv_draw_layer_alloc_buf [#lv_draw_layer_alloc_buf] Try to allocate a buffer for the layer. ```c title=" " lineNumbers=1 void * lv_draw_layer_alloc_buf(lv_layer_t *layer) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | ------------------ | | `layer` | | pointer to a layer | **Returns:** `void *` — pointer to the allocated aligned buffer or NULL on failure lv_draw_layer_go_to_xy [#lv_draw_layer_go_to_xy] Got to a pixel at X and Y coordinate on a layer ```c title=" " lineNumbers=1 void * lv_draw_layer_go_to_xy(lv_layer_t *layer, int32_t x, int32_t y) ``` Parameters | Name | Type | Description | | ------- | ---------------------------------------------------- | ----------------------- | | `layer` | | pointer to a layer | | `x` | | the target X coordinate | | `y` | | the target X coordinate | **Returns:** `void *` — `buf` offset to point to the given X and Y coordinate lv_draw_layer_create_drop_shadow [#lv_draw_layer_create_drop_shadow] ```c title=" " lineNumbers=1 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) ``` Parameters | Name | Type | | -------------- | -------------------------------------------------------------------------- | | `parent_layer` | | | `base` | | | `area` | | lv_draw_layer_finish_drop_shadow [#lv_draw_layer_finish_drop_shadow] ```c title=" " lineNumbers=1 void lv_draw_layer_finish_drop_shadow(lv_layer_t *drop_shadow_layer, const lv_draw_dsc_base_t *base) ``` Parameters | Name | Type | | ------------------- | -------------------------------------------------------------------------- | | `drop_shadow_layer` | | | `base` | | Enums [#enums] lv_draw_task_type_t [#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` | | * `lv_draw_add_task` — param `type` lv_draw_task_state_t [#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. | Structs [#structs] \_lv_layer_t [#_lv_layer_t] | Member | Type | Description | | ------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `draw_buf` | | Target draw buffer of the layer | | `draw_task_head` | | Linked list of draw tasks | | `parent` | | Parent layer | | `next` | | Next layer | | `user_data` | `void *` | User data | | `buf_area` | | The absolute coordinates of the buffer | | `phy_clip_area` | | The physical clipping area relative to the display | | `_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 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` | | Partial y offset | | `recolor` | | Recolor of the layer | | `color_format` | | The color format of the layer. LV\_COLOR\_FORMAT\_... | | `all_tasks_added` | | Flag indicating all tasks are added | | `opa` | | Opacity of the layer | lv_draw_dsc_base_t [#lv_draw_dsc_base_t] | Member | Type | Description | | ------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------- | | `obj` | | The widget for which draw descriptor was created | | `part` | | The widget part for which draw descriptor was created | | `id1` | | A widget type specific ID (e.g. table row index). See the docs of the given widget. | | `id2` | | A widget type specific ID (e.g. table column index). See the docs of the given widget. | | `layer` | | The target layer | | `drop_shadow_ofs_x` | | Drop shadow offset in X | | `drop_shadow_ofs_y` | | Drop shadow offset in Y | | `drop_shadow_color` | | Drop shadow color | | `drop_shadow_opa` | | Drop shadow opacity | | `drop_shadow_blur_radius` | | Drop shadow blur radius | | `drop_shadow_quality` | | Drop shadow blur quality | | `dsc_size` | | Size of the specific draw descriptor into which this base descriptor is embedded | | `user_data` | `void *` | Any custom user data | * `lv_draw_layer_create_drop_shadow` — param `base` * `lv_draw_layer_finish_drop_shadow` — param `base` Macros [#macros] LV_DRAW_UNIT_NONE [#lv_draw_unit_none] ```c title=" " lineNumbers=1 #define LV_DRAW_UNIT_NONE 0 ``` Modified by NXP in 2024 LV_DRAW_UNIT_IDLE [#lv_draw_unit_idle] ```c title=" " lineNumbers=1 #define LV_DRAW_UNIT_IDLE -1 ``` The draw unit is idle, new dispatching might be requested to try again Dependencies [#dependencies]