ej.microui.display

Class GraphicsContext

java.lang.Object

ej.microui.display.GraphicsContext

public class GraphicsContext
extends Object

A GraphicsContext provides access to a modifiable pixel buffer.

For example, a graphics context can be used to read or write the pixels of the Display or of a BufferedImage.

Painting classes such as Painter provide utility methods to draw specific shapes and objects using a graphics context.

Colors are interpreted as 24-bit RGB colors. If the display or image associated with the graphics context does not support such color depth, its implementation is in charge of mapping the desired colors to the most appropriate supported colors.

A graphics context defines a translation vector in order to change the position of subsequent drawings.

It also defines a clipping rectangle which restricts the pixels that will be modified by subsequent drawings. Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed. The position of this clipping area is relative to the origin of this graphics context, regardless of the value of the translation vector.

A graphics context uses the following coordinate system:

• its origin is the top-left corner of the top-left pixel of the destination.
• its x axis is positive towards the right.
• its y axis is positive towards the bottom.

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 the low-level side.
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.
static int	OPAQUE Maximum opacity.
static int	TRANSPARENT Minimum opacity.

Method Summary

Modifier and Type	Method and Description
int	checkDrawingLogFlags() Throws an exception if the error flag is currently set.
void	disableEllipsis() Disables ellipsis.
void	enableEllipsis(int width) Enables ellipsis when drawing characters.
static int	getAlpha(int opacityPercent) Returns the alpha level for the given opacity percentage.
int	getAndClearDrawingLogFlags() Gets and clears the drawing log flags from a graphics context.
int	getBackgroundColor() Returns the background color of this graphics context.
int	getClipHeight() Returns the height of the clipping area of this graphics context.
int	getClipWidth() Returns the width of the clipping area of this graphics context.
int	getClipX() Returns the x coordinate of the clipping area of this graphics context.
int	getClipY() Returns the y coordinate of the clipping area of this graphics context.
int	getColor() Returns the color of this graphics context.
int	getEllipsisWidth() Returns the width limit before applying the ellipsis.
int	getHeight() Returns the height of this graphics context.
byte[]	getSNIContext() Returns the SNI context data of this graphics context.
int	getTranslationX() Returns the x coordinate of the translation vector of this graphics context.
int	getTranslationY() Returns the y coordinate of the translation vector of this graphics context.
int	getWidth() Returns the width of this graphics context.
boolean	hasBackgroundColor() Returns whether this graphics context has a background color.
void	intersectClip(int x, int y, int width, int height) Combines the given clipping rectangle with the clipping area of this graphics context.
void	notifyDrawingRegion() Notifies that the current clip will be considered as a completely repainted region by subsequent drawings.
int	readPixel(int x, int y) Returns the color of a pixel of this graphics context.
void	readPixels(int[] array, int offset, int scanLength, int x, int y, int width, int height) Retrieves the color of the pixels of a region of this graphics context.
void	removeBackgroundColor() Removes the background color of this graphics context.
void	reset() Resets this graphics context to its initial configuration.
void	resetClip() Resets the clipping area of this graphics context to its entire bounds.
void	resetTranslation() Resets the translation vector of this graphics context to the (0,0) vector.
void	setBackgroundColor(int color) Sets the background color of this graphics context.
void	setClip(int x, int y, int width, int height) Sets the clipping area of this graphics context to the given rectangle.
void	setColor(int color) Sets the color of this graphics context.
void	setTranslation(int x, int y) Sets the translation vector of this graphics context to the (x,y) vector.
void	translate(int x, int y) Adds a given translation vector to the translation vector of this graphics context.

Methods inherited from class java.lang.Object

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

