Class RGBImage

java.lang.Object

com.codename1.ui.Image

com.codename1.ui.RGBImage

All Implemented Interfaces:

ActionSource

public class RGBImage
extends Image

An image that stores its data as an integer RGB array internally, this image cannot be manipulated via Graphics primitives however its array is accessible and modifiable programmatically. This is very useful for 2 distinct use cases.

The first use case allows us to manipulate images in a custom way while still preserving alpha information where applicable.

The second use case allows us to store images in the Java heap which is useful for some constrained devices. In small devices images are often stored in a separate "heap" which runs out eventually, this allows us to place the image in the Java heap which is potentially more wasteful but might sometimes be more abundant.

Note that unless specified otherwise most methods inherited from Image will fail when invoked on this subclass often with a NullPointerException. This image can be drawn on graphics as usual

Constructor Summary

Constructors

Constructor	Description
RGBImage(int[] rgb, int width, int height)	Creates an RGB image from scratch the array isn't copied and can be saved and manipulated
RGBImage(Image img)	Converts an image to an RGB image after which the original image can be GC'd

Method Summary

Modifier and Type	Method	Description
protected void	drawImage(Graphics g, Object nativeGraphics, int x, int y)	Callback invoked internally by Codename One to draw the image/frame onto the display.
Graphics	getGraphics()	This method is unsupported in this image type
int	getHeight()	Returns the height of the image
int[]	getRGB()	Returns a mutable array that can be used to change the appearance of the image arranged as AARRGGBB.
int	getWidth()	Returns the width of the image
boolean	isOpaque()	Indicates if an image should be treated as opaque, this can improve support for fast drawing of RGB images without alpha support.
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.
boolean	requiresDrawImage()	New label optimizations don't invoke drawImage and instead just pass the native image directly to the underlying renderer.
Image	rotate(int degrees)	Unsupported in the current version, this method will be implemented in a future release
void	scale(int width, int height)	Scale the image to the given width and height, this is a fast algorithm that preserves translucent information
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.
void	setOpaque(boolean opaque)	Sets whether this image should be treated as fully opaque.
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.

Methods inherited from class Image

addActionListener, animate, applyMask, applyMask, applyMaskAutoScale, asyncLock, createImage, createImage, createImage, createImage, createImage, createImage, createImage, createIndexed, createMask, createSVG, dispose, drawImage, exifRotation, exifRotation, exifRotation, fill, fireChangedEvent, flipHorizontally, flipVertically, getExifOrientationTag, getExifOrientationTag, getImage, getImageName, getRGB, getRGBCached, getSVGDocument, isAlphaMutableImageSupported, isAnimation, isJPEG, isLocked, isPNG, isSVG, isSVGSupported, lock, mirror, modifyAlpha, modifyAlphaWithTranslucency, removeActionListener, rotate180Degrees, rotate270Degrees, rotate90Degrees, scaledHeight, scaledLargerRatio, scaledSmallerRatio, scaledWidth, setImageName, toRGB, unlock

