Up till this point in our ongoing Allegro Tutorial Series we have covered creating a window, handling a game loop, drawing sprites, handling input and playing audio, pretty much every aspect of creating a basic game.  In this final tutorial we are going to look at some of the other graphics capabilities in Allegro, specifically graphics primitives.

If you’ve been following the tutorial series till this point, it should come has no surprise that primitives are implemented as an add-on as well.  In this case it’s using the Primitives add-on:

Without further ado, let’s jump straight into the code example:

#include "stdafx.h"
#include <allegro5\allegro.h>
#include <allegro5\allegro_primitives.h>

int main()
{
	ALLEGRO_DISPLAY * display;

	al_init();
	display = al_create_display(640, 480);
	al_init_primitives_addon();
	float points[8] = {0.0f, 0.0f, 100.00f, 100.00f, 200.00f, 100.00f, 640.00f, 150.00f};

	float polygon[8] = { 640.0f, 100.0f, 640.0f, 300.0f, 380.0f, 350.0f, 200.0f, 200.0f };

	bool running = true;
	while (running) {
		al_draw_line(0, 0, al_get_display_width(display), al_get_display_height(display), al_map_rgb(255, 0, 0),5.0);
		al_draw_rectangle(100, 100, 300, 300, al_map_rgb(0, 255, 0), 1);
		al_draw_ellipse(300, 300, 120, 50, al_map_rgb(0, 0, 255), 3);

		al_draw_spline(points, al_map_rgb(128, 128, 0), 8);

		//al_draw_polygon(polygon, 8, ALLEGRO_LINE_JOIN_BEVEL, al_map_rgb(255, 15, 15),3,1);
		al_draw_filled_polygon(polygon, 8, al_map_rgb(255, 0, 0));
		al_flip_display();
	}

	al_destroy_display(display);
	
	return 0;
}

When you run this example you should see:

Granted, a pretty chaotic mess in the end, but illustrating a number of concepts in a single example.  First we start off by calling the appropriate init() method for the Primitives add-on.  When then draw a line in red ( R = 255, G = 0, B=0 ) from the top left to the bottom right corner of our display.  Next we illustrate drawing a rectangle, followed by an eclipse.  Finally we illustrate a slightly more advanced example of drawing a spline, then a polygon, by providing an array of points/vertices to draw.  As you can notice from the commented function, there are also functions specifically for drawing primitives fill with a solid colour.

We have only scratched the surface of the drawing functionality the Primitive add-on is capable of in this example, but the basic concept applies to all functions.

That concludes the tutorial series and should hopefully give you a good foundation on getting started with Allegro.  If you wish to jump into more depth with Allegro, be sure to check out the official manual available here.

Back To Table Of Contents

Programming 2D CPP Tutorial

In the first tutorial we looked at creating our initial application, while in the second tutorial we looked at events and a cleaner game loop, in the third tutorial we looked at drawing bitmaps on screen.  We then moved on to handling the keyboard and mouse while in this tutorial we are going to cover handling audio in Allegro.

Once again, lets jump straight into the code example.

#include "stdafx.h"
#include <allegro5/allegro.h>
#include <allegro5/allegro_audio.h>
#include <allegro5/allegro_acodec.h>

int main()
{
	ALLEGRO_DISPLAY *display = NULL;
	ALLEGRO_SAMPLE *sample = NULL;
	ALLEGRO_SAMPLE_INSTANCE *sampleInstance = NULL;

	al_init();
	al_install_audio();
	al_init_acodec_addon();
	
	al_reserve_samples(1);

	sample = al_load_sample("explode.wav");

	// The commented out version below is much easier
	//al_play_sample(sample, 1.0, 0, 1, ALLEGRO_PLAYMODE_LOOP,NULL);

	//However if you need access to additional control, such as currently playing position, you need
	//to attach it to a mixer, like the following example
	sampleInstance = al_create_sample_instance(sample);
	al_attach_sample_instance_to_mixer(sampleInstance, al_get_default_mixer());
	al_play_sample_instance(sampleInstance);

	// Loop until sound effect is done playing
	while (al_get_sample_instance_playing(sampleInstance)) {}

	al_destroy_sample_instance(sampleInstance);
	al_destroy_sample(sample);
	al_uninstall_audio();
}

