GameCanvaspublic abstract class GameCanvas extends javax.microedition.lcdui.Canvas | 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.
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.
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}.
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 typical
game loop:
// 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();
}
|
| Fields Summary |
|---|
| private com.sun.midp.lcdui.GameCanvasLFImpl | gameCanvasLFThe look&feel implementation associated with this GameCanvas | | private static com.sun.midp.lcdui.GameAccess | gameAccessImplementor of GameAccess interface handed out to external packages | | public static final int | UP_PRESSEDThe bit representing the UP key. This constant has a value of
0x0002 (1 << Canvas.UP). | | public static final int | DOWN_PRESSEDThe bit representing the DOWN key. This constant has a value of
0x0040 (1 << Canvas.DOWN). | | public static final int | LEFT_PRESSEDThe bit representing the LEFT key. This constant has a value of
0x0004 (1 << Canvas.LEFT). | | public static final int | RIGHT_PRESSEDThe bit representing the RIGHT key. This constant has a value of
0x0020 (1 << Canvas.RIGHT). | | public static final int | FIRE_PRESSEDThe bit representing the FIRE key. This constant has a value of
0x0100 (1 << Canvas.FIRE). | | public static final int | GAME_A_PRESSEDThe bit representing the GAME_A key (may not be supported on all
devices). This constant has a value of
0x0200 (1 << Canvas.GAME_A). | | public static final int | GAME_B_PRESSEDThe bit representing the GAME_B key (may not be supported on all
devices). This constant has a value of
0x0400 (1 << Canvas.GAME_B). | | public static final int | GAME_C_PRESSEDThe bit representing the GAME_C key (may not be supported on all
devices). This constant has a value of
0x0800 (1 << Canvas.GAME_C). | | public static final int | GAME_D_PRESSEDThe bit representing the GAME_D key (may not be supported on all
devices). This constant has a value of
0x1000 (1 << Canvas.GAME_D). |
| Constructors Summary |
|---|
protected GameCanvas(boolean suppressKeyEvents)Creates a new instance of a GameCanvas. A new buffer is also created
for the GameCanvas and is initially filled with white pixels.
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.
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.
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.
// 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.
super();
setSuppressKeyEvents((Canvas)this, suppressKeyEvents);
gameCanvasLF = new GameCanvasLFImpl(this);
// Create and hand out game accessor tunnel instance
if (gameAccess == null) {
gameAccess = new GameAccessImpl();
GameMap.registerGameAccess(gameAccess);
}
|
| Methods Summary |
|---|
| public void | flushGraphics(int x, int y, int width, int height)Flushes the specified region of the off-screen buffer to the display.
The contents of the off-screen buffer are not changed as a result of
the flush operation. This method does not return until the flush has
been completed, so the app may immediately begin to render the next
frame to the same buffer once this method returns.
If the specified region extends beyond the current bounds of the
GameCanvas, only the intersecting region is flushed. No pixels are
flushed if the specified width or height is less than 1.
This method does nothing and returns immediately if the GameCanvas is
not currently shown or the flush request cannot be honored because the
system is busy.
gameCanvasLF.flushGraphics(x, y, width, height);
| | public void | flushGraphics()Flushes the off-screen buffer to the display. The size of the flushed
area is equal to the size of the GameCanvas. The contents
of the off-screen buffer are not changed as a result of the flush
operation. This method does not return until the flush has been
completed, so the app may immediately begin to render the next frame
to the same buffer once this method returns.
This method does nothing and returns immediately if the GameCanvas is
not currently shown or the flush request cannot be honored because the
system is busy.
gameCanvasLF.flushGraphics();
| | protected javax.microedition.lcdui.Graphics | getGraphics()Obtains the Graphics object for rendering a GameCanvas. The returned
Graphics object renders to the off-screen buffer belonging to this
GameCanvas.
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).
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.
The newly created Graphics object has the following properties:
- the destination is this GameCanvas' buffer;
- the clip region encompasses the entire buffer;
- the current color is black;
- the font is the same as the font returned by
{@link javax.microedition.lcdui.Font#getDefaultFont
Font.getDefaultFont()};
- the stroke style is {@link Graphics#SOLID SOLID}; and
- the origin of the coordinate system is located at the upper-left
corner of the buffer.
return gameCanvasLF.getGraphics();
| | public int | getKeyStates()Gets the states of the physical game keys. Each bit in the returned
integer represents a specific key on the device. A key's bit will be
1 if the key is currently down or has been pressed at least once since
the last time this method was called. The bit will be 0 if the key
is currently up and has not been pressed at all since the last time
this method was called. This latching behavior ensures that a rapid
key press and release will always be caught by the game loop,
regardless of how slowly the loop runs.
For example:
// Get the key state and store it
int keyState = getKeyStates();
if ((keyState & LEFT_KEY) != 0) {
positionX--;
}
else if ((keyState & RIGHT_KEY) != 0) {
positionX++;
}
Calling this method has the side effect of clearing any latched state.
Another call to getKeyStates immediately after a prior call will
therefore report the system's best idea of the current state of the
keys, the latched bits having been cleared by the first call.
Some devices may not be able to query the keypad hardware directly and
therefore, this method may be implemented by monitoring key press and
release events instead. Thus the state reported by getKeyStates might
lag the actual state of the physical keys since the timeliness
of the key information is be subject to the capabilities of each
device. Also, some devices may be incapable of detecting simultaneous
presses of multiple keys.
This method returns 0 unless the GameCanvas is currently visible as
reported by {@link javax.microedition.lcdui.Displayable#isShown}.
Upon becoming visible, a GameCanvas will initially indicate that
all keys are unpressed (0); if a key is held down while the GameCanvas
is being shown, the key must be first released and then pressed in
order for the key press to be reported by the GameCanvas.
return gameCanvasLF.getKeyStates();
| | com.sun.midp.lcdui.GameCanvasLFImpl | getLFImpl()Gets look&feel implementation associated with this GameCanvas
return gameCanvasLF;
| | public void | paint(javax.microedition.lcdui.Graphics g)Paints this GameCanvas. By default, this method renders the
the off-screen buffer at (0,0). Rendering of the buffer is
subject to the clip region and origin translation of the Graphics
object.
gameCanvasLF.drawBuffer(g);
| | private native void | setSuppressKeyEvents(javax.microedition.lcdui.Canvas c, boolean suppressKeyEvents)Set a private field in the Canvas object. We use a
native method to work around the package boundary.
|
|
