Image (Mobile Information Device Profile 3.0)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

MIDP3.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.microedition.lcdui
Class Image

java.lang.Object
  javax.microedition.lcdui.Image

Direct Known Subclasses:: AnimatedImage, ScalableImage

public class Image
extends java.lang.Object
extends java.lang.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.

Mutable vs. Immutable Images

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 as blank images containing only white pixels. The application may render on a mutable image by calling getGraphics() on the Image to obtain a Graphics object expressly for this purpose.

Images, including AnimatedImages and ScalableImages, may be placed within Alert, Choice, Form, ImageItem, Command, List, Menu, Notification, or TabbedPane objects. The high-level user interface implementation may need to update the display at any time, without notifying the application. In order to provide predictable behavior, the high-level user interface objects provide snapshot semantics for the image. That is, when a mutable image is placed within an Alert, Choice, Form, ImageItem Command, List, Menu, Notification, or TabbedPane object, the effect is as if an immutable copy is taken of its current contents. This immutable copy is then used for all subsequent painting of the high-level user interface component. If the application modifies the contents of the image, the application must update the component containing the image (for example, by calling ImageItem.setImage) in order to make the modified contents visible.

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);

If the mutable image includes alpha channel information, the following code is used instead:

  Image sourceWithAlpha; // the image to be copied
  sourceWithAlpha = Image.createImage(...);
  fillColor = 0x5500FF00; //the color that the below mutable image is initially filled with
  Image copyWithAlpha = Image.createImage(source.getWidth(), source.getHeight(), true, fillColor);
  Graphics g = copyWithAlpha.getGraphics();
  g.setBlendingMode(Graphics.SRC);
  g.drawImage(sourceWithAlpha, 0, 0, TOP|LEFT);

Alpha Channels

An Image may include an alpha channel that specifies the opacity of each pixel. Pixels may be fully opaque, fully transparent, or semi-transparent. All implementations must store alpha information with at least 4 bits of accuracy (i.e. 16 distinct levels).

An immutable Image will include an alpha channel if the resource used to create it contains an alpha channel or transparency information. A mutable Image will include an alpha channel if one was requested during instantiation.

PNG Image Format

Implementations are required to support images stored in the PNG format, as specified by the PNG (Portable Network Graphics) Specification, Version 1.2. All conforming MIDP implementations are also conformant to the minimum set of requirements given by the PNG Specification. MIDP implementations also must conform to additional requirements given here with respect to handling of PNG images. Note that the requirements listed here take precedence over any conflicting recommendations given in the PNG Specification.

Critical Chunks

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. The dimensions of the resulting Image object must match the dimensions of the PNG image. That is, the values returned by getWidth() and getHeight() and the rendered width and height must equal the width and height specified in the IHDR chunk.
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, although the alpha values may be converted based on the number of alpha levels supported by the device.
For color types 4 & 6 (grayscale with alpha and RGB with alpha, respectively) the alpha channel must be decoded and stored in the resulting image.
All bit depth values for the given color type are supported.
Compression method 0 (deflate) is the only supported compression method. This method utilizes the "zlib" compression scheme, which is also used for JARs; thus, the decompression (inflate) code may be shared between the jar decoding and PNG decoding implementations. As noted in the PNG specification, the compressed data stream may comprised internally of both compressed and uncompressed (raw) data.
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 Chunks

PNG defines several 'ancillary' chunks that may be present in a PNG image but are not critical for image decoding.

The tRNS chunk. All implementations must support the tRNS chunk. This chunk is used to implement transparency without providing alpha channel data for each pixel. For color types 0 and 2, a particular gray or RGB value is defined to be a transparent pixel. In this case, the implementation must treat pixels with this value as fully transparent (alpha = 0). Pixel value comparison must be based on the actual pixel values using the original sample depth; that is, this comparison must be performed before the pixel values are resampled to reflect the display capabilities of the device. For color type 3 (indexed color), 8-bit alpha values are potentially provided for each entry in the color palette. In this case, any pixels with intermediate alpha values must be carried through to the resulting image.

The implementation may (but is not required to) support any of the other ancillary chunks. The implementation must silently ignore any unsupported ancillary chunks that it encounters. The currently defined optional ancillary chunks are:


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

