ej.microui.display

Interface LLUIDisplay

public interface LLUIDisplay

This interface represents the MicroUI Graphics Engine (MicroUI framework). It provides some methods to map MicroUI byte arrays in MicroUI Graphics Context objects, to manipulate MicroUI colors etc.

An instance of this framework is available via the Instance field. To use the framework methods, caller must synchronize its calls on this Instance field.

Field Summary

Fields

Modifier and Type	Field and Description
static LLUIDisplay	Instance Unique instance of MicroUI Graphics Engine.

Method Summary

Modifier and Type	Method and Description
int	blend(int foreground, int background, int alpha) Blends two colors applying a global alpha factor.
int	convertARGBColorToColorToDraw(int color) Converts the given MicroUI color (format 0xAARRGGBB) in a truncated color (same format: 0xAARRGGBB).
void	convertRegion(MicroUIImage image, int x, int y, int width, int height) Converts the colors of the pixels in the given image's region.
BufferedImageProvider	getBufferedImageProvider(MicroUIImageFormat format) Gets the buffered image provider used to create images with the given format.
MicroUIImageFormat	getDisplayFormat() Gets the display format.
int	getDisplayPixelDepth() Gets the number of bits (opacity included) to represent a pixel on the hardware device.
java.nio.ByteOrder	getEndianness() Gets the endianness of the architecture.
MicroUIImage	getSource(MicroUIImage image) Returns an image that targets the front buffer (display buffer) instead of the back buffer.
UIDrawing	getUIDrawer(MicroUIGraphicsContext gc) Gets the drawer used to draw on the given graphics context.
UIDrawing	getUIDrawer(MicroUIImageFormat format) Gets the drawer used to draw with the given format.
UIDrawing	getUIDrawerSoftware() Unique instance of MicroUI Graphics Engine's internal software drawer.
UIFontDrawing	getUIFontDrawer(MicroUIFont font) Gets the font drawer used to draw the given font.
UIFontDrawing	getUIFontDrawer(MicroUIFontFormat format) Gets the font drawer used to draw the fonts with the given format.
UIImageDrawing	getUIImageDrawer(MicroUIImage image) Gets the image drawer used to draw the given image.
UIImageDrawing	getUIImageDrawer(MicroUIImageFormat format) Gets the image drawer used to draw the images with the given format.
boolean	isCustomFormat(MicroUIFontFormat format) Tells if format is a custom format or not.
boolean	isCustomFormat(MicroUIImageFormat format) Tells if format is a custom format or not.
boolean	isDisplayFormat(MicroUIImageFormat format) Tells if format is the display format or not.
MicroUIFont	mapMicroUIFont(byte[] font) Maps a MicroUI Font byte array (retrieved by MicroEJ application calling font.getSNIContext()) on a MicroUIFont.
MicroUIGraphicsContext	mapMicroUIGraphicsContext(byte[] gc) Maps a MicroUI GraphicsContext byte array (retrieved by MicroEJ application calling gc.getSNIContext()) on a MicroUIGraphicsContext.
MicroUIImage	mapMicroUIImage(byte[] image) Maps a MicroUI Image byte array (retrieved by MicroEJ application calling image.getSNIContext()) on a MicroUIImage.
MicroUIRenderableString	mapMicroUIRenderableString(byte[] renderableString) Maps a MicroUI RenderableString byte array (retrieved by MicroEJ application calling renderableString.getSNIContext()) on a MicroUIRenderableString.
char[]	mapString(char[] chars, int offset, int length) Maps a char array subset on a string.
MicroUIGraphicsContext	newMicroUIGraphicsContext(byte[] gc) Creates a new MicroUIGraphicsContext for the given MicroUI GraphicsContext byte array.
MicroUIImage	newMicroUIImage(byte[] image) Creates a new MicroUIImage for the given MicroUI Image byte array.
void	registerBufferedImageProvider(BufferedImageProvider provider) Registers a buffered image provider.
void	registerUIDrawer(UIDrawing drawer) Registers a drawer that supports a specific format.
void	registerUIFontDrawer(UIFontDrawing drawer) Registers a drawer that supports a specific format.
void	registerUIImageDrawer(UIImageDrawing drawer) Registers a drawer that supports a specific format.
void	requestFlush() Requests a call to LLUIDisplayImpl.flush() if something has been drawn in the back buffer (application dirty region is not null).
void	requestRender() Requests a call to Displayable.render() (current displayable on display).
void	unregisterBufferedImageProvider(MicroUIImageFormat format) Unregisters the buffered image provider registered for a specific format.
void	unregisterUIDrawer(MicroUIImageFormat format) Unregisters the drawer registered for the given format.
void	unregisterUIFontDrawer(MicroUIFontFormat format) Unregisters the drawer registered for the given format.
void	unregisterUIImageDrawer(MicroUIImageFormat format) Unregisters the drawer registered for the given format.

