|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object | +--javax.microedition.lcdui.Image
The Image class is used to 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 an ImageItem or onto Form
or Alert screens 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
Image copy = Image.createImage(source.getWidth(),
source.getHeight());
Graphics g = copy.getGraphics();
g.drawImage(source, 0, 0, TOP|LEFT);
createImage(width, height) 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 suport 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' chuncks 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:
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.
The 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 defined ancillary chunks are:
bKGD cHRM gAMA hIST iCCP iTXt pHYs sBIT sPLT sRGB tEXT tIME tRNS zTXt
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 image)
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 the named resource. |
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 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)
|
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 |
public static Image createImage(byte[] imagedata,
int imageoffset,
int imagelength)
The imageoffset and imagelength parameters specify a range of data in the imagedata byte array. The imageoffset parameter specifies the offset within 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.
imagedata - the array of image data in a supported image
formatimageoffset - the offset of the start of the data in the
arrayimagelength - the length of the data in the array
ArrayIndexOutOfBoundsException - if imageoffset and
imagelength specify an invalid range
IllegalArgumentException - if imagedata is incorrectly formatted or
otherwise cannot be decoded
NullPointerException - if imageData is nullpublic static Image createImage(Image image)
This method is useful for placing images drawn off-screen into
Alert, Choice, Form, and
ImageItem objects. The application can create an
off-screen image using the createImage(width, height) 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, or ImageItem object.
image - the image to be copied
NullPointerException - if image is null
public static Image createImage(int width,
int height)
width - the width, in pixels, of the new imageheight - the height, in pixels, of the new image
IllegalArgumentException - if width or height is
less than zero.
public static Image createImage(String name)
throws IOException
Class.getResourceAsStream(name).
name - the name of the resource containing the pixel data in
one of the supported image formats.
IOException - if the resource does not exist, the
data cannot be loaded, or the image data cannot be decoded
NullPointerException - if name is nullpublic Graphics getGraphics()
isMutable() method.The newly created Graphics object has the following properties:
getDefaultFont() SOLID The lifetime of Graphics objects created using this method is indefinite. They may be used at any time, by any thread.
IllegalStateException - if the image is immutablepublic int getHeight()
public int getWidth()
public boolean isMutable()
getGraphics() method of this object.
public static Image createImage(Image image,
int x,
int y,
int width,
int height,
int transform)
The source image may be mutable or immutable. For immutable source images, transparency information, if any, is copied to the new image unchanged. No compositing or dithering is performed.
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 transforms allowed are the same as those defined for the
Graphics.drawRegion() method.
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:
image - the source image to be copied fromx - the horizontal location of the region to be copiedy - the vertical location of the region to be copiedwidth - the width of the region to be copiedheight - the height of the region to be copiedtransform - the transform to be applied to the region
NullPointerException - if image is null
IllegalArgumentException - if the transform is not valid
IllegalArgumentException - if the region to be copied exceeds
the bounds of the source image
public static Image createImage(InputStream stream)
throws IOException
Class.getResourceAsStream(name).
NullPointerException - if name is null
IOException - if the resource does not exist,
the data cannot
be loaded, or the image data cannot be decoded
public static Image createRGBImage(int[] rgb,
int width,
int height,
boolean processAlpha)
rgb - an array of ARGB values that composes the image.width - the width of the imageheight - the height of the imageprocessAlpha - true if rgb has an alpha channel,
false if all pixels are fully opaque
NullPointerException - if rgb is null.
ArrayIndexOutOfBoundsException - if the length of rgb is
less than width * height.
public void getRGB(int[] rgbData,
int offset,
int scanlength,
int x,
int y,
int width,
int height)
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||