The Image module contains the part of the MicroVG implementation which manages vectorial images. This module is composed of several elements:
The Image module implements the MicroVG VectorImage framework. It provides an offline tool that consists in opening and decoding an image file and some Abstraction Layer APIs that manipulate the image at runtime.
A compile-time image file:
- is either an AVD (Android Vector Drawable) or a Scalable Vector Graphics (SVG),
- is identified by the resource name,
- is encoded in a binary format compatible with the image renderer,
- can be stored as an internal resource or an external one (see External Memory),
- is an immutable image: the application cannot draw into it.
The offline tool is an extension of the MicroUI Image Generator. This tool is automatically installed during the VEE Port build.
The tool converts :
- The Android Vector Drawable (AVD): this kind of image can hold linear gradients, animations on colors, opacity, path transformations, etc.
- The Scalable Vector Graphics (SVG): this kind of image is partially supported: linear gradients but no animations. It is advised to convert the SVG files into AVD files before using the Image Converter tool.
The tool generates a binary (RAW) file compatible with the Rendering Engine. The RAW file consists in a series of vector paths and animations.
To list the images to convert, the tool uses the application list files whose extension is
The generator provides an option to encode the path data (the path’s points): it can be stored on signed 8, 16, 32-bit words or in
Respectively, the options are
This is an example of a
# Convert an AVD in float format /avd_image_1.xml:VGF # Convert an AVD in signed 16-bit format /path/to/avd_image_2.xml:VG16 # Convert an SVG in signed 8-bit format /svg_image.svg:VG8
To load this kind of image, the application has to call VectorImage.getImage().
This API takes the image relative path:
The implementation uses the Abstraction Layer API to retrieve the image. No data is stored in the Java heap (except the VectorImage object’s instance).
Resource Vector Image¶
The Image module implements the MicroVG ResourceVectorImage framework.
MicroVG VectorImage.filterImage() API allows to transform an image using a 4x5 color matrix. The result of the image transformation is stored in the MicroUI Images Heap. MicroVG ports for dedicated GPU (Low Level implementation) are responsible of the deallocation of this generated image. An implementation is available for MicroVG Over VGLite.
MicroVG provides the API ResourceVectorImage.loadImage(). This is an extension of the compile-time images (the concepts are exactly the same), but it allows a load of a RAW image stored in an external memory that is not byte-addressable.
An external image loaded from byte-addressable memory is processed the same way than any compile-time image. For an image loaded from an external memory which is not byte-addressable, its data must be copied into byte-addressable memory before the image can be used for drawings. By default (see C Modules), the image data is copied into MicroUI Images Heap. The implementation is responsible for the image’s lifecycle: allocation and release (already implemented in the C Modules).
Like compile-time images, the Image Generator uses a list file whose extension is
The rules are exactly the sames than the compile-time images.
The process to open a Vector Image from an external memory is exactly the same than the loading of an external MicroUI Image .
The following steps describe how to setup the loading of an external resource from the application:
- Add the image to the application project resources (typically in the source folder
src/main/resourcesand in the package
- Create / open the configuration file (e.g.
- Add the relative path of the image and its output format (e.g.
/images/myImage.avd:VGFsee Image Generator).
- Build the application: the Image Generator converts the image in RAW format in the external resources folder (
- Deploy the external resources to the external memory (SDCard, flash, etc.) of the device.
- (optional) Configure the External Resources Loader to load from this source.
- Build the application and run it on the device.
- The application loads the external resource using ResourceVectorImage.loadImage().
- The image loader looks for the image and copies it in the images heap (no copy if the external memory is byte-addressable).
- The external resource is immediately closed: the image’s bytes have been copied in the images heap, or the image’s bytes are always available (byte-addressable memory).
- The application can use the image.
- The application closes the image: the image is removed from the image heap.
The Simulator automatically manages the external resources like internal resources.
All images listed in
*.externvectorimages.list files are copied in the external resources folder, and this folder is added to the Simulator’s classpath.
Buffered Vector Image¶
This image is a ResourceVectorImage that the application can draw into. More specifically, the drawings are not performed but stored.
The concept consists in storing the compatible MicroUI drawings  and all MicroVG drawings into a command list. The application can then play this list of commands applying (or not) a global transformation.
The implementation uses the concept of MicroUI custom format (the custom
The way to register the drawing commands is strongly linked to the targeted GPU:
- The paths and gradients are stored to be used directly by the GPU to render the image (prevent runtime modifications before the image rendering).
- Depending on the GPU capabilities (a GPU may be able to draw a MicroUI anti-aliased line but not an aliased line), some MicroUI drawing API may be implemented (see Buffered Image).
As a consequence, the implementation is dedicated to the GPU. The C Modules provide some implementations, and the Front Panel (for the Simulation) features the same limitations as the embedded side (it is not possible to store a MicroUI drawing in the simulator if the embedded side is not able to perform it).
|||The compatible MicroUI drawings depend on the GPU Port; see:ref:section_vg_cco.|
This library uses a simple XML parser (for performance and footprint convenience) that limits compatibility with the AVD specification. For instance, this loader does not manage the animations.
The Vector Image Generator can generate a compatible AVD file in the
AVD as output format.
# Convert an AVD into a compatible AVD format /avd_image.xml:AVD # Convert an SVG into a compatible AVD format /svg_image.svg:AVD
The Vector Image Rendering Engine has the responsibility of drawing the vector images. The destination is the display buffer, a MicroUI BufferedImage or a MicroVG BufferedVectorImage.
Three transformations can be applied when drawing a vector image:
- a global path transformation (3x3 matrix)
- a color transformation (4x5 color matrix)
- an opacity (value between 0 and 255)
The C Modules and the Front Panel already implement this engine.
Abstraction Layer API¶
There are two separate Abstraction Layer API header files:
LLVG_BVI_impl.hspecifies the Abstraction Layer APIs used to open and manage the BufferedVectorImage cycle-life.
LLVG_PAINTER_impl.hlists the Abstraction Layer APIs called by VectorGraphicsPainter to draw an image (compile-time, runtime, or buffered vector image).
- MicroVG library calls the BSP functions through the header files
- A C module dedicated to a GPU provides an implementation of
LLVG_PATH_PAINTER_impl.h: the implementation is specific to the target (the GPU): the format of the RAW paths, gradients, and animations are GPU compliant.
- These files are automatically copied in the BSP project when fetching the C modules during the VEE Port build.
The implementation of the MicroVG library is included in the VG Pack. No specific support is required to retrieve and use the images.