totalcross.ui.image

Class Image4D

java.lang.Object

totalcross.ui.gfx.GfxSurface

totalcross.ui.image.Image4D

public class Image4D
extends GfxSurface

Image is a rectangular image.

You can draw into an image and copy an image to a surface using a Graphics object. Images are always 24bpp, and TotalCross supports PNG and JPEG formats at device, and PNG/JPEG/GIF/BMP at desktop (the last two are converted to png when deploying). The deployed png may contain transparency information which is correctly handled.

This is a code sample of how to run a multi-framed image. Note that it will work in the same way in desktop or in device.

   Image img = new Image("alligator.gif");
   add(new ImageControl(img),LEFT,TOP,FILL,PREFERRED);
   for (int i = 0; i < 100; i++)
   {
      repaintNow();
      Vm.sleep(200);
      img.nextFrame();
   }
 

Some transformation methods returns a new instance of this image and other apply to the current instance. To preserve an image with a single frame, use getFrameInstance(0). Note: TotalCross does not support grayscale PNG with alpha-channel. Convert the image to true-color with alpha-channel and it will work fine (the only backdraw is that the new image will be bigger). The hwScale methods should not be used in images that are shown using transition effects.

See Also:

Graphics

Field Summary

Fields

Modifier and Type	Field and Description
int	alphaMask A global alpha mask to be applied to the whole image when drawing it, ranging from 0 to 255.
java.lang.String	comment
static int	FADE_VALUE
protected int	height
double	hwScaleH Hardware accellerated scaling.
double	hwScaleW Hardware accellerated scaling.
int	lastAccess
static int	NO_TRANSPARENT_COLOR Dumb field to keep compilation compatibility with TC 1
protected int[]	pixelsOfAllFrames
int	surfaceType
int	transparentColor Dumb field to keep compilation compatibility with TC 1
boolean	useAlpha Dumb field to keep compilation compatibility with TC 1
protected int	width

Constructor Summary

Constructors

Constructor and Description
Image4D(byte[] fullDescription)
Image4D(byte[] fullDescription, int len)
Image4D(int width, int height)
Image4D(Stream s)
Image4D(java.lang.String path)

Method Summary

Modifier and Type	Method and Description
void	applyChanges()
void	applyColor(int color) Applies the given color r,g,b values to all pixels of this image, preserving the transparent color and alpha channel, if set.
void	applyColor2(int color) Applies the given color r,g,b values to all pixels of this image, preserving the transparent color and alpha channel, if set.
void	applyFade(int fadeValue) Applies the given fade value to r,g,b of this image while preserving the alpha value.
void	changeColors(int from, int to)
void	createJpg(Stream s, int quality)
void	createPng(Stream s)
boolean	equals(java.lang.Object o) Returns true if the given Image object has the same size and RGB pixels of this one.
void	finalize()
Image4D	getAlphaInstance(int delta)
Image4D	getClippedInstance(int x, int y, int w, int h) Returns a clipped image from the current position.
Image4D	getCopy() Gets a copy of this image; if the image is multi-framed, returns a copy of the first frame.
int	getCurrentFrame()
Image4D	getFadedInstance()
Image4D	getFadedInstance(int backColor)
int	getFrameCount()
Image4D	getFrameInstance(int frame) In a multi-frame image, returns a copy of the given frame.
Graphics	getGraphics()
int	getHeight()
Image4D	getHwScaledInstance(int width, int height)
static Image	getJpegBestFit(java.lang.String path, int targetWidth, int targetHeight)
static Image	getJpegScaled(java.lang.String path, int scaleNumerator, int scaleDenominator)
java.lang.String	getPath()
void	getPixelRow(byte[] fillIn, int y)
Image4D	getRotatedScaledInstance(int percScale, int angle, int fillColor)
Image4D	getScaledInstance(int newWidth, int newHeight)
Image4D	getSmoothScaledInstance(int newWidth, int newHeight)
Image4D	getSmoothScaledInstance(int newWidth, int newHeight, int backColor) Deprecated. TotalCross 2 no longer uses the backColor parameter.
Image4D	getTouchedUpInstance(byte brightness, byte contrast)
int	getWidth()
int	getX() Returns 0
int	getY() Returns 0
Image4D	hwScaledBy(double scaleX, double scaleY)
Image4D	hwScaledFixedAspectRatio(int newSize, boolean isHeight)
static boolean	isSupported(java.lang.String filename) Returns true if the given filename is a supported image: Png or Jpeg.
static Image	loadFrom(PDBFile cat, java.lang.String name)
void	lockChanges()
static void	nativeResizeJpeg(java.lang.String inputPath, java.lang.String outputPath, int maxPixelSize)
void	nextFrame()
void	prevFrame()
static void	resizeJpeg(java.lang.String inputPath, java.lang.String outputPath, int maxPixelSize)
void	saveTo(PDBFile cat, java.lang.String name)
Image4D	scaledBy(double scaleX, double scaleY)
void	setCurrentFrame(int nr)
void	setFrameCount(int n)
void	setHwScaleFixedAspectRatio(int newSize, boolean isHeight)
Image	setTransparentColor(int color)
Image4D	smoothScaledBy(double scaleX, double scaleY)
Image4D	smoothScaledBy(double scaleX, double scaleY, int backColor) Deprecated. TotalCross 2 no longer uses the backColor parameter.
Image4D	smoothScaledFixedAspectRatio(int newSize, boolean isHeight)
Image4D	smoothScaledFixedAspectRatio(int newSize, boolean isHeight, int backColor) Deprecated. TotalCross 2 no longer uses the backColor parameter.
Image4D	smoothScaledFromResolution(int originalRes) Returns a smooth scaled instance of this image with a fixed aspect ratio based on the given resolution (which is the resolution that you used to MAKE the image).
Image4D	smoothScaledFromResolution(int originalRes, int backColor) Deprecated. TotalCross 2 no longer uses the backColor parameter.
static void	writeFrameCount(java.lang.String filePath, int count) Utility method used to change the frame count of an image.

