gamecanvas.java

现在大部分手机都不支持WTK2.0

// generated by de.enough.doc2java.Doc2Java (www.enough.de) on Sat Dec 06 15:06:43 CET 2003
// only include this file for midp1-devices:
//#condition (polish.midp1 && ! polish.api.siemens-color-game-api) || (polish.usePolishGameApi == true) || polish.blackberry
/*
 * 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.Canvas;
import javax.microedition.lcdui.Graphics;
import javax.microedition.lcdui.Image;

import de.enough.polish.ui.MasterCanvas;

//#ifdef polish.usePolishGui
	//# import de.enough.polish.ui.Screen;
//#endif

/**
 * The GameCanvas class provides the basis for a game user interface.
 * 
 * The GameCanvas class provides the basis for a game user interface.  In
 * addition to the features inherited from Canvas (commands, input events,
 * etc.) it also provides game-specific capabilities such as an
 * off-screen graphics buffer and the ability to query key status.
 * <p>
 * A dedicated buffer is created for each GameCanvas instance.  Since a
 * unique buffer is provided for each GameCanvas instance, it is preferable
 * to re-use a single GameCanvas instance in the interests of minimizing
 * heap usage.  The developer can assume that the contents of this buffer
 * are modified only by calls to the Graphics object(s) obtained from the
 * GameCanvas instance; the contents are not modified by external sources
 * such as other MIDlets or system-level notifications.  The buffer is
 * initially filled with white pixels.
 * <p>
 * The buffer's size is set to the maximum dimensions of the GameCanvas.
 * However, the area that may be flushed is limited by the current
 * dimensions of the GameCanvas (as influenced by the presence of a Ticker,
 * Commands, etc.) when the flush is requested.  The current dimensions of
 * the GameCanvas may be obtained by calling
 * <A HREF="../../../../javax/microedition/lcdui/Displayable.html#getWidth()"><CODE>getWidth</CODE></A> and
 * <A HREF="../../../../javax/microedition/lcdui/Displayable.html#getHeight()"><CODE>getHeight</CODE></A>.
 * <p>
 * A game may provide its own thread to run the game loop.  A typical loop
 * will check for input, implement the game logic, and then render the updated
 * user interface. The following code illustrates the structure of a typcial
 * game loop: <code>
 * <pre>
 * // Get the Graphics object for the off-screen buffer
 * Graphics g = getGraphics();
 * 
 * while (true) {
 * // Check user input and update positions if necessary
 * int keyState = getKeyStates();
 * if ((keyState & LEFT_PRESSED) != 0) {
 * sprite.move(-1, 0);
 * }
 * else if ((keyState & RIGHT_PRESSED) != 0) {
 * sprite.move(1, 0);
 * }
 * 
 * // Clear the background to white
 * g.setColor(0xFFFFFF);
 * g.fillRect(0,0,getWidth(), getHeight());
 * 
 * // Draw the Sprite
 * sprite.paint(g);
 * 
 * // Flush the off-screen buffer
 * flushGraphics();
 * }
 * </pre>
 * </code>
 * 
 * @author Robert Virkus (initial implementation)
 * @author Jan Peknik (Optimizations)
 * @author Thomas Broyer (Optimizations)
 * 
 * @since MIDP 2.0
 */
public abstract class GameCanvas
//#if !(polish.classes.fullscreen:defined || (polish.midp2 && ( !polish.useMenuFullScreen || polish.hasCommandKeyEvents)))
		extends Canvas
//#else
	// a fullscreen class is available
	//#if (polish.GameCanvas.useFullScreen == false) || (polish.GameCanvas.useFullScreen == no)
		//# extends Canvas
	//#elif (polish.GameCanvas.useFullScreen == true) || (polish.GameCanvas.useFullScreen == yes)
		//#define tmp.useFullScreen
		//#= extends ${polish.classes.fullscreen}
	//#elif (polish.GameCanvas.useFullScreen == menu) || ( polish.useFullScreen && polish.useMenuFullScreen ) 
		// a menu should be used along with the full screen:
		//#ifdef polish.usePolishGui
			//#define tmp.useFullScreen
			//#define tmp.extendsPolishScreen
			//# extends Screen
		//#else
			//# extends Canvas
		//#endif
	//#elif (polish.useFullScreen && !polish.useMenuFullScreen)
		//#define tmp.useFullScreen
		//#= extends ${polish.classes.fullscreen}
	//#else
		//# extends Canvas
	//#endif
