File	Doc	Category	Size	Date	Package
Image.java	API Doc	phoneME MR2 API (J2ME)	34774	Wed May 02 18:00:10 BST 2007	javax.microedition.lcdui

Image

• java.lang.Object

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

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

Fields Summary
private int	width Width of the image in pixels.
private int	height Height of the image in pixels.
private ImageData	imageData ImageData instance associated with this Image.
static final int	INVALID_TRANSFORM_BITS Valid transforms possible are 0 - 7
static final int	TRANSFORM_SWAP_AXIS Transform swap axis bit is the 3 bit

Constructors Summary
private Image(ImageData imageData) Creates an Immutable image from the given ImageData. param imageData ImageData instance to be used to create new Image this.imageData = imageData; this.width = imageData.getWidth(); this.height = imageData.getHeight();

Methods Summary
public static javax.microedition.lcdui.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. param width the width of the new image, in pixels param height the height of the new image, in pixels return the created image throws IllegalArgumentException if either width or height is zero or less if (width <= 0 || height <= 0) { throw new IllegalArgumentException(); } // SYNC NOTE: Not accessing any shared data, no locking necessary return new Image(ImageDataFactory.getImageDataFactory(). createOffScreenImageData(width, height));
public static javax.microedition.lcdui.Image	createImage(javax.microedition.lcdui.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 an immutable source image contains transparency 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 {@link #createImage(int, int) createImage(w, h)} method, draw into it using a Graphics object obtained with the {@link #getGraphics() getGraphics()} method, and then create an immutable copy of it with this method. The immutable copy may then be placed into Choice objects. param source the source image to be copied return the new, immutable image throws NullPointerException if source is null // SYNC NOTE: Not accessing any shared data, no locking necessary if (source.isMutable()) { return new Image(ImageDataFactory.getImageDataFactory(). createImmutableCopy(source.imageData)); } else { return source; }
public static javax.microedition.lcdui.Image	createImage(java.lang.String name) Creates an immutable image from decoded image data obtained from the named resource. The name parameter is a resource name as defined by {@link Class#getResourceAsStream(String) Class.getResourceAsStream(name)}. The rules for resolving resource names are defined in the Application Resource Files section of the java.lang package documentation. param name the name of the resource containing the image data in one of the supported image formats return the created image throws NullPointerException if name is null throws java.io.IOException if the resource does not exist, the data cannot be loaded, or the image data cannot be decoded return new Image(ImageDataFactory.getImageDataFactory(). createResourceImageData(name));
public static javax.microedition.lcdui.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. param imageData the array of image data in a supported image format param imageOffset the offset of the start of the data in the array param imageLength the length of the data in the array return the created image throws ArrayIndexOutOfBoundsException if imageOffset and imageLength specify an invalid range throws NullPointerException if imageData is null throws IllegalArgumentException if imageData is incorrectly formatted or otherwise cannot be decoded if (imageOffset < 0 || imageOffset >= imageData.length || imageLength < 0 || imageOffset + imageLength > imageData.length) { throw new ArrayIndexOutOfBoundsException(); } return new Image(ImageDataFactory.getImageDataFactory(). createImmutableImageData(imageData, imageOffset, imageLength));
public static javax.microedition.lcdui.Image	createImage(javax.microedition.lcdui.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 {@link javax.microedition.lcdui.game.Sprite 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. param image the source image to be copied from param x the horizontal location of the region to be copied param y the vertical location of the region to be copied param width the width of the region to be copied param height the height of the region to be copied param transform the transform to be applied to the region return the new, immutable image throws NullPointerException if image is null throws IllegalArgumentException if the region to be copied exceeds the bounds of the source image throws IllegalArgumentException if either width or height is zero or less throws IllegalArgumentException if the transform is not valid if ((transform & INVALID_TRANSFORM_BITS) != 0) { throw new IllegalArgumentException(); } if (x < 0 || y < 0 || (x + width) > image.getWidth() || // throws NPE if image is null (y + height) > image.getHeight() || width <= 0 || height <= 0) { throw new IllegalArgumentException(); } if (x == 0 && y == 0 && width == image.getWidth() && height == image.getHeight() && transform == Sprite.TRANS_NONE) { return createImage(image); } else { return new Image(ImageDataFactory.getImageDataFactory(). createImmutableImageData(image.imageData, x, y, width, height, transform)); }
public static javax.microedition.lcdui.Image	createImage(java.io.InputStream stream) Creates an immutable image from decoded image data obtained froH 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. param stream the name of the resource containing the image data in one of the supported image formats return the created image throws NullPointerException if stream is null throws java.io.IOException if an I/O error occurs, if the image data cannot be loaded, or if the image data cannot be decoded if (stream == null) { throw new java.lang.NullPointerException(); } try { return new Image(ImageDataFactory.getImageDataFactory(). createImmutableImageData(stream)); } catch (IllegalArgumentException e) { throw new java.io.IOException(); }
public static javax.microedition.lcdui.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 param rgb an array of ARGB values that composes the image param width the width of the image param height the height of the image param processAlpha true if rgb has an alpha channel, false if all pixels are fully opaque return the created image throws NullPointerException if rgb is null. throws IllegalArgumentException if either width or height is zero or less throws ArrayIndexOutOfBoundsException if the length of rgb is less than width * height. if (width <= 0 || height <= 0) { throw new IllegalArgumentException(); } if ((width * height) > rgb.length) { throw new ArrayIndexOutOfBoundsException(); } return new Image(ImageDataFactory.getImageDataFactory(). createImmutableImageData(rgb, width, height, processAlpha));
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 {@link Font#getDefaultFont() Font.getDefaultFont()}; the stroke style is {@link Graphics#SOLID 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. return a Graphics object with this image as its destination throws IllegalStateException if the image is immutable if (isMutable()) { // SYNC NOTE: no locking necessary as getGraphics() only allocates // a new object return Graphics.getImageGraphics(this); } else { // SYNC NOTE: Not accessing any shared data, no locking necessary throw new IllegalStateException(); }
public int	getHeight() Gets the height of the image in pixels. The value returned must reflect the actual height of the image when rendered. return height of the image return height;
ImageData	getImageData() Returns ImageData associated with this Image. return The ImageData associated with this Image. return imageData;
public native void	getRGB(int[] rgbData, int offset, int scanlength, int x, int y, int width, int height)
static javax.microedition.lcdui.Image	getRomizedImage(int imageDataArrayPtr, int imageDataArrayLength) Function to load an romized Image. param imageDataArrayPtr native pointer to image data as Java int param imageDataArrayLength length of image data array return image created. Null if no romized image matches the id. try { AbstractImageDataFactory f = ImageDataFactory.getImageDataFactory(); ImageData data = f.createImmutableImageData(imageDataArrayPtr, imageDataArrayLength); return new Image(data); } catch (IllegalArgumentException iae) { return null; }
public int	getWidth() Gets the width of the image in pixels. The value returned must reflect the actual width of the image when rendered. return width of the image return width;
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. return true if the image is mutable, false otherwise return imageData.isMutable();
native boolean	render(Graphics g, int x, int y, int anchor) Renders this Image onto the provided Graphics object. param g the Graphics object to be rendered upon param x the x coordinate of the anchor point param y the y coordinate of the anchor point param anchor the anchor point for positioning the image return false if anchor is not a legal value see Graphics
native boolean	renderRegion(Graphics g, int x_src, int y_src, int width, int height, int transform, int x_dest, int y_dest, int anchor) Renders the specified region onto the provided Graphics object. ImmutableImage overrides this method so that the native implementation handles this appropriately. param g the Graphics object to be rendered upon param x_src the x coordinate of the upper left corner of the region within the source image to copy param y_src the y coordinate of the upper left corner of the region within the source image to copy param width the width of the region to copy param height the height of the region to copy param transform the desired transformation for the selected region being copied param x_dest the x coordinate of the anchor point in the destination drawing area param y_dest the y coordinate of the anchor point in the destination drawing area param anchor the anchor point for positioning the region within the destination image return false if src is the same image as the destination of this Graphics object, or transform is invalid, or anchor is invalid, or the region to be copied exceeds the bounds of the source image. see Graphics
void	resize(int width, int height, boolean keepContent) Resize Image optionally saving its content clipped according to the new geometry param width new width of the Image param height new height of the Image param keepContent keep current content of the image binded to the (0, 0) of the resized image and clipped according to the new image dimensions if (!imageData.isMutable() || width <= 0 || height <= 0) { throw new IllegalArgumentException(); } // IMPL_NOTE: In the case content is not kept it is possible // to resize the image more efficiently, especially for the // case of rotation, when the memory reallocation is not needed. // However, now there are no scenarios when resize is needed // without content saving. Image newImage = createImage(width, height); synchronized(this) { if (keepContent) { render(Graphics.getImageGraphics(newImage), 0, 0, Graphics.TOP | Graphics.LEFT); } this.width = width; this.height = height; imageData = newImage.getImageData(); }