Methods inherited from class java.lang.Object

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

Field Detail

surfaceType

public int surfaceType

width

protected int width

height

protected int height

transparentColor

public int transparentColor

Dumb field to keep compilation compatibility with TC 1

useAlpha

public boolean useAlpha

Dumb field to keep compilation compatibility with TC 1

alphaMask

public int alphaMask

A global alpha mask to be applied to the whole image when drawing it, ranging from 0 to 255.

lastAccess

public int lastAccess

pixelsOfAllFrames

protected int[] pixelsOfAllFrames

comment

public java.lang.String comment

hwScaleW

public double hwScaleW

Hardware accellerated scaling. The original image is scaled up or down by the video card when its displayed. In high end devices, the quality is the same of the algorithm used in smooth instances. Works only if Settings.isOpenGL or on JavaSE. If you set this in non-opengl environments, nothing will happen; you should use the hwScaledBy, getHwScaledInstance and hwScaledFixedAspectRatio methods. To apply the changes, just call repaint().

Since:

TotalCross 2.0

See Also:

setHwScaleFixedAspectRatio(int,boolean), hwScaledBy(double, double), hwScaledFixedAspectRatio(int, boolean), getHwScaledInstance(int, int)

hwScaleH

public double hwScaleH

Hardware accellerated scaling. The original image is scaled up or down by the video card when its displayed. In high end devices, the quality is the same of the algorithm used in smooth instances. Works only if Settings.isOpenGL or on JavaSE. If you set this in non-opengl environments, nothing will happen; you should use the hwScaledBy, getHwScaledInstance and hwScaledFixedAspectRatio methods. To apply the changes, just call repaint().

Since:

TotalCross 2.0

See Also:

setHwScaleFixedAspectRatio(int,boolean), hwScaledBy(double, double), hwScaledFixedAspectRatio(int, boolean), getHwScaledInstance(int, int)

NO_TRANSPARENT_COLOR

public static final int NO_TRANSPARENT_COLOR

Dumb field to keep compilation compatibility with TC 1

See Also:

Constant Field Values

FADE_VALUE

public static int FADE_VALUE

Constructor Detail

Image4D

public Image4D(int width,
               int height)
        throws ImageException

Throws:

ImageException

Image4D

public Image4D(java.lang.String path)
        throws ImageException

Throws:

ImageException

Image4D

public Image4D(Stream s)
        throws ImageException,
               IOException

Throws:

ImageException

IOException

Image4D

public Image4D(byte[] fullDescription)
        throws ImageException

Throws:

ImageException

Image4D

public Image4D(byte[] fullDescription,
               int len)
        throws ImageException

Throws:

ImageException

Method Detail

getPath

public java.lang.String getPath()

setFrameCount

public void setFrameCount(int n)
                   throws java.lang.IllegalArgumentException,
                          java.lang.IllegalStateException,
                          ImageException

Throws:

java.lang.IllegalArgumentException

java.lang.IllegalStateException

ImageException

getFrameCount

public int getFrameCount()

setCurrentFrame

public void setCurrentFrame(int nr)

getCurrentFrame

public int getCurrentFrame()

nextFrame

public void nextFrame()

prevFrame

public void prevFrame()

getHeight

public int getHeight()

Specified by:

getHeight in class GfxSurface

getWidth

public int getWidth()

Specified by:

getWidth in class GfxSurface

getGraphics

public Graphics getGraphics()

applyChanges

public void applyChanges()

changeColors

public void changeColors(int from,
                         int to)

saveTo

public void saveTo(PDBFile cat,
                   java.lang.String name)
            throws ImageException,
                   IOException

Throws:

ImageException

IOException

loadFrom

public static Image loadFrom(PDBFile cat,
                             java.lang.String name)
                      throws IOException,
                             ImageException

Throws:

IOException

ImageException

createPng

public void createPng(Stream s)
               throws ImageException,
                      IOException

Throws:

ImageException

IOException

getPixelRow

public void getPixelRow(byte[] fillIn,
                        int y)

getFadedInstance

public Image4D getFadedInstance(int backColor)
                         throws ImageException

Throws:

ImageException

getFadedInstance

public Image4D getFadedInstance()
                         throws ImageException

Throws:

ImageException

getAlphaInstance

public Image4D getAlphaInstance(int delta)
                         throws ImageException

Throws:

ImageException

smoothScaledFixedAspectRatio

public Image4D smoothScaledFixedAspectRatio(int newSize,
                                            boolean isHeight)
                                     throws ImageException

Throws:

ImageException

getScaledInstance

public Image4D getScaledInstance(int newWidth,
                                 int newHeight)
                          throws ImageException

Throws:

ImageException

getSmoothScaledInstance

public Image4D getSmoothScaledInstance(int newWidth,
                                       int newHeight)
                                throws ImageException

Throws:

ImageException

getRotatedScaledInstance

public Image4D getRotatedScaledInstance(int percScale,
                                        int angle,
                                        int fillColor)
                                 throws ImageException

Throws:

ImageException

getTouchedUpInstance

public Image4D getTouchedUpInstance(byte brightness,
                                    byte contrast)
                             throws ImageException

Throws:

ImageException

scaledBy

public Image4D scaledBy(double scaleX,
                        double scaleY)
                 throws ImageException

Throws:

ImageException

smoothScaledBy

public Image4D smoothScaledBy(double scaleX,
                              double scaleY)
                       throws ImageException

Throws:

ImageException

setTransparentColor

public Image setTransparentColor(int color)

finalize

public void finalize()

Overrides:

finalize in class java.lang.Object

lockChanges

public void lockChanges()

createJpg

public void createJpg(Stream s,
                      int quality)
               throws ImageException,
                      IOException

Throws:

ImageException

IOException

setHwScaleFixedAspectRatio

public void setHwScaleFixedAspectRatio(int newSize,
                                       boolean isHeight)

hwScaledFixedAspectRatio

public Image4D hwScaledFixedAspectRatio(int newSize,
                                        boolean isHeight)
                                 throws ImageException

Throws:

ImageException

getHwScaledInstance

public Image4D getHwScaledInstance(int width,
                                   int height)
                            throws ImageException

Throws:

ImageException

hwScaledBy

public Image4D hwScaledBy(double scaleX,
                          double scaleY)
                   throws ImageException

Throws:

ImageException

getX

public int getX()

Returns 0

Specified by:

getX in class GfxSurface

getY

public int getY()

Returns 0

Specified by:

getY in class GfxSurface

isSupported

public static boolean isSupported(java.lang.String filename)

Returns true if the given filename is a supported image: Png or Jpeg. Gif and Bmp are supported on JavaSE only.

Since:

TotalCross 1.0

getFrameInstance

public Image4D getFrameInstance(int frame)
                         throws ImageException

In a multi-frame image, returns a copy of the given frame. In a single-frame image, gets a copy of the image.

Throws:

