Published: August 22, 2008
Revised: August 23, 2008
by Richard G. Baldwin
File: Allegro00110
This lesson is part of a series (see Resources) designed to teach you how to use Allegro to do graphics programming in C++. My purpose in writing the series is to provide lecture and lab material for a course titled Game Development Using C++ that I teach at Austin Community College in Austin, Texas. However, if you have stumbled upon this series and you find it useful, you are welcome to study it.
I recommend that you open another copy of this document in a separate browser window and use the following links to easily find and view the figures and listings while you are reading about them.
I recommend that you also study the other lessons in my extensive collection of online programming tutorials. You will find a consolidated index at www.DickBaldwin.com.
In this lesson, we will examine the source code for an Allegro project that produces the graphical screen output shown in Figure 1.
Figure 1. Screen output for HelloWorld01 project.
|
|
A complete listing of the source code for the project is shown in Listing 9 near the end of the lesson. I will explain that code in fragments.
According to C++ Game Programming (see Resources), when programming with Allegro, you no longer need to include iostream. Allegro includes all of the functions that you will need, at least for the lessons in the early part of this series. However, we do have to include allegro.h as shown by the code fragment in Listing 1.
Listing 1. Required header file for Allegro.
#include <allegro.h> |
According to Jay Bernardo (see Resources) the call to allegro_init shown in Listing 2 is required at the beginning of the program. This call will set up all the components that Allegro needs in order to run. Bernardo tells us, "This function basically does all the hard stuff for you."
Listing 2. Initialize Allegro.
int main(){
allegro_init();
|
Install the keyboard interrupt handler
According to allegro.cc (see Resources), the function call in Listing 3 installs the Allegro keyboard interrupt handler.
Listing 3. Install the keyboard interrupt handler.
install_keyboard(); |
You must call the function shown in Listing 3 before using any of the keyboard input routines. Once you have set up the Allegro handler, you can no longer use operating system calls or C library functions to access the keyboard.
The function call in Listing 4 sets the graphics mode to a 320x240-pixel window as shown in Figure 1.
Listing 4. Set the graphics mode.
set_gfx_mode(GFX_AUTODETECT_WINDOWED, 320,240,0,0); |
The first parameter in the function call in Listing 4 sets the graphics mode to a window whose rectangular size is specified by the second and third parameters.
According to allegro.cc, there are five alternative graphics modes that behave in different ways. For example, the graphics mode identified by GFX_AUTODETECT attempts to map a rectangle specified by the dimensions in the second and third parameters to the full screen, even if the height-to-width ratio of the screen is different from the height-to-width ratio of the rectangle. This can do bad things to the aspect ratio of shapes such as circles.
The virtual screen size
According to allegro.cc, the last two parameters in Listing 4 can be used to specify a minimum virtual screen size in case you need a large virtual screen for hardware scrolling or page flipping. You should set these two parameters to zero if you don't need a large virtual screen, and that is exactly what we will be doing in the lessons in the early part of this series.
The call to the textout_ex function in Listing 5 draws the text "HELLO WORLD" on the graphics screen as shown in Figure 1.
Listing 5. Draw text on the window.
textout_ex(screen,//Specify bitmap on the screen
font,//Use a default font
"HELLO WORLD",//Specify the text to display
20,//X-coordinate for text
30,//Y-coordinate for text
makecol(255,255,0),//Color text yellow
makecol( 255,0,0) );//Put red behind text
|
|
A more precise description
More precisely, according to allegro.cc, the call to the function named textout_ex in Listing 5 writes the string "HELLO WORLD" onto the bitmap pointed to by the value of the variable named screen at position 20,30, using the font pointed to by the variable named font with the color of the characters specified by the RGB color value 255,255,0 (yellow) and the color of the area behind the characters specified by 255,0,0 (red).
Special transparency considerations
Special transparency considerations apply if either or both of the color values are specified as -1. For example, setting the second color parameter to -1 and leaving the first color parameter at yellow produces the screen output shown in Figure 2.
Figure 2. Output for second color parameter set to -1.
|
|
In Figure 2, the area behind the characters has become transparent allowing the color of the window to show through.
Output for first color parameter set to -1
Setting the first color parameter to -1 and leaving the second color parameter at red produces the output shown in Figure 3.
Figure 3. Output for first color parameter set to -1.
|
|
Apparently in this case, instead of making the characters transparent, they are made opaque white by default. You can read about this at allegro.cc.
Output for both color parameters set to -1
Finally, setting both color parameters to -1 produces white characters on a transparent background as shown in Figure 4.
Figure 4. Output for both color parameters set to -1.
|
|
Block and wait for a user keystroke
If we didn't do something to prevent it from happening, control would fall through the main function very quickly and at most we might see a flash on the screen as the window shown in Figure 1 appears and then disappears.
Listing 6 shows a common trick that is often used to prevent such a thing from happening, particularly in college computer labs.
Listing 6. Block and wait for a user keystroke.
readkey(); |
The call to the readKey function in Listing 6 returns the next character from the keyboard buffer in ASCII format. If the buffer is empty, it blocks and waits until a key is pressed. As a result, the window shown in Figure 1 remains on the screen until you press a key, at which time it disappears. In this case, the program simply ignores the value of the keystroke that is returned.
Return a zero and terminate
The return statement in Listing 7 returns a value of zero, which by convention means that the program terminated properly. Then the main function terminates, causing the program to terminate.
Listing 7. Return a zero and terminate.
return 0;//Return 0 to indicate a successful run. }//end main function |
A macro that is specific to Allegro
According to allegro.cc, in order to maintain cross-platform compatibility, you must put the macro shown in Listing 8 at the very end of your main function. This macro requirement is specific to Allegro.
Listing 8. A macro that is specific to Allegro.
END_OF_MAIN() |
In this lesson, I explained a project containing the minimum source code required to put a graphics window on the screen and to draw some text in that window as shown in Figure 1.
Listing 9. Source code for project HelloWorld01.
//Project HelloWorld01
#include <allegro.h>
int main(){
allegro_init();//Allegro initialization
install_keyboard();//Set up for keyboard input
//Set the graphics mode to a 320x240-pixel window.
set_gfx_mode(GFX_AUTODETECT_WINDOWED, 320,240,0,0);
//Draw text on the window.
textout_ex(screen,//Specify bitmap on the screen
font,//Use a default font
"HELLO WORLD",//Specify the text to display
20,//X-coordinate for text
30,//Y-coordinate for text
makecol(255,255,0),//Color text yellow
makecol( 255,0,0) );//Put red behind text
//Block and wait until the user presses a key.
readkey();
return 0;//Return 0 to indicate a successful run.
}//end main function
//The following macro is peculiar to Allegro.In order to
// maintain cross-platform compatibility, you have to put
// this macro at the very end of your main function.
END_OF_MAIN()
|
Copyright 2008, Richard G. Baldwin. Reproduction in whole or in part in any form or medium without express written permission from Richard Baldwin is prohibited.
Richard has participated in numerous consulting projects and he frequently provides onsite training at the high-tech companies located in and around Austin, Texas. He is the author of Baldwin's Programming Tutorials, which have gained a worldwide following among experienced and aspiring programmers. He has also published articles in JavaPro magazine.
In addition to his programming expertise, Richard has many years of practical experience in Digital Signal Processing (DSP). His first job after he earned his Bachelor's degree was doing DSP in the Seismic Research Department of Texas Instruments. (TI is still a world leader in DSP.) In the following years, he applied his programming and DSP expertise to other interesting areas including sonar and underwater acoustics.
Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.
-end-