At this point it should come as no surprise that audio support in Allegro is implemented as an add-on.  In fact it’s implemented as a pair of add-ons.

The audio add-on implements the audio playback functionality, while the Codec add-on is what supports loading the various different audio file formats.  Speak of file formats, Allegro supports the following file formats: .wav, .flac, .ogg, .opus, .it, .mod, .s3m, .xm and .voc.  Since they are implemented as add-ons, we once again need to call the corresponding init or install function before we can use audio functions.

Audio files are loading into memory as samples.  Before we go to far, we need to reserve resources for the samples we are going to use.  In this simple example we have only a single example, thus we call al_reserve_samples(1).  Now that our resources are allocated, we actually load the sample from disk with a call to al_load_sample(), in this case I am passing in a sample named “explode.wav”, which I have copied into my debug directory. 

Now that our sample is loaded into memory there are two ways to access it.  One is very simple, a fire and forget function you can see commented in the example above.

	al_play_sample(sample, 1.0, 0, 1, ALLEGRO_PLAYMODE_LOOP,NULL);

This is the easiest way by far to play audio in Allegro.  This example will play the sample “sample” at normal volume (gain), centered, at regular 1x speed, in a constant loop.

If you want a bit more control over the audio playback however, this function will no longer suffice.  So for example if you want to be able to determine when a sample is done playing, you instead need to create a SAMPLE_INSTANCE, which is done by passing our sample to al_create_sample_instance().  We also need a mixer to actually play the instance, which thankfully there is one already available for us, accessible using the function al_get_default_mixer(). 

Notice that both the sample and instance need to be cleaned up after use or they will leak resources.  Not shown in this tutorial, there are also streaming functions for breaking larger audio files up into smaller chunks for streaming.  In this day of abundant RAM, these functions are less used, so I have not covered them here.

Back to Table Of Contents

Programming 2D CPP Tutorial

In the first tutorial we looked at creating our initial application, while in the second tutorial we looked at events and a cleaner game loop then in the third tutorial we looked at drawing bitmaps on screen.  Today we are going to look at handling keyboard and mouse input.  We covered this slightly in earlier tutorials when we looked at event queues and enabled the application to exit when the user pressed a key.  This tutorial will go into a great deal more depth.  Without further ado, let’s jump into the code sample:

#include "stdafx.h"
#include <allegro5\allegro.h>
#include <allegro5\allegro_image.h>

int main()
{
	ALLEGRO_DISPLAY * display;
	ALLEGRO_EVENT_QUEUE *queue;
	ALLEGRO_BITMAP * bitmap = NULL;

	al_init();
	display = al_create_display(640, 480);
	queue = al_create_event_queue();

	al_install_keyboard();
	al_install_mouse();

	al_register_event_source(queue, al_get_keyboard_event_source());
	al_register_event_source(queue, al_get_display_event_source(display));
	al_register_event_source(queue, al_get_mouse_event_source());

	al_init_image_addon();
	
	bitmap = al_load_bitmap("image64x64.jpg");
	assert(bitmap != NULL);

	bool running = true;
	float x = 0, y = 0;

	int width = al_get_display_width(display);
	while (running) {
		al_clear_to_color(al_map_rgba_f(0, 0, 0, 1));
		al_draw_bitmap(bitmap, x, y, 0);
		al_flip_display();

		ALLEGRO_EVENT event;

		if (!al_is_event_queue_empty(queue)) {
			al_wait_for_event(queue, &event);
			if (event.type == ALLEGRO_EVENT_DISPLAY_CLOSE)
				running = false;


			if (event.type == ALLEGRO_EVENT_MOUSE_AXES) {
				x = event.mouse.x;
				y = event.mouse.y;
			}

			if (event.type == ALLEGRO_EVENT_MOUSE_BUTTON_UP) {
				x = y = 0;
				al_set_mouse_xy(display, 0, 0);
			}
		}

		// Actively poll the keyboard
		ALLEGRO_KEYBOARD_STATE keyState;

		al_get_keyboard_state(&keyState);
		if (al_key_down(&keyState, ALLEGRO_KEY_RIGHT))
			if (al_key_down(&keyState, ALLEGRO_KEY_LCTRL))
				x += 0.1;
			else
				x += 0.01;
		if (al_key_down(&keyState, ALLEGRO_KEY_LEFT))
			if (al_key_down(&keyState, ALLEGRO_KEY_LCTRL))
				x -= 0.1;
			else
				x -= 0.01;
	}

	al_destroy_display(display);
	al_uninstall_keyboard();
	al_uninstall_mouse();
	al_destroy_bitmap(bitmap);

	return 0;
}

