sprite.java

j2me is based on j2mepolish, client & server for mobile application. menu sample

//#condition (polish.midp1 || polish.usePolishGameApi == true) || (polish.blackberry && polish.usePolishGui) || (polish.doja && polish.usePolishGui)

// generated by de.enough.doc2java.Doc2Java (www.enough.de) on Sat Dec 06 15:06:44 CET 2003
/*
 * Copyright (c) 2004-2005 Robert Virkus / Enough Software
 *
 * This file is part of J2ME Polish.
 *
 * J2ME Polish is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * J2ME Polish is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with J2ME Polish; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * Commercial licenses are also available, please
 * refer to the accompanying LICENSE.txt or visit
 * http://www.j2mepolish.org for details.
 */
package de.enough.polish.ui.game;


import javax.microedition.lcdui.Graphics;
import javax.microedition.lcdui.Image;
//#ifdef polish.api.siemens-color-game-api
	//# import com.siemens.mp.color_game.TiledLayer;
//#endif

//#ifdef polish.api.nokia-ui
	//# import com.nokia.mid.ui.DirectGraphics;
	//# import com.nokia.mid.ui.DirectUtils;
//#endif

/**
 * 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.
 * <h3>Sprite Frames</h3>
 * The raw frames used to render a Sprite are provided in a single Image
 * object, which may be mutable or immutable.  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.
 * <br>
 * <center><img src="doc-files/frames.gif" width=777 height=402
 * ALT="Sprite Frames"></center>
 * <br>
 * <p>
 * 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
 * <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#getRawFrameCount()"><CODE>getRawFrameCount()</CODE></A> returns the total number of raw frames.
 * <h3>Frame Sequence</h3>
 * A Sprite's frame sequence defines an ordered list of frames to be displayed.
 * The default frame sequence mirrors the list of available frames, so
 * there is a direct mapping between the sequence index and the corresponding
 * frame index.  This also means that the length of the default frame sequence
 * is equal to the number of raw frames.  For example, if a Sprite has 4
 * frames, its default frame sequence is {0, 1, 2, 3}.
 * <center><img src="doc-files/defaultSequence.gif" width=182 height=269
 * ALT="Default Frame Sequence"></center>
 * The developer must manually switch the current frame in the frame sequence.
 * This may be accomplished by calling <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#setFrame(int)"><CODE>setFrame(int)</CODE></A>,
 * <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#prevFrame()"><CODE>prevFrame()</CODE></A>, or <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#nextFrame()"><CODE>nextFrame()</CODE></A>.  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.
 * <center><img src="doc-files/specialSequence.gif" width=346 height=510
 * ALT="Special Frame Sequence"></center>
 * By calling <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#nextFrame()"><CODE>nextFrame()</CODE></A> each time the display is updated, the
 * resulting animation would like this:
 * <br>
 * <center><img src="doc-files/sequenceDemo.gif" width=96 height=36></center>
 * <h3>Reference Pixel</h3>
 * Being a subclass of Layer, Sprite inherits various methods for setting and
 * retrieving its location such as <A HREF="../../../../javax/microedition/lcdui/game/Layer.html#setPosition(int, int)"><CODE>setPosition(x,y)</CODE></A>,
 * <A HREF="../../../../javax/microedition/lcdui/game/Layer.html#getX()"><CODE>getX()</CODE></A>, and <A HREF="../../../../javax/microedition/lcdui/game/Layer.html#getY()"><CODE>getY()</CODE></A>.  These methods all define
 * position in terms of the upper-left corner of the Sprite's visual bounds;
 * however, in some cases, it is more convenient to define the Sprite's position
 * in terms of an arbitrary pixel within its frame, especially if transforms
 * are applied to the Sprite.
 * Therefore, Sprite includes the concept of a <em>reference pixel</em>.
 * The reference pixel is defined by specifying its location in the
 * Sprite's untransformed frame using
 * <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#defineReferencePixel(int, int)"><CODE>defineReferencePixel(x,y)</CODE></A>.
 * By default, the reference pixel is defined to be the pixel at (0,0)
 * in the frame.  If desired, the reference pixel may be defined outside
 * of the frame's bounds.
 * <p>
 * In this example, the reference pixel is defined to be the pixel that
 * the monkey appears to be hanging from:
 * <p>
 * <center><img src="doc-files/refpixel.gif" width=304 height=199
 * ALT="Defining The Reference Pixel"></center>
 * <p>
 * <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#getRefPixelX()"><CODE>getRefPixelX()</CODE></A> and <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#getRefPixelY()"><CODE>getRefPixelY()</CODE></A>
 * can be used to query the location of the reference pixel in the painter's
 * coordinate system.  The developer can also use
 * <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#setRefPixelPosition(int, int)"><CODE>setRefPixelPosition(x,y)</CODE></A> to position the Sprite
 * so that reference pixel appears at a specific location in the painter's
 * coordinate system.  These methods automatically account for any transforms
 * applied to the Sprite.
 * <p>
 * In this example, the reference pixel's position is set to a point at the end
 * of a tree branch; the Sprite's location changes so that the reference pixel
 * appears at this point and the monkey appears to be hanging from the branch:
 * <p>
 * <center><img src="doc-files/setrefposition.gif" width=332 height=350
 * ALT="Setting The Reference Pixel Position"></center>
 * <p>
 * <a name="transforms"></a>
 * <h3>Sprite Transforms</h3>
 * Various transforms can be applied to a Sprite.  The available transforms
 * include rotations in multiples of 90 degrees, and mirrored (about
 * the vertical axis) versions of each of the rotations.  A Sprite's transform
 * is set by calling <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#setTransform(int)"><CODE>setTransform(transform)</CODE></A>.
 * <p>
 * <center><img src="doc-files/transforms.gif" width=355 height=575
 * ALT="Transforms"></center>
 * <br>
 * When a transform is applied, the Sprite is automatically repositioned
 * such that the  reference pixel appears stationary in the painter's
 * coordinate system.  Thus, the reference pixel effectively becomes the
 * center of the transform operation.  Since the reference pixel does not
 * move, the values returned by <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#getRefPixelX()"><CODE>getRefPixelX()</CODE></A> and
 * <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#getRefPixelY()"><CODE>getRefPixelY()</CODE></A> remain the same; however, the values returned by
 * <A HREF="../../../../javax/microedition/lcdui/game/Layer.html#getX()"><CODE>getX()</CODE></A> and <A HREF="../../../../javax/microedition/lcdui/game/Layer.html#getY()"><CODE>getY()</CODE></A> may change to reflect the
 * movement of the Sprite's upper-left corner.
 * <p>
 * Referring to the monkey example once again, the position of the
 * reference pixel remains at (48, 22) when a 90 degree rotation
 * is applied, thereby making it appear as if the monkey is swinging
 * from the branch:
 * <p>
 * <center><img src="doc-files/transcenter.gif" width=333 height=350
 * ALT="Transform Center"></center>
 * <p>
 * <h3>Sprite Drawing</h3>
 * Sprites can be drawn at any time using the <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#paint(javax.microedition.lcdui.Graphics)"><CODE>paint(Graphics)</CODE></A> 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.<p>
 * <p>
 * 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).
 * <p>
 * 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.
 * <p>
  * 
 * @author Robert Virkus (original implementation)
 * @author Thomas Boyer (optimizations)
 */
