The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

Example ExHello

From Allegro Wiki
Jump to: navigation, search
This article is a stub. Please help Allegro by expanding it.


Hello World!

This page will guide you through how to make a simple application that will say "Hello World" and then quit once the user presses a key. To make this code work you will first need to set up a Compiler and then download and install Allegro. You should be able to find this example in the examples directory of your Allegro installation named 'exhello.c'. This article assumes that you already have a basic knowledge of the C programming language.

The Code

Heres the code for the famous "Hello World" program done through Allegro. Don't worry if its confusing as we'll step through each section and explain it in turn.

<highlightSyntax language="cpp">/*

*    Example program for the Allegro library, by Shawn Hargreaves.
*
*    This is a very simple program showing how to get into graphics
*    mode and draw text onto the screen.
*/


  1. include <allegro.h>


int main(void) {

  /* you should always do this at the start of Allegro programs */
  if (allegro_init() != 0)
     return 1;
  /* set up the keyboard handler */
  install_keyboard(); 
  /* set a graphics mode sized 320x200 */
  if (set_gfx_mode(GFX_AUTODETECT, 320, 200, 0, 0) != 0) {
     if (set_gfx_mode(GFX_SAFE, 320, 200, 0, 0) != 0) {
   set_gfx_mode(GFX_TEXT, 0, 0, 0, 0);
   allegro_message("Unable to set any graphic mode\n%s\n", allegro_error);
   return 1;
     }
  }
  /* set the color palette */
  set_palette(desktop_palette);
  /* clear the screen to white */
  clear_to_color(screen, makecol(255, 255, 255));
  /* you don't need to do this, but on some platforms (eg. Windows) things
   * will be drawn more quickly if you always acquire the screen before
   * trying to draw onto it.
   */
  acquire_screen();
  /* write some text to the screen with black letters and transparent background */
  textout_centre_ex(screen, font, "Hello, world!", SCREEN_W/2, SCREEN_H/2, makecol(0,0,0), -1);
  /* you must always release bitmaps before calling any input functions */
  release_screen();
  /* wait for a keypress */
  readkey();
  return 0;

}

END_OF_MAIN()

</highlightSyntax>

This program will make a small window on windowed operating systems (eg. Windows, Mac, Linux), or capture the whole screen on non-windowed operating systems (eg. DOS, Linux Console). The background will be white and the text Hello World will be written on the screen in the default Allegro font.

Now we will step through each of the different sections of the program in turn, explaining what each section is doing.

<highlightSyntax language="cpp">#include <allegro.h>

</highlightSyntax>

To use Allegro functions you will need to use the #include directive to include the allegro headers.

<highlightSyntax language="cpp">if (allegro_init() != 0)

  return 1;
</highlightSyntax>

This bit of code intiates the library and actually silently handles the shutting down of it as well. If the function fails the program cannot use any allegro functions. It is probably best to just end your program if this is the case, as this example does. The curious can learn more about how allegro_init silently handles shutting down by checking out the documentation for allegro_init and install_allegro.

<highlightSyntax language="cpp">install_keyboard();

</highlightSyntax>

Here we intall the keyboard drivers. This allows us to use the readkey function and check the status of certain keys (eg. if they're pressed or not). Although this example program assumes this function will succeed, it is possible that it will fail. If the return value is non-zero, the keyboard could not be installed. If this is the case your program will either have to make due without keyboard input or quit and hopefully display an error.

<highlightSyntax language="cpp">if (set_gfx_mode(GFX_AUTODETECT, 320, 200, 0, 0) != 0) {

if (set_gfx_mode(GFX_SAFE, 320, 200, 0, 0) != 0) {
 set_gfx_mode(GFX_TEXT, 0, 0, 0, 0);
 allegro_message("Unable to set any graphic mode\n%s\n", allegro_error);
 return 1;
}

}

</highlightSyntax>

First we call the function set_gfx_mode. This function loads a new window for us to use, which we can access through the variable screen. The function takes 5 parameters. The first specifies which driver to use when creating the window. For our first try at the function we use GFX_AUTODETECT. This is a magic driver that will try all available drivers until it finds one that will work. The next two variables specify the width and height of the window to capture respectively. We want a window that is 320 wide and 200 tall so we pas these two values. The last two values specify the amount of memory we want to allocate on the graphics card. For now we will just ignore these by setting them to 0. The curious can look at the documentation for set_gfx_mode.

If set_gfx_mode fails, it will return a non-zero value. If this happens, we try calling set_gfx_mode again, but this time with GFX_SAFE as the driver. This is another magic driver that is guaranteed to work if any sort of graphics window can be rendered on this computer at all, even if it requires changing the width and the height to do so.

If set_gfx_mode fails again, no graphics mode will work on the computer at all. What we do now is alert the user that this is the case and quit the program. allegro_message is designed to give a proper error message depending on the operating system (for example on windows it will display a small alert box, while on DOS it will print the message to the screen). Before this function can be used, set_gfx_mode should be called with GFX_TEXT as its driver parameter. GFX_TEXT should not fail, so it is unnecessary to check the return value.

allegro_message's parameters are the same as the parameters passed to printf. The first parameter is the format string specifying what the message will be. Following that are a variable number of parameters specified in the format string. In the example we simply display "Unable to set any graphic mode" followed by the string pointed to by allegro_error on its own line. allegro_error will hold a short description of what went wrong, so the user is not left totally in the dark. After alerting the user the example quits the program.

<highlightSyntax language="cpp"> </highlightSyntax>