ej.microui.display

Interface LLUIDisplayImpl

public interface LLUIDisplayImpl

This interface holds all methods required by MicroUI implementation to be compatible with the MicroUI Graphics Engine.

An implementation of this interface is required to run a MicroUI application which uses the class MicroUI Display; otherwise some errors will be thrown at runtime and the application will not able to run correctly. This implementation should be a widget which allows to draw in an Image. This image is used as "back buffer" (see isDoubleBuffered()). At the end of MicroEJ application drawings (via MicroUI painter classes), a call to flush() is performed to render the image on the visible part of front panel.

The display size may be different than the widget size. This allows to show on computer a bigger or smaller display in pixels than the embedded display. The display size is the size given to the MicroEJ application. To retrieve the display size, the methods Image.getWidth() and Image.getHeight() (on the image returned by initialize()) are called (instead of Widget.getWidth() and Widget.getHeight() which return the widget size). The both values can be automatically set by the front panel parser if the display widget (implementation of this interface) declares the following Widget.WidgetAttribute:

 @WidgetAttribute(name = "displayWidth", isOptional = true)
 @WidgetAttribute(name = "displayHeight", isOptional = true)
 

This size may be optional, in this case the display size is equal to the widget size. This size (if applicable the widget size) must be used to create the Image returned by initialize().

This interface stubs a lot of methods. Only initialize() and flush() are mandatory. All others methods are optional and perform same defaut behavior like embedded side.

Field Summary

Fields

Modifier and Type	Field and Description
static int	BACKLIGHT_MAX Maximal value of backlight according MicroUI specification.
static int	BACKLIGHT_MIN Minimal value of backlight according MicroUI specification.
static int	CONTRAST_MAX Maximal value of contrast according MicroUI specification.
static int	CONTRAST_MIN Minimal value of contrast according MicroUI specification.

Method Summary

Modifier and Type	Method and Description
default int	convertARGBColorToDisplayColor(int argbColor) Converts the 32-bit ARGB color format (A-R-G-B) into the display color format.
default int	convertDisplayColorToARGBColor(int displayColor) Converts the display color format into a 32-bit ARGB color format (A-R-G-B).
default ej.fp.Image	decode(byte[] data) Decodes the image defined by the data array.
void	flush() Flushes a part of the display limited by the specified bounds when the display is double buffered.
default int	getBacklight() Returns the backlight of the display.
default int	getContrast() Returns the contrast of the display.
default ej.fp.Image	getCurrentBackBuffer() Gets the current back buffer (the buffer when the Graphics Engine has to draw).
default ej.fp.Image	getCurrentDrawingBuffer() Deprecated. Implements getCurrentBackBuffer() instead.
ej.fp.Image	getDisplayedImage() Gets the image currently displayed (with or without debug tools, backlight, contrast, etc.).
default int	getNumberOfColors() Gets the number of colors that can be represented on the device.
default boolean	hasBacklight() Returns true if the display holds a backlight.
ej.fp.Image	initialize() Initializes the display widget to be compatible with MicroUI Graphics Engine.
default boolean	isColor() Asks if the display is a colored display or not.
default boolean	isDoubleBuffered() Returns if the display uses an underlying double buffer.
void	newDrawingRegion(int x1, int y1, int x2, int y2, boolean drawingNow) Notifies that a region will be modified by the application in the display back buffer.
default boolean	prepareBlendingOfIndexedColors(java.util.concurrent.atomic.AtomicInteger foreground, java.util.concurrent.atomic.AtomicInteger background) Prepares the blending of two ARGB colors.
default void	setBacklight(int backlight) Sets the backlight of the display.
default void	setContrast(int contrast) Sets the contrast of the display.
default void	waitFlush() Simulates the waiting of end of an asynchronous flush when the display is double buffered.

Field Detail

BACKLIGHT_MIN

static final int BACKLIGHT_MIN

Minimal value of backlight according MicroUI specification.

See Also:

Constant Field Values

BACKLIGHT_MAX

static final int BACKLIGHT_MAX

Maximal value of backlight according MicroUI specification.

See Also:

Constant Field Values

