UEFI News and Commentary

Sunday, November 13, 2016

The UEFI Maze Game, Part 1

This UEFI Shell application features a very simple maze game that uses UEFI’s Graphics Output protocol to draw a random maze and direct a character from entrance to exit using a keyboard. It will be added to the SVN repository after the last article in this series is published.

This application features a few nifty touches, including converting bitmap (.bmp) files to HII, merging bitmaps using transparency and a nifty maze generation algorithm. This application uses both the standard C library, as well as UEFI-specific libraries.

This game doesn’t have any villains or time limits, yet. Originally, I planned to integrate the thermometer application previously discussed so that the main character got hotter and hotter and little ice cubs in the maze would cool him down. You can add villains in the maze, or the animation could move smoothly from cell to cell or there could be some sort of time limit.

The source is spread over two .C files. It also uses three bitmap files, which are included in the online source code. These bitmaps are: a rock, a player, and a solid green background.

The First Source File: Game.c
Figure 1: Global Variables in Game.c
Lines 1-13
These are the include files for the standard C library, basic UEFI services and, surprise(!) bitmaps. The MdePkg\Include\IndustryStandard contains constants, data structures and file formats from many popular industry standards, including PCI, ACPI and USB.
Lines 15-41
These are the key function declarations from the other source file, Bitmap.c. Rather than create a separate header file, they are just listed here.
Figure 2: Game State Data in Game.c

Next we move on the various global variables that maintain the game state.

Lines 46-47
DisplayImageStack is the global function that refreshes the screen from the internal buffer that holds the game’s bitmap image.
Lines 50-51, 64-65
These globals hold the width of the loaded background images and other images. These should be the same.
Lines 52-54
These point to the three bitmaps used in the game: the rock, the background and the player. Each is 50 x 50 pixels.
Lines 56-58
The game maintains a pixel-for-pixel copy of what is actually going to be displayed on the maze portion of the screen.  All of the player actions are updated here before they are copied to the screen. 
Lines 60-62
The game also maintains a cell-by-cell copy of what is in each part of the grid. The array mGrid contains a two dimensional array, mGridWidth cells wide by mGridHeight cells tall. Each element in the array points to one of the bitmaps: rock, background or player. The size of the array is calculated based on the screen resolution.
Lines 67-74
These mark the coordinates (within mGrid) of the character’s position, the entrance position and the exit position. Initially, the character’s position is at the entrance position. The game ends when the character reaches the exit position.
Figure 3 Game entry point in Game.c

Now that you are thoroughly bored with the global definitions, we finally reach the entry point of the game. 

Lines 590-596
This uses the standard C-style entry point. But there are no command-line options parsed.
Line 598
The srand() function is used to initialize the random number generator with a seed value. In this case, the seed value is derived from the system time. When debugging the maze generation algorithm, it was useful to set this to a fixed value so that the maze would be the same each time, facilitation easier debugging of issues.
Line 600
Reset the console so that the screen is empty.
Lines 602-606
Load all of the bitmap images and convert them into the format used by the UEFI graphics output functions. If there is an error, it means that not all of the images could be loaded or (less likely) the system cannot switch to graphics mode.
Line 608
Initialize the game data structures, including the maze.
Line 610-614
Display the maze for the first time.
Line 616
Enter the main game loop. This loop continues until the user indicates they are finished or they have reached the maze exit.
Line 619-621
Clear the screen and exit.

Figure 4 Setup bitmap images and Graphics Output Protocol in Game.c

The first step for the game is to load all of the bitmaps out of the files.

Lines 108-110
Find the instance of the UEFI Graphics Output protocol.
Lines 112-127
Load each of the three bitmaps from external files. Each of the files is formatted using the industry standard .bmp file format. 

Next Time
In the next installment, we'll look at exactly how to initialize UEFI's Graphics Output Protocol and load a bitmap.

No comments: