EncodedImage (codenameone-core 7.0.45 API)

java.lang.Object
- com.codename1.ui.Image
- - com.codename1.ui.EncodedImage

All Implemented Interfaces:

ActionSource

Direct Known Subclasses:

ComponentImage.EncodedWrapper, FileEncodedImage, FileEncodedImageAsync, ReplaceableImage, StorageImage, StorageImageAsync, URLImage
```
public class EncodedImage
extends Image
```
EncodedImage is the workhorse of Codename One. Images returned from resource files are EncodedImage and many API's expect it.

EncodedImage is effectively a an image that is "hidden" and extracted as needed to remove the memory overhead associated with loaded image. When creating an EncodedImage only the PNG (or JPEG etc.) is loaded to an array in RAM. Normally such images are very small (relatively) so they can be kept in memory without much overhead.

When image information is needed (pixels) the image is decoded into RAM and kept in a weak/sort reference (see Display.createSoftWeakRef(java.lang.Object)). This allows the image to be cached for performance and allows the garbage collector to reclaim it when the memory becomes scarce.

Since the fully decoded image can be pretty big (width X height X 4) the ability to store just the encoded image can be pretty stark. E.g. A standard 50x100 image will take up 20,000 bytes of RAM for a standard image but an EncodedImage can reduce that to 1kb-2kb of RAM.

When drawing an EncodedImage it checks the weak reference cache and if the image is cached then it is shown otherwise the image is loaded the encoded image cache it then drawn.

EncodedImage is not final and can be derived to produce complex image fetching strategies e.g. the URLImage class that can dynamically download its content from the web.

EncodedImage can be instantiated via the create methods in the class. Pretty much any image can be converted into an `EncodedImage` via the createFromImage(com.codename1.ui.Image, boolean) method.

EncodedImage Locking

Naturally loading the image is more expensive so we want the images that are on the current form to remain in cache (otherwise GC will thrash a lot). That's where lock() kicks in, when lock() is active we keep a hard reference to the actual native image so it won't get GC'd. This significantly improves performance!

Internally this is invoked automatically for background images, icons etc. which results in a huge performance boost. This makes sense since these images are currently showing and they will be in RAM anyway. However, if you use a complex renderer or custom drawing UI you should lock() your images where possible!

To verify that locking might be a problem you can launch the performance monitor tool (accessible from the simulator menu), if you get log messages that indicate that an unlocked image was drawn you might have a problem.

Author:

Shai Almog

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`EncodedImage(int width, int height)` Allows subclasses to create more advanced variations of this class that lazily store the data in an arbitrary location.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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 EncodedImage`	`create(byte[] data)` Creates an image from the given byte array
`static EncodedImage`	`create(byte[] data, int width, int height, boolean opacity)` Creates an image from the given byte array with the variables set appropriately.
`static EncodedImage`	`create(InputStream i)` Creates an image from the input stream
`static EncodedImage`	`create(InputStream i, int size)` Creates an image from the input stream, this version of the method is somewhat faster than the version that doesn't accept size
`static EncodedImage`	`create(String i)` Creates an image from the input stream
`static EncodedImage`	`createFromImage(Image i, boolean jpeg)` Converts an image to encoded image
`static Image`	`createFromRGB(int[] argb, int width, int height, boolean jpeg)` Tries to create an encoded image from RGB which is more efficient, however if this fails it falls back to regular RGB image.
`static EncodedImage`	`createMulti(int[] dpis, byte[][] data)` Deprecated. this method is meant for internal use only, it would be very expensive to use this method for real applications. Its here for simulators and development purposes where screen DPI/resolution can vary significantly in runtime (something that just doesn't happen on devices).
`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.
`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.
`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
`Object`	`getImage()` Returns the platform specific image implementation, warning the implementation class can change between revisions of Codename One and platforms.
`byte[]`	`getImageData()` Returns the byte array data backing the image allowing the image to be stored and discarded completely from RAM.
`protected Image`	`getInternal()` Returns the actual image represented by the encoded image, this image will be cached in a weak/soft reference internally.
`int`	`getWidth()` Returns the width of the image
`boolean`	`isAnimation()` Returns true if this is an animated image
`boolean`	`isLocked()` Returns true if the image is locked
`boolean`	`isOpaque()` Indicates whether this image is opaque or not
`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.
`protected void`	`resetCache()` A subclass might choose to load asynchroniously and reset the cache when the image is ready.
`Image`	`rotate(int degrees)` Returns an instance of this image rotated by the given number of degrees.
`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.
`EncodedImage`	`scaledEncoded(int width, int height)` Performs scaling using ImageIO to generate an encoded Image
`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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - EncodedImage
```
protected EncodedImage(int width,
                       int height)
