ej.microui.display

Class Image

java.lang.Object

ej.microui.display.Image

public class Image
extends java.lang.Object

An Image object holds graphical display data.
An Image is either mutable or immutable depending on the way it has been created.

Immutable images are created/loaded from data resources, and they may not be modified. They can be either loaded from an internal non-standard image format or dynamically created from supported standard image formats, depending on the MicroUI implementation.

Creating images may not be possible within a particular MicroUI implementation. If the MicroUI implementation doesn't allow the allocation of memory to store the image's buffer, an OutOfMemoryError is thrown.

Mutable images are created as blank images containing only white pixels. The application may render on a mutable image by calling getGraphicsContext() on the image to obtain a GraphicsContext object expressly for this purpose.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Image.OutputFormat Specify the format to apply when creating an immutable image.

Method Summary

Modifier and Type	Method and Description
static Image	createImage(Display d, int width, int height) Creates a new mutable image which respects the pixel organization (layout, bpp etc.) of the given display and with the given size.
static Image	createImage(Image image, int x, int y, int width, int height) Creates an immutable image from another image area.
static Image	createImage(Image image, int x, int y, int width, int height, Image.OutputFormat format) Creates an immutable image from another image area.
static Image	createImage(java.io.InputStream stream, int size) Creates an immutable image from an InputStream. The resource image format (input format) is a standard image format (PNG etc.) According the MicroUI implementation the image can be loaded or not.
static Image	createImage(java.io.InputStream stream, int size, Image.OutputFormat format) Creates an immutable image from an InputStream. The resource image format (input format) is a standard image format ( PNG etc.) According the MicroUI implementation the image can be loaded or not.
static Image	createImage(int width, int height) Creates a new mutable image which respects the pixel organization (layout, bpp etc.) of the default display and with the given size.
static Image	createImage(java.lang.String name) Creates an immutable image from a resource. The resource image format (input format) is a standard image format (PNG etc.) or an internal MicroUI implementation specific format.
static Image	createImage(java.lang.String name, Image.OutputFormat format) Creates an immutable image from a resource. The resource image format (input format) is a standard image format (PNG etc.) or an internal MicroUI implementation specific format.
void	getARGB(int[] argbData, int offset, int scanlength, int x, int y, int width, int height) Obtains ARGB pixel data from the specified region of this image and stores it in the provided array of integers.
GraphicsContext	getGraphicsContext() Returns a new GraphicsContext object to draw on the image.
int	getHeight() Returns the height of the image in pixels.
int	getWidth() Returns the width of the image in pixels.
boolean	isMutable() Tells whether this image is mutable.
boolean	isTransparent() Tells whether this image contains at least a transparent pixel.
int	readPixel(int x, int y) Obtains the ARGB color of the pixel at (x,y).

Methods inherited from class java.lang.Object

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

Method Detail

createImage

public static Image createImage(int width,
                                int height)

Creates a new mutable image which respects the pixel organization (layout, bpp etc.) of the default display and with the given size. Every pixel within the newly created image is white. Given width and height must be greater than zero.The effect is identical to
createImage(Display.getDefaultDisplay(), width, height);

Parameters:

width - the width of the new image, in pixels.

height - the height of the new image, in pixels.

Returns:

the created image.

Throws:

java.lang.IllegalArgumentException - if either width or height is zero or less.

ImageCreationException - if MicroUI implementation cannot create the image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

java.lang.IllegalStateException - if MicroUI is not started.

java.lang.SecurityException - if a security manager exists and does not allow the caller to create an image.

See Also:

createImage(Display, int, int)

createImage

public static Image createImage(Display d,
                                int width,
                                int height)

Creates a new mutable image which respects the pixel organization (layout, bpp etc.) of the given display and with the given size. Every pixel within the newly created image is white. Given width and height must be greater than zero.

Parameters:

d - the display for which the image is created.

width - the width of the new image, in pixels.

height - the height of the new image, in pixels.

Returns:

the created image.

Throws:

java.lang.IllegalArgumentException - if either width or height is zero or less

ImageCreationException - if MicroUI implementation cannot create the image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

java.lang.SecurityException - if a security manager exists and does not allow the caller to create an image.

createImage

public static Image createImage(java.lang.String name)
                         throws java.io.IOException

Creates an immutable image from a resource.

The resource image format (input format) is a standard image format (PNG etc.) or an internal MicroUI implementation specific format. According the MicroUI implementation the image can be loaded or not. For instance, when MicroUI implementation does not hold a dynamic PNG decoder, load a PNG is impossible.
The MicroUI implementation is responsible to retrieve the right image decoder and/or loader to decode and/or load the image.
When a resource cannot be loaded, an IOException is thrown.

