C Modules

Principle

Several C modules implement the VG Pack’s Abstraction Layer APIs. Some are generic, and some are VEE Port dependent (more precisely: GPU dependent). The generic modules provide header files to be extended by the specific modules. The generic C modules are available on the Central Repository and the specific C modules on the Developer Repository.

The following picture illustrates the available C modules and their relations for an implementation that uses:

  • FreeType library for the font renderer and the font layouter in simple layout mode.
  • Harfbuzz library for the font layouter in complex layout mode.
  • Vivante VGLite library for the drawing of vector paths

The following chapters explain the aim and relations of each C module.

Note

It is a simplified view: all sources and headers files of each C module are not visible.

MicroVG C Modules

MicroVG C Modules

UI Pack & MicroUI C Modules

The UI Pack provides a header file to implement the MicroUI drawings: LLUI_PAINTER_impl.h. See C Modules chapter to have more information.

Library: Vivante VGLite

This library is the official Vivante VGLite library. The C modules use its header files to target the GPU.

Note

The library must be patched to be compatible with the C module “MicroUI over VGLite”. Consult the C module’s ReadMe file for more information.

VG Pack

The VG Pack provides a set of header files to implement the MicroVG concepts. The header files are described in the dedicated chapters: Matrix module, Path module, Gradient module, Image module and Font module.

The VG Pack is an extension of the UI Pack. The VG Pack’s header files require the UI Pack’s header files to manipulate the MicroUI concepts. Consequently, the VG Pack must be installed on a VEE Port that fetches a UI Pack.

The VG Pack and its header files are available on the Central Repository: com.microej.pack.vg#vg-pack.

C Module: MicroVG

Description

This generic C module provides an implementation of MicroVG concepts: matrix, path, linear gradient and font; respectively LLVG_MATRIX_impl.c, LLVG_PATH_impl.c, LLVG_GRADIENT_impl.c and LLVG_FONT_freetype.c.

  • Matrix (see Matrix module’s Abstraction Layer API): a basic software implementation.
  • Path (see Path module’s Abstraction Layer API): a generic implementation that manages the command buffer’s life cycle and dispatches the command encoding to a 3rd-party header file microvg_path.h.
  • Gradient (see Gradient module’s Abstraction Layer API): a generic implementation that manages the gradient buffer’s life cycle and dispatches the gradient encoding to a 3rd-party header file microvg_gradient.h.
  • Font (see Font module’s Abstraction Layer API): an implementation of vector font over FreeType: open font file and retrieve font’s characteristics.
  • The MicroVG painter native functions are implemented in LLVG_PAINTER_impl.c and the drawings are redirected to vg_drawing.h.
  • Image management is too specific to the GPU and is not implemented in this C module.

This C module is available on the Central Repository: com.microej.clibrary.llimpl#microvg.

Dependencies

This generic C module requires some specific modules:

  • Path and Gradient require a C module specific to a VEE Port (to a GPU format).
  • Font requires the FreeType library and optionally the Harfbuzz library to manage the complex layout.

Usage

  1. This C module transitively fetches the C Module for MicroUI, follow its implementation rules.
  2. Add all C files in the BSP project.
  3. Configure the option in the header file microvg_configuration.h.

Library: FreeType

Description

The FreeType library compatible with MicroEJ is packaged in a C module on the Developer Repository: com.microej.clibrary.thirdparty#freetype.

This C module provides a fork of FreeType 2.11.0.

Memory Heap Configuration

The FreeType library requires a memory Heap for FreeType internal objects allocated when a font file is loaded (see https://freetype.org/freetype2/docs/design/design-4.html). The size of this heap depends on the number of fonts loaded in parallel and on the fonts themselves. This size is defined by VG_FEATURE_FREETYPE_HEAP_SIZE in microvg_configuration.h.

All fonts do not require the same heap size. FreeType heap usage can be monitored using the following configurations:

  • MICROVG_MONITOR_HEAP defined in microvg_helper.h
  • MEJ_LOG_MICROVG and MEJ_LOG_INFO_LEVEL defined in mej_log.h

Principle

  1. The Application loads a font with ej.microvg.VectorFont.loadFont().
    • If the resource is internal or external from byte-addressable memory, the FreeType library is configured to read directly from that resource memory section.
    • Else, if the resource is external from non-byte-addressable memory, the FreeType library is configured to use the external loader to read from that memory.
    • At this point, the font resources are allocated and the font generic data (including baseline & height metrics) is loaded on the FreeType dedicated heap.
  2. The Application requests metrics.
    • For generic metrics, already loaded data is directly used (and scaled to the font size used).
    • For text-dependent metrics: computed by loading metrics of every glyph required by the input string (the glyphs bitmaps are not actually rendered here).
  3. The Application requests drawings.
    • For every character to draw:
      • the associated glyph is loaded,
      • the bitmap is rendered for the given font size and
      • the character is drawn in the given graphic context.
  4. The Application unloads the font with ej.microvg.VectorFont.close().
    • Any resource associated with the font is released.
    • At this point, any attempt to use the font will result in an exception.

Library: Harfbuzz

The library Harfbuzz compatible with MicroEJ is packaged in a C module on the Developer Repository: com.microej.clibrary.thirdparty#harfbuzz.

This C module provides a fork of Harfbuzz 4.2.1.

The Harfbuzz library requires a memory Heap for Harfbuzz internal objects allocated when a font file is loaded. The size of this heap depends on the number of fonts loaded in parallel and on the fonts themselves. This size is defined by VG_FEATURE_HARFBUZZ_HEAP_SIZE_HEAP in microvg_configuration.h.

All fonts do not require the same heap size. The MICROVG_MONITOR_HEAP define in microvg_helper.h and MEJ_LOG_MICROVG and MEJ_LOG_INFO_LEVEL defines in mej_log.h can be used to monitor the Harfbuzz heap evolution.

FreeType and Harfbuzz libraries are not sharing the same heap, but this could easilly be done by updating ft_system.c and hb-alloc.c files.

C Module: MicroVG Over VGLite

Overview

This C module is a specific implementation of the VG Pack drawings over the official Vivante VGLite library (that targets some GPU with vector graphics acceleration):

  • It implements the MicroVG API vg_drawing.h in vg_drawing_vglite.c and LLVG_PAINTER_FONT_freetype_vglite.c.
  • It implements the MicroVG Image management (draw a compile-time image, create a BufferedVectorImage, etc.): LLVG_RAW_impl.c.
  • It provides an implementation of MicroVG drawings to the MicroVG BufferedVectorImage: vg_drawing_bvi.c.
  • It also implements MicroUI drawings to the MicroVG BufferedVectorImage: ui_drawing_bvi.c.

The implementation requires:

  • the concepts of the C module MicroVG,
  • the concepts of the C module MicroUI over VGLite,
  • the FreeType library,
  • the Vivante VGLite library.

This C module is available on the Developer Repository: com.microej.clibrary.llimpl#microvg-vglite.

Usage

  1. This C module transitively fetches the C Module for MicroUI for VGLite, follow its implementation rules.
  2. Add all C files in the BSP project.

Compatibility

The compatibility between the components (Packs, C modules, and Libraries) is described in the Release Notes.