FreeBASIC Allegro Tutorial 1
----------------------------

Written by: Gustav (UbeltaterSchatten@Hotmail.com)
Also available at: http://ee.1asphost.com/dbent/Gustav/tut01.txt

----------------------------

Someone recently told me about freeBASIC and I've been a C++ programmer for awhile now so I decided to port a basic allegro application from C++ to freeBASIC and write a tutorial about it.

The first thing you must always do when creating a freeBASIC allegro application is declear the
library like this;

freeBASIC                                     C++
'$include "allegro.bi"                        #include <allegro.h>

The next thing I'll be doing is declearing some constant variables. This is done by using the
define statement. This is then followed by a variable and then its parameter like in the
following syntax;

freeBASIC                                     C++
#define SCREEN_WIDTH  640                     #define SCREEN_WIDTH  640
#define SCREEN_HEIGHT 480                     #define SCREEN_HEIGHT 480

This is particulairly useful because if your program becomes very large and you want to change
one of the variables you only change it in the define statement. As opposed to changing it at
every statement in the program that uses the variable.

Next, we need to create our procedures/subs. I'll be creating one procedure that initiates
allegro, one for the main loop and one that exits the program. The first procedure will contain
a statement that initiates allegro, the next will install they keyboard and the third will set
the graphics mode.

freeBASIC                                     C++
sub rs_init_allegro()                         void rs_init_allegro(void) {
  allegro_init                                  allegro_init();
  install_keyboard()                            install_keyboard();
  set_gfx_mode(GFX_AUTODETECT, SCREEN_WIDTH,    set_gfx_mode(GFX_AUTODETECT, SCREEN_WIDTH,
               SCREEN_HEIGHT, 0, 0)                          SCREEN_HEIGHT, 0, 0)
end sub                                       }

GFX_AUTODETECT is the mode in which the application will be displayed, also known as the screen-
mode. This particulair screen-mode sets the application at full-screen but if the resolution is
not allowed it detects that, and sets the mode to windowed. There are also many other screen-
modes such as the following;

-GFX_TEXT
  Returns to text-mode
-GFX_AUTODETECT_FULLSCREEN
  Returns appropiate screen-mode in full-screen, only if supported by operating system
-GFX_AUTODETECT_WINDOWED
  Returns appropiate windowed screen-mode
-GFX_SAFE
  Returns a random screen-mode most appropiate for operating system
-GFX_FBCON
  Uses the frame buffer
-GFX_VGA
  Sets standard VGA mode

The next procedure we'll be creating is the main procedure that will handle the main loop. It
will also detect whether you have pressed the ESC key and if so, it will then exit the loop. It
should look something like this;

freeBASIC                                    C++
sub rc_main_loop()                           void rc_main_loop(void)
  do                                           while (!key[KEY_ESC)
    if (*(@al_key+KEY_ESC) <> 0) then          {
      exit do
    end if                                     }
  loop                                       }
end sub

The last procedure necessary to write a basic allegro program is the procedure that exits the
program. It should close any bitmaps that were loaded or created. It is quite simple and should
look like this;

freeBASIC                                   C++
sub rc_exit()                               void rc_exit(void) {
  allegro_exit()                              allegro_exit();
end sub                                     }

The allegro_exit() function is not necessary to exit the application but it is always good to
include it. Next on our list is the main body of code. In this section of code we simply call all
the procedures we've created and then end the program.

freeBASIC                                   C++
  rs_init_allegro()                         int main(int argc, char *argv) {
  rs_main_loop()                              rs_init_allegro();
  rs_exit()                                   rs_main_loop();
end 0                                         rs_exit();
                                            } END_OF_MAIN();

Now that you've finished writing your code it should look something like this;

'' Simple Alegro Window Programmed by Gustav

'' Declear Libraries
'$include: "allegro.bi"

'' Definitions
#define SCREEN_WIDTH  640
#define SCREEN_HEIGHT 480

'' Procedures
sub rs_init_allegro()
   allegro_init '' Install allegro
   install_keyboard() '' Install keyboard
   set_gfx_mode(GFX_AUTODETECT, SCREEN_WIDTH, SCREEN_HEIGHT, 0, 0) '' Set graphics mode
end sub

sub rs_main_loop()
   do
      if (*(@al_key+KEY_ESC) <> 0) then '' Determin is ESC is pressed
         exit do '' Exit loop
      end if
   loop
end sub

sub rs_exit()
   allegro_exit() '' Exits allegro
end sub

'' Main Procedure
   rs_init_allegro() '' Install allegro & set graphics
   rs_main_loop() '' Begin main loop
   rs_exit() '' Exit application
end 0