Image Renderer

Principle

The Image Renderer is a module of the MicroUI runtime that reads and draws the images (see Image Format). It calls Abstraction Layer APIs to draw and transform the images (rotation, scaling, deformation, etc.). It also includes software algorithms to perform the rendering.

Functional Description

All MicroUI image drawings are redirected to a set of Abstraction Layer APIs. All Abstraction Layer APIs are implemented by weak functions, which call software algorithms. The BSP can override this default behavior for each Abstraction Layer API independently. Furthermore, the BSP can override an Abstraction Layer API for a specific MicroEJ format (for instance ARGB8888) and call the software algorithms for all other formats.

Destination Format

Since MicroUI 3.2, the destination buffer of the drawings can be different from the display buffer format (see MicroEJ Format: Display). This destination buffer format can be a standard format (ARGB8888, A8, etc.) or a custom format.

See Buffered Image for more information about how to create buffered images with another format than the display format and how to draw in them.

Input Formats

Standard

The Image Renderer is by default able to draw all standard formats. No extra support in the VEE Port is required to draw this kind of image.

The image drawing resembles a shape drawing. The drawing is performed by default by the Graphics Engine Software Algorithms and can be overridden to use a third-party library or a GPU.

Custom

A MicroEJ Format: Custom image can be:

• an image with a pixel buffer but whose pixel organization is not standard,
• an image with a data buffer: an image encoded with a third-party encoder (proprietary format or not),
• an image with a “command” buffer: instead of performing the drawings on pixels, the image stores the drawing actions to replay them later,
• etc.

The VEE Port must extend the Image Renderer to support the drawing of these images. This extension can consist in:

• decoding the image at runtime to draw it,
• using a compatible GPU to draw it,
• using a command interpreter to perform some shape drawings,
• etc.

To draw the custom images, the Image Renderer introduces the notion of custom image drawer. This drawer is an engine that has the responsibility to draw the image. Each custom image format (0 to 7) has its own image drawer.

Each drawing of a custom image is redirected to the associated image drawer.

Note

A custom image drawer can call the UI Shapes Drawing API to draw its elements in the destination.

The implementation is not the same between the Embedded side and the Simulation. However, the concepts are the same and are described in dedicated chapters.

MicroUI C Module

Principle

As described above, an image drawer allows drawing the images whose format is custom. The MicroUI C module is designed to manage the notion of drawers: it does not support the custom formats but allows adding some additional drawers.

This support uses several weak functions and tables to redirect the image drawings. When this support is not used (when the VEE Port does not need to support custom images), this support can be removed to reduce the footprint (by removing the indirection tables) and improve the performances (by reducing the number of runtime function calls).

Standard Formats Only (Default)

The default implementation can only draw images with a standard format. In other words, the application cannot draw a custom image. This is the most frequent use case, the only one available with MicroUI before version 3.2.

Hint

To select this implementation (to disable the custom format support), the define LLUI_IMAGE_CUSTOM_FORMATS must be unset.

The following graph illustrates the drawing of an image:

LLUI_PAINTER_IMPL_drawImage (available in MicroUI C Module)

Similar to LLUI_PAINTER_IMPL_drawLine, see MicroUI C Module.

UI_DRAWING_drawImage

// Available in MicroUI C Module
#define UI_DRAWING_DEFAULT_drawImage UI_DRAWING_drawImage

// To write in the BSP (optional)
#define UI_DRAWING_GPU_drawImage UI_DRAWING_drawImage

The function names are set thanks to some define. These name redirections are helpful when the VEE Port features more than one destination format (not the use-case here).

UI_DRAWING_GPU_drawImage (to write in the BSP)

Similar to UI_DRAWING_GPU_drawLine (see MicroUI C Module), but lets the image drawer manage the image instead of calling the software drawer directly.

// Unlike the MicroUI C Module, this function is not "weak".
DRAWING_Status UI_DRAWING_GPU_drawImage(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha) {

   DRAWING_Status status;

   if (is_gpu_compatible(xxx)) {

      // See chapter "Drawings"
      // [...]
   }
   else {
      // Let the image drawer manages the image (available in the C module)
      status = UI_IMAGE_DRAWING_draw(gc, img, regionX, regionY, width, height, x, y, alpha);
   }
   return status;
}

