BenQ Mobile

javax.microedition.lcdui.game
Class Sprite

java.lang.Object
  extended byjavax.microedition.lcdui.game.Layer
      extended byjavax.microedition.lcdui.game.Sprite

public class Sprite
extends Layer

Description:

A Sprite is a basic visual element that can be rendered with one of several frames stored in an Image; different frames can be shown to animate the Sprite. As with all Layer subclasses, a Sprite’s location can be changed and it can also be made visible or invisible.

Sprite Frames:

The raw frames used to render a Sprite are provided in a single Image object. If more than one frame is used, the Image is broken up into a series of equally-sized frames of a specified width and height. As shown in the figure below, the same set of frames may be stored in several different arrangements depending on what is the most convenient for the game developer.


Field Summary
static int TRANMIRROR
           
static int TRANMIRROR_ROT180
           
static int TRANMIRROR_ROT270
           
static int TRANMIRROR_ROT90
           
static int TRANNONE
           
static int TRANROT180
           
static int TRANROT270
           
static int TRANROT90
           
 
Constructor Summary
Sprite(Image image)
          Creates a new non-animated Sprite using the provided Image.
Sprite(Image image, int frameWidth, int frameHeight)
          Creates a new animated Sprite using frames contained in the provided Image.
Sprite(Sprite s)
          Creates a new Sprite from another Sprite.
 
Method Summary
 boolean collidesWith(Image image, int x, int y, boolean pixelLevel)
          Checks for a collision between this Sprite and the image specified located at (x, y).
 boolean collidesWith(Sprite s, boolean pixelLevel)
          Checks for a collision between this Sprite and the specified Sprite.
 boolean collidesWith(TiledLayer t, boolean pixelLevel)
          Checks for a collision between this Sprite and the specified TiledBackground.
 void defineCollisionRectangle(int x, int y, int width, int height)
          Defines the Sprite’s bounding rectangle that is used for collision detection purposes.
 void defineReferencePixel(int x, int y)
          Defines the location of the reference point within this Sprite.
 int getFrame()
          Gets the current frame in the frame sequence.
 int getFrameSequenceLength()
          Gets the number of elements in the frame sequence.
 int getRawFrameCount()
          Gets the number of raw frames for this Sprite.
 int getRefPixelX()
          Gets the horizontal location of this Sprite’s reference point.
 int getRefPixelY()
          Gets the vertical location of this Sprite’s reference point.
 void nextFrame()
          Selects the next frame in the frame sequence.
 void paint(Graphics g)
          Draws the Sprite.
 void prevFrame()
          Selects the next frame in the frame sequence.
 void setFrame(int sequenceIndex)
          Selects current frame in the frame sequence.
 void setFrameSequence(int[] sequence)
          Set the frame sequence for this Sprite.
 void setImage(Image image, int frameWidth, int frameHeight)
          Changes the image used for the Sprite.
 void setRefPixelPosition(int x, int y)
          Sets this Sprite’s position such that its reference point is located at (x,y), accounting for any transform that may be in effect.
 void setTransform(int transform)
          Sets the transformation for this Sprite.
 
Methods inherited from class javax.microedition.lcdui.game.Layer
getHeight, getWidth, getX, getY, isVisible, move, setPosition, setVisible
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TRANNONE

public static final int TRANNONE
See Also:
Constant Field Values

TRANROT180

public static final int TRANROT180
See Also:
Constant Field Values

TRANROT270

public static final int TRANROT270
See Also:
Constant Field Values

TRANROT90

public static final int TRANROT90
See Also:
Constant Field Values

TRANMIRROR

public static final int TRANMIRROR
See Also:
Constant Field Values

TRANMIRROR_ROT180

public static final int TRANMIRROR_ROT180
See Also:
Constant Field Values

TRANMIRROR_ROT270

public static final int TRANMIRROR_ROT270
See Also:
Constant Field Values

TRANMIRROR_ROT90

public static final int TRANMIRROR_ROT90
See Also:
Constant Field Values
Constructor Detail

Sprite

public Sprite(Image image)
Creates a new non-animated Sprite using the provided Image. This constructor is functionally equivalent to calling new Sprite(image, image.getWidth(), image.getHeight()) By default, the Sprite is visible and positioned at (0,0).

Parameters:
image - The Image to use as the single frame for the Sprite
Throws:
java.lang.NullPointerException - if image is null

Sprite

public Sprite(Image image,
              int frameWidth,
              int frameHeight)
Creates a new animated Sprite using frames contained in the provided Image. The frames must be equally sized, with the dimensions specified by frameWidth and frameHeight. They may be laid out in the image horizontally, vertically, or as a grid. The width of the source image must be an integer multiple of the frame width, and the height of the source image must be an integer multiple of the frame height. Sprites have a default frame sequence corresponding to the raw frame numbers, starting with frame 0. The frame sequence may be modified with setFrameSequence(int[]).

By default, the Sprite is visible and positioned at (0,0).