When you run this application, the sprite will be drawn in the position of the mouse cursor.  Clicking and mouse button will reset the sprite’s position back to (0,0).  You can also control the position of the sprite by using the left and right arrow keys.

As we can see mouse and keyboard functionality is optional, so we need to call the appropriate init() function for both devices, then later the appropriate uninstall() function to clean them up.  Just like earlier we create an event queue, and register additional event sources for both keyboard and mouse.  As you can see, multiple event types can exist in a single event queue.

Mouse handling is extremely straight forward, when the mouse is moved it will fire a ALLEGRO_MOUSE_AXES_EVENT with the mouse location stored in the events mouse.x and mouse.y properties.  You can also see that mouse button activity fire a ALLEGRO_MOUSE_BUTTON_UP_EVENT when a mouse button is released.  In this case we set the position of the mouse using al_set_mouse_xy().

We take a slightly different approach with keyboard handling.  We could use a similar approach, however it would only handle one key event at a time.  What we instead want to do is poll the current status of the keyboard every pass through our game loop.  We take this approach so we can detect multiple concurrent key presses.  This is done by populating a ALLEGRO_KEYBOARD_STATE structure with a call to al_get_keyboard_state().  We can then poll the status of individual keys by calling al_key_down().

Back to Table Of Contents

Programming CPP Tutorial 2D

In the first tutorial we looked at creating our initial application, while in the second tutorial we looked at events and a cleaner game loop.  Today we get to the fun stuff… drawing bitmaps to the screen.  If you are from another game engine, the term bitmap in Allegro might be a bit misleading as it generally represents an image on disk.  In Allegro terms a bitmap is much more, basically its an all in one term for images that can be load and displayed on screen, taking the role often reserved for sprites in other game libraries.  Let’s just jump into the example:

#include "stdafx.h"
#include <allegro5\allegro.h>
#include <allegro5\allegro_image.h>

int main()
{
	ALLEGRO_DISPLAY * display;
	ALLEGRO_EVENT_QUEUE *queue;
	ALLEGRO_BITMAP * bitmap = NULL;

	al_init();
	display = al_create_display(640, 480);
	queue = al_create_event_queue();

	al_install_keyboard();
	al_register_event_source(queue, al_get_keyboard_event_source());
	al_register_event_source(queue, al_get_display_event_source(display));

	al_init_image_addon();
	bitmap = al_load_bitmap("image.jpg");
	assert(bitmap != NULL);

	bool running = true;
	float x = 0;

	int width = al_get_display_width(display);
	while (running) {
		al_clear_to_color(al_map_rgba_f(1, 1, 1, 1));
		al_draw_bitmap(bitmap, x += 0.01, 0, 0);
		al_flip_display();


		if (x > width) x = -al_get_bitmap_width(bitmap);

		ALLEGRO_EVENT event;

		if (!al_is_event_queue_empty(queue)) {
			al_wait_for_event(queue, &event);
			if (event.type == ALLEGRO_EVENT_KEY_UP || event.type == ALLEGRO_EVENT_DISPLAY_CLOSE)
				running = false;
		}
	}

	al_destroy_display(display);
	al_uninstall_keyboard();
	al_destroy_bitmap(bitmap);

	return 0;
}

Most of the code has already been explained in the previous tutorials, so lets jump right into the new code.  You will notice we are using another add-on in this example, the image add on.  This is the module that enables us to load images from file and needs to be enabled in the same way we enabled the font and ttf add-ons earlier.

