ej.microui.display

Class LLUIPainter

java.lang.Object

ej.microui.display.LLUIPainter

public class LLUIPainter
extends java.lang.Object

This class provides implementations of native methods of MicroUI library which perform some drawings.

The equivalent of embedded structures and enumerations are MicroUIImage, MicroUIGraphicsContext and MicroUIImageFormat. They are used to identify the MicroUI graphical objects: GraphicsContext, Image, image format. etc.

Implementation must use the framework object LLUIDisplay.Instance as monitor to synchronize drawings.

All native methods have a byte array as the first parameter. This identifies the destination target: the MicroUI GraphicsContext. This target is retrieved in MicroEJ application calling the method gc.getSNIContext(). The returned byte array must be mapped on a MicroUIGraphicsContext object in MicroUI native drawing method implementation (see LLUIDisplay.mapMicroUIGraphicsContext(byte[])).

For a MicroUI Image, MicroEJ application has to call image.getSNIContext() to get the image byte array. This byte array must be mapped it on a MicroUIImage object in MicroUI native drawing method implementation (see LLUIDisplay.mapMicroUIImage(byte[])).

A graphics context holds a clip and the drawer is not allowed to perform a drawing outside this clip (otherwise the behavior is unknown). Note the bottom-right coordinates might be smaller than top-left (in x and/or y) when the clip width and/or height is null. The clip may be disabled (when the current drawing fits the clip); this allows to reduce runtime. See MicroUIGraphicsContext.isClipEnabled(). Note: several clip methods are available in MicroUIGraphicsContext to check if a drawing fits the clip.

The drawing method must:

• Convert the MicroUI graphics context color calling MicroUIGraphicsContext.getRenderingColor() (in order to respect embedded display pixel representation constraints),
• Respect the graphics context clip; if not respected, the front panel behavior is unknown.

The native method implementation pattern is:

        void drawXxx(byte[] target, ...) {

                LLUIDisplay graphicsEngine = LLUIDisplay.Instance;

                // all calls to GraphicsEngine.Instance APIs must be synchronized on GraphicsEngine.Instance itself
                synchronized (graphicsEngine) {

                        // map a MicroUIGraphicsContext on given byte array which represents the destination target
                        MicroUIGraphicsContext gc = graphicsEngine.mapMicroUIGraphicsContext(target);

                        // ask to the Graphics Engine if a drawing can be performed on target
                        if (gc.requestDrawing()) {

                                // call current drawer's equivalent drawing method
                                LLUIDisplay.Instance.getUIDrawer(gc).drawXxx(gc, x, y);

                                // contrary to MicroUI native drawing methods implementation for embedded (LLUI_PAINTER_impl.h), there
                                // is no status to set in MicroUI Graphics Engine
                        }
                }
        }
 

Field Summary

Fields

Modifier and Type	Field and Description
static int	DRAWING_LOG_CLIP_MODIFIED Flag stating that the clip area of a graphics context was modified by MicroUIGraphicsContext.setClip(int, int, int, int) or MicroUIGraphicsContext.intersectClip(int, int, int, int).
static int	DRAWING_LOG_ERROR Flag stating that an error occurred during a drawing.
static int	DRAWING_LOG_FORBIDDEN Flag stating that a function was called in a context that does not allow that operation.
static int	DRAWING_LOG_LIBRARY_INCIDENT Flag describing incidents occurring in a drawing library.
static int	DRAWING_LOG_MISSING_CHARACTER Flag stating that an undefined character was drawn.
static int	DRAWING_LOG_NOT_IMPLEMENTED Flag stating that a drawing function is lacking an implementation.
static int	DRAWING_LOG_OUT_OF_MEMORY Flag stating that the system ran out of memory while attempting to perform a drawing.
static int	DRAWING_LOG_UNKNOWN_INCIDENT Flag describing incidents that do not match other values.
static int	DRAWING_SUCCESS Value used when no incident occurred.

Method Summary