//#endif
{
	/**
	 * The bit representing the UP key.  This constant has a value of
	 * <code>0x0002</code> (1 << Canvas.UP).
	 */
	public static final int UP_PRESSED = 0x0002;

	/**
	 * The bit representing the DOWN key.  This constant has a value of
	 * <code>0x0040</code> (1 << Canvas.DOWN).
	 */
	public static final int DOWN_PRESSED = 0x0040;

	/**
	 * The bit representing the LEFT key.  This constant has a value of
	 * <code>0x0004</code> (1 << Canvas.LEFT).
	 */
	public static final int LEFT_PRESSED = 0x0004;

	/**
	 * The bit representing the RIGHT key.  This constant has a value of
	 * <code>0x0020</code> (1 << Canvas.RIGHT).
	 */
	public static final int RIGHT_PRESSED = 0x0020;

	/**
	 * The bit representing the FIRE key.  This constant has a value of
	 * <code>0x0100</code> (1 << Canvas.FIRE).
	 */
	public static final int FIRE_PRESSED = 0x0100;

	/**
	 * The bit representing the GAME_A key (may not be supported on all
	 * devices).  This constant has a value of
	 * <code>0x0200</code> (1 << Canvas.GAME_A).
	 */
	public static final int GAME_A_PRESSED = 0x0200;

	/**
	 * The bit representing the GAME_B key (may not be supported on all
	 * devices).  This constant has a value of
	 * <code>0x0400</code> (1 << Canvas.GAME_B).
	 */
	public static final int GAME_B_PRESSED = 0x0400;

	/**
	 * The bit representing the GAME_C key (may not be supported on all
	 * devices).  This constant has a value of
	 * <code>0x0800</code> (1 << Canvas.GAME_C).
	 */
	public static final int GAME_C_PRESSED = 0x0800;

	/**
	 * The bit representing the GAME_D key (may not be supported on all
	 * devices).  This constant has a value of
	 * <code>0x1000</code> (1 << Canvas.GAME_D).
	 */
	public static final int GAME_D_PRESSED = 0x1000;

	private int keyStates;
	private int releasedKeys;
	private Image bufferedImage;
	private int clipX, clipY, clipWidth, clipHeight;
	private boolean setClip;

	/**
	 * Creates a new instance of a GameCanvas.  A new buffer is also created
	 * for the GameCanvas and is initially filled with white pixels.
	 * <p>
	 * If the developer only needs to query key status using the getKeyStates
	 * method, the regular key event mechanism can be suppressed for game keys
	 * while this GameCanvas is shown.  If not needed by the application, the
	 * suppression of key events may improve performance by eliminating
	 * unnecessary system calls to keyPressed, keyRepeated and keyReleased
	 * methods.
	 * <p>
	 * If requested, key event suppression for a given GameCanvas is started
	 * when it is shown (i.e. when showNotify is called) and stopped when it
	 * is hidden (i.e. when hideNotify is called).  Since the showing and
	 * hiding of screens is serialized with the event queue, this arrangement
	 * ensures that the suppression effects only those key events intended for
	 * the corresponding GameCanvas.  Thus, if key events are being generated
	 * while another screen is still shown, those key events will continue to
	 * be queued and dispatched until that screen is hidden and the GameCanvas
	 * has replaced it.
	 * <p>
	 * Note that key events can be suppressed only for the defined game keys
	 * (UP, DOWN, FIRE, etc.); key events are always generated for all other
	 * keys.
	 * <p>
	 * 
	 * @param suppressKeyEvents - true to suppress the regular key event mechanism for game keys, otherwise false.
	 */
	protected GameCanvas( boolean suppressKeyEvents ) {
		//#ifdef tmp.extendsPolishScreen
			//# super( null, null, false );
		//#else
			super();
		//#endif
		//#if (tmp.useFullScreen || polish.midp2) && polish.FullCanvasSize:defined
			//#= int width = ${polish.FullCanvasWidth};
			//#= int height = ${polish.FullCanvasHeight};
		//#else
			int width = getWidth();
			int height = getHeight();
		//#endif
			
		// create image buffer:	
		this.bufferedImage = Image.createImage( width, height );
		
	}

	/**
	 * Obtains the Graphics object for rendering a GameCanvas.  The returned
	 * Graphics object renders to the off-screen buffer belonging to this
	 * GameCanvas.
	 * <p>