As always there is an init function al_init_image_addon() that needs to be called before any image code can be called.  One initialized we can load a bitmap from disk calling al_load_bitmap() passing in the name of the image file.  Be sure to place this file in debug directory, just like we did earlier with the font file.  The next critical call is the function al_draw_bitmap() which is used to draw our bitmap to the backbuffer at the given coordinates.  In this simple example we are simply incrementing the X coordinate every pass through the game loop.  We then check that the bitmap hasnt moved off screen, if it is, we move it back to the beginning, minus the width of our image and start the process again.  This will cause the image to smoothly scroll back on screen. 

Here is our application in action:

There are a few things that are important to note.  First off, notice the call to al_destroy_bitmap(), this is important to call when you are done with your bitmap or resources will leak.  Next notice how drawing coordinates work.  When drawing, the origin (0,0) is the top left corner of the window as well as the top left corner of the bitmap.

It’s also important to realize in addition to al_draw_bitmap() there are several other draw functions available such as al_draw_rotated_bitmap(), al_draw_scaled_bitmap() etc.

Back to Table Of Contents

Programming 2D CPP Tutorial

In the first tutorial we created a simple Hello World application using Allegro.  However, that application was very limited.  In fact, it couldn’t even be closed!  It simply looped forever.  In this example we are going to change that up slightly, by allowing the application to exit if the user hits a key or clicks the close icon on the app window.

In order to accomplish this we are going to cover the basics of handling events and keyboards.  To handle events of any kind we need to first create an event queue.  As we saw earlier with addons, in Allegro you enable the functionality you need, this includes the keyboard.  Without further ado, lets jump into our new example.

#include "stdafx.h"
#include <allegro5\allegro.h>

int main()
{
	ALLEGRO_DISPLAY * display;
	ALLEGRO_EVENT_QUEUE *queue;

	al_init();
	display = al_create_display(640, 480);
	queue = al_create_event_queue();

	al_install_keyboard();
	al_register_event_source(queue, al_get_keyboard_event_source());
	al_register_event_source(queue, al_get_display_event_source(display));


	bool running = true;
	while (running) {
		al_flip_display();

		ALLEGRO_EVENT event;
		al_wait_for_event(queue, &event);
		if (event.type == ALLEGRO_EVENT_KEY_UP || event.type == ALLEGRO_EVENT_DISPLAY_CLOSE)
			running = false;
	}

	al_destroy_display(display);
	al_uninstall_keyboard();

	return 0;
}

When run this example will simply display an empty window.  The big difference is now it can be closed using the X icon or by pressing (and releasing) any key on the keyboard.  You will also notice in this example that since we can now exit our main loop, after the main game loop we do some cleanup work.  Generally every create function has a corresponding destroy function to clean up resources used.  This is also true with install and uninstall functions.

It’s possible that you want your game loop to run at a fixed rate, for example 30 or 60 frames per second.  This is also dont using ALLEGRO_EVENT, in this case a timer.  Here is a simple tweak to the above example that causes the graphics to be updated 60 times per second.

#include "stdafx.h"
#include <allegro5\allegro.h>

int main()
{
	ALLEGRO_DISPLAY * display;
	ALLEGRO_EVENT_QUEUE *queue;
	ALLEGRO_TIMER *timer;

	al_init();
	display = al_create_display(640, 480);
	queue = al_create_event_queue();
	timer = al_create_timer(1.0 / 60.0);

	al_install_keyboard();
	al_register_event_source(queue, al_get_keyboard_event_source());
	al_register_event_source(queue, al_get_display_event_source(display));
	al_register_event_source(queue, al_get_timer_event_source(timer));

	bool running = true;
	while (running) {
		

		ALLEGRO_EVENT event;
		al_wait_for_event(queue, &event);
		if (event.type == ALLEGRO_EVENT_KEY_UP || event.type == ALLEGRO_EVENT_DISPLAY_CLOSE)
			running = false;

		if (event.type == ALLEGRO_EVENT_TIMER) {
			al_flip_display();
		}
	}

	al_destroy_display(display);
	al_uninstall_keyboard();
	al_destroy_timer(timer);

	return 0;
}

Back to Table Of Contents

Programming Tutorial 2D CPP