|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
|
+--javax.microedition.lcdui.game.Layer
|
+--javax.microedition.lcdui.game.Sprite
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. Several transforms such as flipping and rotation can also be applied to a Sprite to further vary its appearance. As with all Layer subclasses, a Sprite's location can be changed and it can also be made visible or invisible.
Each frame is assigned a unique index number. The frame located in the
upper-left corner of the Image is assigned an index of 0. The remaining
frames are then numbered consecutively in row-major order (indices are
assigned across the first row, then the second row, and so on). The method
getRawFrameCount() returns the total number of raw frames.
The developer must manually switch the current frame in the frame sequence.
This may be accomplished by calling setFrame(int),
prevFrame(), or nextFrame(). Note that these methods
always operate on the sequence index, they do not operate on frame indices;
however, if the default frame sequence is used, then the sequence indices
and the frame indices are interchangeable.
If desired, an arbitrary frame sequence may be defined for a Sprite. The frame sequence must contain at least one element, and each element must reference a valid frame index. By defining a new frame sequence, the developer can conveniently display the Sprite's frames in any order desired; frames may be repeated, omitted, shown in reverse order, etc.
For example, the diagram below shows how a special frame sequence might be used to animate a mosquito. The frame sequence is designed so that the mosquito flaps its wings three times and then pauses for a moment before the cycle is repeated.
nextFrame() each time the display is updated, the
resulting animation would like this:
setPosition(x,y),
getX(), and getY()). These methods all define
position in terms of the upper-left corner of the Sprite; however, in many
cases, it is more convenient to define the Sprite's position in terms of an
arbitrary reference point, especially if transforms are applied to the
Sprite.
Therefore, Sprite includes additional methods for specifying and retrieving
the Sprite's location in terms of an arbitrary reference point.
The location of the reference point is defined using
defineReferencePixel(x,y).
The reference point's location is specified relative to the upper-left
corner of the un-transformed Sprite, as shown in the following diagram.
By default, the reference point is at (0,0) (i.e. the upper-left corner of
the Sprite). If desired, the reference point may be defined outside of the
Sprite's bounds.
paint(Graphics) method.
The Sprite will be drawn on the Graphics object according to the current
state information maintained by the Sprite (i.e. position, frame,
visibility). Erasing the Sprite is always the responsibility of code
outside the Sprite class.
Sprites can be implemented using whatever techniques a manufacturers wishes to use (e.g hardware acceleration may be used for all Sprites, for certain sizes of Sprites, or not at all).
For some platforms, certain Sprite sizes may be more efficient than others; manufacturers may choose to provide developers with information about device-specific characteristics such as these.
| Field Summary | |
static int |
TRANS_MIRROR
Tranform that causes the Sprite to appear as its mirror image. |
static int |
TRANS_MIRROR_ROT180
Tranform that causes the Sprite to appear as its mirror image rotated clockwise by 180 degrees around its reference point. |
static int |
TRANS_MIRROR_ROT270
Tranform that causes the Sprite to appear as its mirror image rotated clockwise by 270 degrees around its reference point. |
static int |
TRANS_MIRROR_ROT90
Tranform that causes the Sprite to appear as its mirror image rotated clockwise by 90 degrees around its reference point. |
static int |
TRANS_NONE
No tranform is applied to the Sprite. |
static int |
TRANS_ROT180
Tranform that causes the Sprite to appear rotated clockwise by 180 degrees around its reference point. |
static int |
TRANS_ROT270
Tranform that causes the Sprite to appear rotated clockwise by 270 degrees around its reference point. |
static int |
TRANS_ROT90
Tranform that causes the Sprite to appear rotated clockwise by 90 degrees around its reference point. |
| 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 specified Image with its upper left corner at the specified location. |
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 TiledLayer. |
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 pixel for this Sprite. |
int |
getFrame()
Gets the current index 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 position of this Sprite's reference pixel in the painter's coordinate system. |
int |
getRefPixelY()
Gets the vertical position of this Sprite's reference pixel in the painter's coordinate system. |
void |
nextFrame()
Selects the next frame in the frame sequence. |
void |
paint(Graphics g)
Draws the Sprite. |
void |
prevFrame()
Selects the previous 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 newImage,
int fWidth,
int fHeight)
Changes the Image containing the Sprite's frames. |
void |
setRefPixelPosition(int x,
int y)
Sets this Sprite's position such that its reference pixel is located at (x,y) in the painter's coordinate system. |
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 |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final int TRANS_NONE
0.
public static final int TRANS_ROT90
5.
public static final int TRANS_ROT180
3.
public static final int TRANS_ROT270
6.
public static final int TRANS_MIRROR
2.
public static final int TRANS_MIRROR_ROT90
7.
public static final int TRANS_MIRROR_ROT180
1.
public static final int TRANS_MIRROR_ROT270
4.
| Constructor Detail |
public Sprite(Image image)
new Sprite(image, image.getWidth(), image.getHeight())
By default, the Sprite is visible and its upper-left
corner is positioned at (0,0) in the painter's coordinate system.
image - the Image to use as the single frame
for the Sprite
NullPointerException - if img is null
public Sprite(Image image,
int frameWidth,
int frameHeight)
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.
The values returned by Layer.getWidth() and
Layer.getHeight() will reflect the frame width and frame height
subject to the Sprite's current transform.
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 its upper-left corner is positioned at (0,0) in the painter's coordinate system.
image - the Image to use for SpriteframeWidth - the width, in pixels, of the
individual raw framesframeHeight - the height, in pixels, of the
individual raw frames
NullPointerException - if img is null
IllegalArgumentException - if frameHeight or
frameWidth is less than 1
IllegalArgumentException - if the image
width is not an integer multiple of the frameWidth
IllegalArgumentException - if the image
height is not an integer multiple of the frameHeightpublic Sprite(Sprite s)
All instance attributes (raw frames, position, frame sequence, current frame, reference point, collision rectange, transform, and visibility) of the source Sprite are duplicated in the new Sprite.
s - the Sprite to create a copy of
NullPointerException - if s is null| Method Detail |
public void defineReferencePixel(int x,
int y)
By default, a Sprite's reference pixel is located at (0,0); that is, the upper-left corner of the Sprite.
Changing the location of the reference pixel does not change the
Sprite's physical position in the game; the values returned
by Layer.getX() and Layer.getY() will not change as a result of
defining the reference pixel. However, subsequent calls to
methods that use the reference pixel will be impacted by its new
location.
x - the horizontal location of the reference pixel, relative
to the left edge of the Spritey - the vertical location of the reference pixel, relative
to the top edge of the SpritesetRefPixelPosition(int, int),
getRefPixelX(),
getRefPixelY()
public void setRefPixelPosition(int x,
int y)
x - the horizontal location of the reference pixely - the vertical location of the reference pixeldefineReferencePixel(int, int),
getRefPixelX(),
getRefPixelY()public int getRefPixelX()
defineReferencePixel(int, int),
setRefPixelPosition(int, int),
getRefPixelY()public int getRefPixelY()
defineReferencePixel(int, int),
setRefPixelPosition(int, int),
getRefPixelX()public void setFrame(int sequenceIndex)
The current frame is rendered when paint(Graphics) is called.
The index provided refers to the desired entry in the frame sequence, not the index of the actual frame itself.
sequenceIndex - the index of of the desired entry in the frame
sequence
IndexOutOfBoundsException - if frameIndex is
less than0
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(int[]),
getFrame()public final int getFrame()
The index returned refers to the current entry in the frame sequence, not the index of the actual frame that is displayed.
setFrameSequence(int[]),
setFrame(int)public int getRawFrameCount()
getFrameSequenceLength()public int getFrameSequenceLength()
getRawFrameCount()public void nextFrame()
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 entry in the sequence.
setFrameSequence(int[]),
prevFrame()public void prevFrame()
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 entry in the sequence.
setFrameSequence(int[]),
nextFrame()public final void paint(Graphics g)
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 Layer.getX() and Layer.getY().
Rendering is subject to the clip region of the Graphics object. The Sprite will be drawn only if it is visible.
paint in class Layerg - the graphics object to draw Sprite on
NullPointerException - if g is nullpublic void setFrameSequence(int[] sequence)
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. The current index in the frame sequence is reset to zero as a result of calling this method.
Passing in null causes the Sprite to revert to the
default frame sequence.
sequence - an array of integers, where each integer represents
a frame index
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()
IllegalArgumentException - if the array has less than
1 elementnextFrame(),
prevFrame(),
setFrame(int),
getFrame()
public void setImage(Image newImage,
int fWidth,
int fHeight)
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. The
values returned by Layer.getWidth() and Layer.getHeight()
will reflect the new frame width and frame height subject to the
Sprite's current transform.
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:
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 fewer frames than the previous frame set, then:
The reference pixel location is unchanged as a result of calling this method, both in terms of its defined location within the Sprite and its position in the painter's coordinate system. However, if the frame size is changed, the position of the Sprite's upper-left corner may change such that the reference pixel remains stationary.
If the Sprite's frame size is changed by this method, the collision rectangle is reset to its default value (i.e. it is set to the new bounds of the untransformed Sprite).
NullPointerException - if img is null
IllegalArgumentException - if frameHeight or
frameWidth is less than 1
IllegalArgumentException - if the image width is not an integer
multiple of the frameWidth
IllegalArgumentException - if the image height is not an integer
multiple of the frameHeight
public void defineCollisionRectangle(int x,
int y,
int width,
int height)
x - the horizontal location of the collision rectangle relative to
the untransformed Sprite's left edgey - the vertical location of the collision rectangle relative to
the untransformed Sprite's top edgewidth - the width of the collision rectangleheight - the height of the collision rectangle
IllegalArgumentException - if the specified
width or height is
less than 0public void setTransform(int transform)
By default, a Sprite's transform is TRANS_NONE.
All transforms are performed around the Sprite's reference pixel.
Thus, the Sprite's reference pixel remains at the same (x,y) position
in the painter's coordinate system whenever the Sprite's transform is
modified. This may affect the position of the Sprite's upper left
corner returned by Layer.getX() and Layer.getY(). Furthermore, the
values returned by Layer.getWidth() and Layer.getHeight() may be
swapped as a result of changing the transform.
transform - the desired transform for this Sprite
IllegalArgumentException - if the requested
transform is invalidTRANS_NONE,
TRANS_ROT90,
TRANS_ROT180,
TRANS_ROT270,
TRANS_MIRROR,
TRANS_MIRROR_ROT90,
TRANS_MIRROR_ROT180,
TRANS_MIRROR_ROT270
public final boolean collidesWith(Sprite s,
boolean pixelLevel)
If pixel-level detection is used, a collision is detected only if opaque pixels collide. That is, an opaque pixel in the first Sprite would have to collide with an opaque pixel in the second Sprite for a collision to be detected. Only those pixels within the Sprites' respective collision rectangles are checked.
If pixel-level detection is not used, this method simply checks if the Sprites' collision rectangles intersect.
Any transforms applied to the Sprites are automatically accounted for.
s - the Sprite to test for collision withpixelLevel - true to test for collision on a
pixel-by-pixel basis, false to test using simple
bounds checking.
true if the two Sprites have collided, otherwise
false
NullPointerException - if Sprite s is null
public final boolean collidesWith(TiledLayer t,
boolean pixelLevel)
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 transform applied to the Sprite is automatically accounted for.
t - the TiledLayer to test for collision withpixelLevel - true to test for collision on a
pixel-by-pixel basis, false to test using simple bounds
checking against non-empty cells.
true if this Sprite has
collided with the TiledLayer, otherwise
false
NullPointerException - if t is null
public final boolean collidesWith(Image image,
int x,
int y,
boolean pixelLevel)
If pixel-level detection is not used, this method simply checks if the Sprite's collision rectangle intersects with the Image's bounds.
Any transform applied to the Sprite is automatically accounted for.
image - the Image to test for collisionx - the horizontal location of the Image's
upper left cornery - the vertical location of the Image's
upper left cornerpixelLevel - true to test for collision on a
pixel-by-pixel basis, false to test using simple
bounds checking
true if this Sprite has
collided with the Image, otherwise
false
NullPointerException - if image is
null
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||