github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(libs): proofread docs batch18 (#7688)

Browse Source 
Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Co-authored-by: Liam Howatt <30486941+liamHowatt@users.noreply.github.com>
This commit is contained in:
Victor Wheeler
2025-02-19 06:39:03 -07:00
committed by GitHub
parent 10fbcef470
commit 377cc5aa80
12 changed files with 261 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/details/libs/ffmpeg.rst
View File

@@ -1,17 +1,26 @@
.. _ffmpeg:
==============
FFmpeg support
FFmpeg Support
==============
A complete, cross-platform solution to record, convert and stream audio and video.
**FFmpeg** is a complete, cross-platform solution to record, convert and stream audio and video.
Detailed introduction: https://www.ffmpeg.org
The FFmpeg is an LVGL extension that interfaces with the official FFmpeg library to help
you add platform-independent recording, converting and streaming audio and video into
your LVGL UI.
Install FFmpeg
--------------
The set-up steps below are for Linux, but they can be adapted for other platforms.
Download first FFmpeg from `here <https://www.ffmpeg.org/download.html>`__, then install it:
For a detailed introduction, see: https://www.ffmpeg.org
Installing FFmpeg
*****************
Download the FFmpeg library from `its official download page
<https://www.ffmpeg.org/download.html>`__, then install it:
.. code-block:: shell
@@ -19,39 +28,65 @@ Download first FFmpeg from `here <https://www.ffmpeg.org/download.html>`__, then
make
sudo make install
Add FFmpeg to your project
--------------------------
- Add library: ``FFmpeg`` (for GCC: ``-lavformat -lavcodec -lavutil -lswscale -lm -lz -lpthread``)
Adding FFmpeg to Your Project
*****************************
To use the ``FFmpeg`` library in your project, you will need to link against these
libraries:
:libavformat: part of FFmpeg library
:libavcodec: part of FFmpeg library
:libavutil: part of FFmpeg library
:libswscale: part of FFmpeg library
:libm:
:libz:
:libpthread:
If you are using GCC-based toolchain, this can be taken care of by adding the
following command-line options:
.. code-block:: shell
-lavformat -lavcodec -lavutil -lswscale -lm -lz -lpthread
.. _ffmpeg_usage:
Usage
-----
*****
Enable :c:macro:`LV_USE_FFMPEG` in ``lv_conf.h``.
Set the :c:macro:`LV_USE_FFMPEG` in ``lv_conf.h`` to ``1``.
See the examples below.
Also set :c:macro:`LV_FFMPEG_PLAYER_USE_LV_FS` in ``lv_conf.h`` to ``1`` if you want
to integrate the LVGL :ref:`file_system` extension into FFmpeg.
See the examples below for how to correctly use this library.
:note: Enable :c:macro:`LV_FFMPEG_PLAYER_USE_LV_FS` in ``lv_conf.h`` if you want to integrate the lvgl file system into FFmpeg.
.. _ffmpeg_example:
Events
------
******
- :cpp:enumerator:`LV_EVENT_READY` Sent when playback is complete and auto-restart is not enabled.
Learn more about :ref:`events`.
Example
-------
Examples
********
.. include:: ../../examples/libs/ffmpeg/index.rst
.. _ffmpeg_api:
API
---
***

41
docs/details/libs/freetype.rst
View File

@@ -1,23 +1,29 @@
.. _freetype:
================
FreeType support
FreeType Support
================
Interface to FreeType library to generate font bitmaps at run time.
**FreeType** is a freely available software library to render fonts.
A detailed introduction can be found at: https://freetype.org/ .
The LVGL FreeType extension is an interface to the FreeType library, enabling you to
generate font bitmaps at run time from most vector- and bitmap-font file formats.
For a detailed introduction, see: https://freetype.org/ .
Add FreeType to your project
****************************
Adding FreeType to Your Project
*******************************
First, Download FreeType from `here <https://sourceforge.net/projects/freetype/files/>`__.
First, Download FreeType from the ``freetype2`` folder (and optionally ``freetype-docs``
and ``freetype-demos``) from its `official repository
<https://sourceforge.net/projects/freetype/files/>`__. (The latest version is
recommended.)
If you haven't already done so, now is a good time to get familiar with setting up
and configuring this library. The above website is a good place to start, as is the
``README`` file in the top directory of the freetype project directory.
``README`` file in the top directory of the version you downloaded.
There are two ways to use FreeType:
@@ -30,7 +36,7 @@ For UNIX systems, the following is recommended to compile and install FreeType l
- ``make``
- ``sudo make install``
- Add include path: ``/usr/include/freetype2`` (for GCC: ``-I/usr/include/freetype2 -L/usr/local/lib``)
- Link library: ``freetype`` (for GCC: ``-L/usr/local/lib -lfreetype``)
- Link against library: ``freetype`` (for GCC: ``-L/usr/local/lib -lfreetype``)
For Embedded Devices
--------------------
@@ -77,7 +83,7 @@ save limited FLASH space.
Usage
*****
Enable :c:macro:`LV_USE_FREETYPE` in ``lv_conf.h``.
Set :c:macro:`LV_USE_FREETYPE` in ``lv_conf.h`` to ``1``.
Cache configuration:
@@ -109,7 +115,14 @@ rendered. An example on how to draw a colored bitmap glyph is shown below.
Use the :cpp:func:`lv_freetype_font_create` function to create a font. To
delete a font, use :cpp:func:`lv_freetype_font_delete`. For more detailed usage,
please refer to example code.
please refer to the example code below.
.. admonition:: Further Reading
- `FreeType tutorial <https://www.freetype.org/freetype2/docs/tutorial/step1.html>`__
- LVGL's :ref:`add_font`
@@ -122,14 +135,6 @@ Examples
Learn More
**********
- FreeType`tutorial <https://www.freetype.org/freetype2/docs/tutorial/step1.html>`__
- LVGL's :ref:`add_font`
.. _freetype_api:
API

45
docs/details/libs/gif.rst
View File

@@ -1,49 +1,54 @@
.. _gif:
===========
GIF decoder
GIF Decoder
===========
Allow using GIF images in LVGL.
**GIF Decoder** is an LVGL extension that enables you to use GIF images in your LVGL UI.
Detailed introduction: https://github.com/lecram/gifdec
For a detailed introduction, see: https://github.com/lecram/gifdec .
When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_GIF`
Usage
*****
Once enabled in ``lv_conf.h`` by setting :c:macro:`LV_USE_GIF` to ``1``,
:cpp:expr:`lv_gif_create(parent)` can be used to create a gif widget.
:cpp:expr:`lv_gif_set_src(widget, src)` works very similarly to :cpp:func:`lv_image_set_src`.
As source, it also accepts images as variables (:c:struct:`lv_image_dsc_t`) or
files.
As source, it also accepts images as variables (:c:struct:`lv_image_dsc_t`) or files.
Convert GIF files to C array
----------------------------
Converting GIF Files to C Arrays
--------------------------------
To convert a GIF file to byte values array use `LVGL's online
To convert a GIF file to an array of bytes, use `LVGL's online
converter <https://lvgl.io/tools/imageconverter>`__. Select "Raw" color
format and "C array" Output format.
Use GIF images from file
------------------------
Using GIF Images from Files
---------------------------
For example:
Example:
.. code-block:: c
lv_gif_set_src(widget, "S:path/to/example.gif");
Note that, a file system driver needs to be registered to open images
from files. Read more about it :ref:`overview_file_system` or just
enable one in ``lv_conf.h`` with ``LV_USE_FS_...``
from files. To do so, follow the instructions in :ref:`file_system`.
Memory requirements
Memory Requirements
-------------------
To decode and display a GIF animation the following amount of RAM is
required:
To decode and display a GIF animation the following amount of RAM (in bytes) is
required for each of the following color depths:
- :c:macro:`LV_COLOR_DEPTH` ``8``: 3 x image width x image height
- :c:macro:`LV_COLOR_DEPTH` ``16``: 4 x image width x image height
- :c:macro:`LV_COLOR_DEPTH` ``32``: 5 x image width x image height
.. |times| unicode:: U+000D7 .. MULTIPLICATION SIGN
- :c:macro:`LV_COLOR_DEPTH` ``8``: 3 |times| image width |times| image height
- :c:macro:`LV_COLOR_DEPTH` ``16``: 4 |times| image width |times| image height
- :c:macro:`LV_COLOR_DEPTH` ``32``: 5 |times| image width |times| image height
.. _gif_example:

26
docs/details/libs/lfs.rst
View File

@@ -1,23 +1,28 @@
.. _lfs:
==============
========
littlefs
==============
========
littlefs is a little fail-safe filesystem designed for microcontrollers.
**littlefs** is a little fail-safe filesystem library designed for microcontrollers.
The lv_fs_littlefs extension is an interface to the littlefs library.
For a detailed introduction, see: https://github.com/littlefs-project/littlefs .
Detailed introduction: https://github.com/littlefs-project/littlefs
Usage
-----
*****
Enable :c:macro:`LV_USE_FS_LITTLEFS` and define a :c:macro:`LV_FS_LITTLEFS_LETTER` in ``lv_conf.h``.
Set :c:macro:`LV_USE_FS_LITTLEFS` in ``lv_conf.h`` to ``1`` and define an upper-case
letter (as a C character type) for :c:macro:`LV_FS_LITTLEFS_LETTER` in the range
['A'..'Z'].
When enabled :c:macro:`lv_littlefs_set_handler` can be used to set up a mount point.
When enabled :cpp:func:`lv_littlefs_set_handler` can be used to set up a mount point.
Example
-------
*******
.. code-block:: c
@@ -55,6 +60,9 @@ Example
API
---
***
:ref:`lv_fsdrv_h`
See also: `lvgl/src/libs/fsdrv/lv_fs_littlefs.c <https://github.com/lvgl/lvgl/blob/master/src/libs/fsdrv/lv_fs_littlefs.c>`__

52
docs/details/libs/libjpeg_turbo.rst
View File

@@ -1,27 +1,38 @@
.. _libjpeg:
=====================
libjpeg-turbo decoder
libjpeg-turbo Decoder
=====================
**libjpeg-turbo** is a JPEG image codec that uses SIMD instructions to accelerate baseline JPEG compression and decompression on x86,
x86-64, Arm, PowerPC, and MIPS systems, as well as progressive JPEG compression on x86, x86-64, and Arm systems.
**libjpeg-turbo** is an LVGL interface to the libjpeg-turbo library --- a JPEG image
codec that uses SIMD instructions to accelerate baseline JPEG compression and
decompression on x86, x86-64, Arm, PowerPC, and MIPS systems, as well as progressive
JPEG compression on x86, x86-64, and Arm systems.
On such systems, libjpeg-turbo is generally 2-6x as fast as libjpeg, all else being
equal.
For a detailed introduction, see: https://libjpeg-turbo.org .
Library source: https://github.com/libjpeg-turbo/libjpeg-turbo
Detailed introduction: https://libjpeg-turbo.org
Library source: https://github.com/libjpeg-turbo/libjpeg-turbo
.. _libjpeg_install:
Install
-------
*******
.. code-block:: bash
sudo apt install libjpeg-turbo8-dev
Add libjpeg-turbo to your project
---------------------------------
Adding libjpeg-turbo to Your Project
*************************************
Cmake:
.. code-block:: cmake
@@ -29,28 +40,41 @@ Add libjpeg-turbo to your project
include_directories(${JPEG_INCLUDE_DIR})
target_link_libraries(${PROJECT_NAME} PRIVATE ${JPEG_LIBRARIES})
.. _libjpeg_usage:
Usage
-----
*****
Enable :c:macro:`LV_USE_LIBJPEG_TURBO` in ``lv_conf.h``.
Set :c:macro:`LV_USE_LIBJPEG_TURBO` in ``lv_conf.h`` to ``1``.
See the examples below.
It should be noted that each image of this decoder needs to consume ``image width x image height x 3`` bytes of RAM,
and it needs to be combined with the :ref:`overview_image_caching` feature to ensure that the memory usage is within a reasonable range.
.. |times| unicode:: U+000D7 .. MULTIPLICATION SIGN
It should be noted that each image decoded needs to consume:
image width |times| image height |times| 3
bytes of RAM, and it needs to be combined with the :ref:`overview_image_caching`
feature to ensure that the memory usage is within a reasonable range.
.. _libjpeg_example:
Example
-------
*******
.. include:: ../../examples/libs/libjpeg_turbo/index.rst
.. _libjpeg_api:
API
---
***
:ref:`lv_libjpeg_turbo_h`

47
docs/details/libs/libpng.rst
View File

@@ -1,22 +1,30 @@
.. _libpng:
==============
libpng decoder
libpng Decoder
==============
libpng is the official PNG reference library. It supports almost all PNG features, is extensible, and has been extensively tested for over 28 years.
**libpng** is an LVGL interface to the the official PNG reference library, which
supports almost all PNG features, is extensible, and has been extensively tested for
over 28 years.
For a detailed introduction, see: http://www.libpng.org/pub/png/libpng.html .
Detailed introduction: http://www.libpng.org/pub/png/libpng.html
Install
-------
*******
.. code-block:: bash
sudo apt install libpng-dev
Add libpng to your project
--------------------------
Adding libpng to Your Project
*****************************
Cmake:
.. code-block:: cmake
@@ -24,29 +32,42 @@ Add libpng to your project
include_directories(${PNG_INCLUDE_DIR})
target_link_libraries(${PROJECT_NAME} PRIVATE ${PNG_LIBRARIES})
.. _libpng_usage:
Usage
-----
*****
Enable :c:macro:`LV_USE_LIBPNG` in ``lv_conf.h``.
Set :c:macro:`LV_USE_LIBPNG` in ``lv_conf.h`` to ``1``.
See the examples below.
It should be noted that each image of this decoder needs to consume ``width x height x 4`` bytes of RAM,
and it needs to be combined with the :ref:`overview_image_caching` feature to ensure that the memory usage is within a reasonable range.
The decoded image is stored in RGBA pixel format.
.. |times| unicode:: U+000D7 .. MULTIPLICATION SIGN
It should be noted that each image of this decoder needs to consume
width |times| height |times| 4
bytes of RAM, and it needs to be combined with the :ref:`overview_image_caching` feature to
ensure that the memory usage is within a reasonable range. The decoded image is
stored in RGBA pixel format.
.. _libpng_example:
Example
-------
*******
.. include:: ../../examples/libs/libpng/index.rst
.. _libpng_api:
API
---
***
:ref:`libpng`

51
docs/details/libs/lodepng.rst
View File

@@ -1,29 +1,40 @@
.. _lodepng_rst:
===============
LodePNG decoder
LodePNG Decoder
===============
Allow the use of PNG images in LVGL.
**LodePNG** is an LVGL interface to the LodePNG library --- a PNG encoder and decoder
in C and C++, without any dependencies, giving you an alternate way to use PNG images
in your LVGL UI.
Detailed introduction: https://github.com/lvandeve/lodepng
For a detailed introduction, see: https://github.com/lvandeve/lodepng .
If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_LODEPNG` LVGL will register a new
image decoder automatically so PNG files can be directly used as any
other image sources.
If enabled in ``lv_conf.h`` by setting :c:macro:`LV_USE_LODEPNG` to ``1``, LVGL will
register a new image decoder automatically so PNG files can be used directly as an
image source.
:note: a file system driver needs to be registered to open images from
files. Read more about it :ref:`overview_file_system` or just
enable one in ``lv_conf.h`` with ``LV_USE_FS_...``
.. note::
A file system driver needs to be registered to open images from files. To do so,
follow the instructions in :ref:`file_system`.
.. |times| unicode:: U+000D7 .. MULTIPLICATION SIGN
The whole PNG image is decoded, so
width |times| height |times| 4
bytes of RAM is required from the LVGL heap. The decoded image is stored in RGBA
pixel format.
Since it might take significant time to decode PNG images LVGL's
:ref:`overview_image_caching` feature can be useful.
The whole PNG image is decoded, so ``width x height x 4`` bytes free RAM space is required.
The decoded image is stored in RGBA pixel format.
As it might take significant time to decode PNG images LVGL's :ref:`overview_image_caching` feature can be useful.
Compress PNG files
------------------
Compressing PNG Files
*********************
PNG file format supports True color (24/32 bit), and 8-bit palette colors.
Usually cliparts, drawings, icons and simple graphics are stored in PNG format,
@@ -35,17 +46,23 @@ to compress images.
One option is to use a free online PNG compressor site,
for example Compress PNG: https://compresspng.com/
.. _lodepng_example:
Example
-------
*******
.. include:: ../../examples/libs/lodepng/index.rst
.. _lodepng_api:
API
---
***
:ref:`lodepng_h`
:ref:`lv_lodepng_h`

52
docs/details/libs/tjpgd.rst
View File

@@ -4,29 +4,37 @@
Tiny JPEG Decompressor (TJpgDec)
================================
Allow the use of JPEG (JPG) images in LVGL.
**Tiny JPEG Decompressor** is an LVGL interface to the TJpgDec library --- a generic
JPEG image decompressor module that highly optimized for small embedded systems. It
works with very low memory consumption, so that it can be incorporated into tiny
microcontrollers, such as AVR, 8051, PIC, Z80, Cortex-M0, etc..
For a detailed introduction, see: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__.
Detailed introduction: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__
.. _tjpgd_overview:
Overview
--------
********
Features and restrictions:
- JPEG is decoded in 8x8 tiles.
- Only baseline JPEG files are supported (no progressive JPEG support).
- Read from file and C array are implemented.
- Only the required portions of the JPEG images are decoded,
therefore they cannot be zoomed or rotated.
- JPEG is decoded in 8x8 tiles.
- Only baseline JPEG files are supported (no progressive JPEG support).
- Read from file and C array are implemented.
- Only the required portions of the JPEG images are decoded,
therefore they can't be zoomed or rotated.
.. _tjpgd_usage:
Usage
-----
*****
If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_TJPGD` LVGL will register a new
image decoder automatically so JPEG files can be used directly
as image sources.
Set :c:macro:`LV_USE_TJPGD` to ``1`` in ``lv_conf.h``. LVGL will register a new
image decoder automatically so JPEG files can be used directly as image sources.
For example:
@@ -34,31 +42,37 @@ For example:
lv_image_set_src(my_img, "S:path/to/picture.jpg");
:note: a file system driver needs to be registered to open images from
files. Read more about :ref:`overview_file_system` or just
enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` config.
.. note::
A file system driver needs to be registered to open images from files. To do so,
follow the instructions in :ref:`file_system`.
Converter
---------
*********
Converting JPEG to C array
~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------
- Use lvgl online tool https://lvgl.io/tools/imageconverter
- Color format = RAW, output format = C Array
.. _tjpgd_example:
Example
-------
*******
.. include:: ../../examples/libs/tjpgd/index.rst
.. _tjpgd_api:
API
---
***
:ref:`lv_tjpgd_h`

2
docs/details/main-components/font.rst
View File

@@ -343,7 +343,7 @@ to have a special binary format. (Not TTF or WOFF). Use
`lv_font_conv <https://github.com/lvgl/lv_font_conv/>`__ with the
``--format bin`` option to generate an LVGL compatible font file.
:note: To load a font :ref:`LVGL's filesystem <overview_file_system>`
:note: To load a font :ref:`LVGL's filesystem <file_system>`
needs to be enabled and a driver must be added.
Example

2
docs/details/main-components/image.rst
View File

@@ -47,7 +47,7 @@ registered in LVGL to make file operations. You can add an interface to
a standard file system (FAT32 on SD card) or you create your simple file
system to read data from an SPI Flash memory. In every case, a *Drive*
is just an abstraction to read and/or write data to memory. See the
:ref:`File system <overview_file_system>` section to learn more.
:ref:`File system <file_system>` section to learn more.
Images stored as files are not linked into the resulting executable, and
must be read into RAM before being drawn. As a result, they are not as

4
docs/details/other-components/file_explorer.rst
View File

@@ -37,7 +37,7 @@ non-zero value to use the "Quick-Access" panel.
.. note::
In order to use File Explorer, :ref:`overview_file_system` has to be set up and
In order to use File Explorer, :ref:`file_system` has to be set up and
know about all the drive letters you use when passing paths to File System
(described below).
@@ -47,7 +47,7 @@ Prerequisites
*************
If you haven't already done so, you will need to learn about the LVGL :ref:`File
System abstraction <overview_file_system>`, since it must be set up and be functional
System abstraction <file_system>`, since it must be set up and be functional
for File Explorer to work.

2
docs/details/widgets/image.rst
View File

@@ -48,7 +48,7 @@ To use external files, you also need to convert the image files using
the online converter tool, but select the binary output
format. You also need to use LVGL's file system module and register a
driver with some functions for basic file operations. See
:ref:`File system <overview_file_system>` to learn more. Then set the translated
:ref:`File system <file_system>` to learn more. Then set the translated
image as the image source with :cpp:expr:`lv_image_set_src(img, "S:folder1/my_img.bin")`.
You can also set a symbol as an image source similar to a :ref:`Labels <lv_label>`. In