JPEG Image Format

All conforming MIDP implementations MUST support ISO/IEC JPEG together with JFIF. The support for ISO/IEC JPEG only applies to baseline DCT, non-differential, Huffman coding, as defined in table B.1, symbol 'SOF0' in [1].

GIF Image Format

All conforming MIDP implementations MUST support the GIF89a image format including animated variants, in accordance to the GIF89a Specification.

SVG Image Format

All conforming MIDP implementations MUST support the SVG Tiny 1.1 image format as defined in the Mobile SVG Profiles specification. Support for animation is OPTIONAL, and interactive functionality MAY be disabled.

Scalable images can be created using those static factory methods of the Image class which return immutable objects. Methods that return mutable images MUST rasterize the scalable image and return the result as a bitmap image, as described in the method documentation.

Methods that return pixel-level information (getRGB, getRGB16, getARGB16) MUST first rasterize the scalable image to its current viewport size, and the returned image MUST be based on the result of the rasterization.

References

[PNG]	T. Boutell, et. al., Portable Network Graphics) Specification, Version 1.2., RFC2083. Available at : http://libpng.org/pub/png/spec/1.2 or http://www.faqs.org/rfcs/rfc2083.html
[ISOIECJPEG]	ITU-T Recommendation T.81: "Information technology; Digital compression and coding of continuous-tone still images: Requirements and guidelines" 09/02. Available at : http://www.w3.org/Graphics/JPEG/itu-t81
[JFIF]	"JPEG File Interchange Format", Version 1.02, September 1, 1992. Available at : http://www.jpeg.org/public/jfif.pdf
[GIF89a]	CompuServe Inc, Graphics Interchange Format Version 89a. Available at : http://www.w3.org/Graphics/GIF/spec-gif89a.txt
[SVGTiny]	W3C, Mobile SVG Profiles: SVG Tiny and SVG Basic. Available at : http://www.w3.org/TR/SVGMobile