```
    Allows subclasses to create more advanced variations of this class that lazily store the data in an arbitrary location.
    
    Parameters:
    
    width - -1 if unknown ideally the width/height should be known in advance
    
    height - -1 if unknown ideally the width/height should be known in advance
- Method Detail
  - resetCache
```
protected void resetCache()
```
    A subclass might choose to load asynchroniously and reset the cache when the image is ready.
  - createMulti
```
public static EncodedImage createMulti(int[] dpis,
                                       byte[][] data)
```
    Deprecated. this method is meant for internal use only, it would be very expensive to use this method for real applications. Its here for simulators and development purposes where screen DPI/resolution can vary significantly in runtime (something that just doesn't happen on devices).
    
    Creates an encoded image that acts as a multi-image, DO NOT USE THIS METHOD. Its for internal use to improve the user experience of the simulator
    
    Parameters:
    
    dpis - device DPI's
    
    data - the data matching each multi-image DPI
    
    Returns:
    
    an encoded image that acts as a multi-image in runtime
  - createFromImage
```
public static EncodedImage createFromImage(Image i,
                                           boolean jpeg)
```
    Converts an image to encoded image
    
    Parameters:
    
    i - image
    
    jpeg - true to try and set jpeg, will do a best effort but this isn't guaranteed
    
    Returns:
    
    an encoded image or null
  - createFromRGB
```
public static Image createFromRGB(int[] argb,
                                  int width,
                                  int height,
                                  boolean jpeg)
```
    Tries to create an encoded image from RGB which is more efficient, however if this fails it falls back to regular RGB image. This method is slower than creating an RGB image (not to be confused with the RGBImage class which is something ENTIRELY different!).
    
    Parameters:
    
    argb - an argb array
    
    width - the width for the image
    
    height - the height for the image
    
    jpeg - uses jpeg format internally which is opaque and could be faster/smaller
    
    Returns:
    
    an image which we hope is an encoded image
  - getImageData
```
public byte[] getImageData()
```
    Returns the byte array data backing the image allowing the image to be stored and discarded completely from RAM.
    
    Returns:
    
    byte array used to create the image, e.g. encoded PNG, JPEG etc.
  - create
```
public static EncodedImage create(byte[] data)
```
    Creates an image from the given byte array
    
    Parameters:
    
    data - the data of the image
    
    Returns:
    
    newly created encoded image
  - create
```
public static EncodedImage create(byte[] data,
                                  int width,
                                  int height,
                                  boolean opacity)
```
    Creates an image from the given byte array with the variables set appropriately. This saves LWUIT allot of resources since it doesn't need to actually traverse the pixels of an image to find out details about it.
    
    Parameters:
    
    data - the data of the image
    
    width - the width of the image
    
    height - the height of the image
    
    opacity - true for an opaque image
    
    Returns:
    
    newly created encoded image
  - getImage
```
public Object getImage()
```
    Returns the platform specific image implementation, warning the implementation class can change between revisions of Codename One and platforms.
    
    Overrides:
    
    getImage in class Image
    
    Returns:
    
    platform specific native implementation for this image object
  - create
```
public static EncodedImage create(InputStream i)
                           throws IOException
```
    Creates an image from the input stream
    
    Parameters:
    
    i - the input stream
    
    Returns:
    
    newly created encoded image
    
    Throws:
    
    IOException - if thrown by the input stream
  - create
```
public static EncodedImage create(InputStream i,
                                  int size)
                           throws IOException
```
    Creates an image from the input stream, this version of the method is somewhat faster than the version that doesn't accept size
    
    Parameters:
    
    i - the input stream
    
    size - the size of the stream
    
    Returns:
    
    newly created encoded image
    
    Throws:
    
    IOException - if thrown by the input stream
  - getInternal
```
protected Image getInternal()
```
    Returns the actual image represented by the encoded image, this image will be cached in a weak/soft reference internally. This method is useful to detect when the system actually created an image instance. You shouldn't invoke this method manually!
    
    Returns:
    
    drawable image instance
  - isLocked
```
public boolean isLocked()
```
    Returns true if the image is locked
    
    Overrides:
    
    isLocked in class Image
    
    Returns:
    
    false by default
  - asyncLock
```
public 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. On completion this method will invoke repaint on the main form if applicable.
    
    Overrides:
    
    asyncLock in class Image
    
    Parameters:
    
    internal - the image to show while the actual image loads.
  - 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.
    
    Overrides:
    
    lock in class Image
  - unlock
