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
(first draft of basic display handling)
m
Line 7: Line 7:
  
 
=== Code ===
 
=== Code ===
<source lang="c">
+
<source lang="c" line="1">
 
#include <stdio.h>
 
#include <stdio.h>
 
#include <allegro5/allegro.h>
 
#include <allegro5/allegro.h>
Line 42: Line 42:
 
Now to someone new to Allegro 5, that may look a little intimidating, so we will go through it line by line.
 
Now to someone new to Allegro 5, that may look a little intimidating, so we will go through it line by line.
  
<source lang="c">#include <stdio.h>
+
<source lang="c" line="1">#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 used allegro functions.
 
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 used allegro functions.
  
<source lang="c">int main(int argc, char **argv)
+
<source lang="c" start="4" line>int main(int argc, char **argv)
 
{</source>
 
{</source>
  
 
Just your standard main function definition. Note both arguments are unused, which may cause a compiler warning, it is safe to ignore this warning for now.
 
Just your standard main function definition. Note both arguments are unused, which may cause a compiler warning, it is safe to ignore this warning for now.
  
<source lang="c">if(!al_init()) {
+
<source lang="c" line start="8">if(!al_init()) {
 
       fprintf(stderr, "failed to initialize allegro!\n");
 
       fprintf(stderr, "failed to initialize allegro!\n");
 
       return -1;
 
       return -1;
Line 59: Line 59:
 
Here we initialize the allegro library. Should it fail, it will return false, and the <code>if()</code> block will execute, printing a message to standard error, and exiting.
 
Here we initialize the allegro library. Should it fail, it will return false, and the <code>if()</code> block will execute, printing a message to standard error, and exiting.
  
<source lang="c">display = al_create_display(640, 480);</source>
+
<source lang="c" line start="13">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">  if(!display) {
+
<source lang="c" line start="14">  if(!display) {
 
       fprintf(stderr, "failed to create display!\n");
 
       fprintf(stderr, "failed to create display!\n");
 
       return -1;
 
       return -1;
Line 72: Line 72:
 
Now to the more interesting bits.
 
Now to the more interesting bits.
  
<source lang="c">al_clear_to_color(al_map_rgb(0,0,0));</source>
+
<source lang="c" line start="19">al_clear_to_color(al_map_rgb(0,0,0));</source>
  
 
This here is a two-for-one. <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.
 
This here is a two-for-one. <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.
Line 78: Line 78:
 
And <code>al_clear_to_color</code> clears the current display <ref>the one we just created, but more on this later</ref> to a given color.
 
And <code>al_clear_to_color</code> clears the current display <ref>the one we just created, but more on this later</ref> to a given color.
  
<source lang="c">al_flip_display();</source>
+
<source lang="c" line start="21">al_flip_display();</source>
  
 
This is somewhat interesting. If you're familiar with Allegro 4, it will be totally alien to you. What <code>al_flip_display</code> does is make sure what you did to the display actually shows up. Typically Allegro 5 displays are by default double (or more) buffered. So when you draw to a display, it won't actually show up, you were actually drawing to what is called the "backbuffer". And in order to show that backbuffer, you need to "flip" the buffers.
 
This is somewhat interesting. If you're familiar with Allegro 4, it will be totally alien to you. What <code>al_flip_display</code> does is make sure what you did to the display actually shows up. Typically Allegro 5 displays are by default double (or more) buffered. So when you draw to a display, it won't actually show up, you were actually drawing to what is called the "backbuffer". And in order to show that backbuffer, you need to "flip" the buffers.
  
<source lang="c">al_rest(10.0);</source>
+
<source lang="c" line start="23">al_rest(10.0);</source>
  
 
Here we rest, or sleep for 10 seconds. <code>al_rest</code> takes a floating point integer specifying how many seconds to sleep. And yes, it is perfectly valid to choose 0.5 seconds, or any other floating point number. It will try its best to sleep for the amount of time you picked, but may not be 100% accurate.
 
Here we rest, or sleep for 10 seconds. <code>al_rest</code> takes a floating point integer specifying how many seconds to sleep. And yes, it is perfectly valid to choose 0.5 seconds, or any other floating point number. It will try its best to sleep for the amount of time you picked, but may not be 100% accurate.
  
<source lang="c">al_destroy_display(display);</source>
+
<source lang="c" line start="25">al_destroy_display(display);</source>
  
 
This (obviously?) destroys our display. The display will disappear, and you can't use it any longer.
 
This (obviously?) destroys our display. The display will disappear, and you can't use it any longer.

Revision as of 22:42, June 5, 2010

Displays

Abstract

In this section we teach you how to create a display, and set 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

 1 #include <stdio.h>
 2 #include <allegro5/allegro.h>
 3 
 4 int main(int argc, char **argv)
 5 {
 6    ALLEGRO_DISPLAY *display = NULL;
 7 
 8    if(!al_init()) {
 9       fprintf(stderr, "failed to initialize allegro!\n");
10       return -1;
11    }
12 
13    display = al_create_display(640, 480);
14    if(!display) {
15       fprintf(stderr, "failed to create display!\n");
16       return -1;
17    }
18 
19    al_clear_to_color(al_map_rgb(0,0,0));
20    
21    al_flip_display();
22 
23    al_rest(10.0);
24 
25    al_destroy_display(display);
26 
27    return 0;
28 }

Walk through

Now to someone new to Allegro 5, that may look a little intimidating, so we will go through it line by line.

1 #include <stdio.h>
2 #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 used allegro functions.

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

Just your standard main function definition. Note both arguments are unused, which may cause a compiler warning, it is safe to ignore this warning for now.

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

Here we initialize the allegro library. Should it fail, it will return false, and the if() block will execute, printing a message to standard error, and exiting.

13 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.

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

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

Now to the more interesting bits.

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

This here is a two-for-one. 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.

And al_clear_to_color clears the current display [1] to a given color.

21 al_flip_display();

This is somewhat interesting. If you're familiar with Allegro 4, it will be totally alien to you. What al_flip_display does is make sure what you did to the display actually shows up. Typically Allegro 5 displays are by default double (or more) buffered. So when you draw to a display, it won't actually show up, you were actually drawing to what is called the "backbuffer". And in order to show that backbuffer, you need to "flip" the buffers.

23 al_rest(10.0);

Here we rest, or sleep for 10 seconds. al_rest takes a floating point integer specifying how many seconds to sleep. And yes, it is perfectly valid to choose 0.5 seconds, or any other floating point number. It will try its best to sleep for the amount of time you picked, but may not be 100% accurate.

25 al_destroy_display(display);

This (obviously?) destroys our display. The display will disappear, and you can't use it any longer.

And that concludes our basic introduction to Allegro 5 displays.

Notes

  1. the one we just created, but more on this later