javax.microedition.lcdui
Class Image

java.lang.Object
  |
  +--javax.microedition.lcdui.Image

public class Image

extends Object

The Image class is used to hold graphical image data. Image objects exist independently of the display device. They exist only in off-screen memory and will not be painted on the display unless an explicit command is issued by the application (such as within the paint() method of a Canvas) or when an Image object is placed within a Form screen or an Alert screen and that screen is made current.

Images are either mutable or immutable depending upon how they are created. Immutable images are generally created by loading image data from resource bundles, from files, or from the network. They may not be modified once created. Mutable images are created in off-screen memory. The application may paint into them after having created a Graphics object expressly for this purpose. Images to be placed within Alert, Choice, Form, or ImageItem objects are required to be immutable because the implementation may use them to update the display at any time, without notifying the application.

An immutable image may be created from a mutable image through the use of the createImage method. It is possible to create a mutable copy of an immutable image using a technique similar to the following:

    Image source; // the image to be copied
    source = Image.createImage(...);
    Image copy = Image.createImage(source.getWidth(), source.getHeight());
    Graphics g = copy.getGraphics();
    g.drawImage(source, 0, 0, TOP|LEFT);
 

It is also possible to use this technique to create a copy of a subrectangle of an image, by altering the width and height parameters of the createImage() call that creates the destination image and by altering the x and y parameters of the drawImage() call.

PNG Image Format

Implementations are required to support images stored in the PNG (Portable Network Graphics) format, version 1.0.

Note: The remainder of this section consists of a summary of the minimum set of features required for PNG conformance, along with some considerations for MIDP implementors and application developers. The information about PNG has been condensed from the PNG (Portable Network Graphics) Specification, Version 1.0. Any discrepancies between this section and the PNG Specification should be resolved in favor of the PNG Specification.

All of the 'critical' chunks specified by PNG must be supported. The paragraphs below describe these critical chunks.

The IHDR chunk. MIDP devices must handle the following values in the IHDR chunk:

• All positive values of width and height are supported; however, a very large image may not be readable because of memory constraints.
• All color types are supported, although the appearance of the image will be dependent on the capabilities of the device's screen. Color types that include alpha channel data are supported; however, the implementation may ignore all alpha channel information and treat all pixels as opaque.
• All bit depth values for the given color type are supported.
• Compression method 0 (deflate) is the only supported compression method. This is the same compression method that is used for jar files, and so the decompression (inflate) code may be shared between the jar decoding and PNG decoding implementations.
• The filter method represents a series of encoding schemes that may be used to optimize compression. The PNG spec currently defines a single filter method (method 0) that is an adaptive filtering scheme with five basic filter types. Filtering is essential for optimal compression since it allows the deflate algorithm to exploit spatial similarities within the image. Therefore, MIDP devices must support all five filter types defined by filter method 0.
• MIDP devices are required to read PNG images that are encoded with either interlace method 0 (None) or interlace method 1 (Adam7). Image loading in MIDP is synchronous and cannot be overlapped with image rendering, and so there is no advantage for an application to use interlace method 1. Support for decoding interlaced images is required for compatibility with PNG and for the convenience of developers who may already have interlaced images available.

The PLTE chunk. Palette-based images must be supported.

The IDAT chunk. Image data may be encoded using any of the 5 filter types defined by filter method 0 (None, Sub, Up, Average, Paeth).

The IEND chunk. This chunk must be found in order for the image to be considered valid.

Ancillary chunk support. PNG defines several 'ancillary' chunks that may be present in a PNG image but are not critical for image decoding. A MIDP implementation may (but is not required to) support any of these chunks. The implementation should silently ignore any unsupported ancillary chunks that it encounters. The currently defined ancillary chunks are:

    bKGD cHRM gAMA hIST iCCP iTXt pHYs
    sBIT sPLT sRGB tEXt tIME tRNS zTXt 

Reference

PNG (Portable Network Graphics) Specification, Version 1.0. W3C Recommendation, October 1, 1996. http://www.w3.org/TR/REC-png.html. Also available as RFC 2083, http://www.ietf.org/rfc/rfc2083.txt.

Method Summary

