Programming Wireless Devices with the Java2 Platform

11.4 Creating and Using Images

11.4.1 Immutable Images

Images in a MIDP implementation may be either immutable or mutable. Immutable Images can be created directly from resource files, binary data, RGB data, or other Images. Once created, the contents of an immutable Image cannot be changed.

• The Image.createImage(String name) method is used to create an immutable Image from binary data in a resource file bundled with the application in the application's JAR file. The name must begin with "/" and include the full name of the binary file within the JAR file.

• The Image.createImage(byte[], int offset, int length) method is used to create an immutable Image from binary data contained in a byte array.

• The Image.createImage(Image image) method is used to create an immutable Image from another Image (which could be either mutable or immutable).

• The Image.createImage(java.io.InputStream stream) method is used to create an immutable Image from a stream of binary data.

• The Image.createImage(Image image, int x, int y, int width, int height, int transform) method is used to create an immutable Image from the transformed region of another Image (which could be either mutable or immutable).

• The Image.createRGBImage(int[] rgb, int width, int height, boolean alpha) method is used to create an immutable Image from an array of RGB color values, either with or without alpha channel data.

If binary image data is used to create an Image, it must be in a format that is supported by the device. Though some devices may optionally support additional formats, all devices must support Portable Network Graphics (PNG) format as specified by the W3C-PNG (Portable Network Graphics) Specification, Version 1.0. W3C Recommendation, October 1, 1996. This specification is available at http://www.w3.org/TR/REC-png.html and as RFC 2083, available at http://www.ietf.org/rfc/rfc2083.txt.

11.4.2 Mutable Images

Mutable Images are created with specific dimensions and can be modified as needed. Mutable Images are created with the method Image.createImage(int width, int height) and are initially filled with white pixels. The Image has the same characteristics as the display of the device: for example, color or gray-scale, and the number of available colors or gray levels.

The Image.getGraphics method returns a Graphics object that can be used for drawing into the Image. All normal Graphics methods operate on the Image, and multiple Graphics objects can be obtained if needed.

11.4.3 Transparency and Alpha Blending

Mutable Images are fully opaque, but immutable Images may contain transparent pixels. When an Image with transparency is drawn, the pixels that are transparent are not rendered, and the corresponding pixels in the target Image are left unchanged.

Some devices may also support alpha channel blending. This feature allows pixels to vary progressively from opaque to transparent, therefore allowing an Image to be blended with the target Image. Alpha blending is useful for creating special effects such as fog, smoke, and shadows.

11.4.4 Getting RGB Data

The getRGB method obtains RGB color values from a rectangular region of an Image. The color values are stored in a provided array of integers, with each color value stored in one element of the array.

getRGB(int[] rgb, int offset, int scanlength, int x, int y,
       int width, int height)

The offset parameter specifies the index at which to store the color value for the first pixel in the first row of the region. The scanlength parameter controls the number of elements in the RGB array between the first pixel of successive rows of the region. The absolute value of scanlength must be at least as large as the width of the region; this requirement prevents multiple rows from storing color values in the same elements of the array.

Color values are returned using the same form as the setColor method (0xAARRGGBB) and are subject to the display limitations of the device. Therefore, several pixels may indicate the same color value even though they are different colors in the original image data. For example, red, green, and blue pixels may be represented by the same shade of gray on a device that does not have color display capabilities.

The alpha channel byte for all of the color values will be 0xFF if the Image is opaque. If the Image is transparent, the alpha channel byte will be either 0xFF or 0x00, depending on the opacity of the pixel; the alpha channel value may vary between 0x00 and 0xFF on devices that support alpha blending.

In the following example, the offset is 2, so color value for the first pixel in the first row is stored in the array element with index 2. The scanlength is 6, so the index for the first pixel of the second row is obtained by adding 6 to the offset; the index for the first pixel of the third row is obtained by adding 6 once again. (Refer to Figure 11.2.)

int[] rgb = new int[21];
img.getRGB(rgb, 2, 6, 4, 2, 5, 3);

11.4.5 Anchor Points

Drawing operations that involve text or Images use anchor points to control their placement. The anchor points correspond to well-defined locations within the content to be rendered. For each rendering operation, the application specifies which anchor point is to be used and the (x,y) location in the Graphics coordinate system where that anchor point should appear. By using anchor points, the placement of text and Images is greatly simplified and tedious layout calculations are not needed.

Anchor points are defined using three horizontal constants and three vertical constants, thereby defining nine unique anchor points. A vertical constant and a horizontal constant are combined by logically OR-ing them to specify the desired anchor point.

For Image rendering operations, the Graphics class defines the anchor point constants shown in Figure 11.3.

As shown in Figure 11.4, the same anchor point constants are used for text rendering operations except for the VCENTER constant. Since the vertical center of text is somewhat ambiguous, this constant is replaced with the BASELINE constant for text rendering. Note that the overall bounding area of the text includes any inter character and inter line spacing.