The Allegro 5 Library Reference Manual Version 5.2.7 © 2008 — 2015 Contents Contents iii 1 Getting started guide1 1.1 Introduction......................................... 1 1.2 Structure of the library and its addons .......................... 1 1.3 The main function ..................................... 2 1.4 Initialisation......................................... 2 1.5 Opening a window ..................................... 2 1.6 Display an image ...................................... 2 1.7 Changing the drawing target................................ 2 1.8 Event queues and input................................... 2 1.9 Displaying some text .................................... 3 1.10 Drawing primitives..................................... 3 1.11 Blending........................................... 3 1.12 Sound ............................................ 3 1.13 Unstable API......................................... 3 1.14 Not the end ......................................... 4 2 Configuration files 5 2.1 ALLEGRO_CONFIG..................................... 6 2.2 ALLEGRO_CONFIG_SECTION............................... 6 2.3 ALLEGRO_CONFIG_ENTRY ................................ 6 2.4 al_create_config....................................... 6 2.5 al_destroy_config...................................... 6 2.6 al_load_config_file ..................................... 7 2.7 al_load_config_file_f .................................... 7 2.8 al_save_config_file ..................................... 7 2.9 al_save_config_file_f .................................... 7 2.10 al_add_config_section ................................... 7 2.11 al_remove_config_section ................................. 8 2.12 al_add_config_comment.................................. 8 2.13 al_get_config_value..................................... 8 2.14 al_set_config_value..................................... 8 2.15 al_remove_config_key ................................... 9 2.16 al_get_first_config_section................................. 9 2.17 al_get_next_config_section................................. 9 2.18 al_get_first_config_entry.................................. 9 2.19 al_get_next_config_entry.................................. 9 2.20 al_merge_config....................................... 10 2.21 al_merge_config_into.................................... 10 3 Displays 11 iii CONTENTS 3.1 Display creation....................................... 11 3.1.1 ALLEGRO_DISPLAY ................................... 11 3.1.2 al_create_display..................................... 12 3.1.3 al_destroy_display .................................... 12 3.1.4 al_get_new_display_flags ................................ 12 3.1.5 al_set_new_display_flags ................................ 12 3.1.6 al_get_new_display_option ............................... 14 3.1.7 al_set_new_display_option ............................... 14 3.1.8 al_reset_new_display_options.............................. 16 3.1.9 al_get_new_window_position.............................. 16 3.1.10 al_set_new_window_position.............................. 17 3.1.11 al_get_new_display_refresh_rate ............................ 17 3.1.12 al_set_new_display_refresh_rate ............................ 17 3.2 Display operations ..................................... 17 3.2.1 al_get_display_event_source............................... 17 3.2.2 al_get_backbuffer..................................... 17 3.2.3 al_flip_display ...................................... 18 3.2.4 al_update_display_region ................................ 18 3.2.5 al_wait_for_vsync .................................... 18 3.3 Display size and position.................................. 19 3.3.1 al_get_display_width................................... 19 3.3.2 al_get_display_height .................................. 19 3.3.3 al_resize_display..................................... 19 3.3.4 al_acknowledge_resize.................................. 19 3.3.5 al_get_window_position................................. 19 3.3.6 al_set_window_position................................. 20 3.3.7 al_get_window_constraints ............................... 20 3.3.8 al_set_window_constraints ............................... 20 3.3.9 al_apply_window_constraints.............................. 20 3.4 Display settings....................................... 21 3.4.1 al_get_display_flags ................................... 21 3.4.2 al_set_display_flag.................................... 21 3.4.3 al_get_display_option .................................. 21 3.4.4 al_set_display_option .................................. 21 3.4.5 al_get_display_format .................................. 22 3.4.6 al_get_display_orientation................................ 22 3.4.7 al_get_display_refresh_rate ............................... 22 3.4.8 al_set_window_title ................................... 22 3.4.9 al_set_new_window_title ................................ 23 3.4.10 ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE..................... 23 3.4.11 al_get_new_window_title ................................ 23 3.4.12 al_set_display_icon.................................... 23 3.4.13 al_set_display_icons ................................... 23 3.5 Drawing halts........................................ 24 3.5.1 al_acknowledge_drawing_halt ............................. 24 3.5.2 al_acknowledge_drawing_resume............................ 24 3.6 Screensaver ......................................... 24 3.6.1 al_inhibit_screensaver.................................. 24 3.7 Clipboard .......................................... 24 3.7.1 al_get_clipboard_text .................................. 25 3.7.2 al_set_clipboard_text................................... 25 3.7.3 al_clipboard_has_text .................................. 25 4 Event system and events 27 4.1 ALLEGRO_EVENT...................................... 27 4.1.1 ALLEGRO_EVENT_JOYSTICK_AXIS........................... 28 4.1.2 ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN.................... 28 iv Contents 4.1.3 ALLEGRO_EVENT_JOYSTICK_BUTTON_UP...................... 28 4.1.4 ALLEGRO_EVENT_JOYSTICK_CONFIGURATION ................... 28 4.1.5 ALLEGRO_EVENT_KEY_DOWN............................. 28 4.1.6 ALLEGRO_EVENT_KEY_UP ............................... 28 4.1.7 ALLEGRO_EVENT_KEY_CHAR ............................. 29 4.1.8 ALLEGRO_EVENT_MOUSE_AXES............................ 29 4.1.9 ALLEGRO_EVENT_MOUSE_BUTTON_DOWN..................... 30 4.1.10 ALLEGRO_EVENT_MOUSE_BUTTON_UP ....................... 30 4.1.11 ALLEGRO_EVENT_MOUSE_WARPED.......................... 30 4.1.12 ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY..................... 31 4.1.13 ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY ..................... 31 4.1.14 ALLEGRO_EVENT_TOUCH_BEGIN........................... 31 4.1.15 ALLEGRO_EVENT_TOUCH_END ............................ 31 4.1.16 ALLEGRO_EVENT_TOUCH_MOVE ........................... 32 4.1.17 ALLEGRO_EVENT_TOUCH_CANCEL.......................... 32 4.1.18 ALLEGRO_EVENT_TIMER................................ 32 4.1.19 ALLEGRO_EVENT_DISPLAY_EXPOSE.......................... 32 4.1.20 ALLEGRO_EVENT_DISPLAY_RESIZE.......................... 32 4.1.21 ALLEGRO_EVENT_DISPLAY_CLOSE .......................... 33 4.1.22 ALLEGRO_EVENT_DISPLAY_LOST........................... 33 4.1.23 ALLEGRO_EVENT_DISPLAY_FOUND.......................... 33 4.1.24 ALLEGRO_EVENT_DISPLAY_SWITCH_OUT...................... 33 4.1.25 ALLEGRO_EVENT_DISPLAY_SWITCH_IN ....................... 33 4.1.26 ALLEGRO_EVENT_DISPLAY_ORIENTATION...................... 34 4.1.27 ALLEGRO_EVENT_DISPLAY_HALT_DRAWING..................... 34 4.1.28 ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING................... 34 4.1.29 ALLEGRO_EVENT_DISPLAY_CONNECTED....................... 35 4.1.30 ALLEGRO_EVENT_DISPLAY_DISCONNECTED..................... 35 4.2 ALLEGRO_USER_EVENT.................................. 35 4.3 ALLEGRO_EVENT_QUEUE................................. 36 4.4 ALLEGRO_EVENT_SOURCE................................ 36 4.5 ALLEGRO_EVENT_TYPE.................................. 36 4.6 ALLEGRO_GET_EVENT_TYPE............................... 36 4.7 ALLEGRO_EVENT_TYPE_IS_USER ............................ 37 4.8 al_create_event_queue................................... 37 4.9 al_destroy_event_queue .................................. 37 4.10 al_register_event_source.................................. 38 4.11 al_unregister_event_source................................. 38 4.12 al_is_event_source_registered............................... 38 4.13 al_pause_event_queue ................................... 38 4.14 al_is_event_queue_paused................................. 39 4.15 al_is_event_queue_empty ................................. 39 4.16 al_get_next_event...................................... 39 4.17 al_peek_next_event..................................... 39 4.18 al_drop_next_event..................................... 39 4.19 al_flush_event_queue.................................... 40 4.20 al_wait_for_event...................................... 40 4.21 al_wait_for_event_timed.................................. 40 4.22 al_wait_for_event_until................................... 40 4.23 al_init_user_event_source ................................. 41 4.24 al_destroy_user_event_source............................... 41 4.25 al_emit_user_event..................................... 42 4.26 al_unref_user_event .................................... 42 4.27 al_get_event_source_data ................................. 42 4.28 al_set_event_source_data.................................. 42 5 File I/O 45 v CONTENTS 5.1 ALLEGRO_FILE......................................