Since:: MIDP 1.0

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(Image image, int x, int y, int width, int height, int transform, int img_width, int img_height)` Creates an immutable image using pixel data from the specified region of a source image, transformed as specified and scaled to a specific size.
`static Image`	`createImage(java.io.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 without an alpha channel for off-screen drawing.
`static Image`	`createImage(int width, int height, boolean withAlpha, int fillColor)` Creates a new mutable image with or without an alpha channel for off-screen drawing.
`static Image`	`createImage(java.lang.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 using the 32-bit ARGB format.
`void`	`getARGB16(short[] 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 chars.
`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.
`void`	`getRGB16(short[] rgbData, int offset, int scanlength, int x, int y, int width, int height)` Obtains RGB pixel data from the specified region of this image and stores it in the provided array of shorts.
`int`	`getWidth()` Gets the width of the image in pixels.
`boolean`	`hasAlpha()` Checks if this image has alpha channel information.
`boolean`	`isAnimated()` Checks if this Image is an AnimatedImage comprised of several frames.
`boolean`	`isMutable()` Check if this image is mutable.
`boolean`	`isScalable()` Checks if this Image is a ScalableImage that can be rasterized at a variety of different pixel sizes.

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 without an alpha channel for off-screen drawing. Each pixel within the newly created image is initially white and fully opaque. The width and height of the image must both be greater than zero.

This method is equivalent to calling createImage(width, height, false, 0x00FFFFFF)

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

createImage

public static Image createImage(int width,
                                int height,
                                boolean withAlpha,
                                int fillColor)

Creates a new mutable image with or without an alpha channel for off-screen drawing. The width and height of the image must both be greater than zero.

If withAlpha is true, the returned Image includes an alpha channel and the opacity of each pixel can be modified using a Graphics object with the SRC blending mode.

The initial content of the pixels is determined by the fillColor parameter. If withAlpha is false, the fillColor value is interpreted as a 24-bit RGB color value (0x00RRGGBB); the value of the upper byte is ignored and the pixels are all fully opaque. If withAlpha is true, the fillColor value is interpreted as a 32-bit ARGB color value (0xAARRGGBB) and the pixels' alpha values are set according to the value of the upper byte.

Parameters:: width - the width of the new image, in pixels; height - the height of the new image, in pixels; withAlpha - true to create an image with an alpha channel, false to create a opaque image without an alpha channel; fillColor - the color (and alpha, if applicable) that the pixels are initially filled with
Returns:: the new image
Throws:: java.lang.IllegalArgumentException - if either width or height is zero or less
Since:: MIDP 3.0

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. If the source image contains alpha channel information, this information is copied to the new image unchanged.

This method is useful for placing the contents of mutable images into Choice 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 Choice objects.

This method can be used to create a pixel-based Image object using a ScalableImage as the source. In this case, a new Image is returned that is a copy of the ScalableImage in its rasterized form. The dimensions of the new Image will equal the current pixel dimensions of the ScalableImage and cannot be changed.

Parameters:: source - the source image to be copied
Returns:: the new, immutable image
Throws:: java.lang.NullPointerException - if source is null

createImage

public static Image createImage(java.lang.String name)
                         throws java.io.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). The rules for resolving resource names are defined in the Application Resource Files section of the java.lang package documentation.

This method returns a object of type Image for static, bitmapped image data. An AnimatedImage is returned if the image data contains an animated bitmap image. A ScalableImage is returned if the image data contains valid vector graphics content such as SVG Tiny 1.1.

Parameters:: name - the name of the resource containing the image data in one of the supported image formats
Returns:: the created image
Throws:: java.lang.NullPointerException - if name is null; java.io.IOException - if the resource does not exist, the data cannot be loaded, or the image data cannot be decoded

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 the mandatory image formats.

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.

This method returns a object of type Image for static, bitmapped image data. An AnimatedImage is returned if the image data contains an animated bitmap image. A ScalableImage is returned if the image data contains valid vector graphics content such as SVG Tiny 1.1.

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:: java.lang.ArrayIndexOutOfBoundsException - if imageOffset and imageLength specify an invalid range; java.lang.NullPointerException - if imageData is null; java.lang.IllegalArgumentException - if imageData is incorrectly formatted or otherwise cannot be decoded

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. Alpha channel 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 source image is not a ScalableImage or AnimatedImage;
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:: java.lang.NullPointerException - if image is null; java.lang.IllegalArgumentException - if the region to be copied exceeds the bounds of the source image; java.lang.IllegalArgumentException - if either width or height is zero or less; java.lang.IllegalArgumentException - if the transform is not valid
Since:: MIDP 2.0

createImage

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

Creates an immutable image using pixel data from the specified region of a source image, transformed as specified and scaled to a specific size.

The source image may be mutable or immutable. If it is mutable, the new Image will represent a snapshot of the source image's contents; subsequent changes to the source image are not reflected in the new image.Alpha channel information, if any, is copied to the new image unchanged.

If the source image is a ScalableImage, the returned Image will contain a rasterized version of the vector graphics content. The specified region is interpreted in terms of the ScalableImage's current pixel dimensions, and the vector graphics content is rasterized directly into an image of the requested dimensions to avoid scaling artifacts. The specified transform is applied to the resulting bitmap data.

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 source image is not a ScalableImage or AnimatedImage;
the region represents the entire source image;
the requested image dimensions match that of the 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; img_width - the width of the new Image; img_height - the height of the new Image
Returns:: the new, immutable image
Throws:: java.lang.NullPointerException - if image is null; java.lang.IllegalArgumentException - if the region to be copied exceeds the bounds of the source image; java.lang.IllegalArgumentException - if either width or height is zero or less; java.lang.IllegalArgumentException - if the transform is not valid; java.lang.IllegalArgumentException - if either img_width or img_height is less than 1
Since:: MIDP 3.0

createImage

public static Image createImage(java.io.InputStream stream)
                         throws java.io.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:: java.lang.NullPointerException - if stream is null; java.io.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 current alpha level is fully opaque;
the current blending mode is SRC_OVER;
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 blending mode may be changed to SRC only if the Image includes an alpha channel.

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:: java.lang.IllegalStateException - if the image is immutable

getWidth

public int getWidth()

Gets the width of the image in pixels. The value returned must reflect the actual width of the image when rendered.

Returns:: width of the image

getHeight

public int getHeight()

Gets the height of the image in pixels. The value returned must reflect the actual height of the image when rendered.

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

hasAlpha

public boolean hasAlpha()

Checks if this image has alpha channel information. All of the pixels are fully opaque in an Image without an alpha channel. If an alpha channel is present, pixels within the Image may be opaque, or partially or fully transparent.

An immutable Image will have an alpha channel if it was created with an image resource having an transparent pixels. That is, the image resource contain at least one non-opaque pixel present in the image data. A mutable Image will have an alpha channel if it was explicitly created to have one; an alpha channel is required in order to use the SRC blending mode when rendering to a mutable image.

Returns:: true if the image has an alpha channel false otherwise
Since:: MIDP 3.0

isAnimated

public boolean isAnimated()

Checks if this Image is an AnimatedImage comprised of several frames. If this method returns true, the Image is an instance of AnimatedImage and it may be cast to an AnimatedImage as needed.

Returns:: true if this Image is an instance of an AnimatedImage
Since:: MIDP 3.0
See Also:: AnimatedImage

isScalable

public boolean isScalable()

Checks if this Image is a ScalableImage that can be rasterized at a variety of different pixel sizes. If this method returns true, the Image is an instance of ScalableImage and it may be cast to a ScalableImage as needed.

Returns:: true if this Image is an instance of a ScalableImage
Since:: MIDP 3.0
See Also:: ScalableImage

createRGBImage

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

Creates an immutable image from a sequence of ARGB values, specified using the 32-bit ARGB format. 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 and the resulting image will have an alpha channel. That is, 0x00RRGGBB specifies a fully transparent pixel, 0xFFRRGGBB specifies a fully opaque pixel, and intermediate alpha values specify semi-transparency.

If processAlpha is false, the high-order byte is ignored and the resulting image will not have an alpha channel. All pixels will be 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 the image should include alpha channel information contained in rgb, false if the image and all of its pixels should be fully opaque
Returns:: the created image
Throws:: java.lang.NullPointerException - if rgb is null.; java.lang.IllegalArgumentException - if either width or height is zero or less; java.lang.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 using the 32-bit ARGB format.

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 alpha values are returned regardless of the image type, but they will all be 0xFF if the image does not include an alpha channel.

The returned values are not guaranteed to be identical to values from the original source, such as from createRGBImage or from an image of the mandatory image format. 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). Alpha channel values may be resampled to reflect the number of levels alpha supported by the device.

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.

 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:: 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 rgbData is null
Since:: MIDP 2.0

getRGB16

public void getRGB16(short[] rgbData,
                     int offset,
                     int scanlength,
                     int x,
                     int y,
                     int width,
                     int height)

Obtains RGB pixel data from the specified region of this image and stores it in the provided array of shorts. Each pixel value is stored in a 16-bit RGB format. The alpha values of the pixels are not reflected in the data returned.

 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

Parameters:: rgbData - an array of shorts in which the RGB pixel data is stored; offset - the index into the array where the first RGB 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 rgbData is null
Since:: MIDP 3.0

getARGB16

public void getARGB16(short[] 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 chars. Each pixel value is stored in a 16-bit ARGB format that includes both the color and alpha values of the pixels.

 argbData[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

Parameters:: argbData - an array of shorts in which the ARGB pixel data is stored; offset - the index into the array where the first ARGB value is to be 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 argbData 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
Since:: MIDP 3.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

MIDP3.0

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Send a comment or suggestionVersion 3.0 of Mobile Information Device Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-2009 Motorola Inc. Portions copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved.

javax.microedition.lcdui Class Image

Mutable vs. Immutable Images

Alpha Channels

PNG Image Format

Critical Chunks

Ancillary Chunks

JPEG Image Format

GIF Image Format

SVG Image Format

References

createImage

createImage

createImage

createImage

createImage

createImage

createImage

createImage

getGraphics

getWidth

getHeight

isMutable

hasAlpha

isAnimated

isScalable

createRGBImage

getRGB

getRGB16

getARGB16

javax.microedition.lcdui
Class Image