Parameters:
image - Image to use for Sprite
frameWidth - width, in pixels, of the individual raw frames
frameHeight - height, in pixels, of the individual raw frames
Throws:
java.lang.NullPointerException - if image is null
java.lang.IllegalArgumentException - if frameHeight or frameWidth is less than 1
java.lang.IllegalArgumentException - if the image width is not an integer multiple of the frameWidth
java.lang.IllegalArgumentException - if the image height is not an integer multiple of the frameHeight

Sprite

public Sprite(Sprite s)
Creates a new Sprite from another Sprite.
All instance attributes (raw frames, position, frame sequence, current frame, visibility) of the source Sprite are duplicated in the new Sprite.

Parameters:
s - Sprite to create a copy of
Throws:
java.lang.NullPointerException - if s is null
Method Detail

collidesWith

public final boolean collidesWith(Sprite s,
                                  boolean pixelLevel)
Checks for a collision between this Sprite and the specified Sprite.
This method simply checks if the Sprites’ collision rectangles intersect.

Pixel-level detection is @@@.

Parameters:
s - The Sprite to test for collision with
pixelLevel - True to test for collision on a pixel-by-pixel basis, false to test using simple bounds checking.
Returns:
True if the two Sprites have collided, otherwise false.

collidesWith

public final boolean collidesWith(Image image,
                                  int x,
                                  int y,
                                  boolean pixelLevel)
Checks for a collision between this Sprite and the image specified located at (x, y).
This method simply checks if the Sprites’ collision rectangles intersect.

Pixel-level detection is @@@.

Parameters:
image - The image to test for collision with
x - x coordinate of image
y - y coordinate of image
pixelLevel - True to test for collision on a pixel-by-pixel basis, false to test using simple bounds checking.
Returns:
True if the Sprite has collided, otherwise false.

collidesWith

public final boolean collidesWith(TiledLayer t,
                                  boolean pixelLevel)
Checks for a collision between this Sprite and the specified TiledBackground. If pixel-level detection is used, a collision is detected only if opaque pixels collide. That is, an opaque pixel in the Sprite would have to collide with an opaque pixel in TiledLayer for a collision to be detected. Only those pixels within the Sprite’s collision rectangle are checked.

If pixel-level detection is not used, this method simply checks if the Sprite’s collision rectangle intersects with a non-empty cell in the TiledLayer.

Any transformation applied to the Sprite is automatically accounted for.

Parameters:
t - The TiledLayer to test for collision with
pixelLevel - True to test for collision on a pixel-by-pixel basis, false to test using simple bounds checking against non-empty cells.
Returns:
True if this Sprite has collided with the TiledBackground, otherwise false.

defineReferencePixel

public void defineReferencePixel(int x,
                                 int y)
Defines the location of the reference point within this Sprite. The location is specified relative to the upperleft corner of the un-transformed Sprite.

By default, a Sprite’s reference point is located at (0,0); that is, the upper-left corner of the Sprite. Changing the location of the reference point does not change the Sprite’s physical position in the game. However, subsequent calls to methods that use the reference point will be impacted by its new location.

Parameters:
x - The horizontal location of the reference point, relative to the left edge of the Sprite.
y - The vertical location of the reference point, relative to the top edge of the Sprite.

getFrame

public final int getFrame()
Gets the current frame in the frame sequence. The index returned is the index in the frame sequence, not the index of the actual frame.

Returns:
index of of the current entry in the frame sequence

getFrameSequenceLength

public int getFrameSequenceLength()
Gets the number of elements in the frame sequence. The value returned reflects the length of the Sprite’s frame sequence; it does not reflect the number of raw frames. However, these two values will be the same if the default frame sequence is used.

Returns:
Number of frames for this Sprite

getRawFrameCount

public int getRawFrameCount()
Gets the number of raw frames for this Sprite. The value returned reflects the number of frames; it does not reflect the length of the Sprite’s frame sequence. However, these two values will be the same if the default frame sequence is used.

Returns:
Number of frames for this Sprite

getRefPixelX

public int getRefPixelX()
Gets the horizontal location of this Sprite’s reference point.

Returns:
The horizontal location of the reference point

getRefPixelY

public int getRefPixelY()
Gets the vertical location of this Sprite’s reference point.

Returns:
The vertical location of the reference point

nextFrame

public void nextFrame()
Selects the next frame in the frame sequence.
The frame sequence is considered to be circular, i.e. if nextFrame() is called when at the end of the sequence, this method will advance to the first frame in the sequence.


paint

public final void paint(Graphics g)
Draws the Sprite.
Draws current frame of Sprite using the provided Graphics object. The Sprite’s upper left corner is rendered at the Sprite’s current position relative to the origin of the Graphics object. The current position of the Sprite’s upper-left corner can be retrieved by calling getX() and getY().

Rendering is subject to the clip region of the Graphics object. The Sprite will be drawn only if it is visible.