CONTRAST_MIN

static final int CONTRAST_MIN

Minimal value of contrast according MicroUI specification.

See Also:

Constant Field Values

CONTRAST_MAX

static final int CONTRAST_MAX

Maximal value of contrast according MicroUI specification.

See Also:

Constant Field Values

Method Detail

initialize

ej.fp.Image initialize()

Initializes the display widget to be compatible with MicroUI Graphics Engine. Called by framework when MicroEJ application is calling MicroUI.start().

This method has to return an image where MicroUI will performing its drawings. As mentioned in class comment, the widget size can be higher or smaller than the simulated display (embedded display). The returned buffer must have the embedded display size (and not the widget size).

This buffer is given as parameter in flush() method.

Returns:

the buffer where performing the MicroUI drawing.

flush

void flush()

Flushes a part of the display limited by the specified bounds when the display is double buffered. This display's flush may be synchronous (the implementation updates the front buffer immediately) or asynchronous (the implementation uses a thread to simulate the embedded side). In second case, the call to waitFlush() must synchronize the Graphics Engine with the widget display. If the display does not have a backBuffer (not double buffered), nothing has to be done.

newDrawingRegion

void newDrawingRegion(int x1,
                      int y1,
                      int x2,
                      int y2,
                      boolean drawingNow)

Notifies that a region will be modified by the application in the display back buffer.

This function is called by the Graphics Engine:

• For each call to MicroUIGraphicsContext.requestDrawing() (in the display back buffer) if the drawing region set by the application is different than the previous drawing region. In this case, the drawingNow parameter is set to true.
• For each call to GraphicsContext.notifyDirtyRegion(). In this case, the drawingNow parameter is set to false.

Parameters:

x1 - the left x coordinate of the drawing region.

y1 - the top y coordinate of the drawing region.

x2 - the right x coordinate of the drawing region.

y2 - the bottom y coordinate of the drawing region.

drawingNow - true if a drawing is following this call, false otherwise.

waitFlush

default void waitFlush()

Simulates the waiting of end of an asynchronous flush when the display is double buffered. When the call to flush() performs a synchronous flush, this method should stay empty because there is nothing to wait (default implementation). When the call to flush() performs an asynchronous flush (to simulate the same behavior than embedded side): this method is useful to wait the end of this asynchronous flush. If the display does not have a backBuffer (not double buffered), nothing is done. This method should stay empty.

Parameters:

gc - the flushed graphics context.

getCurrentBackBuffer

default ej.fp.Image getCurrentBackBuffer()

Gets the current back buffer (the buffer when the Graphics Engine has to draw).

Returns:

the current back buffer.

getCurrentDrawingBuffer

@Deprecated
default ej.fp.Image getCurrentDrawingBuffer()

Deprecated. Implements getCurrentBackBuffer() instead.

Returns:

the current back buffer.

getDisplayedImage

ej.fp.Image getDisplayedImage()

Gets the image currently displayed (with or without debug tools, backlight, contrast, etc.).

Returns:

an image that represents the content of the display currently visible

setContrast

default void setContrast(int contrast)

Sets the contrast of the display. By default this method does nothing (feature not supported).

Parameters:

contrast - the new value of the contrast (range CONTRAST_MIN-CONTRAST_MAX).

getContrast

default int getContrast()

Returns the contrast of the display. By default this method returns CONTRAST_MIN.

Returns:

the current contrast of the display (range CONTRAST_MIN-CONTRAST_MAX).

hasBacklight

default boolean hasBacklight()

Returns true if the display holds a backlight. By default this method returns false (feature not supported).

Returns:

true when widget manages display backlight.

setBacklight

default void setBacklight(int backlight)

Sets the backlight of the display. By default this method does nothing (feature not supported).

Parameters:

backlight - the new value of the backlight (range BACKLIGHT_MIN-BACKLIGHT_MAX).

getBacklight

default int getBacklight()

Returns the backlight of the display. By default this method returns BACKLIGHT_MIN.

Returns:

the backlight of the display (range BACKLIGHT_MIN-BACKLIGHT_MAX).

isColor

default boolean isColor()