ImageException

Since:

TotalCross 1.12

applyColor

public final void applyColor(int color)

Applies the given color r,g,b values to all pixels of this image, preserving the transparent color and alpha channel, if set.

Parameters:

color - The color to be applied

Since:

TotalCross 1.12

smoothScaledFromResolution

public final Image4D smoothScaledFromResolution(int originalRes)
                                         throws ImageException

Returns a smooth scaled instance of this image with a fixed aspect ratio based on the given resolution (which is the resolution that you used to MAKE the image). The target size is computed as image_size*min(screen_size)/original_resolution

Parameters:

originalRes - The original resolution that the image was developed for. Its a good idea to create images for 320x320 and then scale them down.

Throws:

ImageException

Since:

TotalCross 1.12

equals

public boolean equals(java.lang.Object o)

Returns true if the given Image object has the same size and RGB pixels of this one. The alpha-channel is ignored.

Overrides:

equals in class java.lang.Object

Since:

TotalCross 1.3

applyColor2

public final void applyColor2(int color)

Applies the given color r,g,b values to all pixels of this image, preserving the transparent color and alpha channel, if set. This method is used to colorize the Android buttons. If the color's alpha is 0xAA, the image's alpha will also be changed. This is used by the Spinner.

Parameters:

color - The color to be applied

Since:

TotalCross 1.3

getSmoothScaledInstance

@Deprecated
public Image4D getSmoothScaledInstance(int newWidth,
                                                   int newHeight,
                                                   int backColor)
                                            throws ImageException

Deprecated. TotalCross 2 no longer uses the backColor parameter.

Throws:

ImageException

smoothScaledBy

@Deprecated
public Image4D smoothScaledBy(double scaleX,
                                          double scaleY,
                                          int backColor)
                                   throws ImageException

Deprecated. TotalCross 2 no longer uses the backColor parameter.

Throws:

ImageException

smoothScaledFixedAspectRatio

@Deprecated
public Image4D smoothScaledFixedAspectRatio(int newSize,
                                                        boolean isHeight,
                                                        int backColor)
                                                 throws ImageException

Deprecated. TotalCross 2 no longer uses the backColor parameter.

Throws:

ImageException

smoothScaledFromResolution

@Deprecated
public final Image4D smoothScaledFromResolution(int originalRes,
                                                            int backColor)
                                                     throws ImageException

Deprecated. TotalCross 2 no longer uses the backColor parameter.

Throws:

ImageException

applyFade

public void applyFade(int fadeValue)

Applies the given fade value to r,g,b of this image while preserving the alpha value.

writeFrameCount

public static void writeFrameCount(java.lang.String filePath,
                                   int count)

Utility method used to change the frame count of an image. This method exists in java only, not on device. The frame count of a TotalCross' Image is stored in a comment inside the PNG file. If you create a PNG with many frames and don't want to keep calling the setFrameCount manually, you can call this method like:

 Image.writeFrameCount("c:/project/src/images/people.png",2);
 

Be careful that this must be done once only; this method does not exist in the device and will abort the vm if you try to call it there!

Since:

TotalCross 3.1

getCopy

public Image4D getCopy()
                throws ImageException

Gets a copy of this image; if the image is multi-framed, returns a copy of the first frame.

Throws:

ImageException

Since:

TotalCross 3.1

getClippedInstance

public Image4D getClippedInstance(int x,
                                  int y,
                                  int w,
                                  int h)
                           throws ImageException

Returns a clipped image from the current position. Note that you must ensure that the values are correct or an exception will be thrown

Throws:

ImageException

resizeJpeg

public static void resizeJpeg(java.lang.String inputPath,
                              java.lang.String outputPath,
                              int maxPixelSize)

nativeResizeJpeg

public static void nativeResizeJpeg(java.lang.String inputPath,
                                    java.lang.String outputPath,
                                    int maxPixelSize)

getJpegBestFit

public static Image getJpegBestFit(java.lang.String path,
                                   int targetWidth,
                                   int targetHeight)
                            throws java.io.IOException,
                                   ImageException

Throws:

java.io.IOException

ImageException

getJpegScaled

public static Image getJpegScaled(java.lang.String path,
                                  int scaleNumerator,
                                  int scaleDenominator)
                           throws java.io.IOException,
                                  ImageException

Throws:

java.io.IOException

ImageException