The output format is the best format for the input format. For instance the PNG image output format is Image.OutputFormat.ARGB8888 (32 bits per pixels with 256 levels of transparency).
The output format for the MicroUI implementation specific images formats is often the encoded format.

The effect is identical to
createImage(name, null);

Parameters:

name - a resource name matching image data in a supported image format.

Returns:

the created image.

Throws:

java.lang.NullPointerException - if name is null.

java.io.IOException - if the resource is not found, if the data can not be decoded or if the name is not an absolute path.

ImageCreationException - if MicroUI implementation cannot create the image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

java.lang.SecurityException - if a security manager exists and does not allow the caller to create an image.

java.lang.IllegalStateException - if MicroUI is not started.

Since:

2.0

See Also:

createImage(String, OutputFormat)

createImage

public static Image createImage(java.lang.String name,
                                Image.OutputFormat format)
                         throws java.io.IOException

Creates an immutable image from a resource.

The resource image format (input format) is a standard image format (PNG etc.) or an internal MicroUI implementation specific format. According the MicroUI implementation the image can be loaded or not. For instance, when MicroUI implementation does not hold a dynamic PNG decoder, load a PNG is impossible.
The MicroUI implementation is responsible to retrieve the right image decoder and/or loader to decode and/or load the image.
When a resource cannot be loaded, an IOException is thrown.

