Programming Wireless Devices with the Java2 Platform

12.1 The GameCanvas API

The Canvas class was designed for applications that are event-driven; that is, the user interface is updated in response to a user input, such as selecting an option or pressing a soft key. However, game applications are generally time-driven and continue to run and update the display whether or not the user provides input. To overcome this difference, the GameCanvas class provides a game-centric model for accessing the display and checking for key inputs.

Game applications typically employ a single thread to run the game. This thread executes a main loop, shown in Figure 12.1, that repeatedly checks for user input, implements logic to update the state of the game, and then updates the user interface to reflect the new state. Unlike Canvas, the GameCanvas class provides methods that directly support this programming model.

12.1.1 Key Polling

The GameCanvas class also provides the ability to poll the status of the keys instead of having to implement callback methods to process each key event. Key polling allows all of the application's key handling logic to be coded together and executed at the appropriate point in the game loop. It also enables simultaneous key presses to be detected on devices that support them.

The getKeyStates method returns the key state in the form of an integer value in which each bit indicates whether a specific key is pressed or has been pressed since the last invocation of the getKeyStates method. This latching behavior allows very quick key presses to be detected even if the game loop is running fairly slowly. If the current state of the keys is desired without the latching behavior, the getKeyStates method can be called twice.

To determine whether or not a specific key is pressed, the integer value is AND-ed with one of the key polling constants defined in GameCanvas, as shown in the following example:

int keyStates = getKeyStates();
if ((keyStates & UP_PRESSED) != 0) yPosition--;
if ((keyStates & DOWN_PRESSED) != 0) yPosition++;
if ((keyStates & FIRE_PRESSED) != 0) fireRocket();

12.1.2 Screen Buffer

Unlike Canvas (which shares screen resources with other applications), each GameCanvas object has its own dedicated screen buffer, which the developer can draw on at any time using a Graphics object. Graphics objects are obtained by calling method getGraphics. Multiple Graphics objects can be created if desired.

Changes to the screen buffer contents are limited to rendering calls made by the application, so the buffer can be updated incrementally instead of being completely rendered for each frame.

Synchronous methods are provided for flushing the contents of the buffer to the physical display, so continuous animations are much easier to implement than with the asynchronous repainting model of the Canvas class. The flushGraphics methods flush the contents of the buffer to the physical display, either for the entire buffer or for a specific region of the buffer. These methods do nothing if the GameCanvas is not currently shown.