mirror of
https://github.com/lvgl/lvgl.git
synced 2025-02-04 07:13:00 +08:00
126 lines
3.3 KiB
ReStructuredText
126 lines
3.3 KiB
ReStructuredText
.. _lv_canvas:
|
|
|
|
==================
|
|
Canvas (lv_canvas)
|
|
==================
|
|
|
|
|
|
Overview
|
|
********
|
|
|
|
A Canvas inherits from :ref:`Image <lv_image>` and extends it, enabling the user to draw
|
|
anything. Rectangles, text, images, lines, arcs, etc. can be drawn here using
|
|
LVGL's extensive drawing engine.
|
|
|
|
|
|
.. _lv_canvas_parts_and_styles:
|
|
|
|
Parts and Styles
|
|
****************
|
|
|
|
- :cpp:enumerator:`LV_PART_MAIN` Uses the :ref:`typical background <typical bg props>`
|
|
and image style properties.
|
|
|
|
|
|
.. _lv_canvas_usage:
|
|
|
|
Usage
|
|
*****
|
|
|
|
Buffer
|
|
------
|
|
|
|
The Canvas needs a buffer in which to store the drawn image. To assign a
|
|
buffer to a Canvas, use
|
|
:cpp:expr:`lv_canvas_set_buffer(canvas, buffer, width, height, LV_COLOR_FORMAT_...)`.
|
|
Where ``buffer`` is a static buffer (not just a local variable) to hold
|
|
the image of the Canvas. For example for a 100x50 ARGB8888 buffer:
|
|
``static uint8_t buffer[100 * 50 * 4]``.
|
|
|
|
Or you can use
|
|
``static uint8_t buffer[LV_CANVAS_BUF_SIZE(width, height, bits_per_pixel, stride_in_bytes)]``.
|
|
|
|
Canvas supports all the color formats like
|
|
:cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` or :cpp:enumerator:`LV_COLOR_FORMAT_I2`. See the full
|
|
list in the :ref:`Color formats <overview_image_color_formats>` section.
|
|
|
|
Indexed colors
|
|
--------------
|
|
|
|
For indexed color formats (``LV_COLOR_FORMAT_I1/2/4/8``), the palette needs to be
|
|
populated for all palette indices that will be used using
|
|
:cpp:expr:`lv_canvas_set_palette(canvas, index, color)`. For example, the following
|
|
sets pixels with *index==3* to red.
|
|
|
|
.. code-block:: c
|
|
|
|
lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000))
|
|
|
|
Drawing
|
|
-------
|
|
|
|
To set an individual pixel's color on the Canvas, use
|
|
:cpp:expr:`lv_canvas_set_px(canvas, x, y, color, opa)`. With indexed color formats
|
|
(``LV_COLOR_FORMAT_I1/2/4/8``) pass the color index as the ``color`` argument by using
|
|
the *blue* channel in the ``color`` value, e.g. :cpp:expr:`lv_color_make(0, 0, index)`.
|
|
|
|
:cpp:expr:`lv_canvas_fill_bg(canvas, lv_color_hex(0x00ff00), LV_OPA_50)` fills the whole
|
|
Canvas to blue with 50% opacity. Note that if the current color format
|
|
doesn't support colors (e.g. :cpp:enumerator:`LV_COLOR_FORMAT_A8`) the color will be
|
|
ignored. Similarly, if opacity is not supported
|
|
(e.g. :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`), it will be ignored.
|
|
|
|
An array of pixels can be copied to the Canvas with
|
|
:cpp:expr:`lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height)`. The
|
|
color format of the buffer and Canvas need to match.
|
|
|
|
To draw something to the Canvas use LVGL's draw functions directly. See the examples for more details.
|
|
|
|
The draw functions can draw to any color format to which LVGL can render. Typically this means
|
|
:cpp:enumerator:`LV_COLOR_FORMAT_RGB565`, :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`,
|
|
:cpp:enumerator:`LV_COLOR_FORMAT_XRGB888`, and :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`.
|
|
|
|
|
|
|
|
.. _lv_canvas_events:
|
|
|
|
Events
|
|
******
|
|
|
|
No special events are sent by Canvas Widgets.
|
|
|
|
.. admonition:: Further Reading
|
|
|
|
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
|
|
|
|
Learn more about :ref:`events`.
|
|
|
|
|
|
|
|
.. _lv_canvas_keys:
|
|
|
|
Keys
|
|
****
|
|
|
|
No *Keys* are processed by Canvas Widgets.
|
|
|
|
.. admonition:: Further Reading
|
|
|
|
Learn more about :ref:`indev_keys`.
|
|
|
|
|
|
|
|
.. _lv_canvas_example:
|
|
|
|
Example
|
|
*******
|
|
|
|
.. include:: ../../examples/widgets/canvas/index.rst
|
|
|
|
|
|
|
|
.. _lv_canvas_api:
|
|
|
|
API
|
|
***
|