The output format is the format specified as paremeter. This format may be different than the best format for the input format (@see createImage(String).

Parameters:

name - a resource name matching image data in a supported image format.

format - the expected output format or null to use the best output format according the input image format.

Returns:

the created image.

Throws:

java.lang.NullPointerException - if name is null.

java.io.IOException - if the resource is not found, if the data can not be decoded or if the name is not an absolute path.

ImageCreationException - if MicroUI implementation cannot create the image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

java.lang.SecurityException - if a security manager exists and does not allow the caller to create an image.

java.lang.IllegalStateException - if MicroUI is not started.

Since:

2.0

createImage

public static Image createImage(Image image,
                                int x,
                                int y,
                                int width,
                                int height)

Creates an immutable image from another image area. The image is created with the same format as the original image.
The area of the source image to copy is defined by an upper-left location (x,y) relative to the image and a size (width,height).

If the defined zone matches the entire source image and if the source image is immutable, then the source image image may be returned.

The effect is identical to
createImage(image, x, y, width, height, null);

Parameters:

image - the source image.

x - the x coordinate of the area to copy.

y - the y coordinate of the area to copy.

width - the width of the area to copy.

height - the height of the area to copy.

Returns:

an immutable image.

Throws:

java.lang.NullPointerException - if image is null.

java.lang.IllegalArgumentException - if the area to copy is out of the bounds of the source image or if either width or height is zero or negative.

ImageCreationException - if MicroUI implementation cannot create the image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

java.lang.SecurityException - if a security manager exists and does not allow the caller to create an image.

See Also:

createImage(Image, int, int, int, int, OutputFormat)

createImage

public static Image createImage(Image image,
                                int x,
                                int y,
                                int width,
                                int height,
                                Image.OutputFormat format)

Creates an immutable image from another image area. The image is created with the specified format.
The area of the source image to copy is defined by an upper-left location (x,y) relative to the image and a size (width,height).

If the defined zone matches the entire source image and if the source image is immutable, then the source image image may be returned.

Parameters:

image - the source image.

x - the x coordinate of the area to copy.

y - the y coordinate of the area to copy.

width - the width of the area to copy.

height - the height of the area to copy.

format - the expected output format or null to use the source image format.

Returns:

an immutable image

Throws:

java.lang.NullPointerException - if image is null.

java.lang.IllegalArgumentException - if the area to copy is out of the bounds of the source image or if either width or height is zero or negative.

ImageCreationException - if MicroUI implementation cannot create the image

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

java.lang.SecurityException - if a security manager exists and does not allow the caller to create an image.

Since:

2.0

createImage

public static Image createImage(java.io.InputStream stream,
                                int size)
                         throws java.io.IOException

Creates an immutable image from an InputStream.

The resource image format (input format) is a standard image format (PNG etc.) According the MicroUI implementation the image can be loaded or not. For instance, when MicroUI implementation does not hold a dynamic PNG decoder, load a PNG is impossible.
The MicroUI implementation is responsible to retrieve the right image decoder and/or loader to decode and/or load the image.
When a resource cannot be loaded, an IOException is thrown.

The output format is the best format for the input format. For instance the PNG image output format is Image.OutputFormat.ARGB8888 (32 bits per pixels with 256 levels of transparency).

The effect is identical to
createImage(stream, size, format);

Parameters:

stream - a stream providing image data.

size - the number of bytes to read.

Returns:

the created image

Throws:

java.lang.NullPointerException - if stream is null.

java.io.IOException - if the resource is not found, if the data can not be decoded or if the stream cannot be read.

ImageCreationException - if MicroUI implementation cannot create the image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

java.lang.SecurityException - if a security manager exists and does not allow the caller to create an image.

java.lang.IllegalStateException - if MicroUI is not started.

Since:

2.0

See Also:

createImage(InputStream, int, OutputFormat)

createImage

public static Image createImage(java.io.InputStream stream,
                                int size,
                                Image.OutputFormat format)
                         throws java.io.IOException

Creates an immutable image from an InputStream.

The resource image format (input format) is a standard image format ( PNG etc.) According the MicroUI implementation the image can be loaded or not. For instance, when MicroUI implementation does not hold a dynamic PNG decoder, load a PNG is impossible.
The MicroUI implementation is responsible to retrieve the right image decoder and/or loader to decode and/or load the image.
When a resource cannot be loaded, an IOException is thrown.

The output format is the format specified as paremeter. This format may be different than the best format for the input format (@see createImage(InputStream, int).

Parameters:

stream - a stream providing image data

size - the number of bytes to read

format - the expected output format or null to use the best output format according the input image format

Returns:

the created image

Throws:

java.lang.NullPointerException - if stream is null

java.io.IOException - if the resource is not found, if the data can not be decoded or if the stream cannot be read.

ImageCreationException - if MicroUI implementation cannot create the image

java.lang.SecurityException - if a security manager exists and does not allow the caller to create an image.

java.lang.OutOfMemoryError - if there is not enough room to add a new image.

java.lang.IllegalStateException - if MicroUI is not started.

Since:

2.0

getGraphicsContext

public GraphicsContext getGraphicsContext()

Returns a new GraphicsContext object to draw on the image. The image must be mutable, otherwise an IllegalArgumentException is thrown. The returned GraphicsContext object has the default GraphicsContext behavior and allows the entire image to be drawn.

Returns:

a GraphicsContext object which maps this image

Throws:

java.lang.IllegalArgumentException - if the image is immutable

getWidth

public int getWidth()

Returns the width of the image in pixels.

Returns:

width of the image

getHeight

public int getHeight()

Returns the height of the image in pixels.

Returns:

height of the image

isMutable

public boolean isMutable()

Tells whether this image is mutable.

Returns:

whether the image is mutable.

isTransparent

public boolean isTransparent()

Tells whether this image contains at least a transparent pixel.

Returns:

whether the image contains at least a transparent pixel.

readPixel

public int readPixel(int x,
                     int y)

Obtains the ARGB color of the pixel at (x,y). The read color may be different than the drawing color. It is screen dependent, according to the number of bits per pixels (see Display.getBPP() ).

Parameters:

x - the x coordinate of the pixel

y - the y coordinate of the pixel

Returns:

the ARGB color of the pixel

Throws:

java.lang.IllegalArgumentException - if the pixel coordinates are out of bounds of the source graphics context

getARGB

public void getARGB(int[] argbData,
                    int offset,
                    int scanlength,
                    int x,
                    int y,
                    int width,
                    int height)

Obtains ARGB pixel data from the specified region of this image and stores it in the provided array of integers.
Each pixel value is stored in 0xAARRGGBB format, where the high-order byte contains the alpha channel and the remaining bytes contain color components for red, green and blue, respectively. The alpha channel specifies the opacity of the pixel, where a value of 0x00 represents a pixel that is fully transparent and a value of 0xFF represents a fully opaque pixel.

The returned values are not guaranteed to be identical to values from the original source, such as from createRGBImage or from a PNG image. Color values may be resampled to reflect the display capabilities of the device (for example, red, green or blue pixels may all be represented by the same gray value on a grayscale device). On devices that do not support alpha blending, the alpha value will be 0xFF for opaque pixels and 0x00 for all other pixels. On devices that support alpha blending, alpha channel values may be resampled to reflect the number of levels of semitransparency supported.

The scanlength specifies the relative offset within the array between the corresponding pixels of consecutive rows. In order to prevent rows of stored pixels from overlapping, the absolute value of scanlength must be greater than or equal to width. Negative values of scanlength are allowed. In all cases, this must result in every reference being within the bounds of the rgbData array.

Parameters:

argbData - an array of integers in which the ARGB pixel data is stored

offset - the index into the array where the first ARGB value is stored

scanlength - the relative offset in the array between corresponding pixels in consecutive rows of the region

x - the x-coordinate of the upper left corner of the region

y - the y-coordinate of the upper left corner of the region

width - the width of the region

height - the height of the region

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the requested operation would attempt to access an element in the rgbData array whose index is either negative or beyond its length (the contents of the array are unchanged)

java.lang.IllegalArgumentException - if the area being retrieved exceeds the bounds of the source image

java.lang.IllegalArgumentException - if the absolute value of scanlength is less than width

java.lang.NullPointerException - - if argbData is null