```
public void unlock()
```
    This callback indicates that a component pointing at this image is now deinitilized This method may be invoked multiple times.
    
    Overrides:
    
    unlock in class Image
  - create
```
public static EncodedImage create(String i)
                           throws IOException
```
    Creates an image from the input stream
    
    Parameters:
    
    i - the resource
    
    Returns:
    
    newly created encoded image
    
    Throws:
    
    IOException - if thrown by the input stream
  - 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.
    
    Overrides:
    
    subImage in class Image
    
    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.
    
    Overrides:
    
    rotate in class Image
    
    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
  - 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.
    
    Overrides:
    
    modifyAlpha in class Image
    
    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.
    
    Overrides:
    
    modifyAlpha in class Image
    
    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
  - getGraphics
```
public Graphics getGraphics()
```
    If this is a mutable image a graphics object allowing us to draw on it is returned.
    
    Overrides:
    
    getGraphics in class Image
    
    Returns:
    
    Graphics object allowing us to manipulate the content of a mutable image
  - getWidth
```
public int getWidth()
```
    Returns the width of the image
    
    Overrides:
    
    getWidth in class Image
    
    Returns:
    
    the width of the image
  - getHeight
```
public int getHeight()
```
    Returns the height of the image
    
    Overrides:
    
    getHeight in class Image
    
    Returns:
    
    the height of the 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.
    
    Overrides:
    
    drawImage in class Image
    
    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,
                         Object nativeGraphics,
                         int x,
                         int y,
                         int w,
                         int h)
```
    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.
    
    Overrides:
    
    drawImage in class Image
    
    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
    
    Overrides:
    
    toRGB in class Image
    
    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
  - 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
    
    Overrides:
    
    scaledWidth in class Image
    
    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
    
    Overrides:
    
    scaledHeight in class Image
    
    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
    
    Overrides:
    
    scaledSmallerRatio in class Image
    
    Parameters:
    
    width - the given new image width
    
    height - the given new image height
    
    Returns:
    
    the newly created image
  - scaledEncoded
```
public EncodedImage scaledEncoded(int width,
                                  int height)
```
    Performs scaling using ImageIO to generate an encoded Image
    
    Parameters:
    
    width - the width of the image, -1 to scale based on height and preserve aspect ratio
    
    height - the height of the image, -1 to scale based on width and preserve aspect ratio
    
    Returns:
    
    new encoded 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.
    
    Overrides:
    
    scaled in class Image
    
    Parameters:
    
    width - width for the scaling
    
    height - height of the scaled image
    
    Returns:
    
    new image instance scaled to the given height and width
  - 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
    
    Overrides:
    
    scale in class Image
    
    Parameters:
    
    width - width for the scaling
    
    height - height of the scaled image
  - isAnimation
```
public boolean isAnimation()
```
    Returns true if this is an animated image
    
    Overrides:
    
    isAnimation in class Image
    
    Returns:
    
    true if this image represents an animation
  - isOpaque
```
public boolean isOpaque()
```
    Indicates whether this image is opaque or not
    
    Overrides:
    
    isOpaque in class Image
    
    Returns:
    
    true if the image is completely opqaque which allows for some heavy optimizations

Class EncodedImage

EncodedImage Locking

Constructor Summary

Method Summary

Methods inherited from class com.codename1.ui.Image

Methods inherited from class java.lang.Object

Constructor Detail

EncodedImage

Method Detail

resetCache

createMulti

createFromImage

createFromRGB

getImageData

create

create

getImage

create

create

getInternal

isLocked

asyncLock

lock

unlock

create

subImage

rotate

modifyAlpha

modifyAlpha

getGraphics

getWidth

getHeight

drawImage

drawImage

toRGB

scaledWidth

scaledHeight

scaledSmallerRatio

scaledEncoded

scaled

scale

isAnimation

isOpaque