Modifier and Type	Method and Description
static void	drawCircle(byte[] target, int x, int y, int diameter) MicroUI native "drawCircle".
static void	drawCircleArc(byte[] target, int x, int y, int diameter, float startAngle, float arcAngle) MicroUI native "drawCircleArc".
static void	drawEllipse(byte[] target, int x, int y, int width, int height) MicroUI native "drawEllipse".
static void	drawEllipseArc(byte[] target, int x, int y, int width, int height, float startAngle, float arcAngle) MicroUI native "drawEllipseArc".
static void	drawHorizontalLine(byte[] target, int x, int y, int width) MicroUI native "drawHorizontalLine".
static void	drawImage(byte[] target, byte[] source, int regionX, int regionY, int width, int height, int x, int y, int alpha) MicroUI native "drawImage".
static void	drawLine(byte[] target, int x1, int y1, int x2, int y2) MicroUI native "drawLine".
static void	drawRectangle(byte[] target, int x, int y, int width, int height) MicroUI native "drawRectangle".
static void	drawRenderableString(byte[] target, char[] chars, int offset, int length, byte[] fontData, int charsWidth, byte[] renderableStringSNIContext, int x, int y) Draws a renderable string.
static void	drawRoundedRectangle(byte[] target, int x, int y, int width, int height, int arcWidth, int arcHeight) MicroUI native "drawRoundedRectangle".
static void	drawString(byte[] target, char[] chars, int offset, int length, byte[] fontData, int x, int y) Draws a string.
static void	drawVerticalLine(byte[] target, int x, int y, int height) MicroUI native "drawVerticalLine".
static void	fillCircle(byte[] target, int x, int y, int diameter) MicroUI native "fillCircle".
static void	fillCircleArc(byte[] target, int x, int y, int diameter, float startAngle, float arcAngle) MicroUI native "fillCircleArc".
static void	fillEllipse(byte[] target, int x, int y, int width, int height) MicroUI native "fillEllipse".
static void	fillEllipseArc(byte[] target, int x, int y, int width, int height, float startAngle, float arcAngle) MicroUI native "fillEllipseArc".
static void	fillRectangle(byte[] target, int x, int y, int width, int height) MicroUI native "fillRectangle".
static void	fillRoundedRectangle(byte[] target, int x, int y, int width, int height, int arcWidth, int arcHeight) MicroUI native "fillRoundedRectangle".
static int	initializeRenderableStringSNIContext(char[] chars, int offset, int length, byte[] fontData, byte[] renderableStringSNIContext) Computes the rendered width of a renderable string and fills its SNI context.
static void	logDrawnRegion(MicroUIGraphicsContext gc, int x, int y, int w, int h) Logs a drawn region.
static void	logDrawnRegion(MicroUIGraphicsContext gc, Rectangle rect) Logs a drawn region.
static void	logOutOfClip(MicroUIGraphicsContext gc) Logs that a drawing is out-of-clip.
static int	stringWidth(char[] chars, int offset, int length, byte[] fontData) Computes the rendered width of a string.
static void	writePixel(byte[] target, int x, int y) MicroUI native "writePixel".

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DRAWING_SUCCESS

public static final int DRAWING_SUCCESS

Value used when no incident occurred.

See Also:

Constant Field Values

DRAWING_LOG_ERROR

public static final int DRAWING_LOG_ERROR

Flag stating that an error occurred during a drawing. This flag will cause an exception to be thrown when checking the flags in the application. No exception will be thrown if this flag is not set, although other flags will keep their state and be readable in the application. This flag is to be combined with other flags describing the error.

See Also:

Constant Field Values

DRAWING_LOG_NOT_IMPLEMENTED

public static final int DRAWING_LOG_NOT_IMPLEMENTED

Flag stating that a drawing function is lacking an implementation. This flag is typically set when the format of the graphics context is not supported by the implementation.

See Also:

Constant Field Values

DRAWING_LOG_FORBIDDEN

public static final int DRAWING_LOG_FORBIDDEN

Flag stating that a function was called in a context that does not allow that operation. This flag is typically set when a drawing function has been disabled for a specific format, like a vector drawing function called on a raster-only graphics context.

See Also:

Constant Field Values

DRAWING_LOG_OUT_OF_MEMORY

public static final int DRAWING_LOG_OUT_OF_MEMORY

Flag stating that the system ran out of memory while attempting to perform a drawing.

See Also:

Constant Field Values

DRAWING_LOG_CLIP_MODIFIED

public static final int DRAWING_LOG_CLIP_MODIFIED

Flag stating that the clip area of a graphics context was modified by MicroUIGraphicsContext.setClip(int, int, int, int) or MicroUIGraphicsContext.intersectClip(int, int, int, int). If this flag is set, the caller is responsible for saving the previous clip area and restore it afterwards. This flag merely warns the user that the clip values returned by GraphicsContext.getClipX, GraphicsContext.getClipY, GraphicsContext.getClipWidth and GraphicsContext.getClipHeight may not be identical to the clip values used in the low-level side. It is meant to be used as a debugging hint if a drawing seems incorrect.

See Also:

MicroUIGraphicsContext.setClip(int, int, int, int), MicroUIGraphicsContext.intersectClip(int, int, int, int), Constant Field Values

DRAWING_LOG_MISSING_CHARACTER

public static final int DRAWING_LOG_MISSING_CHARACTER

Flag stating that an undefined character was drawn. This happens when drawing a string that contains a character that is not included in the font used.

See Also:

Constant Field Values

DRAWING_LOG_LIBRARY_INCIDENT

public static final int DRAWING_LOG_LIBRARY_INCIDENT

Flag describing incidents occurring in a drawing library. Refer to the MicroUI implementation in the VEE port for more information about this incident.

See Also:

Constant Field Values

DRAWING_LOG_UNKNOWN_INCIDENT

public static final int DRAWING_LOG_UNKNOWN_INCIDENT

Flag describing incidents that do not match other values.

See Also:

Constant Field Values

Method Detail

writePixel

public static void writePixel(byte[] target,
                              int x,
                              int y)

MicroUI native "writePixel". Draws a pixel at given position.

See class comment to have more information about native method implementation.

Parameters:

target - drawing destination target: a byte array to map on a MicroUIGraphicsContext.

x - the pixel X coordinate.

y - the pixel Y coordinate.

drawLine

public static void drawLine(byte[] target,
                            int x1,
                            int y1,
                            int x2,
                            int y2)

MicroUI native "drawLine". Draws a line at between points x1,y1 (included) and x2,y2 (included). Note: x1 may be higher than x2 (and/or y1 may be higher than y2).

See class comment to have more information about native method implementation.

Parameters:

target - drawing destination target: a byte array to map on a MicroUIGraphicsContext.

x1 - the first pixel line X coordinate.

y1 - the first pixel line Y coordinate.

x2 - the last pixel line X coordinate.

y2 - the last pixel line Y coordinate.

drawHorizontalLine

public static void drawHorizontalLine(byte[] target,
                                      int x,
                                      int y,
                                      int width)

MicroUI native "drawHorizontalLine". Draws a horizontal line at between points x,y (included) and x+width-1,y (included).

See class comment to have more information about native method implementation.

Parameters:

target - drawing destination target: a byte array to map on a MicroUIGraphicsContext.

x - the first pixel line X coordinate.

y - the first pixel line Y coordinate.

width - the line size.

drawVerticalLine

public static void drawVerticalLine(byte[] target,
                                    int x,
                                    int y,
                                    int height)

MicroUI native "drawVerticalLine". Draws a vertical line at between points x,y (included) and x,y+height-1 (included).

See class comment to have more information about native method implementation.

Parameters:

target - drawing destination target: a byte array to map on a MicroUIGraphicsContext.

x - the first pixel line X coordinate.

y - the first pixel line Y coordinate.

height - the line size.

drawRectangle

public static void drawRectangle(byte[] target,
                                 int x,
                                 int y,
                                 int width,
                                 int height)

MicroUI native "drawRectangle". Draws a rectangle at from top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

See class comment to have more information about native method implementation.

Parameters:

target - drawing destination target: a byte array to map on a MicroUIGraphicsContext.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the rectangle width.

height - the rectangle height.

fillRectangle

public static void fillRectangle(byte[] target,
                                 int x,
                                 int y,
                                 int width,
                                 int height)

MicroUI native "fillRectangle". Fills a rectangle at from top-left point x1,y1 (included) and bottom-right point x2,y2 (included). Caller ensures that x1 <= x2 and y1 <= y2.

See class comment to have more information about native method implementation.

Parameters:

target - drawing destination target: a byte array to map on a MicroUIGraphicsContext.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the rectangle width.

height - the rectangle height.

drawRoundedRectangle

public static void drawRoundedRectangle(byte[] target,
                                        int x,
                                        int y,
                                        int width,
                                        int height,
                                        int arcWidth,
                                        int arcHeight)

MicroUI native "drawRoundedRectangle". Draws a rounded rectangle at from top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the rectangle width.

height - the rectangle height.

arcWidth - the horizontal diameter of the arc at the corners.

arcHeight - the vertical diameter of the arc at the corners.

fillRoundedRectangle

public static void fillRoundedRectangle(byte[] target,
                                        int x,
                                        int y,
                                        int width,
                                        int height,
                                        int arcWidth,
                                        int arcHeight)

MicroUI native "fillRoundedRectangle". Fills a rounded rectangle at from top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the rectangle width.

height - the rectangle height.

arcWidth - the horizontal diameter of the arc at the corners.

arcHeight - the vertical diameter of the arc at the corners.

drawCircleArc

