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

Difference between revisions of "Allegro 5 Tutorial/Displays"

From Allegro Wiki
Jump to: navigation, search
m (standarizing)
Line 1: Line 1:
= Displays =
 
== Abstract ==
 
 
In this section we will walk through a simple example, explaining how to create a display and setting optional properties for the display.
 
In this section we will walk through a simple example, explaining how to create a display and setting optional properties for the display.
  
== Basic Example ==
 
Here we demonstrate how to create a display, clear the display, display it for 10 seconds, and exit.
 
 
=== Code ===
 
 
<source lang="c">
 
<source lang="c">
 
#include <stdio.h>
 
#include <stdio.h>
 
#include <allegro5/allegro.h>
 
#include <allegro5/allegro.h>
  
int main(int argc, char **argv)
+
int main(int argc, char **argv){
{
+
 
 
   ALLEGRO_DISPLAY *display = NULL;
 
   ALLEGRO_DISPLAY *display = NULL;
  
Line 42: Line 36:
 
These walk throughs will explain important lines of code in the examples.
 
These walk throughs will explain important lines of code in the examples.
  
<source lang="c" line="1">#include <stdio.h>
+
<source lang="c">#include <stdio.h>
 
#include <allegro5/allegro.h></source>
 
#include <allegro5/allegro.h></source>
  
 
Here we include the headers necessary for this example. <code>stdio.h</code> is required for the <code>fprintf</code> function, and <code>allegro5/allegro.h</code> is necessary for all of the allegro functions that are used in this example.
 
Here we include the headers necessary for this example. <code>stdio.h</code> is required for the <code>fprintf</code> function, and <code>allegro5/allegro.h</code> is necessary for all of the allegro functions that are used in this example.
  
<source lang="c" start="4" line>int main(int argc, char **argv)
+
<source lang="c">int main(int argc, char **argv)
 
{</source>
 
{</source>
  
 
A standard main function, with the argument count and argument vector parameters.
 
A standard main function, with the argument count and argument vector parameters.
  
<source lang="c" line start="8">if(!al_init()) {
+
<source lang="c">if(!al_init()) {
 
       fprintf(stderr, "failed to initialize allegro!\n");
 
       fprintf(stderr, "failed to initialize allegro!\n");
 
       return -1;
 
       return -1;
Line 59: Line 53:
 
Here we initialize the Allegro library. If it should fail, it will return false, and the <code>if()</code> block will execute, printing a message to standard error, and then exit.
 
Here we initialize the Allegro library. If it should fail, it will return false, and the <code>if()</code> block will execute, printing a message to standard error, and then exit.
  
<source lang="c" line start="13">display = al_create_display(640, 480);</source>
+
<source lang="c">display = al_create_display(640, 480);</source>
  
 
<code>al_create_display</code> will create a display with the given width and height. Should <code>al_create_display</code> fail to create a display for some reason, it will return <code>NULL</code>.
 
<code>al_create_display</code> will create a display with the given width and height. Should <code>al_create_display</code> fail to create a display for some reason, it will return <code>NULL</code>.
  
<source lang="c" line start="14">  if(!display) {
+
<source lang="c">  if(!display) {
 
       fprintf(stderr, "failed to create display!\n");
 
       fprintf(stderr, "failed to create display!\n");
 
       return -1;
 
       return -1;
Line 70: Line 64:
 
Should <code>al_create_display</code> fail, we trigger this if block, print a failure message, and then exit.
 
Should <code>al_create_display</code> fail, we trigger this if block, print a failure message, and then exit.
  
<source lang="c" line start="19">al_clear_to_color(al_map_rgb(0,0,0));</source>
+
<source lang="c">al_clear_to_color(al_map_rgb(0,0,0));</source>
  
 
<code>al_map_rgb</code> takes three arguments, the value for the red, green, and blue components of the color respectively, and will return a <code>ALLEGRO_COLOR</code> structure.
 
<code>al_map_rgb</code> takes three arguments, the value for the red, green, and blue components of the color respectively, and will return a <code>ALLEGRO_COLOR</code> structure.
 
<code>al_clear_to_color</code> clears the current display <ref>the one we just created</ref> to a given color.
 
<code>al_clear_to_color</code> clears the current display <ref>the one we just created</ref> to a given color.
  
<source lang="c" line start="21">al_flip_display();</source>
+
<source lang="c">al_flip_display();</source>
  
 
Allegro, by default, creates two image buffers -- the one being displayed on the screen, and the one being drawn on in the code. When you have finished drawing to one of the image buffers for one loop, then you are ready to display its result to the screen for the user. <code>al_flip_display</code> is called to swap the two image buffers around so that the first image buffer is now displayed to the user while the second image buffer becomes the one you will draw on. Failing to call this function will result in only the single, blank image buffer being shown on the screen.
 
Allegro, by default, creates two image buffers -- the one being displayed on the screen, and the one being drawn on in the code. When you have finished drawing to one of the image buffers for one loop, then you are ready to display its result to the screen for the user. <code>al_flip_display</code> is called to swap the two image buffers around so that the first image buffer is now displayed to the user while the second image buffer becomes the one you will draw on. Failing to call this function will result in only the single, blank image buffer being shown on the screen.
  
<source lang="c" line start="23">al_rest(10.0);</source>
+
<source lang="c">al_rest(10.0);</source>
  
 
Here we rest the program for 10 seconds. <code>al_rest</code> takes a floating point integer specifying how many seconds to sleep. Using any valid floating point number is valid, including numbers less than 1.0. Allegro will attempt to sleep for the amount of time specified, but it does not have perfect accuracy.
 
Here we rest the program for 10 seconds. <code>al_rest</code> takes a floating point integer specifying how many seconds to sleep. Using any valid floating point number is valid, including numbers less than 1.0. Allegro will attempt to sleep for the amount of time specified, but it does not have perfect accuracy.
  
<source lang="c" line start="25">al_destroy_display(display);</source>
+
<source lang="c">al_destroy_display(display);</source>
  
 
This function destroys our display and frees the memory and should be called when you are about to shut down the program.
 
This function destroys our display and frees the memory and should be called when you are about to shut down the program.
Line 89: Line 83:
 
And that concludes our basic introduction to Allegro 5 displays.
 
And that concludes our basic introduction to Allegro 5 displays.
  
[[../|Up]] >> [[../Events|Next]]
 
  
= Notes =
+
----
 
<references/>
 
<references/>

Revision as of 11:36, November 25, 2011

In this section we will walk through a simple example, explaining how to create a display and setting optional properties for the display.

#include <stdio.h>
#include <allegro5/allegro.h>

int main(int argc, char **argv){
   
   ALLEGRO_DISPLAY *display = NULL;

   if(!al_init()) {
      fprintf(stderr, "failed to initialize allegro!\n");
      return -1;
   }

   display = al_create_display(640, 480);
   if(!display) {
      fprintf(stderr, "failed to create display!\n");
      return -1;
   }

   al_clear_to_color(al_map_rgb(0,0,0));
   
   al_flip_display();

   al_rest(10.0);

   al_destroy_display(display);

   return 0;
}

Walk through

These walk throughs will explain important lines of code in the examples.

#include <stdio.h>
#include <allegro5/allegro.h>

Here we include the headers necessary for this example. stdio.h is required for the fprintf function, and allegro5/allegro.h is necessary for all of the allegro functions that are used in this example.

int main(int argc, char **argv)
{

A standard main function, with the argument count and argument vector parameters.

if(!al_init()) {
      fprintf(stderr, "failed to initialize allegro!\n");
      return -1;
}

Here we initialize the Allegro library. If it should fail, it will return false, and the if() block will execute, printing a message to standard error, and then exit.

display = al_create_display(640, 480);

al_create_display will create a display with the given width and height. Should al_create_display fail to create a display for some reason, it will return NULL.

   if(!display) {
      fprintf(stderr, "failed to create display!\n");
      return -1;
   }

Should al_create_display fail, we trigger this if block, print a failure message, and then exit.

al_clear_to_color(al_map_rgb(0,0,0));

al_map_rgb takes three arguments, the value for the red, green, and blue components of the color respectively, and will return a ALLEGRO_COLOR structure. al_clear_to_color clears the current display [1] to a given color.

al_flip_display();

Allegro, by default, creates two image buffers -- the one being displayed on the screen, and the one being drawn on in the code. When you have finished drawing to one of the image buffers for one loop, then you are ready to display its result to the screen for the user. al_flip_display is called to swap the two image buffers around so that the first image buffer is now displayed to the user while the second image buffer becomes the one you will draw on. Failing to call this function will result in only the single, blank image buffer being shown on the screen.

al_rest(10.0);

Here we rest the program for 10 seconds. al_rest takes a floating point integer specifying how many seconds to sleep. Using any valid floating point number is valid, including numbers less than 1.0. Allegro will attempt to sleep for the amount of time specified, but it does not have perfect accuracy.

al_destroy_display(display);

This function destroys our display and frees the memory and should be called when you are about to shut down the program.

And that concludes our basic introduction to Allegro 5 displays.



  1. the one we just created