UI_DRAWING_DEFAULT_drawImage (available in MicroUI C Module)

// Use the preprocessor 'weak'
__weak DRAWING_Status UI_DRAWING_DEFAULT_drawImage(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha) {
#if !defined(LLUI_IMAGE_CUSTOM_FORMATS)
   return UI_DRAWING_SOFT_drawImage(gc, img, regionX, regionY, width, height, x, y, alpha);
#else
   return UI_IMAGE_DRAWING_draw(gc, img, regionX, regionY, width, height, x, y, alpha);
#endif
}

The define LLUI_IMAGE_CUSTOM_FORMATS is not set, so the implementation of the weak function only consists in calling the Graphics Engine’s software algorithm.

Custom Format Support

In addition to the standard formats, this implementation allows drawing images with a custom format. This advanced use case is available only with MicroUI 3.2 or higher.

Hint

To select this implementation, the define LLUI_IMAGE_CUSTOM_FORMATS must be set (no specific value).

The MicroUI C module uses some tables to redirect the image management to the expected extension. There is one table per Image Abstraction Layer API (draw, copy, region, rotate, scale, flip) to embed only necessary algorithms (a table and its functions are only embedded in the final binary file if and only if the MicroUI drawing method is called).

Each table contains ten elements:

static const UI_IMAGE_DRAWING_draw_t UI_IMAGE_DRAWING_draw_custom[] = {
      &UI_DRAWING_STUB_drawImage,
      &UI_DRAWING_SOFT_drawImage,
      &UI_IMAGE_DRAWING_draw_custom0,
      &UI_IMAGE_DRAWING_draw_custom1,
      &UI_IMAGE_DRAWING_draw_custom2,
      &UI_IMAGE_DRAWING_draw_custom3,
      &UI_IMAGE_DRAWING_draw_custom4,
      &UI_IMAGE_DRAWING_draw_custom5,
      &UI_IMAGE_DRAWING_draw_custom6,
      &UI_IMAGE_DRAWING_draw_custom7,
};

• UI_DRAWING_STUB_drawImage is the drawing function called when the drawing function is not implemented,
• UI_DRAWING_SOFT_drawImage is the drawing function that redirects the drawing to the Graphics Engine Software Algorithms,
• UI_IMAGE_DRAWING_draw_customX (0 to 7) are the drawing functions for each custom format.

The MicroUI C Module retrieves the table index according to the image format.

The following graph illustrates the drawing of an image:

Take the same example as the Standard Formats Only implementation (draw an image):

UI_DRAWING_DEFAULT_drawImage (available in MicroUI C Module)

// Use the preprocessor 'weak'
__weak DRAWING_Status UI_DRAWING_DEFAULT_drawImage(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha) {
#if !defined(LLUI_IMAGE_CUSTOM_FORMATS)
   return UI_DRAWING_SOFT_drawImage(gc, img, regionX, regionY, width, height, x, y, alpha);
#else
   return UI_IMAGE_DRAWING_draw(gc, img, regionX, regionY, width, height, x, y, alpha);
#endif
}

The define LLUI_IMAGE_CUSTOM_FORMATS is set so the implementation of the weak function redirects the image drawing to the image drawers manager (ui_image_drawing.h).

UI_IMAGE_DRAWING_draw (available in MicroUI C Module)

static const UI_IMAGE_DRAWING_draw_t UI_IMAGE_DRAWING_draw_custom[] = {
   &UI_DRAWING_STUB_drawImage,
   &UI_DRAWING_SOFT_drawImage,
   &UI_IMAGE_DRAWING_draw_custom0,
   &UI_IMAGE_DRAWING_draw_custom1,
   &UI_IMAGE_DRAWING_draw_custom2,
   &UI_IMAGE_DRAWING_draw_custom3,
   &UI_IMAGE_DRAWING_draw_custom4,
   &UI_IMAGE_DRAWING_draw_custom5,
   &UI_IMAGE_DRAWING_draw_custom6,
   &UI_IMAGE_DRAWING_draw_custom7,
};