public class Sprite
//#ifdef polish.api.siemens-color-game-api
	//# extends com.siemens.mp.color_game.Sprite
//#else
	extends Layer
//#endif
{
	/**
	 * No transform is applied to the Sprite.
	 * This constant has a value of <code>0</code>.
	 */
	public static final int TRANS_NONE = 0;

	/**
	 * Causes the Sprite to appear rotated clockwise by 90 degrees.
	 * This constant has a value of <code>5</code>.
	 */
	public static final int TRANS_ROT90 = 5;

	/**
	 * Causes the Sprite to appear rotated clockwise by 180 degrees.
	 * This constant has a value of <code>3</code>.
	 */
	public static final int TRANS_ROT180 = 3;

	/**
	 * Causes the Sprite to appear rotated clockwise by 270 degrees.
	 * This constant has a value of <code>6</code>.
	 */
	public static final int TRANS_ROT270 = 6;

	/**
	 * Causes the Sprite to appear reflected about its vertical
	 * center.
	 * This constant has a value of <code>2</code>.
	 */
	public static final int TRANS_MIRROR = 2;

	/**
	 * Causes the Sprite to appear reflected about its vertical
	 * center and then rotated clockwise by 90 degrees.
	 * This constant has a value of <code>7</code>.
	 */
	public static final int TRANS_MIRROR_ROT90 = 7;

	/**
	 * Causes the Sprite to appear reflected about its vertical
	 * center and then rotated clockwise by 180 degrees.
	 * This constant has a value of <code>1</code>.
	 */
	public static final int TRANS_MIRROR_ROT180 = 1;

	/**
	 * Causes the Sprite to appear reflected about its vertical
	 * center and then rotated clockwise by 270 degrees.
	 * This constant has a value of <code>4</code>.
	 */
	public static final int TRANS_MIRROR_ROT270 = 4;
		
	private Image image;
	private int refPixelX;
	private int refPixelY;
	private int frameSequenceIndex;
	private int[] frameSequence;
	private int transform;
	//#ifdef polish.api.nokia-ui
		//# private static final int[] NOKIA_TRANSFORM_LOOKUP = {
			//# 0,
			//# DirectGraphics.FLIP_VERTICAL,
			//# DirectGraphics.FLIP_HORIZONTAL,
			//# DirectGraphics.ROTATE_180,
			//# DirectGraphics.ROTATE_90 | DirectGraphics.FLIP_VERTICAL,
			//# DirectGraphics.ROTATE_270,
			//# DirectGraphics.ROTATE_90,
			//# DirectGraphics.ROTATE_90 | DirectGraphics.FLIP_HORIZONTAL
		//# };
		//# private int nokiaTransform;
		//# private Image nokiaFrame;
		//# private Image[] nokiaFrames;
	//#endif
	private int collisionX;
	private int collisionY;
	private int collisionWidth;
	private int collisionHeight;
	private int transformedCollisionX;
	private int transformedCollisionY;
	private int transformedCollisionWidth;
	private int transformedCollisionHeight;

	private int frameHeight;
	private int frameWidth;
	private int rawFrameCount;
	private boolean isSingleFrame;
	private int transformedRefX;
	private int transformedRefY;
	private int numberOfColumns;
	private int column;
	private int row;
	
	//#ifdef polish.api.siemens-color-game-api
		//# protected int xPosition;
		//# protected int yPosition;
		//# protected int width;
		//# protected int height;
		//# protected boolean isVisible = true;
	//#endif

	/**
	 * Creates a new non-animated Sprite using the provided Image.
	 * This constructor is functionally equivalent to calling
	 * <code>new Sprite(image, image.getWidth(), image.getHeight())</code>
	 * <p>
	 * By default, the Sprite is visible and its upper-left
	 * corner is positioned at (0,0) in the painter's coordinate system.
	 * <br>
	 * 
	 * @param image the Image to use as the single frame for the Sprite
	 * @throws NullPointerException if img is null
	 */
	public Sprite( Image image)
	{
		//#ifdef polish.api.siemens-color-game-api
			//# super( image );
		//#else
			setImage( image, image.getWidth(), image.getHeight() );
		//#endif
	}

	/**
	 * Creates a new animated Sprite using frames contained in
	 * the provided Image.  The frames must be equally sized, with the
	 * dimensions specified by <code>frameWidth</code> and
	 * <code>frameHeight</code>.  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