Field Detail

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 the low-level side. This flag merely warns the user that the clip values returned by getClipX(), getClipY(), getClipWidth() and getClipHeight()` may not be identical to the clip values used in the low-level side, notably if the modified low-level values were not properly restored. It is meant to be used as a debugging hint if a drawing seems incorrect.

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_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_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_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_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_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_UNKNOWN_INCIDENT

public static final int DRAWING_LOG_UNKNOWN_INCIDENT

Flag describing incidents that do not match other values.

See Also:

Constant Field Values

DRAWING_SUCCESS

public static final int DRAWING_SUCCESS

Value used when no incident occurred.

See Also:

Constant Field Values

OPAQUE

public static final int OPAQUE

Maximum opacity.

The opacity level (called alpha) is used by some Painter drawing methods to specify the drawing global opacity. When the opacity is maximal, the drawing is fully opaque. When opacity is a value between TRANSPARENT and OPAQUE, the drawing is merging the foreground color with the destination pixel color or with the global background color. When the opacity is TRANSPARENT, the drawing is fully transparent (nothing is drawn).

The opacity is an unsigned byte value between 0 (fully transparent) and 255 (fully opaque). All other values are meaningless.

The method getAlpha(int) allows to convert an opacity expressed in percentage (0% means fully transparent and 100% fully opaque) in an opacity understandable by the Painter drawing methods.

Since:

2.0

See Also:

getAlpha(int), Painter.drawImage(GraphicsContext, Image, int, int, int), Constant Field Values

TRANSPARENT

public static final int TRANSPARENT

Minimum opacity.

See OPAQUE comment.

Since:

2.0

See Also:

Constant Field Values

Method Detail

checkDrawingLogFlags

public int checkDrawingLogFlags()

Throws an exception if the error flag is currently set. The drawing log flags are reset to their success value after retrieving their value. This method is identical to getAndClearDrawingLogFlags(), except it throws an exception if the error flag has been set. Both methods are meant to help investigate drawing errors.

Returns:

the drawing log flags

Throws:

MicroUIException - if the error flag was set

See Also:

Error flag

disableEllipsis

public void disableEllipsis()

Disables ellipsis.

enableEllipsis

public void enableEllipsis(int width)

Enables ellipsis when drawing characters.

When ellipsis is enabled, characters are truncated if their rendering width is higher than the specified width limit. In this case, the last visible character is replaced by the ellipsis character (three dots).

To configure ellipsis using the clipping area as text limit, the given width should be equal to getClipX() + getClipWidth() - x, where x is the x coordinate of the drawing.

The ellipsis is only used by the methods drawing characters.

Parameters:

width - the width limit, in pixels.

Throws:

IllegalArgumentException - if width is negative or zero.

getAlpha

public static int getAlpha(int opacityPercent)

Returns the alpha level for the given opacity percentage.

The returned value may be used in some painting methods such as Painter.drawImage(GraphicsContext, Image, int, int, int).

Parameters:

opacityPercent - the opacity, in percents.

Returns:

the alpha level.

Since:

2.0

getAndClearDrawingLogFlags

public int getAndClearDrawingLogFlags()

Gets and clears the drawing log flags from a graphics context. The flags are reset to their success value after retrieving their value. This method is identical to checkDrawingLogFlags(), except it does not throw an exception if the error flag has been set. Both methods are meant to help investigate drawing errors.

Returns:

the drawing log flags

getBackgroundColor

public int getBackgroundColor()

Returns the background color of this graphics context.

The returned color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

Returns:

the background color of this graphics context.

getClipHeight

public int getClipHeight()

Returns the height of the clipping area of this graphics context.

Returns:

the height of the clipping area of this graphics context, in pixels.

getClipWidth

public int getClipWidth()

Returns the width of the clipping area of this graphics context.

Returns:

the width of the clipping area of this graphics context, in pixels.

getClipX

public int getClipX()

Returns the x coordinate of the clipping area of this graphics context.

Returned clip origin is translated according current graphics context translation.

Returns:

the x coordinate of the clipping area of this graphics context, in pixels.

getClipY

public int getClipY()

Returns the y coordinate of the clipping area of this graphics context.

Returned clip origin is translated according current graphics context translation.

Returns:

the y coordinate of the clipping area of this graphics context, in pixels.

getColor

public int getColor()

Returns the color of this graphics context.

The returned color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

Returns:

the color of this graphics context.

getEllipsisWidth

public int getEllipsisWidth()

Returns the width limit before applying the ellipsis.

If ellipsis is disabled, this method returns zero.

Returns:

the width limit, in pixels.

getHeight

public int getHeight()

Returns the height of this graphics context.

Returns:

the height of this graphics context, in pixels.

getSNIContext

public byte[] getSNIContext()

Returns the SNI context data of this graphics context.

The SNI context can be used to call a native method with SNI. This allows to identify and to use a graphics context in the native world in order to perform drawings on the graphics context or to use it as a source.

The data format is implementation specific.

Returns:

the SNI context of this graphics context.

Throws:

MicroUIException - if this graphics context is associated with a resource which has been closed.

getTranslationX

public int getTranslationX()

Returns the x coordinate of the translation vector of this graphics context.

Returns:

the x coordinate of the translation vector of this graphics context, in pixels.

getTranslationY

public int getTranslationY()

Returns the y coordinate of the translation vector of this graphics context.

Returns:

the y coordinate of the translation vector of this graphics context, in pixels.

getWidth

public int getWidth()

Returns the width of this graphics context.

Returns:

the width of this graphics context, in pixels.

hasBackgroundColor

public boolean hasBackgroundColor()

Returns whether this graphics context has a background color.

Returns:

true if a background color has been set, false otherwise.

intersectClip

public void intersectClip(int x,
                          int y,
                          int width,
                          int height)

Combines the given clipping rectangle with the clipping area of this graphics context.

This method sets the clipping area to be the intersection of the given rectangle with the current clipping area.

Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed.

Given clip origin is translated according current graphics context translation.

Parameters:

x - the x coordinate of the rectangle, in pixels.

y - the y coordinate of the rectangle, in pixels.

width - the width of the rectangle, in pixels.

height - the height of the rectangle, in pixels.

notifyDrawingRegion

public void notifyDrawingRegion()

Notifies that the current clip will be considered as a completely repainted region by subsequent drawings. A clip is already considered as a fully repainted region before each drawing. This method allows a larger region to be notified even if the first drawing in this region uses a smaller clip. This may avoid unnecessary restoration of the contents of this region (in whole or in part). This call has no effect when the graphics context does not target the display.

readPixel

public int readPixel(int x,
                     int y)

Returns the color of a pixel of this graphics context.

For more information on the format of the color value returned by this method, refer to the first paragraphs of the centralized pixel reading documentation.

Given position is translated according to the current graphics context translation.

Parameters:

x - the x coordinate of the pixel.

y - the y coordinate of the pixel.

Returns:

the color of the pixel, in ARGB format.

Throws:

IllegalArgumentException - if the given pixel coordinates are out of the bounds of this graphics context.

MicroUIException - if this graphics context is associated with a resource which has been closed.

readPixels

public void readPixels(int[] array,
                       int offset,
                       int scanLength,
                       int x,
                       int y,
                       int width,
                       int height)

Retrieves the color of the pixels of a region of this graphics context.

Each pixel color is stored in 32-bit ARGB format, where the high-order byte contains the alpha channel and the remaining bytes contain the red, green and blue channels, respectively. This is relevant regardless of the format in which the pixels are stored internally. The alpha channel specifies the opacity of the pixel, ranging between TRANSPARENT and OPAQUE.

The retrieved colors are not guaranteed to be identical to the colors from the original source. Indeed, color values may be resampled to reflect the display capabilities of the device. For example, red, green and blue pixels may all be represented by the same color value on a grayscale device.

On displays which do not support alpha blending, the alpha component will be equal to OPAQUE for opaque pixels and TRANSPARENT for every other pixel. On displays that support alpha blending, alpha channel values may be resampled to reflect the number of levels of opacity supported by the display.

The data is stored in the given int array, which should be big enough to hold the color of all the pixels of the region.

The scan length specifies the relative offset within the array between two pixels of consecutive rows. In order to prevent rows of stored pixels from overlapping, the absolute value of the scan length should be greater than or equal to the width of the region. Negative values of scan length are allowed if the order of rows is inverted in the array.

If an exception occurs during this method, the contents of the given array will remain unchanged.

Given position is translated according to the current graphics context translation.

Parameters:

array - the array in which the pixel data should be stored.

offset - the index of the array at which the first pixel color should be stored.

scanLength - the relative offset in the array between two corresponding pixels in consecutive rows.

x - the x-coordinate of the top-left pixel of the region.

y - the y-coordinate of the top-left pixel of the region.

width - the width of the region.

height - the height of the region.

Throws:

ArrayIndexOutOfBoundsException - if the array is not big enough to hold the color of all the pixels of the region.

IllegalArgumentException - if a part of the region is out of the bounds of this graphics context.

IllegalArgumentException - if the absolute value of scanLength is lower than width.

MicroUIException - if this graphics context is associated with a resource which has been closed.

removeBackgroundColor

public void removeBackgroundColor()

Removes the background color of this graphics context.

reset

public void reset()

Resets this graphics context to its initial configuration.

This methods

• resets both the translation and the clip to their initial state,
• sets the color to Colors.BLACK,
• removes the background color,
• resets the ellipsis.

resetClip

public void resetClip()

Resets the clipping area of this graphics context to its entire bounds.

The current graphics context translation is not taken into account.

This is equivalent to calling gc.setClip(-gc.getTranslationX(), -gc.getTranslationY(), gc.getWidth(), gc.getHeight()).

resetTranslation

public void resetTranslation()

Resets the translation vector of this graphics context to the (0,0) vector.

setBackgroundColor

public void setBackgroundColor(int color)

Sets the background color of this graphics context.

The given color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

The background color is only used by some drawing methods. If the background color is not set, these algorithms have to read the destination pixel color and blend it with the desired color.

The background color is irrelevant for black and white displays.

Parameters:

color - the color to set.

setClip

public void setClip(int x,
                    int y,
                    int width,
                    int height)

Sets the clipping area of this graphics context to the given rectangle.

Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed.

Given clip origin is translated according current graphics context translation.

Parameters:

x - the x coordinate of the rectangle, in pixels.

y - the y coordinate of the rectangle, in pixels.

width - the width of the rectangle, in pixels.

height - the height of the rectangle, in pixels.

setColor

public void setColor(int color)

Sets the color of this graphics context.

The given color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.

Parameters:

color - the color to set.

setTranslation

public void setTranslation(int x,
                           int y)

Sets the translation vector of this graphics context to the (x,y) vector.

Parameters:

x - the x coordinate of the translation vector, in pixels.

y - the y coordinate of the translation vector, in pixels.

translate

public void translate(int x,
                      int y)

Adds a given translation vector to the translation vector of this graphics context.

The new translation vector is equal to the sum of the given translation vector and the current translation vector.

Parameters:

x - the x coordinate of the translation vector to add, in pixels.

y - the y coordinate of the translation vector to add, in pixels.