DRAWING_Status UI_IMAGE_DRAWING_draw(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha){
   return (*UI_IMAGE_DRAWING_draw_custom[_get_table_index(gc, img)])(gc, img, regionX, regionY, width, height, x, y, alpha);
}

The implementation in the MicroUI C module redirects the drawing to the expected drawer. The drawer is retrieved thanks to its format (function _get_table_index()):

• the format is standard but the destination is not the display format: index 0 is returned,
• the format is standard and the destination is the display format: index 1 is returned,
• the format is custom: index 2 to 9 is returned,

UI_IMAGE_DRAWING_draw_custom0 (available in MicroUI C Module)

// Use the preprocessor 'weak'
__weak DRAWING_Status UI_IMAGE_DRAWING_draw_custom0(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha){
   return UI_DRAWING_STUB_drawImage(gc, img, regionX, regionY, width, height, x, y, alpha);
}

The default implementation of UI_IMAGE_DRAWING_draw_custom0 (same behavior for 0 to 7) consists in calling the stub implementation.

UI_DRAWING_STUB_drawImage (available in MicroUI C Module)

DRAWING_Status UI_DRAWING_STUB_drawImage(MICROUI_GraphicsContext* gc, MICROUI_Image* img, jint regionX, jint regionY, jint width, jint height, jint x, jint y, jint alpha){
  // Set the drawing log flag "not implemented"
  LLUI_DISPLAY_reportError(gc, DRAWING_LOG_NOT_IMPLEMENTED);
  return DRAWING_DONE;
}

The implementation only consists in setting the Drawing log flag DRAWING_LOG_NOT_IMPLEMENTED to notify the application that the drawing has not been performed.

Simulation

Principle

The simulation behavior is similar to the MicroUI C Module for the Embedded side.

The Front Panel defines support of the drawers based on Java service loader.

Standard Formats Only (Default Implementation)

The default implementation can draw images with a standard format.

The following graph illustrates the drawing of an image:

It is possible to override the image drawers for the standard format in the same way as the custom formats.

Custom Format Support

It is possible to draw images with a custom format by implementing the UIImageDrawing interface. This advanced use case is available only with MicroUI 3.2 or higher.

The UIImageDrawing interface contains one method for each image drawing primitive (draw, copy, region, rotate, scale, flip). Only the necessary methods can be implemented. Each non-implemented method will result in calling the stub implementation.

The method handledFormat() must be implemented and returns the managed format.

Once created, the UIImageDrawing implementation must be registered as a service.

The following graph illustrates the drawing of an image:

Let’s implement the image drawer for the CUSTOM_0 format.

public class MyCustomImageDrawer implements UIImageDrawing {

   @Override
   public MicroUIImageFormat handledFormat() {
      return MicroUIImageFormat.MICROUI_IMAGE_FORMAT_CUSTOM_0;
   }

   @Override
   public void draw(MicroUIGraphicsContext gc, MicroUIImage img, int regionX, int regionY, int width, int height,
         int x, int y, int alpha) {
      MyCustomImage customImage = (MyCustomImage) img.getImage().getRAWImage();
      customImage.drawOn(gc, regionX, regionY, width, height, x, y, alpha);
   }

}

Now, this drawer needs to be registered as a service. This can be achieved by creating a file in the resources of the Front Panel project named META-INF/services/ej.microui.display.UIImageDrawing. And its content containing the fully qualified name of the previously created image drawer.

com.mycompany.MyCustomImageDrawer

It is also possible to declare it programmatically (see where a drawer is registered in the drawing custom section):

LLUIDisplay.Instance.registerUIImageDrawer(new MyCustomImageDrawer());

Installation

The Image Renderer module is part of the MicroUI module and Display module. Install them to be able to use some images.

Use

The MicroUI image APIs are available in the class ej.microui.display.Image.