org.jrabbit.base.graphics.image
Class Image

java.lang.Object
  extended by org.jrabbit.base.graphics.image.Image
All Implemented Interfaces:
Renderable, Createable, DataController, Destroyable, Referenced

public class Image
extends java.lang.Object
implements Referenced, DataController, Renderable

An image is just that - image data on the graphics card, with methods to simplify rendering and interacting with it. It's assumed that most images will be loaded from file (as indicated by a supplied String). However, it is possible to create an image via different methods, including loading a texture externally and then supplying it in the constructor (example use of this - loading an image via URL, from the web). Images automatically attempt to accelerate their rendering with Display Lists. This gives a (small) gain in performance.

Author:
Chris Molini

Nested Class Summary
protected  class Image.SubImage
          A simple internal class that contains data for drawing a subsection of an image.
 
Field Summary
protected  boolean alpha
          Whether or not this image has an alpha channel.
protected  int dLID
          The ID of the displayList used by this image.
protected  int height
          The height of the image, in pixels.
protected  float heightRatio
          The ratio of the image height to the texture height.
protected  int numSubImages
          The number of sub-images compiled and ready at any given time.
static int PIXELATE
          The texture filter value that results in pixelated textures.
protected  java.lang.String reference
          The reference that identifies this image.
protected  boolean smooth
          Whether or not this image has a smoothing filter applied when it is scaled in size.
static int SMOOTH
          The texture filter value that results in smooth textures.
protected  Image.SubImage[] subImages
          An image can have individual sections of it rendered.
protected  int textureHeight
          The height of the texture that the image is placed upon.
protected  int textureID
          The texture ID on the GPU.
protected  int textureWidth
          Since textures are PoT, and source images can have any dimension, the texture may have different dimensions than the image upon it.
protected  int width
          The width of the image, in pixels.
protected  float widthRatio
          The ratio of the image width to the texture width.
 
Constructor Summary
Image(Loader loader)
          Creates an Image from the indicated loader.
Image(java.lang.String reference)
          Creates an Image from a single reference.
Image(java.lang.String reference, int width, int height)
          Creates a blank Image with the indicated dimensions.
Image(java.lang.String reference, int textureID, int width, int height, int textureWidth, int textureHeight, boolean alphaChannel)
          Creates an Image with the supplied reference and the indicated values.
Image(java.lang.String reference, Loader loader)
          Creates an Image from the indicated loader.
Image(java.lang.String reference, java.lang.String filepath)
          Creates an Image from the indicated reference and filepath.
Image(java.lang.String reference, org.newdawn.slick.opengl.Texture texture)
          Creates an Image with the indicated reference and the already created Texture data.
Image(java.lang.String reference, java.net.URL url)
          Creates an Image from the indicated reference and URL.
Image(java.net.URL url)
          Creates an Image from a URL.
 
Method Summary
 void bind()
          Calls OpenGL so that operations that involve textures use the texture referenced by this Image.
private  void compileDisplayList()
          Creates the display list used to accelerate rendering.
 void create()
          Compiles the display list.
 byte[] data()
          Accesses the texture data of the image, in bytes.
 void destroy()
          Destroys all graphics data associated with this texture.
 boolean destroySubImage(int id)
          Destroys the sub-image at the indicated position in the internal array.
 boolean hasAlpha()
          Learns if the texture has alpha.
 int height()
          Access the dimensions of the image.
 float heightRatio()
          Accesses the dimensions of the image.
 int ID()
          Accesses the texture ID.
static org.newdawn.slick.opengl.Texture load(Loader loader)
          Loads a texture with the indicated Loader.
 java.lang.String reference()
          Accesses the Image's reference.
 void render()
          Draws the image, using a Display List for acceleration.
 void renderNoAcceleration()
          Renders the image without using a Display List, manually passing in all required vertex and texture coordinate data.
 void renderSubImage(float[] coordinates)
          Renders a sub-Image without any acceleration, manually passing in the data for each vertice and texture coordinate.
 void renderSubImage(int id)
          Renders the indicated, pre-compiled sub image.
 void renderSubImageNoAcceleration(int id)
          Renders the indicated, pre-compiled sub image.
 void setDimensions(int width, int height)
          Redefines the dimensions this image uses and refreshes the display list.
 void setHeight(int height)
          Redefines the height this image uses and refreshes the display list.
 void setWidth(int width)
          Redefines the width this image uses and refreshes the display list.
 void smooth(boolean smooth)
          Defines the appearance of the Image when scaled.
 boolean smoothing()
          Learns which scaling filter the Image is using.
 int subImage(float[] coordinates)
          Returns the ID of an accelerated sub-image with the indicated texture coordinates.
 int subImage(float x, float y, float width, float height)
          Returns the ID of an accelerated sub-image with the indicated pixel values.
 float[] subImageCoords(float x, float y, float width, float height)
          Calculates a series of sub-image coordinates from the indicated pixel values.
 int textureHeight()
          Accesses the dimensions of the texture used by this image.
 int textureWidth()
          Accesses the dimensions of the texture used by this image.
 boolean valid()
          Checks whether the image is valid.
 int width()
          Access the dimensions of the image.
 float widthRatio()
          Accesses the dimensions of the image.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SMOOTH

