Image

Class Overview

Image represents an image data.

getImage(int)

The Image class handles all the resources transformed into Images that will be used to display graphic elements on screen.

Here again, the Images are natively transformed to be compliant with OpenGLES i.e. they are transformed into textures respecting OpenGLES constraints.

First of all, there is one thing to understand clearly. To create OpenGLES textures, it is needed to use a temporary standard Android Bitmap from which the texture will be created. This means that every Image creation will use temporarily some standard heap bitmap memory.

This memory allocation can be temporary only if the Image comes from a resource loaded from the apk. If the Image is created with methods like createImage(w, h) or any other Image creator building the Image from something else than a resource, then the temporary bitmap will have to stay in memory until the Image is destroyed. The explanation is simple. With the Android technology, in the event of a suspend/ resume (i.e. incoming call or equivalent), it is needed to reload all the textures contained in the OpenGLES memory. OpenGLES might have trashed them during the Suspend/ Resume. Therefore, in order to reload those textures, there must be a way to reload them on the fly. For Images coming from resources, we keep the resource name within the Image object in order to reload it on the fly when the Suspend/Resume is over. For Images coming from other objects, we do not have any other choice than to keep the original bitmap used to create the Texture in memory to be able to re-upload them into OpenGLES memory.

The temporary memory is taken from the normal Android Bitmap heap memory. Be careful that this memory is limited (and device dependent). This has 2 implications:

• 1) Texture created with other methods than from a resource from the APK will have a quick tendency to overflow the memory so they must be minimized.
• 2) The upload into OpenGLES process prevents from uploading the textures outside of the repaint operation. So if you create some Images from resources outside of the repaint of the game, it is a good practice to divide the loading over multiple frames in order not to create a memory peaks and destabilize your code.

Although we support any kind of Image size, OpenGLES is designed to support optimally Images which will be power2 width and height. If you try to load an Image sized 33x65 the Image will be automatically padded to the upper-closest power2 size i.e. 64x128. This mechanism is transparent for the programmer but still has to be understood has Images will use more memory than they should have.

With this new Image class, it is important to destroy the images explicitly and not set them simply to null. It is needed to explicitly call the destroy method to free the OpenGLES memory used by the Image.

The best practice in terms of performances for OpenGLES is to try to avoid texture swapping. Texture swapping is when you change the current texture being drawn from one texture to another. As a consequence, if possible, it is a good idea to regroup multiple images into single bigger one (typically creating an image atlas containing a large number of small images and use the drawRegion method from the Graphics class to display them. The best is to create large Images sized 1024x1024 containing a large number of small pictures inside and sort them so they are grouped by drawing calls.

Example:

If your code displays:

Background 2
Background 1
Ground
Foreground
Hero
Enemies
Shots
HUD


Then try to regroup your images into various 1024x1024 images but minimizing the texture swapping by grouping them according to the order of the drawing calls.

Summary

Public Methods
static Image	createImage(InputStream stream) Creates an image based on an InputStream.
int	getHeight() Returns the height of the image
int	getHeightDP() Returns the image height in dp.
int	getWidth() Returns the width of the image
int	getWidthDP() Returns the image width in dp.

[Expand] Inherited Methods

From class java.lang.Object 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(long timeout, int nanos) Causes current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long timeout) Causes current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed. final void wait() Causes current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object.