Field Detail

Instance

static final LLUIDisplay Instance

Unique instance of MicroUI Graphics Engine. It provides some methods to synchronize drawings between them, to map MicroUI byte arrays in graphical objects, to manipulate MicroUI colors etc.

To use the framework methods, caller must synchronize its calls on this Instance field.

Method Detail

getUIDrawerSoftware

UIDrawing getUIDrawerSoftware()

Unique instance of MicroUI Graphics Engine's internal software drawer. It is an instance of UIDrawing and it implements all drawings in software. The rendering is exactly the same than the embedded algorithms listed in ui_drawing_soft.h.

This drawer converts the MicroUI graphics context color, respects the clip and updates the new Display.flush() region (dirty region) as mentioned in LLUIPainter class comment.

Returns:

an implementation of UIDrawing in software.

mapMicroUIGraphicsContext

MicroUIGraphicsContext mapMicroUIGraphicsContext(byte[] gc)

Maps a MicroUI GraphicsContext byte array (retrieved by MicroEJ application calling gc.getSNIContext()) on a MicroUIGraphicsContext.

Implementation notes:

• Same object is always returned, only internal MicroUIGraphicsContext fields are updated. By consequence this method can only be called once during a MicroUI native call. See newMicroUIGraphicsContext(byte[]) to force to create a new MicroUIGraphicsContext instead.
• The implementation assumes given byte array has been retrieved by MicroEJ application calling gc.getSNIContext(). If given byte array does not respect this rule, the behavior is unknown.

Parameters:

gc - the MicroUI GraphicsContext representation.

Returns:

the unique MicroUIGraphicsContext object updated with the given MicroUI GraphicsContext characteristics.

newMicroUIGraphicsContext

MicroUIGraphicsContext newMicroUIGraphicsContext(byte[] gc)

Creates a new MicroUIGraphicsContext for the given MicroUI GraphicsContext byte array. This allows to manipulate several destination targets in same native call. However it takes more time to create a new instance at each native call than mapping the unique instance.

The implementation assumes given byte array has been retrieved by MicroEJ application calling gc.getSNIContext(). If given byte array does not respect this rule, the behavior is unknown.

Parameters:

gc - the MicroUI GraphicsContext representation.

Returns:

a new MicroUIGraphicsContext object updated with the given MicroUI GraphicsContext characteristics.

See Also:

mapMicroUIGraphicsContext(byte[])

mapMicroUIImage

MicroUIImage mapMicroUIImage(byte[] image)

Maps a MicroUI Image byte array (retrieved by MicroEJ application calling image.getSNIContext()) on a MicroUIImage. This image can be used as source (copy image in a graphics context) or as target (copy image in another image).

Implementation notes:

• Same object is always returned, only internal MicroUIImage fields are updated. By consequence this method can only be called once during a MicroUI native call. See newMicroUIImage(byte[]) to force to create a new MicroUIImage instead.
• The implementation assumes given byte array has been retrieved by MicroEJ application calling image.getSNIContext(). If given byte array does not respect this rule, the behavior is unknown.

Parameters:

image - the MicroUI Image representation.

Returns:

the unique MicroUIImage object updated with the given MicroUI Image characteristics.

newMicroUIImage

MicroUIImage newMicroUIImage(byte[] image)

Creates a new MicroUIImage for the given MicroUI Image byte array. This allows to manipulate several sources and targets in same native call. However it takes more time to create a new instance at each native call than mapping the unique instance.

The implementation assumes given byte array has been retrieved by MicroEJ application calling image.getSNIContext(). If given byte array does not respect this rule, the behavior is unknown.

Parameters:

image - the MicroUI Image representation.

Returns:

a new MicroUIImage object updated with the given MicroUI Image characteristics.

See Also:

mapMicroUIImage(byte[])

mapMicroUIFont

MicroUIFont mapMicroUIFont(byte[] font)

Maps a MicroUI Font byte array (retrieved by MicroEJ application calling font.getSNIContext()) on a MicroUIFont.