public static final int SMOOTH
The texture filter value that results in smooth textures.

See Also:
Constant Field Values

PIXELATE

public static final int PIXELATE
The texture filter value that results in pixelated textures.

See Also:
Constant Field Values

reference

protected java.lang.String reference
The reference that identifies this image.


smooth

protected boolean smooth
Whether or not this image has a smoothing filter applied when it is scaled in size.


textureID

protected int textureID
The texture ID on the GPU.


width

protected int width
The width of the image, in pixels.


height

protected int height
The height of the image, in pixels.


textureWidth

protected int textureWidth
Since textures are PoT, and source images can have any dimension, the texture may have different dimensions than the image upon it. This indicates the width of the texture itself.


textureHeight

protected int textureHeight
The height of the texture that the image is placed upon.


widthRatio

protected float widthRatio
The ratio of the image width to the texture width. Used for texture coordinates.


heightRatio

protected float heightRatio
The ratio of the image height to the texture height. Used for texture coordinates.


dLID

protected int dLID
The ID of the displayList used by this image.


alpha

protected boolean alpha
Whether or not this image has an alpha channel.


subImages

protected Image.SubImage[] subImages
An image can have individual sections of it rendered. These sections are considered "sub-images." This list dynamically expands as new sections of the image are required for rendering.


numSubImages

protected int numSubImages
The number of sub-images compiled and ready at any given time.

Constructor Detail

Image

public Image(java.lang.String reference)
Creates an Image from a single reference. This reference will be used to load the image data from the system.

Parameters:
reference - The filepath that will both identify the image and be used to load the required texture data.

Image

public Image(java.lang.String reference,
             java.lang.String filepath)
Creates an Image from the indicated reference and filepath.

Parameters:
reference - The String that will identify the image in the Cache.
filepath - The filepath used to load image data from the system.

Image

public Image(java.net.URL url)
Creates an Image from a URL. This attempts to load the image via URL; and so if the image is on the web, a connection will be formed and it will attempt to be loaded.

Parameters:
url - The web address of the image.

Image

public Image(java.lang.String reference,
             java.net.URL url)
Creates an Image from the indicated reference and URL. The image can be on the web.

Parameters:
reference - The String that will identify the image in the Cache.
url - The web address of the source image.

Image

public Image(Loader loader)
Creates an Image from the indicated loader.

Parameters:
loader - The object that provides access to the source image.

Image

public Image(java.lang.String reference,
             Loader loader)
Creates an Image from the indicated loader.

Parameters:
reference - The String that will identify the image in the Cache.
loader - The object that provides access to the source image.

Image

public Image(java.lang.String reference,
             int width,
             int height)
Creates a blank Image with the indicated dimensions. NOTE: Again, textures must be PoT, so supplying careless dimensions will result in a waste of graphical memory.

Parameters:
reference - The String that will identify the image in the Cache.
width - The width of the image.
height - The height of the image.

Image

public Image(java.lang.String reference,
             org.newdawn.slick.opengl.Texture texture)
Creates an Image with the indicated reference and the already created Texture data.

Parameters:
reference - The String that will identify the image in the Cache.
texture - The texture object representing data on the graphics card.

Image

public Image(java.lang.String reference,
             int textureID,
             int width,
             int height,
             int textureWidth,
             int textureHeight,
             boolean alphaChannel)
Creates an Image with the supplied reference and the indicated values.

Parameters:
reference - The String that will identify the image in the Cache.
textureID - The ID of the texture on the graphics card.
width - The width of the image to render.
height - The height of the image to render.
textureWidth - The width of the texture that the image is on.
textureHeight - The height of the texture that the image is on.
alphaChannel - Whether or not the texture has an alpha channel.
Method Detail

load

public static final org.newdawn.slick.opengl.Texture load(Loader loader)
Loads a texture with the indicated Loader.

Parameters:
loader - A pre-constructed loader that points to the image to load.
Returns:
The texture loaded from the specified image.

compileDisplayList

private void compileDisplayList()
Creates the display list used to accelerate rendering. If a display list was already active (i.e., the display list ID was not 0) then it is destroyed before a new one is made.


create

public void create()
Compiles the display list. Since image creation already requires a valid texture, we really don't have very much left to do.

Specified by:
create in interface Createable

destroy

public void destroy()
Destroys all graphics data associated with this texture. Nothing is recoverable after this method.

Specified by:
destroy in interface Destroyable

valid

public boolean valid()
Checks whether the image is valid.

Specified by:
valid in interface DataController
Returns:
Whether or not the Image is "intact" and can still be used for rendering.

reference

public java.lang.String reference()
Accesses the Image's reference.

Specified by:
reference in interface Referenced
Returns:
The identifier for this Image.

setWidth

