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¶
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 tovg_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.
Configuration¶
This C module uses a configuration file. This file (a header file with some C defines) enables (or disables) and configures some options:
VG_FEATURE_PATH
: set this define to embed the full implementation ofPath
feature. Otherwise, a stub implementation is used, and allPath
drawings are dropped.VG_FEATURE_GRADIENT
: configure this define to embed the full implementation ofLinearGradient
or a stub implementation that only manages one color (linear gradient’s first color). The respective options areVG_FEATURE_GRADIENT_FULL
andVG_FEATURE_GRADIENT_FIRST_COLOR
.VG_FEATURE_FONT
: configure this define to specify the Font Engine and the Font Engine’s backend. Two options are currently available: the FreeType engine with a vectorial backend and the FreeType engine with a bitmap backend. The respective options areVG_FEATURE_FONT_FREETYPE_VECTOR
andVG_FEATURE_FONT_FREETYPE_BITMAP
.VG_FEATURE_FREETYPE_TTF
: set this define to enable the support of TTF font files in FreeType.VG_FEATURE_FREETYPE_OTF
: set this define to enable the support of OTF font files in FreeType.VG_FEATURE_FREETYPE_COLORED_EMOJI
: set this define to enable the support of colored emoji in FreeType.VG_FEATURE_FONT_COMPLEX_LAYOUT
: set this define to enable the support of complex layout. This option is managed by the C moduleHarfbuzz
(see upper).VG_FEATURE_FONT_EXTERNAL
: set this define to allow loading of external font files (outside the application classpath). See External Fonts.VG_FEATURE_FREETYPE_HEAP_SIZE
: specify the FreeType engine’s heap size.VG_FEATURE_FONT_COMPLEX_LAYOUT_HEAP_SIZE
: specify the Harfbuzz engine’s heap size.
Note
This options list is not exhaustive. Please consult the C module’s readme file for more information.
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 inmicrovg_helper.h
MEJ_LOG_MICROVG
andMEJ_LOG_INFO_LEVEL
defined inmej_log.h
Principle¶
- 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.
- 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).
- 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.
- For every character to draw:
- 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¶
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
invg_drawing_vglite.c
andLLVG_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.
Compatibility¶
The compatibility between the components (Packs, C modules, and Libraries) is described in the Release Notes.