Implementation notes:

• Same object is always returned, only internal MicroUIFont fields are updated. By consequence this method can only be called once during a MicroUI native call.
• The implementation assumes given byte array has been retrieved by MicroEJ application calling font.getSNIContext(). If given byte array does not respect this rule, the behavior is unknown.

Parameters:

font - the MicroUI Font representation.

Returns:

the unique MicroUIFont object updated with the given MicroUI Font characteristics.

mapMicroUIRenderableString

MicroUIRenderableString mapMicroUIRenderableString(byte[] renderableString)

Maps a MicroUI RenderableString byte array (retrieved by MicroEJ application calling renderableString.getSNIContext()) on a MicroUIRenderableString.

Implementation notes:

• Same object is always returned, only internal MicroUIRenderableString fields are updated. By consequence this method can only be called once during a MicroUI native call.
• The implementation assumes given byte array has been retrieved by MicroEJ application calling renderableString.getSNIContext(). If given byte array does not respect this rule, the behavior is unknown.

Parameters:

renderableString - the MicroUI RenderableString representation

Returns:

the unique MicroUIRenderableString object updated with the given MicroUI RenderableString characteristics

mapString

char[] mapString(char[] chars,
                 int offset,
                 int length)

Maps a char array subset on a string.

Parameters:

chars - the char array

offset - the offset in the char array

length - the length

Returns:

a char array representing the string

getDisplayPixelDepth

int getDisplayPixelDepth()

Gets the number of bits (opacity included) to represent a pixel on the hardware device. For instance a RGB565 display returns 16.

Returns:

the hardware device pixel depth.

requestFlush

void requestFlush()

Requests a call to LLUIDisplayImpl.flush() if something has been drawn in the back buffer (application dirty region is not null). The call of LLUIDisplayImpl.flush() is synchronized with the MicroEJ application drawing (see MicroUI event pump).

requestRender

void requestRender()

Requests a call to Displayable.render() (current displayable on display). The call of Displayable.render() is synchronized with the MicroEJ application drawing (see MicroUI event pump).

convertARGBColorToColorToDraw

int convertARGBColorToColorToDraw(int color)

Converts the given MicroUI color (format 0xAARRGGBB) in a truncated color (same format: 0xAARRGGBB).

This color takes in consideration the hardware display pixel representation constraints. For instance, for a display with the pixel format RGB565, the truncated color of green color (0xff00ff00) is 0xff00fc00 (because RGB565 format keeps only 6 first bits for green component).

This truncated color must be used to convert the MicroUI GraphicsContext current color in order to respect the hardware display pixel representation constraints.

Parameters:

color - the MicroUI color in format 0xAARRGGBB.

Returns:

the truncated color in format 0xAARRGGBB.

convertRegion

void convertRegion(MicroUIImage image,
                   int x,
                   int y,
                   int width,
                   int height)

Converts the colors of the pixels in the given image's region. This is useful when the given region has been drawn by a third-party algorithm that doesn't respect the image format restrictions. For instance an anti-aliased drawing can draw a pixel with the color 0xfff3f3f3. On a RGB565 image, this color must be converted in 0xfff0f0f0. The implementation consists to call convertARGBColorToColorToDraw(int) for each region's pixel.

Parameters:

image - the image to update.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the region width.

height - the region height.

blend

int blend(int foreground,
          int background,
          int alpha)

Blends two colors applying a global alpha factor.

Parameters:

foreground - the ARGB8888 foreground color.

background - the ARGB8888 background color.

alpha - the global alpha factor.

Returns:

an ARGB8888 color.

getDisplayFormat

MicroUIImageFormat getDisplayFormat()

Gets the display format.

Returns:

the display format.

See Also:

MicroUIImageFormat

isDisplayFormat

boolean isDisplayFormat(MicroUIImageFormat format)

Tells if format is the display format or not.

Parameters:

format - the format to check.

Returns:

true if format refers to the display format, false otherwise

See Also:

MicroUIImageFormat

isCustomFormat

boolean isCustomFormat(MicroUIImageFormat format)

Tells if format is a custom format or not.

Parameters:

format - the format to check.

Returns:

true if format refers to a custom format, false otherwise

See Also:

MicroUIImageFormat

registerUIDrawer

void registerUIDrawer(UIDrawing drawer)

Registers a drawer that supports a specific format.

Parameters:

drawer - the drawer

See Also:

UIDrawing.handledFormat()

unregisterUIDrawer