Modifier and Type	Method	Description
void	addActionListener(ActionListener l)	Adds ActionListener to receive action events form this source.
boolean	animate()	Advances this image's animation state, if it is animated.
Image	applyMask(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(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.
Image	applyMaskAutoScale(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.
void	asyncLock(Image internal)	Async lock is the equivalent of a lock operation, however it uses the given image as the hard cache and performs the actual image loading asynchronously.
static Image	createImage(byte[] bytes, int offset, int len)	creates an image from a given byte array data
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 white opaque 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(InputStream stream)	creates an image from an InputStream
static Image	createImage(Object nativeImage)	creates an image from the given native image (e.g. MIDP image object)
static Image	createImage(String path)	Creates an image from a 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
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(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.
void	dispose()	DO NOT CALL THIS METHOD UNLESS YOU KNOW WHAT YOU ARE DOING, IT WILL CAUSE PLATFORM SPECIFC CRASHES OTHERWISE! Images dispose automatically for most cases except for very rare special cases.
protected void	drawImage(Graphics g, Object nativeGraphics, int x, int y, int w, int h)	Callback invoked internally by Codename One to draw the image/frame onto the display.
static Image	exifRotation(String capturedImage)	The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.
static Image	exifRotation(String capturedImage, String rotatedImage)	The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.
static Image	exifRotation(String capturedImage, String rotatedImage, int maxSize)	The main use case of this method is the automatic rotation and flipping of an image returned from the camera or from the gallery, preserving the original format (jpeg or png); it detects the Exif Orientation Tag, if available (all the possible Exif Orientation Tag values are supported); transparency is not preserved.
Image	fill(int width, int height)	Resizes/crops the image so that its center fills the given dimensions.
void	fireChangedEvent()
Image	flipHorizontally(boolean maintainOpacity)	Flips this image on the horizontal axis
Image	flipVertically(boolean maintainOpacity)	Flips this image on the vertical axis
static int	getExifOrientationTag(InputStream is)	Gets the EXIF orientation tag of an image, if it's available.
static int	getExifOrientationTag(String path)	Gets the EXIF orientation tag of an image if it's available.
Object	getImage()	Returns the platform specific image implementation, warning the implementation class can change between revisions of Codename One and platforms.
String	getImageName()	The name of the image is set for some images mostly to ease the debugging of Codename One application
void	getRGB(int[] rgbData)	Returns the content of this image in the supplied ARGB array.
int[]	getRGBCached()	Returns the content of this image as a newly created ARGB array or a cached instance if possible.
Object	getSVGDocument()	Returns a platform specific DOM object that can be manipulated by the user to change the SVG Image
static boolean	isAlphaMutableImageSupported()	Returns true if mutable images support alpha transparency
boolean	isAnimation()	Returns true if this is an animated image
static boolean	isJPEG(InputStream inputStream)	Very fast method to detect if the given inputStream is a JPEG image (according to its guessed mime type)
boolean	isLocked()	Returns true if the image is locked
static boolean	isPNG(InputStream inputStream)	Very fast method to detect if the given inputStream is a PNG image (according to its guessed mime type)
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	mirror()	Creates a mirror image for the given image which is useful for some RTL scenarios.
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.
void	removeActionListener(ActionListener l)	Removes ActionListener so that it will no longer receive events from this source.
Image	rotate180Degrees(boolean maintainOpacity)	Rotates the image by 180 degrees
Image	rotate270Degrees(boolean maintainOpacity)	Rotates the image by 270 degrees while changing the ratio of the picture
Image	rotate90Degrees(boolean maintainOpacity)	Rotates this image by 90 degrees while changing the ratio of the picture
Image	scaledHeight(int height)	Scales the image to the given height while updating the width based on the aspect ratio of the height
Image	scaledLargerRatio(int width, int height)	Scales the image while maintaining the aspect ratio to the larger size image
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
void	setImageName(String imageName)	The name of the image is set for some images mostly to ease the debugging of Codename One application
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 Object

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

Modifier and Type	Method	Description
protected Object	clone()
boolean	equals(Object obj)	Indicates whether some other object is "equal to" this one.
final Class	getClass()	Returns the runtime class of an object.
int	hashCode()	Returns a hash code value for the object.
final void	notify()	Wakes up a single thread that is waiting on this object's monitor.
final void	notifyAll()	Wakes up all threads that are waiting on this object's monitor.
String	toString()	Returns a string representation of the object.
final void	wait()	Causes current thread to wait until another thread invokes the method or the method for this object.
final void	wait(long timeout)	Causes current thread to wait until either another thread invokes the method or the method for this object, or a specified amount of time has elapsed.
final void	wait(long timeout, int nanos)	Causes current thread to wait until another thread invokes the method or the method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

Constructor Details

RGBImage

public RGBImage(Image img)

Converts an image to an RGB image after which the original image can be GC'd

Parameters

• img: the image to convert to an RGB image

RGBImage

public RGBImage(int[] rgb,
 int width,
 int height)

Creates an RGB image from scratch the array isn't copied and can be saved and manipulated

Parameters

• rgb: AARRGGBB array

• width: width of image

• height: height of image

Method Details

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

Overrides:

subImage in class 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

Overrides:

scaled in class Image

scale

public void scale(int width,
 int height)

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

Deprecated

Overrides:

scale in class Image

rotate

public Image rotate(int degrees)

Unsupported in the current version, this method will be implemented in a future release

Overrides:

rotate in class Image

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

Overrides:

modifyAlpha in class Image

Returns:

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

getGraphics

public Graphics getGraphics()

This method is unsupported in this image type

Overrides:

getGraphics in class Image

getRGB

public int[] getRGB()

Returns a mutable array that can be used to change the appearance of the image arranged as AARRGGBB.

Returns

ARGB int array

Overrides:

getRGB in class Image

drawImage

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

Callback invoked internally by Codename One 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

Overrides:

drawImage in class Image

isOpaque

public boolean isOpaque()

Indicates if an image should be treated as opaque, this can improve support for fast drawing of RGB images without alpha support.

Overrides:

isOpaque in class Image

setOpaque

public void setOpaque(boolean opaque)

Sets whether this image should be treated as fully opaque.

Parameters

• opaque: true to treat this image as opaque.

getWidth

public int getWidth()

Returns the width of the image

Returns

the width of the image

Overrides:

getWidth in class Image

getHeight

public int getHeight()

Returns the height of the image

Returns

the height of the image

Overrides:

getHeight in class Image

requiresDrawImage

public boolean requiresDrawImage()

New label optimizations don't invoke drawImage and instead just pass the native image directly to the underlying renderer. This is problematic for some image types specifically timeline & FontImage and this method allows these classes to indicate that they need that legacy behavior of calling drawImage.

Returns

true if a drawImage call is a required

Overrides:

requiresDrawImage in class Image