public static void drawCircleArc(byte[] target,
                                 int x,
                                 int y,
                                 int diameter,
                                 float startAngle,
                                 float arcAngle)

MicroUI native "drawCircleArc". Draws a circular arc covering the square defined by top-left point x,y (included) and bottom-right point x+diameter-1,y+diameter-1 (included).

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the square whose origin is at (x,y) (upper-left corner) and whose dimension is given by diameter.

Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If either the given diameter is negative or zero, or if arcAngle is zero, nothing is drawn.

The angles are given relative to the square. For instance an angle of 45 degrees is always defined by the line from the center of the square to the upper right corner of the square.

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

diameter - the diameter of the arc to draw.

startAngle - the beginning angle of the arc to draw

arcAngle - the angular extent of the arc from startAngle

drawEllipseArc

public static void drawEllipseArc(byte[] target,
                                  int x,
                                  int y,
                                  int width,
                                  int height,
                                  float startAngle,
                                  float arcAngle)

MicroUI native "drawEllipseArc". Draws an elliptical arc covering the rectangle defined by top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the rectangle whose origin is at (x,y) (upper-left corner) and whose dimension is given by width and height.

Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If either the given width or height is negative or zero, or if arcAngle is zero, nothing is drawn.

The angles are given relative to the rectangle. For instance an angle of 45 degrees is always defined by the line from the center of the rectangle to the upper right corner of the rectangle. Thus for a non squared rectangle angles are skewed along either height or width.

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the rectangle width.

height - the rectangle height.

startAngle - the beginning angle of the arc to draw

arcAngle - the angular extent of the arc from startAngle

fillCircleArc

public static void fillCircleArc(byte[] target,
                                 int x,
                                 int y,
                                 int diameter,
                                 float startAngle,
                                 float arcAngle)

MicroUI native "fillCircleArc". Fills a circular arc covering the square defined by top-left point x,y (included) and bottom-right point x+diameter-1,y+diameter-1 (included). The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the square whose origin is at (x,y) (upper-left corner) and whose dimension is given by width and height. Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation. If either the given diameter is negative or zero, or if arcAngle is zero, nothing is drawn. The angles are given relative to the square. For instance an angle of 45 degrees is always defined by the line from the center of the square to the upper right corner of the square.

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

diameter - the diameter of the arc to draw.

startAngle - the beginning angle of the arc to draw

arcAngle - the angular extent of the arc from startAngle

fillEllipseArc

public static void fillEllipseArc(byte[] target,
                                  int x,
                                  int y,
                                  int width,
                                  int height,
                                  float startAngle,
                                  float arcAngle)

MicroUI native "fillEllipseArc". Fills an arc covering the rectangle defined by top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

The arc is drawn from startAngle up to arcAngle degrees. The center of the arc is defined as the center of the rectangle whose origin is at (x,y) (upper-left corner) and whose dimension is given by width and height.

Angles are interpreted such that 0 degrees is at the 3 o'clock position. A positive value indicates a counter-clockwise rotation while a negative value indicates a clockwise rotation.

If either the given width or height is negative or zero, or if arcAngle is zero, nothing is drawn.

The angles are given relative to the rectangle. For instance an angle of 45 degrees is always defined by the line from the center of the rectangle to the upper right corner of the rectangle. Thus for a non squared rectangle angles are skewed along either height or width.

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the rectangle width.

height - the rectangle height.

startAngle - the beginning angle of the arc to draw

arcAngle - the angular extent of the arc from startAngle

drawEllipse

public static void drawEllipse(byte[] target,
                               int x,
                               int y,
                               int width,
                               int height)

MicroUI native "drawEllipse". Draws an ellipse covering the rectangle defined by top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

If either the given width or height is negative or zero, nothing is drawn.

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the ellipse width.

height - the ellipse height.

fillEllipse

public static void fillEllipse(byte[] target,
                               int x,
                               int y,
                               int width,
                               int height)

MicroUI native "fillEllipse". Fills an ellipse covering the rectangle defined by top-left point x,y (included) and bottom-right point x+width-1,y+height-1 (included).

If either the given width or height is negative or zero, nothing is drawn.

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

width - the ellipse width.

height - the ellipse height.

drawCircle

public static void drawCircle(byte[] target,
                              int x,
                              int y,
                              int diameter)

MicroUI native "drawCircle". Draws a circle covering the square defined by top-left point x,y (included) and bottom-right point x+diameter-1,y+diameter-1 (included).

If the given diameter is negative or zero, nothing is drawn.

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

diameter - the circle square size.

fillCircle