void unregisterUIDrawer(MicroUIImageFormat format)

Unregisters the drawer registered for the given format.

Parameters:

format - the now unsupported format

See Also:

UIDrawing.handledFormat()

getUIDrawer

UIDrawing getUIDrawer(MicroUIGraphicsContext gc)

Gets the drawer used to draw on the given graphics context.

Parameters:

gc - the graphics context to draw on

Returns:

the drawer registered for the format of the graphics context or a stub if none

getUIDrawer

UIDrawing getUIDrawer(MicroUIImageFormat format)

Gets the drawer used to draw with the given format.

Parameters:

format - the format

Returns:

the drawer registered for the format or a stub if none

registerUIImageDrawer

void registerUIImageDrawer(UIImageDrawing drawer)

Registers a drawer that supports a specific format.

Parameters:

drawer - the drawer

See Also:

UIImageDrawing.handledFormat()

unregisterUIImageDrawer

void unregisterUIImageDrawer(MicroUIImageFormat format)

Unregisters the drawer registered for the given format.

Parameters:

format - the now unsupported format

See Also:

UIImageDrawing.handledFormat()

getUIImageDrawer

UIImageDrawing getUIImageDrawer(MicroUIImage image)

Gets the image drawer used to draw the given image.

Parameters:

image - the image to draw

Returns:

the current image drawer (the default drawer if no other drawer has been set)

getUIImageDrawer

UIImageDrawing getUIImageDrawer(MicroUIImageFormat format)

Gets the image drawer used to draw the images with the given format.

Parameters:

format - the format of the image to draw

Returns:

the current image drawer (the default drawer if no other drawer has been set)

registerBufferedImageProvider

void registerBufferedImageProvider(BufferedImageProvider provider)

Registers a buffered image provider.

It will be used to create buffered image for the format it handles (BufferedImageProvider.newBufferedImage(int, int)).

It will also be registered as is also registered as drawer registerUIDrawer(UIDrawing) and custom image drawer registerUIImageDrawer(UIImageDrawing).

Parameters:

provider - the buffered image provider

unregisterBufferedImageProvider

void unregisterBufferedImageProvider(MicroUIImageFormat format)

Unregisters the buffered image provider registered for a specific format.

Parameters:

format - the format

getBufferedImageProvider

BufferedImageProvider getBufferedImageProvider(MicroUIImageFormat format)

Gets the buffered image provider used to create images with the given format.

Parameters:

format - the format of the created images

Returns:

the current buffered image provider (or null if none)

isCustomFormat

boolean isCustomFormat(MicroUIFontFormat format)

Tells if format is a custom format or not.

Parameters:

format - the format to check.

Returns:

true if format refers to a custom format, false otherwise

See Also:

MicroUIFontFormat

getUIFontDrawer

UIFontDrawing getUIFontDrawer(MicroUIFont font)

Gets the font drawer used to draw the given font.

Parameters:

font - the font to draw

Returns:

the current font drawer (the default drawer if no other drawer has been set)

getUIFontDrawer

UIFontDrawing getUIFontDrawer(MicroUIFontFormat format)

Gets the font drawer used to draw the fonts with the given format.

Parameters:

format - the format of the font to draw

Returns:

the current font drawer (the default drawer if no other drawer has been set)

registerUIFontDrawer

void registerUIFontDrawer(UIFontDrawing drawer)

Registers a drawer that supports a specific format.

Parameters:

drawer - the drawer

See Also:

UIFontDrawing.handledFormat()

unregisterUIFontDrawer

void unregisterUIFontDrawer(MicroUIFontFormat format)

Unregisters the drawer registered for the given format.

Parameters:

format - the now unsupported format

See Also:

UIFontDrawing.handledFormat()

getSource

MicroUIImage getSource(MicroUIImage image)

Returns an image that targets the front buffer (display buffer) instead of the back buffer.

This behavior only concerns the following use case:

• the image targets the display (not an image),
• the display buffer refresh strategy (BRS) has not restored yet the content of the old back buffer to the current back buffer.

In that case, the read actions (GraphicsContext.readPixel(), Painter.drawDisplayRegion(), etc.) cannot use the back buffer as source buffer. The algorithm has to call this method to retrieve the front buffer.

For all other use cases, the returned image is the given parameter.

Parameters:

image - the Java image.

Returns:

the result image.

getEndianness

java.nio.ByteOrder getEndianness()

Gets the endianness of the architecture.

Returns:

the endianness