From 377cc5aa801dcb4ca757611238651cd8deed3b96 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Wed, 19 Feb 2025 06:39:03 -0700 Subject: [PATCH] docs(libs): proofread docs batch18 (#7688) Co-authored-by: Gabor Kiss-Vamosi Co-authored-by: Liam Howatt <30486941+liamHowatt@users.noreply.github.com> --- docs/details/libs/ffmpeg.rst | 69 ++++++++++++++----- docs/details/libs/freetype.rst | 41 ++++++----- docs/details/libs/gif.rst | 45 ++++++------ docs/details/libs/lfs.rst | 26 ++++--- docs/details/libs/libjpeg_turbo.rst | 52 ++++++++++---- docs/details/libs/libpng.rst | 47 +++++++++---- docs/details/libs/lodepng.rst | 51 +++++++++----- docs/details/libs/tjpgd.rst | 52 +++++++++----- docs/details/main-components/font.rst | 2 +- docs/details/main-components/image.rst | 2 +- .../other-components/file_explorer.rst | 4 +- docs/details/widgets/image.rst | 2 +- 12 files changed, 261 insertions(+), 132 deletions(-) diff --git a/docs/details/libs/ffmpeg.rst b/docs/details/libs/ffmpeg.rst index 97ee1eb1f..08d4ef080 100644 --- a/docs/details/libs/ffmpeg.rst +++ b/docs/details/libs/ffmpeg.rst @@ -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 `__, then install it: +For a detailed introduction, see: https://www.ffmpeg.org + + + +Installing FFmpeg +***************** + +Download the FFmpeg library from `its official download page +`__, then install it: .. code-block:: shell @@ -19,39 +28,65 @@ Download first FFmpeg from `here `__, 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 ---- +*** diff --git a/docs/details/libs/freetype.rst b/docs/details/libs/freetype.rst index ac7896778..8dc142a53 100644 --- a/docs/details/libs/freetype.rst +++ b/docs/details/libs/freetype.rst @@ -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 `__. +First, Download FreeType from the ``freetype2`` folder (and optionally ``freetype-docs`` +and ``freetype-demos``) from its `official repository +`__. (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 `__ + - LVGL's :ref:`add_font` @@ -122,14 +135,6 @@ Examples -Learn More -********** - -- FreeType`tutorial `__ -- LVGL's :ref:`add_font` - - - .. _freetype_api: API diff --git a/docs/details/libs/gif.rst b/docs/details/libs/gif.rst index 087dd8b7a..3b86b531a 100644 --- a/docs/details/libs/gif.rst +++ b/docs/details/libs/gif.rst @@ -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 `__. 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: diff --git a/docs/details/libs/lfs.rst b/docs/details/libs/lfs.rst index 7ebb314a5..92ca80312 100644 --- a/docs/details/libs/lfs.rst +++ b/docs/details/libs/lfs.rst @@ -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 `__ diff --git a/docs/details/libs/libjpeg_turbo.rst b/docs/details/libs/libjpeg_turbo.rst index d074df584..153bc2f72 100644 --- a/docs/details/libs/libjpeg_turbo.rst +++ b/docs/details/libs/libjpeg_turbo.rst @@ -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` diff --git a/docs/details/libs/libpng.rst b/docs/details/libs/libpng.rst index 4784fb318..bf44605f6 100644 --- a/docs/details/libs/libpng.rst +++ b/docs/details/libs/libpng.rst @@ -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` diff --git a/docs/details/libs/lodepng.rst b/docs/details/libs/lodepng.rst index 1a704de88..77e778482 100644 --- a/docs/details/libs/lodepng.rst +++ b/docs/details/libs/lodepng.rst @@ -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` + diff --git a/docs/details/libs/tjpgd.rst b/docs/details/libs/tjpgd.rst index e8f3e7bc2..e80a8e22d 100644 --- a/docs/details/libs/tjpgd.rst +++ b/docs/details/libs/tjpgd.rst @@ -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 `__. + -Detailed introduction: `TJpgDec `__ .. _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` diff --git a/docs/details/main-components/font.rst b/docs/details/main-components/font.rst index a0a31ee1e..17758d520 100644 --- a/docs/details/main-components/font.rst +++ b/docs/details/main-components/font.rst @@ -343,7 +343,7 @@ to have a special binary format. (Not TTF or WOFF). Use `lv_font_conv `__ with the ``--format bin`` option to generate an LVGL compatible font file. -:note: To load a font :ref:`LVGL's filesystem ` +:note: To load a font :ref:`LVGL's filesystem ` needs to be enabled and a driver must be added. Example diff --git a/docs/details/main-components/image.rst b/docs/details/main-components/image.rst index a89edf520..ccf0bb157 100644 --- a/docs/details/main-components/image.rst +++ b/docs/details/main-components/image.rst @@ -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 ` section to learn more. +:ref:`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 diff --git a/docs/details/other-components/file_explorer.rst b/docs/details/other-components/file_explorer.rst index fb58985fb..f410e315b 100644 --- a/docs/details/other-components/file_explorer.rst +++ b/docs/details/other-components/file_explorer.rst @@ -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 `, since it must be set up and be functional +System abstraction `, since it must be set up and be functional for File Explorer to work. diff --git a/docs/details/widgets/image.rst b/docs/details/widgets/image.rst index 9ede4c37b..08092f00c 100644 --- a/docs/details/widgets/image.rst +++ b/docs/details/widgets/image.rst @@ -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 ` to learn more. Then set the translated +:ref:`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 `. In