Asks if the display is a colored display or not.

By default this method returns false when the display pixel depth is lower than or equals to 4 and true otherwise.

Returns:

true when the display is not a grayscale display, false otherwise.

getNumberOfColors

default int getNumberOfColors()

Gets the number of colors that can be represented on the device.

Note that the number of colors for a black and white display is 2. Usually the number of colors is 1 << BPP (BPP without transparency bits).

By default this method returns a value which follows this default rule.

Returns:

the number of colors of the display.

isDoubleBuffered

default boolean isDoubleBuffered()

Returns if the display uses an underlying double buffer.

By default this method returns true and considers the interface implementation returns a "back" buffer in initialize(). This buffer is used to render the MicroUI drawings in background. When MicroUI Display.flush() method is called, a call to flush() is performed. The implementation has to copy the image content to another image (visible on front panel).

Implementation can override this method to return false. In this case the image returned by initialize() is used as rendering buffer for MicroUI drawings and as visible buffer on front panel at same time.

Returns:

true if the display is double buffered, else otherwise.

convertARGBColorToDisplayColor

default int convertARGBColorToDisplayColor(int argbColor)

Converts the 32-bit ARGB color format (A-R-G-B) into the display color format.

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB8888 , MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB888, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB565, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB1555, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB4444, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C4, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C2 or MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C1.

In case of this function is not implemented whereas it is required, the result of pixel drawing is unknown.

Note: the opacity level (alpha) may be ignored if the display pixel representation does not hold the opacity level information.

The implementation should not directly call this function when performing a drawing. It must call LLUIDisplay.convertARGBColorToColorToDraw(int) instead in case of this conversion is Graphics Engine built-in (standard display).

Parameters:

argbColor - the color to convert.

Returns:

the display color equivalent to microUIColor.

convertDisplayColorToARGBColor

default int convertDisplayColorToARGBColor(int displayColor)

Converts the display color format into a 32-bit ARGB color format (A-R-G-B).

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB8888 , MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB888, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB565, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB1555, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB4444, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C4, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C2 or MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C1.

In case of this function is not implemented whereas it is required, the result of pixel drawing is unknown.

Note: the opacity level (alpha) may be ignored if the display pixel representation does not hold the opacity level information. In this case, the returned alpha level is 0xff (full opaque).

Parameters:

displayColor - the color to convert.

Returns:

the MicroUI color equivalent to displayColor.

prepareBlendingOfIndexedColors

default boolean prepareBlendingOfIndexedColors(java.util.concurrent.atomic.AtomicInteger foreground,
                                               java.util.concurrent.atomic.AtomicInteger background)

Prepares the blending of two ARGB colors.

This function is called only when the display is not a standard display: when the pixel data does not match with one of these formats: MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB8888 , MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB888, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_RGB565, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB1555, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_ARGB4444, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C4, MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C2 or MicroUIImageFormat.MICROUI_IMAGE_FORMAT_C1.

This is useful only when the LCD is a palletized LCD. This method is called by framework when the MicroEJ application draws something which requires a blending between the current foreground color and a specific background color (draw a string, draw an anti-aliased line etc.).

The implementation has to replace the ARGB colors by the indexes of these colors in the LCD CLUT. The framework will use the intermediate values between these two indexes instead of blending in software the ARGB colors. No post conversion will be performed later.

When the ARGB colors are not available in the CLUT or when the range specified by the two ARGB colors is not expected by the CLUT, the implementation should return false (feature not supported). In this way the blending will be done in software and the result color will be converted later thanks a call to convertARGBColorToDisplayColor(int).

By default the method returns false (feature not supported / useless).

Parameters:

foreground - the foreground ARGB color to convert.

background - the background ARGB color to convert.

Returns:

true when the indexes have been found, false otherwise.

decode

default ej.fp.Image decode(byte[] data)
                    throws java.io.IOException

Decodes the image defined by the data array.

The default implementation tries to decode the image by using the platform-specific loader.

Parameters:

data - the data of the image to decode.

Returns:

the device-specific Image created.

Throws:

java.io.IOException - if an error occur during the decoding of the image.