com.sun.lwuit
Class Image

java.lang.Object
  extended by com.sun.lwuit.Image
Direct Known Subclasses:
EncodedImage

public class Image
extends java.lang.Object

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

Author:
Chen Fishbein

Method Summary
 boolean animate()
           
static Image applyIconColor(Image source, int color)
          This method modifies the RGB values of the image and returns a modified image
 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.
 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.
 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
 

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

applyIconColor

public static Image applyIconColor(Image source,
                                   int color)
This method modifies the RGB values of the image and returns a modified image

Parameters:
source - -source image which has to be modified
color- - color value to be filled in the image
Returns:
new Image

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

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