Specified by:
paint in class Layer
Parameters:
g - Graphics object to draw Sprite on
Throws:
java.lang.NullPointerException - if g is null

prevFrame

public void prevFrame()
Selects the next frame in the frame sequence. The frame sequence is considered to be circular, i.e. if prevFrame() is called when at the start of the sequence, this method will advance to the last frame in the sequence.


defineCollisionRectangle

public void defineCollisionRectangle(int x,
                                     int y,
                                     int width,
                                     int height)
Defines the Sprite’s bounding rectangle that is used for collision detection purposes. This rectangle is specified relative to the Sprite’s upper-left corner and defines the area that is checked for collision detection. By default, a Sprite’s collision rectangle is located at 0,0 as has the same dimensions as the Sprite. The collision rectangle may be specified to be larger or smaller than the default rectangle.

Parameters:
x - The horizontal location of the collision rectangle relative to the Sprite’s left edge
y - The vertical location of the collision rectangle relative to the Sprite’s top edge
width - The width of the collision rectangle
height - The height of the collision rectangle
Throws:
java.lang.IllegalArgumentException - if the specified width or height is less than 0

setFrame

public void setFrame(int sequenceIndex)
Selects current frame in the frame sequence.
The current frame is rendered when paint(Graphics) is called. The index provided is the index in the frame sequence, not the index of the actual frame.

Parameters:
sequenceIndex - Index of of the desired entry in the frame sequence
Throws:
java.lang.IndexOutOfBoundsException - if frameIndex is less than 0
java.lang.IndexOutOfBoundsException - if frameIndex is equal to or greater than the length of the current frame sequence (or the number of raw frames for the default sequence)

setFrameSequence

public void setFrameSequence(int[] sequence)
Set the frame sequence for this Sprite.
All Sprites have a default sequence that displays the Sprites frames in order. This method allows for the creation of an arbitrary sequence using the available frames.
Passing in "null" causes the Sprite to revert to the default frame sequence.

Parameters:
sequence - An array of integers, where each integer represents a frame index
Throws:
java.lang.ArrayIndexOutOfBoundsException - if seq is non-null and any member of the array has a value less than 0 or greater than or equal to the number of frames as reported by getRawFrameCount()
java.lang.IllegalArgumentException - if the array has less than 1 element

setImage

public void setImage(Image image,
                     int frameWidth,
                     int frameHeight)
Changes the image used for the Sprite.
Replaces the current raw frames of the Sprite with a new set of raw frames. See the constructor Sprite(Image, int, int) for information on how the frames are created from the image. Changing the image for the Sprite could change the number of raw frames.

If the new frame set has as many or more raw frames than the previous frame set, then:

- The current frame will be unchanged
- If a custom frame sequence has been defined (using setFrameSequence(int[])), it will remain unchanged. If no custom frame sequence is defined (i.e. the default frame sequence is in use), the default frame sequence will be updated to be the default frame sequence for the new frame set. In other words, the new default frame sequence will include all of the frames from the new raw frame set, as if this new image had been used in the constructor.

If the new frame set has less frames than the previous frame set, then:

- The current frame will be reset to frame 0
- Any custom frame sequence will be deleted and the frame sequence will revert to the default frame sequence for the new frame set (all frames in the frame set, left-to-right then top-to-bottom)

Parameters:
image - Image to use for Sprite
frameWidth - The width, in pixels, of the individual raw frames
frameHeight - The height, in pixels, of the individual raw frames
Throws:
java.lang.NullPointerException - if image is null
java.lang.IllegalArgumentException - if frameHeight or frameWidth is less than 1
java.lang.IllegalArgumentException - if the image width is not an integer multiple of the frameWidth
java.lang.IllegalArgumentException - if the image height is not an integer multiple of the frameHeight

setRefPixelPosition

public void setRefPixelPosition(int x,
                                int y)
Sets this Sprite’s position such that its reference point is located at (x,y), accounting for any transform that may be in effect.

Parameters:
x - The horizontal location of the reference point
y - The vertical location of the reference point

setTransform

public void setTransform(int transform)
Sets the transformation for this Sprite. Transformations can be applied to a Sprite to change its rendered appearance; transformations are also applied to the collision rectangle. The specified transformation is applied to original Sprite image; they are not cumulative, nor can they be combined. Note that the Sprite must be re-drawn in order for the effects of the transformation to be observed.

By default, a Sprite’s transform is TRANSFORM_NONE.

All transforms are performed around the Sprite’s reference point. Thus, the reference point does not move as a result of changing the Sprite’s transform.

Parameters:
transform - The desired transform for this Sprite
Throws:
java.lang.IllegalArgumentException - if the requested transform is invalid or unknown

BenQ Mobile

Copyright © 2006 BenQ Mobile GmbH & Co. OHG or respective copyright owner.
All Rights Reserved.
BenQ Corp. is a trademark licensee of Siemens AG.


For further information about Mobility Toolkit (MTK) visit our Developer Portal.