static Image	createImage(byte[] imageData, int imageOffset, int imageLength) Creates an immutable image which is decoded from the data stored in the specified byte array at the specified offset and length.
static Image	createImage(Image source) Creates an immutable image from a source image.
static Image	createImage(Image image, int x, int y, int width, int height, int transform) Creates an immutable image using pixel data from the specified region of a source image, transformed as specified.
static Image	createImage(InputStream stream) Creates an immutable image from decoded image data obtained from an InputStream.
static Image	createImage(int width, int height) Creates a new, mutable image for off-screen drawing.
static Image	createImage(String name) Creates an immutable image from decoded image data obtained from the named resource.
static Image	createRGBImage(int[] rgb, int width, int height, boolean processAlpha) Creates an immutable image from a sequence of ARGB values, specified as 0xAARRGGBB.
Graphics	getGraphics() Creates a new Graphics object that renders to this image.
int	getHeight() Gets the height of the image in pixels.
void	getRGB(int[] rgbData, 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.
int	getWidth() Gets the width of the image in pixels.
boolean	isMutable() Check if this image is mutable.

Methods inherited from class java.lang.Object

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 for off-screen drawing. Every pixel within the newly created image is white. The width and height of the image must both be greater than zero.

Parameters:

width - the width of the new image, in pixels

height - the height of the new image, in pixels

Returns:

the created image

Throws:

IllegalArgumentException - if either width or height is zero or less

Since:

JDE 4.0.2

createImage

public static Image createImage(Image source)

Creates an immutable image from a source image. If the source image is mutable, an immutable copy is created and returned. If the source image is immutable, the implementation may simply return it without creating a new image.

This method is useful for placing images drawn off-screen into Alert, Choice, Form, and StringItem objects. The application can create an off-screen image using the createImage(w, h) method, draw into it using a Graphics object obtained with the getGraphics() method, and then create an immutable copy of it with this method. The immutable copy may then be placed into the Alert, Choice, Form, and StringItem objects.

Parameters:

source - the source image to be copied

Returns:

the new, immutable image

Throws:

NullPointerException - if source is null

Since:

JDE 4.0.2

createImage

public static Image createImage(String name)
                         throws IOException

Creates an immutable image from decoded image data obtained from the named resource. The name parameter is a resource name as defined by Class.getResourceAsStream(name).

Parameters:

name - the name of the resource containing the image data in one of the supported image formats

Returns:

the created image

Throws:

NullPointerException - if name is null

IOException - if the resource does not exist, the data cannot be loaded, or the image data cannot be decoded

Since:

JDE 4.0.2

createImage

public static Image createImage(byte[] imageData,
                                int imageOffset,
                                int imageLength)

Creates an immutable image which is decoded from the data stored in the specified byte array at the specified offset and length. The data must be in a self-identifying image file format supported by the implementation, such as PNG.

The imageoffset and imagelength parameters specify a range of data within the imageData byte array. The imageOffset parameter specifies the offset into the array of the first data byte to be used. It must therefore lie within the range [0..(imageData.length-1)]. The imageLength parameter specifies the number of data bytes to be used. It must be a positive integer and it must not cause the range to extend beyond the end of the array. That is, it must be true that imageOffset + imageLength <= imageData.length.

This method is intended for use when loading an image from a variety of sources, such as from persistent storage or from the network.

Parameters:

imageData - the array of image data in a supported image format

imageOffset - the offset of the start of the data in the array

imageLength - the length of the data in the array

Returns:

the created image

Throws:

ArrayIndexOutOfBoundsException - if imageOffset and imageLength specify an invalid range

NullPointerException - if imageData is null

IllegalArgumentException - if imageData is incorrectly formatted or otherwise cannot be decoded

Since:

JDE 4.0.2

createImage

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

Creates an immutable image using pixel data from the specified region of a source image, transformed as specified.

The source image may be mutable or immutable. For immutable source images, transparency information, if any, is copied to the new image unchanged.

On some devices, pre-transformed images may render more quickly than images that are transformed on the fly using drawRegion. However, creating such images does consume additional heap space, so this technique should be applied only to images whose rendering speed is critical.

The transform function used must be one of the following, as defined in the Sprite class:
Sprite.TRANS_NONE - causes the specified image region to be copied unchanged
Sprite.TRANS_ROT90 - causes the specified image region to be rotated clockwise by 90 degrees.
Sprite.TRANS_ROT180 - causes the specified image region to be rotated clockwise by 180 degrees.
Sprite.TRANS_ROT270 - causes the specified image region to be rotated clockwise by 270 degrees.
Sprite.TRANS_MIRROR - causes the specified image region to be reflected about its vertical center.
Sprite.TRANS_MIRROR_ROT90 - causes the specified image region to be reflected about its vertical center and then rotated clockwise by 90 degrees.
Sprite.TRANS_MIRROR_ROT180 - causes the specified image region to be reflected about its vertical center and then rotated clockwise by 180 degrees.
Sprite.TRANS_MIRROR_ROT270 - causes the specified image region to be reflected about its vertical center and then rotated clockwise by 270 degrees.

The size of the returned image will be the size of the specified region with the transform applied. For example, if the region is 100 x 50 pixels and the transform is TRANS_ROT90, the returned image will be 50 x 100 pixels.

Note: If all of the following conditions are met, this method may simply return the source Image without creating a new one:

• the source image is immutable;
• the region represents the entire source image; and
• the transform is TRANS_NONE.

Parameters:

image - the source image to be copied from

x - the horizontal location of the region to be copied

y - the vertical location of the region to be copied

width - the width of the region to be copied

height - the height of the region to be copied

transform - the transform to be applied to the region

Returns:

the new, immutable image

Throws:

NullPointerException - if image is null

IllegalArgumentException - if the region to be copied exceeds the bounds of the source image

IllegalArgumentException - if either width or height is zero or less

IllegalArgumentException - if the transform is not valid

Since:

MIDP 2.0

createImage

public static Image createImage(InputStream stream)
                         throws IOException

Creates an immutable image from decoded image data obtained from an InputStream. This method blocks until all image data has been read and decoded. After this method completes (whether by returning or by throwing an exception) the stream is left open and its current position is undefined.

Parameters:

stream - the name of the resource containing the image data in one of the supported image formats

Returns:

the created image

Throws:

NullPointerException - if stream is null

IOException - if an I/O error occurs, if the image data cannot be loaded, or if the image data cannot be decoded

Since:

MIDP 2.0

getGraphics

public Graphics getGraphics()

Creates a new Graphics object that renders to this image. This image must be mutable; it is illegal to call this method on an immutable image. The mutability of an image may be tested with the isMutable() method.

The newly created Graphics object has the following properties:

• the destination is this Image object;
• the clip region encompasses the entire Image;
• the current color is black;
• the font is the same as the font returned by Font.getDefaultFont();
• the stroke style is SOLID; and
• the origin of the coordinate system is located at the upper-left corner of the Image.

The lifetime of Graphics objects created using this method is indefinite. They may be used at any time, by any thread.

Returns:

a Graphics object with this image as its destination

Throws:

IllegalStateException - if the image is immutable

getWidth

public int getWidth()

Gets the width of the image in pixels.

Returns:

width of the image

getHeight

public int getHeight()

Gets the height of the image in pixels.

Returns:

height of the image

isMutable

public boolean isMutable()

Check if this image is mutable. Mutable images can be modified by rendering to them through a Graphics object obtained from the getGraphics() method of this object.

Returns:

true if the image is mutable, false otherwise

createRGBImage

public static Image createRGBImage(int[] rgb,
                                   int width,
                                   int height,
                                   boolean processAlpha)

Creates an immutable image from a sequence of ARGB values, specified as 0xAARRGGBB. The ARGB data within the rgb array is arranged horizontally from left to right within each row, row by row from top to bottom. If processAlpha is true, the high-order byte specifies opacity; that is, 0x00RRGGBB specifies a fully transparent pixel and 0xFFRRGGBB specifies a fully opaque pixel. Intermediate alpha values specify semitransparency. If the implementation does not support alpha blending for image rendering operations, it must replace any semitransparent pixels with fully transparent pixels. (See Alpha Processing for further discussion.) If processAlpha is false, the alpha values are ignored and all pixels must be treated as fully opaque.

Consider P(a,b) to be the value of the pixel located at column a and row b of the Image, where rows and columns are numbered downward from the top starting at zero, and columns are numbered rightward from the left starting at zero. This operation can then be defined as:

    P(a, b) = rgb[a + b * width];    

for

     0 <= a < width
     0 <= b < height    

Parameters:

rgb - an array of ARGB values that composes the image

width - the width of the image

height - the height of the image

processAlpha - true if rgb has an alpha channel, false if all pixels are fully opaque

Returns:

the created image

Throws:

NullPointerException - if rgb is null.

IllegalArgumentException - if either width or height is zero or less

ArrayIndexOutOfBoundsException - if the length of rgb is less than width * height.

Since:

MIDP 2.0

getRGB

public void getRGB(int[] rgbData,
                   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 (see Alpha Processing for further discussion.) 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.

Consider P(a,b) to be the value of the pixel located at column a and row b of the Image, where rows and columns are numbered downward from the top starting at zero, and columns are numbered rightward from the left starting at zero. This operation can then be defined as:

    rgbData[offset + (a - x) + (b - y) * scanlength] = P(a, b);

for

     x <= a < x + width
     y <= b < y + height    

The source rectangle is required to not exceed the bounds of the image. This means:

   x >= 0
   y >= 0
   x + width <= image width
   y + height <= image height    

If any of these conditions is not met an IllegalArgumentException is thrown. Otherwise, in cases where width <= 0 or height <= 0, no exception is thrown, and no pixel data is copied to rgbData.

Parameters:

rgbData - 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:

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)

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

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

NullPointerException - if rgbData is null

Since:

MIDP 2.0