/* * @(#)GameCanvas.java	1.39 02/10/11 @(#) * * Copyright (c) 2002 Sun Microsystems, Inc.  All rights reserved. * PROPRIETARY/CONFIDENTIAL * Use is subject to license terms. */package javax.microedition.lcdui.game;import javax.microedition.lcdui.Image;import javax.microedition.lcdui.Graphics;import javax.microedition.lcdui.Canvas;import com.sun.midp.lcdui.DisplayAccess;import com.sun.midp.lcdui.GameMap;/** * 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 * {@link javax.microedition.lcdui.Canvas#getWidth getWidth} and * {@link javax.microedition.lcdui.Canvas#getHeight getHeight}. * <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> * <P> * @since MIDP 2.0 **/public abstract class GameCanvas extends Canvas{    /**     * The bit representing the UP key.  This constant has a value of      * <code>0x0002</code> (1 << Canvas.UP).     */    public static final int UP_PRESSED = 1 << Canvas.UP;        /**     * The bit representing the DOWN key.  This constant has a value of      * <code>0x0040</code> (1 << Canvas.DOWN).     */    public static final int DOWN_PRESSED = 1 << Canvas.DOWN;    /**     * The bit representing the LEFT key.  This constant has a value of      * <code>0x0004</code> (1 << Canvas.LEFT).     */    public static final int LEFT_PRESSED = 1 << Canvas.LEFT;    /**     * The bit representing the RIGHT key.  This constant has a value of      * <code>0x0020</code> (1 << Canvas.RIGHT).     */    public static final int RIGHT_PRESSED = 1 << Canvas.RIGHT;    /**     * The bit representing the FIRE key.  This constant has a value of      * <code>0x0100</code> (1 << Canvas.FIRE).     */    public static final int FIRE_PRESSED = 1 << Canvas.FIRE;    /**     * 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 = 1 << Canvas.GAME_A;    /**     * 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 = 1 << Canvas.GAME_B;    /**     * 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 = 1 << Canvas.GAME_C;    /**     * 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 = 1 << Canvas.GAME_D;    /**     * Height available to draw on in full screen mode.     *     */    private static final int FULLSCREEN_HEIGHT;    /**     * Width available to draw on in full screen mode.     *     */    private static final int FULLSCREEN_WIDTH;    /**      * currently every GameCanvas has one offscreen buffer     * can be optimized so that we put a limit on no of offscreen buffers     * an application can have     */    private Image offscreen_buffer;    /**     * 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 <code>true</code> to suppress the regular     * key event mechanism for game keys, otherwise <code>false</code>.     */    protected GameCanvas(boolean suppressKeyEvents) {	// Create and offscreen Image object that 	// acts as the offscreen buffer to which we draw to.	// the contents of this buffer are flushed to the display         // only when flushGraphics() has been called.	offscreen_buffer = 	    Image.createImage(FULLSCREEN_WIDTH, FULLSCREEN_HEIGHT);	setSuppressKeyEvents((Canvas)this, suppressKeyEvents);    }        /**     * Obtains the Graphics object for rendering a GameCanvas.  The returned      * Graphics object renders to the off-screen buffer belonging to this      * GameCanvas.     * <p>	      * Rendering operations do not appear on the display until flushGraphics()     * is called; flushing the buffer does not change its contents (the pixels     * are not cleared as a result of the flushing operation).     * <p>     * A new Graphics object is created and returned each time this method is     * called; therefore, the needed Graphics object(s) should be obtained      * before the game starts then re-used while the game is running.       * For each GameCanvas instance, all of the provided graphics objects will     * render to the same off-screen buffer.      * <P>