Getting started guide
Introduction
Welcome to Allegro 5!
This short guide should point you at the parts of the API that you’ll want to know about first. It’s not a tutorial, as there isn’t much discussion, only links into the manual. The rest you’ll have to discover for yourself. Read the examples, and ask questions at Allegro.cc.
There is an unofficial tutorial at the wiki. Be aware that, being on the wiki, it may be a little out of date, but the changes should be minor. Hopefully more will sprout when things stabilise, as they did for earlier versions of Allegro.
Structure of the library and its addons
Allegro 5.0 is divided into a core library and multiple addons. The addons are bundled together and built at the same time as the core, but they are distinct and kept in separate libraries. The core doesn’t depend on anything in the addons, but addons may depend on the core and other addons and additional third party libraries.
Here are the addons and their dependencies:
allegro_main -> allegro
allegro_image -> allegro
allegro_primitives -> allegro
allegro_color -> allegro
allegro_font -> allegro
allegro_ttf -> allegro_font -> allegro
allegro_audio -> allegro
allegro_acodec -> allegro_audio -> allegro
allegro_video -> allegro_audio -> allegro
allegro_memfile -> allegro
allegro_physfs -> allegro
allegro_native_dialog -> allegroThe header file for the core library is allegro5/allegro.h. The header files for the addons are named allegro5/allegro_image.h, allegro5/allegro_font.h, etc. The allegro_main addon does not have a header file.
The main function
For the purposes of cross-platform compatibility Allegro puts some requirements on your main function. First, you must include the core header (allegro5/allegro.h) in the same file as your main function. Second, if your main function is inside a C++ file, then it must have this signature: int main(int argc, char **argv). Third, if you’re using C/C++ then you need to link with the allegro_main addon when building your program.
Initialisation
Before using Allegro you must call al_init. Some addons have their own initialisation, e.g. al_init_image_addon, al_init_font_addon, al_init_ttf_addon.
To receive input, you need to initialise some subsystems like al_install_keyboard, al_install_mouse, al_install_joystick.
Opening a window
al_create_display will open a window and return an ALLEGRO_DISPLAY.
To clear the display, call al_clear_to_color. Use al_map_rgba or al_map_rgba_f to obtain an ALLEGRO_COLOR parameter.
Drawing operations are performed on a backbuffer. To make the operations visible, call al_flip_display.
Display an image
To load an image from disk, you need to have initialised the image I/O addon with al_init_image_addon. Then use al_load_bitmap, which returns an ALLEGRO_BITMAP.
Use al_draw_bitmap, al_draw_scaled_bitmap or al_draw_scaled_rotated_bitmap to draw the image to the backbuffer. Remember to call al_flip_display.
Changing the drawing target
Notice that al_clear_to_color and al_draw_bitmap didn’t take destination parameters: the destination is implicit. Allegro remembers the current “target bitmap” for the current thread. To change the target bitmap, call al_set_target_bitmap.
The backbuffer of the display is also a bitmap. You can get it with al_get_backbuffer and then restore it as the target bitmap.
Other bitmaps can be created with al_create_bitmap, with options which can be adjusted with al_set_new_bitmap_flags and al_set_new_bitmap_format.
Event queues and input
Input comes from multiple sources: keyboard, mouse, joystick, timers, etc. Event queues aggregate events from all these sources, then you can query the queue for events.
Create an event queue with al_create_event_queue, then tell input sources to place new events into that queue using al_register_event_source. The usual input event sources can be retrieved with al_get_keyboard_event_source, al_get_mouse_event_source and al_get_joystick_event_source.
Events can be retrieved with al_wait_for_event or al_get_next_event. Check the event type and other fields of ALLEGRO_EVENT to react to the input.
Displays are also event sources, which emit events when they are resized. You’ll need to set the ALLEGRO_RESIZABLE flag with al_set_new_display_flags before creating the display, then register the display with an event queue. When you get a resize event, call al_acknowledge_resize.
Timers are event sources which “tick” periodically, causing an event to be inserted into the queues that the timer is registered with. Create some with al_create_timer.
al_get_time and al_rest are more direct ways to deal with time.
Displaying some text
To display some text, initialise the image and font addons with al_init_image_addon and al_init_font_addon, then load a bitmap font with al_load_font. Use al_draw_text or al_draw_textf.
For TrueType fonts, you’ll need to initialise the TTF font addon with al_init_ttf_addon and load a TTF font with al_load_ttf_font.
Drawing primitives
The primitives addon provides some handy routines to draw lines (al_draw_line), rectangles (al_draw_rectangle), circles (al_draw_circle), etc.
Blending
To draw translucent or tinted images or primitives, change the blender state with al_set_blender.
As with al_set_target_bitmap, this changes Allegro’s internal state (for the current thread). Often you’ll want to save some part of the state and restore it later. The functions al_store_state and al_restore_state provide a convenient way to do that.
Sound
Use al_install_audio to initialize sound. To load any sample formats, you will need to initialise the acodec addon with al_init_acodec_addon.
After that, you can simply use al_reserve_samples and pass the number of sound effects typically playing at the same time. Then load your sound effects with al_load_sample and play them with al_play_sample. To stream large pieces of music from disk, you can use al_load_audio_stream so the whole piece will not have to be pre-loaded into memory.
If the above sounds too simple and you can’t help but think about clipping and latency issues, don’t worry. Allegro gives you full control over how much or little you want its sound system to do. The al_reserve_samples function mentioned above only sets up a default mixer and a number of sample instances but you don’t need to use it.
Instead, to get a “direct connection” to the sound system you would use an ALLEGRO_VOICE (but depending on the platform only one such voice is guaranteed to be available and it might require a specific format of audio data). Therefore all sound can be first routed through an ALLEGRO_MIXER which is connected to such a voice (or another mixer) and will mix together all sample data fed to it.
You can then directly stream real-time sample data to a mixer or a voice using an ALLEGRO_AUDIO_STREAM or play complete sounds using an ALLEGRO_SAMPLE_INSTANCE. The latter simply points to an ALLEGRO_SAMPLE and will stream it for you.
Unstable API
Some of Allegro’s API is marked as unstable, which means that in future versions of Allegro it may change or even be removed entirely! If you want to experiment with the unstable API, define ALLEGRO_UNSTABLE macro before including Allegro’s headers.
Note that when you define that macro, the version check performed by al_install_system and al_init becomes more scrict. See documentation of those functions for details.
Not the end
There’s a heap of stuff we haven’t even mentioned yet.
Enjoy!