Feature/UI pack 14.5

VEEPortingGuide/uiChangeLog.rst

@@ -6,6 +6,71 @@
 Changelog
 =========
 
+.. _section_ui_changelog_14_5_0:
+
+[14.5.0] - 2025-10-07
+=====================
+
+MicroUI
+"""""""
+
+**Fixed**
+
+- Fix ``Image.get()`` and ``Image.canGet()`` of external RAW images: the images must respect the memory constraints (byte addressable, alignment).
+- Fix the loading of external RAW images that does not respect the GPU memory constraints.
+- Fix the reading in the back buffer: it could read in the wrong buffer after a fast GPU draw after a flush.
+
+LLAPIs
+""""""
+
+**Added**
+
+- Add the API ``LLUI_DISPLAY_IMPL_[un]lockJob()`` to enable the use of re-entrant functions in a task other than the MicroJvm virtual machine task.
+- Add the API ``LLUI_DISPLAY_decodeImage()`` to decode an image from the native world.
+- Add the API ``LLUI_DISPLAY_isMutable()`` that tells if an image is mutable or not.
+- Add the API ``LLUI_DISPLAY_getAddress()`` that gives the absolute address of an image.
+- Add the API ``LLUI_DISPLAY_getSize()`` that gives the image size in bytes.
+
+C Module MicroUI
+""""""""""""""""
+
+**Changed**
+
+- Use the include directive ``#include "veeport_configuration.h"`` to configure the UI configuration (``ui_configuration.h``).
+
+**Fixed**
+
+- Fix the log identifiers of the library Drawing.
+
+C Module DMA2D
+""""""""""""""
+
+**Changed**
+
+- Use the include directive ``#include "veeport_configuration.h"`` to configure the DMA2D configuration (``ui_dma2d_configuration.h``).
+
+C Module VGLite
+""""""""""""""""
+
+**Changed**
+
+- Use the include directive ``#include "veeport_configuration.h"`` to configure the VGLite configuration (``ui_vglite_configuration.h``).
+
+**Fixed**
+
+- Fix the use of the VGLite option ``VG_BLIT_WORKAROUND``: it must be ``0`` or undefined to avoid UI testsuite issues.
+
+C Module NemaGFX
+""""""""""""""""
+
+**Changed**
+
+- Use the include directive ``#include "veeport_configuration.h"`` to configure the NemaGFX configuration (``ui_nema_configuration.h``)..
+
+**Fixed**
+
+- Fix the useless include directive.
+
 .. _section_ui_changelog_14_4_2:
 
 [14.4.2] - 2025-05-20

VEEPortingGuide/uiDisplay.rst

@@ -619,11 +619,23 @@ and blue[5]):
 
 1. Configure the VEE Port:
 
-   * Create or open the VEE Port configuration project file ``display/display.properties``: 
+   .. tabs::
 
-   .. code-block:: java 
+      .. tab:: SDK 6
 
-      bpp=16
+         In SDK 6, the configuration is done in the properties file ``configuration.properties`` of the VEE Port project:
+
+         .. code-block:: java 
+
+            com.microej.pack.display.bpp=16
+
+      .. tab:: SDK 5
+
+         In SDK 5, the configuration is done in the properties file ``display/display.properties``:
+
+         .. code-block:: java 
+
+            bpp=16
 
 2. Image Generator:
 
@@ -1052,6 +1064,8 @@ The Abstraction Layer distinguishes between the display *virtual* size and the d
 
 .. note:: The *physical* size may not be configured; in that case, the Graphics Engine considers the *virtual* size os *physical* size.
 
+.. _section_display_llapi_semaphore:
+
 Semaphores
 ----------
 
@@ -1095,14 +1109,26 @@ The principle of implementing a MicroUI drawing function is described in the cha
 
 .. _Painter: https://repository.microej.com/javadoc/microej_5.x/apis/ej/microui/display/Painter.html
 
+.. _section_display_llapi_graphics_engine:
+
 Graphics Engine API
---------------------
+-------------------
 
 The Graphics Engine provides a set of functions to interact with the C archive.
 The functions allow the retrieval of some drawing characteristics, the synchronization of drawings between them, the notification of the end of flush and drawings, etc.
 
 The functions are available in ``LLUI_DISPLAY.h``.
 
+Most APIs are thread-safe, meaning that any C task can call the Graphics Engine APIs at any time.
+However, certain functions need to be synchronized with MicroUI (and the Core Engine task), including ``allocateImageBuffer()``, ``freeImageBuffer()``, and ``decodeImage()``.
+
+.. note:: This list is not exhaustive; please refer to the C documentation for ``LLUI_DISPLAY_IMPL_lockJob()`` for the complete list.
+
+To facilitate this synchronization, the Graphics Engine provides optional supplementary Abstract Layer API: ``LLUI_DISPLAY_IMPL_lockJob()`` and ``LLUI_DISPLAY_IMPL_unlockJob()``.
+The implementation of these APIs simply involves using a binary semaphore.
+
+.. important::  This binary semaphore must not be shared with the :ref:`binary semaphores<section_display_llapi_semaphore>` given to the Graphics Engine during its initialization.
+
 Typical Implementations
 =======================
 
@@ -1709,8 +1735,8 @@ This configuration step is used to choose the kind of implementation (see :ref:`
    .. tab:: SDK 6
 
      In SDK 6, the configuration is done in the properties file ``configuration.properties`` of the VEE Port project.
-	  All the properties names listed below must be prefixed by ``com.microej.runtime.display.``.
-	  For example the ``bpp`` properties is defined by the ``com.microej.runtime.display.bpp`` property.
+	  All the properties names listed below must be prefixed by ``com.microej.pack.display.``.
+	  For example the ``bpp`` properties is defined by the ``com.microej.pack.display.bpp`` property.
 
    .. tab:: SDK 5
 

VEEPortingGuide/uiImageCore.rst

@@ -796,7 +796,7 @@ How to get the file:
 #. Perform some changes into the copied file (see after).
 #. Rebuild the VEE Port: the file in the `dropins` folder is copied in the VEE Port instead of the original one.
 
-.. warning:: When the display format in ``[VEE Port configuration project]/display/display.properties`` changes, the linker file suffix changes too. Perform again all the operations in the new file with the new suffix.
+.. warning:: When the display format changes (see :ref:`section_display_installation`), the linker file suffix changes too. Perform again all the operations in the new file with the new suffix.
 
 The linker file holds five tables, one for each use case, respectively ``IMAGE_UTILS_TABLE_COPY``, ``IMAGE_UTILS_TABLE_COPY_WITH_ALPHA``, ``IMAGE_UTILS_TABLE_DRAW``, ``IMAGE_UTILS_TABLE_SET`` and ``IMAGE_UTILS_TABLE_READ``.
 For each table, a comment describes how to remove an option (when possible) or how to replace an option by a generic function (if available).

VEEPortingGuide/uiImageGenerator.rst

@@ -196,9 +196,15 @@ Additionally, the file becomes compatible with the VEE Port constraints.
 
 If the only constraint is the pixels array alignment, the Image Generator extension is not useful:
 
-1. Open VEE Port configuration file ``display/display.properties``.
-2. Add the property ``imageBuffer.memoryAlignment``.
-3. Build again the VEE Port.
+.. tabs::
+
+   .. tab:: SDK 6
+
+      Add the property ``com.microej.pack.imageBuffer.memoryAlignment`` in the properties file ``configuration.properties`` of the VEE Port project.
+
+   .. tab:: SDK 5
+
+      Add the property ``imageBuffer.memoryAlignment`` in the properties file ``display/display.properties`` of the VEE Port project.
 
 This alignment will be used by the Image Generator and also by the Image Loader.
 

VEEPortingGuide/uiImageLoader.rst

@@ -115,6 +115,9 @@ An image may be pre-processed (:ref:`section_image_generator`) and so already in
 Encoded Image
 =============
 
+Internal Decoders
+-----------------
+
 An image can be encoded (PNG, JPEG, etc.).
 In this case Image Loader asks to its Image Decoders module if a decoder is able to decode the image.
 The source image is not copied in RAM (expect for images stored as :ref:`section_image_external_memory`).
@@ -129,6 +132,9 @@ The UI extension provides two internal Image Decoders modules:
 * PNG Decoder: a full PNG decoder that implements the PNG format (``https://www.w3.org/Graphics/PNG`` ). Regular, interlaced, indexed (palette) compressions are handled.
 * BMP Monochrome Decoder: .bmp format files that embed only 1 bit per pixel can be decoded by this decoder.
 
+Additional Decoders
+-------------------
+
 .. _image_external_decoder:
 
 Some additional decoders can be added.
@@ -155,6 +161,88 @@ The implementation must respect the following rules:
 
 -  Waiting the end of decoding step before returning.
 
+Abstraction Layer API
+---------------------
+
+The internal and external decoders are called by the Graphics Engine when the application invokes the MicroUI API `ej.microui.display.ResourceImage.loadImage()`_.
+They can also be explicitly called by any C task via the supplementary API ``LLUI_DISPLAY_decodeImage()``.
+
+.. important:: If the Abstraction Layer API ``LLUI_DISPLAY_decodeImage()`` is called outside of the Core Engine task (i.e., outside of a native Java context), synchronization functions with the Graphics Engine must be implemented (see :ref:`section_display_llapi_graphics_engine`).
+
+Like MicroUI, this API provides an instruction on the output format (see :ref:`section_image_raw`).
+This instruction may not be followed by the decoder, depending on the encoding capabilities of the decoder and the Graphics Engine.
+The default format of the decoder is then selected instead (depends on the decoder itself).
+
+.. note:: The caller can verify the RAW encoding by checking the ``format`` field of the ``MICROUI_Image``.
+
+Unlike the MicroUI API, which is limited to six output formats, the abstraction layer API allows for additional or compatible formats.
+Some formats may not be available at runtime (it is recommended to use the :ref:`section_image_generator` instead).
+The table below indicates whether the format instruction is adhered to, replaced by a compatible format, or replaced by the default format of the decoder.
+
++-----------------------------------+-----------------------------------+
+| Instruction                       | Output Format                     |
++===================================+===================================+
+| MICROUI_IMAGE_FORMAT_DISPLAY      | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_ARGB8888     | MICROUI_IMAGE_FORMAT_ARGB8888     |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_ARGB1555     | MICROUI_IMAGE_FORMAT_ARGB1555     |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_ARGB4444     | MICROUI_IMAGE_FORMAT_ARGB4444     |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_ARGB8888_PRE | MICROUI_IMAGE_FORMAT_ARGB8888_PRE |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_ARGB1555_PRE | MICROUI_IMAGE_FORMAT_ARGB1555_PRE |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_ARGB4444_PRE | MICROUI_IMAGE_FORMAT_ARGB4444_PRE |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_RGB888       | MICROUI_IMAGE_FORMAT_RGB888       |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_RGB565       | MICROUI_IMAGE_FORMAT_RGB565       |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_A1           | MICROUI_IMAGE_FORMAT_A8           |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_A2           | MICROUI_IMAGE_FORMAT_A8           |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_A4           | MICROUI_IMAGE_FORMAT_A8           |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_A8           | MICROUI_IMAGE_FORMAT_A8           |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_C1           | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_C2           | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_C4           | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_AC11         | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_AC22         | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_AC44         | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_LARGB8888    | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_UNDEFINED    | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_CUSTOM_7     | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_CUSTOM_6     | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_CUSTOM_5     | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_CUSTOM_4     | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_CUSTOM_3     | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_CUSTOM_2     | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_CUSTOM_1     | *default format*                  |
++-----------------------------------+-----------------------------------+
+| MICROUI_IMAGE_FORMAT_CUSTOM_0     | *default format*                  |
++-----------------------------------+-----------------------------------+
+
+.. _ej.microui.display.ResourceImage.loadImage(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/microui/display/ResourceImage.html#loadImage-java.lang.String-
+
 .. _section_decoder_installation:
 
 Installation

VEEPortingGuide/uiMigrationGuide.rst

@@ -6,6 +6,79 @@
 Migration Guide
 ===============
 
+.. _section_ui_migrationguide_pack_14.5.0:
+
+From 14.4.2 to 14.5.0
+=====================
+
+.. _section_ui_migrationguide_pack_14.5.0_bsp:
+
+BSP
+"""
+
+The C Module's options configuration file ``ui_configuration.h`` must not be modified anymore.
+Before installing the new C Module: 
+
+* Create (if not already exists) the global `VEE Port configuration file`_.
+* Move your own configuration from ``ui_configuration.h`` to ``veeport_configuration.h``.
+* Install the `C Module MicroUI 14.5.0`_.
+
+The following options (see ``ui_configuration.h``) have now a value (not just commented/uncommented); check (and adjust) whether they are used outside the UI C Modules:
+
+* ``UI_FEATURE_ALLOCATOR``
+* ``UI_FEATURE_EVENT_DECODER``
+* ``UI_FEATURE_IMAGE_CUSTOM_FORMATS``
+* ``UI_FEATURE_FONT_CUSTOM_FORMATS``
+* ``UI_FEATURE_BRS_FLUSH_SINGLE_RECTANGLE``
+
+.. _VEE Port configuration file: https://github.com/MicroEJ/Tool-Project-Template-VEEPort/tree/master/bsp/vee/port/config
+
+BSP with DMA2D
+""""""""""""""
+
+* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.5.0_bsp`.
+
+The C Module's options configuration file ``ui_dma2d_configuration.h`` must not be modified anymore.
+Before installing the new C Module: 
+
+* Move your own configuration from ``ui_dma2d_configuration.h`` to ``veeport_configuration.h``.
+* Install the `C Module MicroUI over DMA2D to version 8.0.0`_.
+
+BSP with VGLite
+"""""""""""""""
+
+* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.5.0_bsp`.
+
+The C Module's options configuration file ``ui_vglite_configuration.h`` must not be modified anymore.
+Before installing the new C Module: 
+
+* Move your own configuration from ``ui_vglite_configuration.h`` to ``veeport_configuration.h``.
+* Install the `C Module MicroUI over VGLite to version 11.0.0`_.
+
+The following options (see ``ui_vglite_configuration.h``) have now a value (not just commented/uncommented); check (and adjust) whether they are used outside the UI C Modules:
+
+* ``VGLITE_USE_GPU_FOR_SIMPLE_DRAWINGS``
+* ``VGLITE_USE_GPU_FOR_RGB565_IMAGES``
+* ``VGLITE_USE_GPU_FOR_TRANSPARENT_IMAGES``
+* ``VGLITE_OPTION_TOGGLE_GPU``
+
+BSP with NemaGFX
+""""""""""""""""
+
+* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.5.0_bsp`.
+
+The C Module's options configuration file ``ui_nema_configuration.h`` must not be modified anymore.
+Before installing the new C Module: 
+
+* Move your own configuration from ``ui_nema_configuration.h`` to ``veeport_configuration.h``.
+* Install the `C Module MicroUI over NemaGFX to version 5.0.0`_.
+
+The following options (see ``ui_nema_configuration.h``) have now a value (not just commented/uncommented); check (and adjust) whether they are used outside the UI C Modules:
+
+* ``ENABLE_SIMPLE_LINES``
+* ``ENABLE_FADED_LINES``
+* ``ENABLE_IMAGE_ROTATION``
+
 .. _section_ui_migrationguide_pack_14.4.2:
 
 From 14.3.3 to 14.4.2
@@ -19,19 +92,30 @@ Front Panel
 
 .. _Front Panel Widgets 5.3.1: https://forge.microej.com/ui/repos/tree/General/microej-developer-repository-release/ej/tool/frontpanel/widget/5.3.1/
 
+
+.. _section_ui_migrationguide_pack_14.4.2_bsp:
+
+BSP
+"""
+
+* Install the `C Module MicroUI 14.4.2`_.
+
 BSP with DMA2D
 """"""""""""""
 
+* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.4.2_bsp`.
 * Install the `C Module MicroUI over DMA2D to version 7.0.1`_.
 
 BSP with VGLite
 """""""""""""""
 
+* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.4.2_bsp`.
 * Install the `C Module MicroUI over VGLite to version 10.0.1`_.
 
 BSP with NemaGFX
 """"""""""""""""
 
+* **Prerequisite:** follow the migration steps of :ref:`section_ui_migrationguide_pack_14.4.2_bsp`.
 * Install the `C Module MicroUI over NemaGFX to version 4.0.1`_.
 
 Application