public void setWidth(int width)
Redefines the width this image uses and refreshes the display list.

Parameters:
width - The new width of the image.

width

public int width()
Access the dimensions of the image.

Returns:
The width of the image being drawn, in pixels.

setHeight

public void setHeight(int height)
Redefines the height this image uses and refreshes the display list.

Parameters:
height - The new height of the image.

height

public int height()
Access the dimensions of the image.

Returns:
The height of the image being drawn, in pixels.

setDimensions

public void setDimensions(int width,
                          int height)
Redefines the dimensions this image uses and refreshes the display list.

Parameters:
width - The new width of the image.
height - The new height of the image.

textureWidth

public int textureWidth()
Accesses the dimensions of the texture used by this image.

Returns:
The width of the texture.

textureHeight

public int textureHeight()
Accesses the dimensions of the texture used by this image.

Returns:
The height of the texture.

widthRatio

public float widthRatio()
Accesses the dimensions of the image.

Returns:
The proportion of the image width to that of the texture.

heightRatio

public float heightRatio()
Accesses the dimensions of the image.

Returns:
The proportion of the image height to that of the texture.

ID

public int ID()
Accesses the texture ID.

Returns:
The integer that indicates which texture to use on the graphics card.

hasAlpha

public boolean hasAlpha()
Learns if the texture has alpha.

Returns:
Whether or not the texture has a transparency channel.

bind

public void bind()
Calls OpenGL so that operations that involve textures use the texture referenced by this Image.


smooth

public void smooth(boolean smooth)
Defines the appearance of the Image when scaled.

Parameters:
smooth - True if a smoothing filter should be applied when the image is scaled or rotated, false if a pixelated appearance is desired.

smoothing

public boolean smoothing()
Learns which scaling filter the Image is using.

Returns:
True if the image is being smoothed, false if it is pixelated.

render

public void render()
Draws the image, using a Display List for acceleration.

Specified by:
render in interface Renderable

renderNoAcceleration

public void renderNoAcceleration()
Renders the image without using a Display List, manually passing in all required vertex and texture coordinate data.


data

public byte[] data()
Accesses the texture data of the image, in bytes. The format is dependent on the texture itself; if the image has alpha, then the pattern is 4 bytes (R/G/B/A) to a pixel; if not, it is 3 (R/G/B).

Returns:
An array of bytes that represents the texture data.

renderSubImage

public void renderSubImage(float[] coordinates)
Renders a sub-Image without any acceleration, manually passing in the data for each vertice and texture coordinate.

Parameters:
coordinates - The coordinates that detail which section of the image to render. These are not pixel values, but rather percentages. The values in the array should be {x1, y1, x2, y2}, where the first pair of values mark the upper left of the section and the second pair mark the lower right. NOTE: The percentages should be coordinates for the image, not for the texture itself.

renderSubImage

public void renderSubImage(int id)
Renders the indicated, pre-compiled sub image. This call utilizes display lists for acceleration.

Parameters:
id - The place in the array of compiled sub-images to use.

renderSubImageNoAcceleration

public void renderSubImageNoAcceleration(int id)
Renders the indicated, pre-compiled sub image. This call does not use acceleration, but instead manually handles each texture vertex.

Parameters:
id - The place in the array of compiled sub-images to use.

subImageCoords

public float[] subImageCoords(float x,
                              float y,
                              float width,
                              float height)
Calculates a series of sub-image coordinates from the indicated pixel values.

Parameters:
x - The x coordinate of the top-left pixel of the target section.
y - The y coordinate of the top-left pixel of the target section.
width - The width of the target section, in pixels.
height - The height of the target section, in pixels.
Returns:
The calculated coordinates that detail which section of the image to use. These are not pixel values, but rather percentages. The values in the array should be {x1, y1, x2, y2}, where the first pair of values mark the upper left of the section and the second pair mark the lower right.

subImage

public int subImage(float x,
                    float y,
                    float width,
                    float height)
Returns the ID of an accelerated sub-image with the indicated pixel values. If no identical sub-image exists, one is compiled and the list of sub-images is enlarged to fit it.

Parameters:
x - The x coordinate of the top-left pixel of the target section.
y - The y coordinate of the top-left pixel of the target section.
width - The width of the target section, in pixels.
height - The height of the target section, in pixels.
Returns:
The place in the internal array of sub-images.

subImage

public int subImage(float[] coordinates)
Returns the ID of an accelerated sub-image with the indicated texture coordinates. If no identical sub-image exists, one is compiled and the list of sub-images is enlarged to fit it.

Parameters:
coordinates - The coordinates that detail which section of the image to render. These are not pixel values, but rather percentages. The values in the array should be {x1, y1, x2, y2}, where the first pair of values mark the upper left of the section and the second pair mark the lower right.
Returns:
The place in the internal array of sub-images.

destroySubImage

public boolean destroySubImage(int id)
Destroys the sub-image at the indicated position in the internal array.

Parameters:
id - The spot in the array to destroy.
Returns:
True if the operation succeeded, false if not.