public static void fillCircle(byte[] target,
                              int x,
                              int y,
                              int diameter)

MicroUI native "fillCircle". Fills a circle covering the square defined by top-left point x,y (included) and bottom-right point x+diameter-1,y+diameter-1 (included).

If the given diameter is negative or zero, nothing is drawn.

Parameters:

target - the MicroUI GraphicsContext target.

x - the top-left pixel X coordinate.

y - the top-left pixel Y coordinate.

diameter - the circle square size.

drawImage

public static void drawImage(byte[] target,
                             byte[] source,
                             int regionX,
                             int regionY,
                             int width,
                             int height,
                             int x,
                             int y,
                             int alpha)

MicroUI native "drawImage". Draws a region of an image. The region of the image to draw is given relative to the image (origin at the upper-left corner) as a rectangle.

If the specified source region exceeds the image bounds, the copied region is limited to the image boundary. If the copied region goes out of the bounds of the graphics context area, pixels out of the range will not be drawn.

A global opacity value is given. When this value is 0xff (255, opaque), that means the image is drawn on the graphics context without managing an extra opacity. Only the image transparent pixels must have been merged with destination. All image opaque pixels override destination.

When this value is a value between 0 and 0xff, that means each pixel of the image must be merged with destination in addition with the image transparent pixels. An image opaque pixel becomes transparent (its opacity is the given alpha) and the opacity of an image transparent pixel becomes (alpha * alpha(pixel)) / 255.

Parameters:

target - the MicroUI GraphicsContext target.

source - the MicroUI Image to draw.

regionX - the x coordinate of the upper-left corner of the region to copy.

regionY - the y coordinate of the upper-left corner of the region to copy.

width - the width of the region to copy.

height - the height of the region to copy.

x - the x coordinate of the top-left point in the destination.

y - the y coordinate of the top-left point in the destination.

alpha - the opacity level to apply to the region.

drawString

public static void drawString(byte[] target,
                              char[] chars,
                              int offset,
                              int length,
                              byte[] fontData,
                              int x,
                              int y)

Draws a string.

Parameters:

target - the targeted MicroUI GraphicsContext

chars - a string of characters

offset - the number of characters to skip, counting from the beginning

length - the number of characters

fontData - the MicroUI Font to use

x - the left coordinate

y - the top coordinate

stringWidth

public static int stringWidth(char[] chars,
                              int offset,
                              int length,
                              byte[] fontData)

Computes the rendered width of a string.

Parameters:

chars - a string of characters

offset - the number of characters to skip, counting from the beginning

length - the number of characters

fontData - the MicroUI Font to use

Returns:

the width in pixels

drawRenderableString

public static void drawRenderableString(byte[] target,
                                        char[] chars,
                                        int offset,
                                        int length,
                                        byte[] fontData,
                                        int charsWidth,
                                        byte[] renderableStringSNIContext,
                                        int x,
                                        int y)

Draws a renderable string.

Parameters:

target - the targeted MicroUI GraphicsContext

chars - a string of characters

offset - the number of characters to skip, counting from the beginning

length - the number of characters

fontData - the MicroUI Font to use

charsWidth - the string width

renderableStringSNIContext - the renderable string

x - the left coordinate

y - the top coordinate

initializeRenderableStringSNIContext

public static int initializeRenderableStringSNIContext(char[] chars,
                                                       int offset,
                                                       int length,
                                                       byte[] fontData,
                                                       byte[] renderableStringSNIContext)

Computes the rendered width of a renderable string and fills its SNI context.

Parameters:

chars - a string of characters

offset - the number of characters to skip, counting from the beginning

length - the number of characters

fontData - the MicroUI Font to use

renderableStringSNIContext - the renderable string

Returns:

the width in pixels

logDrawnRegion

public static void logDrawnRegion(MicroUIGraphicsContext gc,
                                  Rectangle rect)

Logs a drawn region. This region may be bigger than the graphics context's clip.

Parameters:

gc - the destination of the drawn region

rect - the drawn region size

logDrawnRegion

public static void logDrawnRegion(MicroUIGraphicsContext gc,
                                  int x,
                                  int y,
                                  int w,
                                  int h)

Logs a drawn region. This region may be higher than the graphics context's clip.

Parameters:

gc - the destination of the drawn region

x - the drawn region X-coordinate

y - the drawn region Y-coordinate

w - the drawn region width

h - the drawn region height

logOutOfClip

public static void logOutOfClip(MicroUIGraphicsContext gc)

Logs that a drawing is out-of-clip.

Parameters:

gc - the destination of the drawn region