com.sun.lwuit
Class Image

java.lang.Object
  com.sun.lwuit.Image

Direct Known Subclasses:

EncodedImage, IndexedImage, RGBImage, Timeline

public class Image
extends java.lang.Object

Abstracts the underlying platform images allowing us to treat them as a uniform object.

Constructor Summary

protected

Image(java.lang.Object image) Subclasses may use this and point to an underlying native image which might be null for a case of an image that doesn't use native drawing

Method Summary

boolean	animate()
Image	applyMask(java.lang.Object mask) Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.
Image	applyMask(java.lang.Object mask, int x, int y) Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.
static Image	createImage(byte[] bytes, int offset, int len) creates an image from a given byte array data
static Image	createImage(java.io.InputStream stream) creates an image from an InputStream
static Image	createImage(int[] rgb, int width, int height) creates an image from an RGB image
static Image	createImage(int width, int height) Creates a mutable image that may be manipulated using getGraphics
static Image	createImage(int width, int height, int fillColor) Creates a mutable image that may be manipulated using getGraphics
static Image	createImage(java.lang.Object nativeImage) creates an image from the given native image (e.g.
static Image	createImage(java.lang.String path) creates an image from the given path based on MIDP's createImage(path)
static Image	createIndexed(int width, int height, int[] palette, byte[] data) Creates an indexed image with byte data this method may return a native indexed image rather than an instance of the IndexedImage class
java.lang.Object	createMask() Creates a mask from the given image, a mask can be used to apply an arbitrary alpha channel to any image.
static Image	createSVG(java.lang.String baseURL, boolean animated, byte[] data) Creates an SVG Image from the given byte array data and the base URL, this method will throw an exception if SVG is unsupported.
protected void	drawImage(Graphics g, java.lang.Object nativeGraphics, int x, int y) Callback invoked internally by LWUIT to draw the image/frame onto the display.
protected void	drawImage(Graphics g, java.lang.Object nativeGraphics, int x, int y, int w, int h) Callback invoked internally by LWUIT to draw the image/frame onto the display.
Graphics	getGraphics() If this is a mutable image a graphics object allowing us to draw on it is returned.
int	getHeight() Returns the height of the image
java.lang.Object	getImage() Returns the platform specific image implementation, warning the implementation class can change between revisions of LWUIT and platforms.
int[]	getRGB() Returns the content of this image as a newly created ARGB array.
int[]	getRGBCached() Returns the content of this image as a newly created ARGB array or a cached instance if possible.
java.lang.Object	getSVGDocument() Returns a platform specific DOM object that can be manipulated by the user to change the SVG Image
int	getWidth() Returns the width of the image
static boolean	isAlphaMutableImageSupported() Returns true if mutable images support alpha transparency
boolean	isAnimation() Returns true if this is an animated image
boolean	isOpaque() Indicates whether this image is opaque or not
boolean	isSVG() Indicates if this image represents an SVG file or a bitmap file
static boolean	isSVGSupported() Indicates whether the underlying platform supports creating an SVG Image
void	lock() This callback indicates that a component pointing at this image is initialized, this allows an image to make performance sensitive considerations e.g. an encoded image might choose to cache itself in RAM.
Image	modifyAlpha(byte alpha) Creates a new image instance with the alpha channel of opaque/translucent pixels within the image using the new alpha value.
Image	modifyAlpha(byte alpha, int removeColor) Creates a new image instance with the alpha channel of opaque/translucent pixels within the image using the new alpha value.
Image	modifyAlphaWithTranslucency(byte alpha) Creates a new image instance with the alpha channel of opaque pixels within the image using the new alpha value.
Image	rotate(int degrees) Returns an instance of this image rotated by the given number of degrees.
void	scale(int width, int height) Deprecated. scale should return an image rather than modify the image in place use scaled(int, int) instead
Image	scaled(int width, int height) Returns a scaled version of this image image using the given width and height, this is a fast algorithm that preserves translucent information.
Image	scaledHeight(int height) Scales the image to the given height while updating the width based on the aspect ratio of the height
Image	scaledSmallerRatio(int width, int height) Scales the image while maintaining the aspect ratio to the smaller size image
Image	scaledWidth(int width) Scales the image to the given width while updating the height based on the aspect ratio of the width
Image	subImage(int x, int y, int width, int height, boolean processAlpha) Extracts a subimage from the given image allowing us to breakdown a single large image into multiple smaller images in RAM, this actually creates a standalone version of the image for use.
void	toRGB(RGBImage image, int destX, int destY, int x, int y, int width, int height) Extracts data from this image into the given RGBImage
void	unlock() This callback indicates that a component pointing at this image is now deinitilized This method may be invoked multiple times.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Image

protected Image(java.lang.Object image)

Subclasses may use this and point to an underlying native image which might be null for a case of an image that doesn't use native drawing

Parameters:

image - native image object passed to the LWUIT implementation

Method Detail

lock

public void lock()

This callback indicates that a component pointing at this image is initialized, this allows an image to make performance sensitive considerations e.g. an encoded image might choose to cache itself in RAM. This method may be invoked multiple times.

unlock

public void unlock()

This callback indicates that a component pointing at this image is now deinitilized This method may be invoked multiple times.

isSVGSupported

public static boolean isSVGSupported()

Indicates whether the underlying platform supports creating an SVG Image

Returns:

true if the method create SVG image would return a valid image object from an SVG Input stream

getSVGDocument

public java.lang.Object getSVGDocument()

Returns a platform specific DOM object that can be manipulated by the user to change the SVG Image

Returns:

Platform dependent object, when JSR 226 is supported an SVGSVGElement might be returned.

createSVG

public static Image createSVG(java.lang.String baseURL,
                              boolean animated,
                              byte[] data)
                       throws java.io.IOException

Creates an SVG Image from the given byte array data and the base URL, this method will throw an exception if SVG is unsupported.

Parameters:

baseURL - URL which is used to resolve relative references within the SVG file

animated - indicates if the SVG features an animation

data - the conten of the SVG file

Returns:

an image object that can be used as any other image object.

Throws:

java.io.IOException - if resource lookup fail SVG is unsupported

isSVG

public boolean isSVG()

Indicates if this image represents an SVG file or a bitmap file

Returns:

true if this is an SVG file

createMask

public java.lang.Object createMask()

Creates a mask from the given image, a mask can be used to apply an arbitrary alpha channel to any image. A mask is derived from the blue channel (LSB) of the given image. The generated mask can be used with the apply mask method.

Returns:

mask object that can be used with applyMask

applyMask

public Image applyMask(java.lang.Object mask,
                       int x,
                       int y)

Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.

Parameters:

mask - mask object created by the createMask() method.

x - starting x where to apply the mask

y - starting y where to apply the mask

Returns:

image masked based on the given object

applyMask

public Image applyMask(java.lang.Object mask)

Applies the given alpha mask onto this image and returns the resulting image see the createMask method for indication on how to convert an image into an alpha mask.

Parameters:

mask - mask object created by the createMask() method.

Returns:

image masked based on the given object

Throws:

java.lang.IllegalArgumentException - if the image size doesn't match the mask size

subImage

public Image subImage(int x,
                      int y,
                      int width,
                      int height,
                      boolean processAlpha)

Extracts a subimage from the given image allowing us to breakdown a single large image into multiple smaller images in RAM, this actually creates a standalone version of the image for use.

Parameters:

x - the x offset from the image

y - the y offset from the image

width - the width of internal images

height - the height of internal images

processAlpha - whether alpha should be processed as well as part of the cutting

Returns:

An array of all the possible images that can be created from the source

rotate

public Image rotate(int degrees)

Returns an instance of this image rotated by the given number of degrees. By default 90 degree angle divisions are supported, anything else is implementation dependent. This method assumes a square image. Notice that it is inefficient in the current implementation to rotate to non-square angles,

E.g. rotating an image to 45, 90 and 135 degrees is inefficient. Use rotatate to 45, 90 and then rotate the 45 to another 90 degrees to achieve the same effect with less memory.

Parameters:

degrees - A degree in right angle must be larger than 0 and up to 359 degrees

Returns:

new image instance with the closest possible rotation

createIndexed

public static Image createIndexed(int width,
                                  int height,
                                  int[] palette,
                                  byte[] data)

Creates an indexed image with byte data this method may return a native indexed image rather than an instance of the IndexedImage class

Parameters:

width - image width

height - image height

palette - the color palette to use with the byte data

data - byte data containing palette offsets to map to ARGB colors

modifyAlpha

public Image modifyAlpha(byte alpha)

Creates a new image instance with the alpha channel of opaque/translucent pixels within the image using the new alpha value. Transparent (alpha == 0) pixels remain transparent. All other pixels will have the new alpha value.

Parameters:

alpha - New value for the entire alpha channel

Returns:

Translucent/Opaque image based on the alpha value and the pixels of this image

modifyAlphaWithTranslucency

public Image modifyAlphaWithTranslucency(byte alpha)

Creates a new image instance with the alpha channel of opaque pixels within the image using the new alpha value. Transparent (alpha == 0) pixels remain transparent. Semi translucent pixels will be multiplied by the ratio difference and their translucency reduced appropriately.

Parameters:

alpha - New value for the entire alpha channel

Returns:

Translucent/Opaque image based on the alpha value and the pixels of this image

modifyAlpha

public Image modifyAlpha(byte alpha,
                         int removeColor)

Creates a new image instance with the alpha channel of opaque/translucent pixels within the image using the new alpha value. Transparent (alpha == 0) pixels remain transparent. All other pixels will have the new alpha value.

Parameters:

alpha - New value for the entire alpha channel

removeColor - pixels matching this color are made transparent (alpha channel ignored)

Returns:

Translucent/Opaque image based on the alpha value and the pixels of this image

createImage

public static Image createImage(java.lang.String path)
                         throws java.io.IOException

creates an image from the given path based on MIDP's createImage(path)

Parameters:

path -

Returns:

newly created image object

Throws:

java.io.IOException

createImage

public static Image createImage(java.lang.Object nativeImage)

creates an image from the given native image (e.g. MIDP image object)

Parameters:

nativeImage -

Returns:

newly created LWUIT image object

createImage

public static Image createImage(java.io.InputStream stream)
                         throws java.io.IOException

creates an image from an InputStream

Parameters:

stream - a given InputStream

Returns:

the newly created image

Throws:

java.io.IOException

createImage

public static Image createImage(int[] rgb,
                                int width,
                                int height)

creates an image from an RGB image

Parameters:

rgb - the RGB image array data

width - the image width

height - the image height

Returns:

an image from an RGB image

createImage

public static Image createImage(int width,
                                int height)

Creates a mutable image that may be manipulated using getGraphics

Parameters:

width - the image width

height - the image height

Returns:

an image in a given width and height dimension

isAlphaMutableImageSupported

public static boolean isAlphaMutableImageSupported()

Returns true if mutable images support alpha transparency

Returns:

true if mutable images support alpha in their fillColor argument

createImage

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

Creates a mutable image that may be manipulated using getGraphics

Parameters:

width - the image width

height - the image height

fillColor - the color with which the image should be initially filled

Returns:

an image in a given width and height dimension

createImage

public static Image createImage(byte[] bytes,
                                int offset,
                                int len)

creates an image from a given byte array data

Parameters:

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

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

len - the length of the data in the array

Returns:

the newly created image

getGraphics

public Graphics getGraphics()

If this is a mutable image a graphics object allowing us to draw on it is returned.

Returns:

Graphics object allowing us to manipulate the content of a mutable image

getWidth

public int getWidth()

Returns the width of the image

Returns:

the width of the image

getHeight

public int getHeight()

Returns the height of the image

Returns:

the height of the image

drawImage

protected void drawImage(Graphics g,
                         java.lang.Object nativeGraphics,
                         int x,
                         int y)

Callback invoked internally by LWUIT to draw the image/frame onto the display. Image subclasses can override this method to perform drawing of custom image types.

Parameters:

g - the graphics object

nativeGraphics - the underlying native graphics which might be essential for some image types

x - the x coordinate

y - the y coordinate

drawImage

protected void drawImage(Graphics g,
                         java.lang.Object nativeGraphics,
                         int x,
                         int y,
                         int w,
                         int h)

Callback invoked internally by LWUIT to draw the image/frame onto the display. Image subclasses can override this method to perform drawing of custom image types.

Parameters:

g - the graphics object

nativeGraphics - the underlying native graphics which might be essential for some image types

x - the x coordinate

y - the y coordinate

w - the width to occupy

h - the height to occupy

toRGB

public void toRGB(RGBImage image,
                  int destX,
                  int destY,
                  int x,
                  int y,
                  int width,
                  int height)

Extracts data from this image into the given RGBImage

Parameters:

image - RGBImage that would receive pixel data

destX - x location within RGBImage into which the data will be written

destY - y location within RGBImage into which the data will be written

x - location within the source image

y - location within the source image

width - size of the image to extract from the source image

height - size of the image to extract from the source image

getRGB

public int[] getRGB()

Returns the content of this image as a newly created ARGB array.

Returns:

new array instance containing the ARGB data within this image

getRGBCached

public int[] getRGBCached()

Returns the content of this image as a newly created ARGB array or a cached instance if possible. Note that cached instances may be garbage collected.

Returns:

array instance containing the ARGB data within this image

scaledWidth

public Image scaledWidth(int width)

Scales the image to the given width while updating the height based on the aspect ratio of the width

Parameters:

width - the given new image width

Returns:

the newly created image

scaledHeight

public Image scaledHeight(int height)

Scales the image to the given height while updating the width based on the aspect ratio of the height

Parameters:

height - the given new image height

Returns:

the newly created image

scaledSmallerRatio

public Image scaledSmallerRatio(int width,
                                int height)

Scales the image while maintaining the aspect ratio to the smaller size image

Parameters:

width - the given new image width

height - the given new image height

Returns:

the newly created image

scaled

public Image scaled(int width,
                    int height)

Returns a scaled version of this image image using the given width and height, this is a fast algorithm that preserves translucent information. The method accepts -1 to preserve aspect ratio in the given axis.

Parameters:

width - width for the scaling

height - height of the scaled image

Returns:

new image instance scaled to the given height and width

getImage

public java.lang.Object getImage()

Returns the platform specific image implementation, warning the implementation class can change between revisions of LWUIT and platforms.

Returns:

platform specific native implementation for this image object

scale

public void scale(int width,
                  int height)

Deprecated. scale should return an image rather than modify the image in place use scaled(int, int) instead

Scale the image to the given width and height, this is a fast algorithm that preserves translucent information

Parameters:

width - width for the scaling

height - height of the scaled image

isAnimation

public boolean isAnimation()

Returns true if this is an animated image

Returns:

true if this image represents an animation

animate

public boolean animate()

isOpaque

public boolean isOpaque()

Indicates whether this image is opaque or not

Returns:

true if the image is completely opqaque which allows for some heavy optimizations