System routines

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

al_install_system

bool al_install_system(int version, int (*atexit_ptr)(void (*)(void)))

Source Code

Initialize the Allegro system. No other Allegro functions can be called before this (with one or two exceptions).

The version field should always be set to ALLEGRO_VERSION_INT.

If atexit_ptr is non-NULL, and if hasn’t been done already, al_uninstall_system will be registered as an atexit function.

Returns true if Allegro was successfully initialized by this function call (or already was initialized previously), false if Allegro cannot be used. A common reason for this function to fail is when the version of Allegro you compiled your game against is not compatible with the version of the shared libraries that were found on the system.

The version compatibility check works as follows. Let A = xa.ya.za.* be the version of Allegro you compiled with, and B = xb.yb.zb.* be the version of Allegro found in the system shared library.

If you defined ALLEGRO_UNSTABLE before including Allegro headers, then version A is compatible with B only if xa.ya.za = xb.yb.zb. Otherwise, A is compatible with B only if xa.ya = xb.yb.

al_init

#define al_init()    (al_install_system(ALLEGRO_VERSION_INT, atexit))

Source Code

Like al_install_system, but automatically passes in the version and uses the atexit function visible in the current binary.

Note: It is typically wrong to call al_init anywhere except the final game binary. In particular, do not call it inside a shared library unless you know what you’re doing. In those cases, it is better to call al_install_system either with a NULL atexit_ptr, or with a pointer to atexit provided by the user of this shared library.

al_uninstall_system

void al_uninstall_system(void)

Source Code

Closes down the Allegro system.

Note: al_uninstall_system() can be called without a corresponding al_install_system call, e.g. from atexit().

Examples:

al_is_system_installed

bool al_is_system_installed(void)

Source Code

Returns true if Allegro is initialized, otherwise returns false.

Examples:

common.c

al_get_allegro_version

uint32_t al_get_allegro_version(void)

Source Code

Returns the (compiled) version of the Allegro library, packed into a single integer as groups of 8 bits in the form (major << 24) | (minor << 16) | (revision << 8) | release.

You can use code like this to extract them:

uint32_t version = al_get_allegro_version();
int major = version >> 24;
int minor = (version >> 16) & 255;
int revision = (version >> 8) & 255;
int release = version & 255;

The release number is 0 for an unofficial version and 1 or greater for an official release. For example “5.0.2[1]” would be the (first) official 5.0.2 release while “5.0.2[0]” would be a compile of a version from the “5.0.2” branch before the official release.

al_get_standard_path

ALLEGRO_PATH *al_get_standard_path(int id)

Source Code

Gets a system path, depending on the id parameter. Some of these paths may be affected by the organization and application name, so be sure to set those before calling this function.

The paths are not guaranteed to be unique (e.g., SETTINGS and DATA may be the same on some platforms), so you should be sure your filenames are unique if you need to avoid naming collisions. Also, a returned path may not actually exist on the file system.

ALLEGRO_RESOURCES_PATH

If you bundle data in a location relative to your executable, then you should use this path to locate that data. On most platforms, this is the directory that contains the executable file.

If called from an OS X app bundle, then this will point to the internal resource directory (<bundle.app>/Contents/Resources). To maintain consistency, if you put your resources into a directory called “data” beneath the executable on some other platform (like Windows), then you should also create a directory called “data” under the OS X app bundle’s resource folder.

You should not try to write to this path, as it is very likely read-only.

If you install your resources in some other system directory (e.g., in /usr/share or C:\ProgramData), then you are responsible for keeping track of that yourself.

ALLEGRO_TEMP_PATH

Path to the directory for temporary files.

ALLEGRO_USER_HOME_PATH

This is the user’s home directory. You should not normally write files into this directory directly, or create any sub folders in it, without explicit permission from the user. One practical application of this path would be to use it as the starting place of a file selector in a GUI.

ALLEGRO_USER_DOCUMENTS_PATH

This location is easily accessible by the user, and is the place to store documents and files that the user might want to later open with an external program or transfer to another place.

You should not save files here unless the user expects it, usually by explicit permission.

ALLEGRO_USER_DATA_PATH

If your program saves any data that the user doesn’t need to access externally, then you should place it here. This is generally the least intrusive place to store data. This path will usually not be present on the file system, so make sure to create it before writing to it.

ALLEGRO_USER_SETTINGS_PATH

If you are saving configuration files (especially if the user may want to edit them outside of your program), then you should place them here. This path will usually not be present on the file system, so make sure to create it before writing to it.

ALLEGRO_EXENAME_PATH

The full path to the executable.

Returns NULL on failure. The returned path should be freed with al_destroy_path.

Examples:

al_set_exe_name

void al_set_exe_name(char const *path)

Source Code

This override the executable name used by al_get_standard_path for ALLEGRO_EXENAME_PATH and ALLEGRO_RESOURCES_PATH.

One possibility where changing this can be useful is if you use the Python wrapper. Allegro would then by default think that the system’s Python executable is the current executable - but you can set it to the .py file being executed instead.

Since: 5.0.6, 5.1.0

al_set_app_name

void al_set_app_name(const char *app_name)

Source Code

Sets the global application name.

The application name is used by al_get_standard_path to build the full path to an application’s files.

This function may be called before al_init or al_install_system.

Examples:

ex_get_path.c

al_set_org_name

void al_set_org_name(const char *org_name)

Source Code

Sets the global organization name.

The organization name is used by al_get_standard_path to build the full path to an application’s files.

This function may be called before al_init or al_install_system.

Examples:

ex_get_path.c

al_get_app_name

const char *al_get_app_name(void)

Source Code

Returns the global application name string.

al_get_org_name

const char *al_get_org_name(void)

Source Code

Returns the global organization name string.

al_get_system_config

ALLEGRO_CONFIG *al_get_system_config(void)

Source Code

Returns the system configuration structure. The returned configuration should not be destroyed with al_destroy_config. This is mainly used for configuring Allegro and its addons. You may populate this configuration before Allegro is installed to control things like the logging levels and other features.

Allegro will try to populate this configuration by loading a configuration file from a few different locations, in this order:

Unix only: /etc/allegro5rc
Unix only: $HOME/allegro5rc
Unix only: $HOME/.allegro5rc
allegro5.cfg next to the executable

If multiple copies are found, then they are merged using al_merge_config_into.

The contents of this file are documented inside a prototypical allegro5.cfg that you can find in the root directory of the source distributions of Allegro. They are also reproduced below.

Note that Allegro will not look into that file unless you make a copy of it and place it next to your executable!

#
#  Configuration file for the Allegro 5 library.
#
#  This file should be either in the same directory as your program.
#
#  On Unix, this file may also be stored as ~/.allegro5rc or /etc/allegro5rc.
#  If multiple files exist, they will be merged, with values from more specific
#  files overriding the less specific files.

[graphics]

# Graphics driver.
# Can be 'default', 'opengl' or 'direct3d' (Windows only).
driver=default

# Display configuration selection mode.
#
# Under Linux, it can be used to force the old GLX 1.2 way of choosing
# display settings or the new FBConfig method introduced with GLX 1.3.
#
# Under Windows, when using the OpenGL driver, setting it to old will
# use DescribePixelFormat and new will use wglGetPixelFormatAttribivARB
# (provided by WGL_ARB_pixel_format extension).
#
# Can be 'old' and 'new'. Default is 'new'.
config_selection=new

# What method to use to detect legacy cards for the Direct3D backend of the
# primitives addon. Can be 'default', which means it'll check that the pixel
# shader version supported is below some value. 'force_legacy' will force it to
# detect as a legacy card. 'force_modern' will force it to detect is as a modern
# card.
prim_d3d_legacy_detection=default

# For compatibility reasons, video bitmaps smaller than this size are
# backed by textures with this size. This is often no longer necessary
# on more modern systems, and should be set to < 16 if you're creating
# bitmaps smaller than this size. Note that on Android, this is ignored
# if smaller than 32.
min_bitmap_size=16

[audio]

# Driver can be 'default', 'openal', 'alsa', 'oss', 'pulseaudio' or 'directsound'
# depending on platform.
driver=default

# Mixer quality can be 'linear' (default), 'cubic' (best), or 'point' (bad).
# default_mixer_quality=linear

# The frequency to use for the default voice/mixer. Default: 44100.
# primary_voice_frequency=44100
# primary_mixer_frequency=44100

# Can be 'int16', otherwise defaults to float32.
# primary_voice_depth=float32
# primary_mixer_depth=float32

[oss]

# You can skip probing for OSS4 driver by setting this option to 'yes'.
# Default is 'no'.
force_ver3=no

# When OSS3 is used, you can choose a sound device here.
# Default is '/dev/dsp'.
device=/dev/dsp

[alsa]

# Set the ALSA sound device.
# Default is 'default'.
device=default

# Set the ALSA capture device, e.g. hw:0,0
# Default is 'default'.
capture_device=default

# Set the period size (in samples)
# Note that this is erroneously called 'buffer_size' for backwards
# compatibility.
buffer_size=32

# Set the buffer size (in samples)
buffer_size2=2048

[pulseaudio]

# Set the buffer size (in samples)
buffer_size=1024

[directsound]

# Set the DirectSound buffer size (in samples)
buffer_size = 8192

# Which window to attach the device to. Can be 'desktop', or 'foreground'. Try
# flipping this if there are issues initializing audio.
window = desktop

[opengl]

# If you want to support old OpenGL versions, you can make Allegro
# believe an older version than what you actually have is used with
# this key. This is only for testing/debugging purposes.

# force_opengl_version = 1.2

[opengl_disabled_extensions]

# Any OpenGL extensions can be listed here to make Allegro report them
# as not available. The extensions used by Allegro itself if available
# are shown below - uncommenting them would disable them:

# GL_ARB_texture_non_power_of_two=0
# GL_EXT_framebuffer_object=0

[image]

# Gamma handling of PNG files.
# A value of 0.0 means: Don't do any gamma correction.
# A value of -1.0 means: Use the value from the environment variable
# SCREEN_GAMMA (if available), otherwise fallback to a value of 2.2
# (a good guess for PC monitors, and the value for sRGB colourspace).
# Otherwise, the value is taken as-is.
png_screen_gamma = -1.0

# Compression level for PNG files. Possible values: 0-9, "best", "fastest",
# "none" or "default" (a sane compromise between size and speed).
png_compression_level = default

# Quality level for JPEG files. Possible values: 0-100
jpeg_quality_level = 75

# Quality level for WebP files. Possible values: 0-100 or "lossless"
webp_quality_level = lossless

[joystick]

# Linux: Allegro normally searches for joystick device N at /dev/input/jsN.
# You can override the device file path on a per-device basis, like this.

# device0=/dev/input/by-id/usb-blahblah-joystick

# Windows: You can choose between the XINPUT or DIRECTINPUT driver for
# joysticks and force feedback joysticks. Xinput is the more modern
# system, but DirectInput has more force feedback capabilities for older
# joysticks.
driver=XINPUT

# Windows: Use this to force an XInput DLL version, example "3" forces
# xinput1_3.dll. By default, the latest version is used.

# force_xinput_version = 3

[keyboard]

# You can trap/untrap the mouse cursor within a window with a key combination
# of your choice, e.g. "Ctrl-G", "Shift-Ctrl-G", "Ctrl-LShift", "RWin".
# This feature currently only works on X11 and Windows.

# toggle_mouse_grab_key = ScrollLock

# By default, you can press Ctrl-Alt-Delete or Ctrl-Alt-End to quit Allegro
# programs. Set this to false to disable this feature. This only works on
# Linux.

# enable_three_finger_exit = true

# By default, pressing the LED toggling keys (e.g. CapsLock) will also toggle
# the LED on the keyboard. Setting this to false disable that connection.
# This can only be controled on non-X11 Linux.

# enable_key_led_toggle = true


[trace]
# Comma-separated list of channels to log. Default is "all" which
# disables channel filtering. Some possible channels are:
# system,display,keyboard,opengl
# Channel names can be prefixed with - to exclude only those channels.
# Each addon and source-file can define additional channels though so
# there are more.
channels=all

# Log-level. Can be one of debug, info, warn, error, none or empty.
# In debug builds if it is empty or unset, then the level is set to debug.
# In release builds if it is empty or unset, then the level is set to none.
# If not none, Allegro will write out the logs to an allegro.log file next to
# the binary. Use ALLEGRO_TRACE environment variable to control that file
# location. A special filename of - (dash) means logging to stdout.
# You can override this value via the ALLEGRO_TRACE_LEVEL environment variable.
level=

# Set to 0 to disable line numbers in log files.
lines=1

# Set to 0 to disable timestamps in log files.
timestamps=1

# Set to 0 to disable function names in log files.
functions=1

[x11]
# Can be fullscreen_only, always, never
bypass_compositor = fullscreen_only

[xkeymap]
# Override X11 keycode. The below example maps X11 code 52 (Y) to Allegro
# code 26 (Z) and X11 code 29 (Z) to Allegro code 25 (Y).
# 52=26
# 29=25


[shader]
# If you want to support override version of the d3dx9_xx.dll library
# define this value.
# By default, latest installed version is used.

# force_d3dx9_version = 36

[ttf]

# Set these to something other than 0 to override the default page sizes for TTF
# glyphs.
min_page_size = 0
max_page_size = 0

# This entry contains characters that will be pre-catched during font loading.
# cache_text = a bcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

# Uncomment if you want only the characters in the cache_text entry to ever be drawn
# skip_cache_misses = true

[osx]

# If set to false, then Allegro will send ALLEGRO_EVENT_DISPLAY_HALT_DRAWING
# and ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING events when the user resizes a
# window. Drawing while resizing ("live resizing") has historically been buggy,
# so setting this to false allows you to opt out of this behavior and detect
# when the resize happens.
allow_live_resize = true

[compatibility]

# Prior to 5.2.4 on Windows you had to manually resize the display when
# showing the menu using the dialog addon. After 5.2.4 this is done
# automatically, but may break old code that handled this eventuality.
# Set this to false for such code.
automatic_menu_display_resize = true

# On OSX outside an app bundle, on system init allegro manually promotes the process
# to a graphical application. This may be undesirable for console applications. Set
# this to false to disable this behavior.
osx_tell_dock_outside_bundle = true

# To restore behavior of older code versions, specify this value to the
# Allegro version that had the desired old behavior.
# joystick_version = 5.2.9

Examples:

al_get_system_id

ALLEGRO_SYSTEM_ID al_get_system_id(void)

Source Code

Returns the platform that Allegro is running on.

Since: 5.2.5

al_register_assert_handler

void al_register_assert_handler(void (*handler)(char const *expr,
   char const *file, int line, char const *func))

Source Code

Register a function to be called when an internal Allegro assertion fails. Pass NULL to reset to the default behaviour, which is to do whatever the standard assert() macro does.

Since: 5.0.6, 5.1.0

al_register_trace_handler

void al_register_trace_handler(void (*handler)(char const *))

Source Code

Register a callback which is called whenever Allegro writes something to its log files. The default logging to allegro.log is disabled while this callback is active. Pass NULL to revert to the default logging.

This function may be called prior to al_install_system.

See the example allegro5.cfg for documentation on how to configure the used debug channels, logging levels and trace format.

Since: 5.1.5

al_get_cpu_count

int al_get_cpu_count(void)

Source Code

Returns the number of CPU cores that the system Allegro is running on has and which could be detected, or a negative number if detection failed. Even if a positive number is returned, it might be that it is not correct. For example, Allegro running on a virtual machine will return the amount of CPU’s of the VM, and not that of the underlying system.

Furthermore even if the number is correct, this only gives you information about the total CPU cores of the system Allegro runs on. The amount of cores available to your program may be less due to circumstances such as programs that are currently running.

Therefore, it’s best to use this for advisory purposes only. It is certainly a bad idea to make your program exclusive to systems for which this function returns a certain “desirable” number.

This function may be called prior to al_install_system or al_init.

Since: 5.1.12

Examples:

ex_cpu.c

al_get_ram_size

int al_get_ram_size(void)

Source Code

Returns the size in MB of the random access memory that the system Allegro is running on has and which could be detected, or a negative number if detection failed. Even if a positive number is returned, it might be that it is not correct. For example, Allegro running on a virtual machine will return the amount of RAM of the VM, and not that of the underlying system.

Furthermore even if the number is correct, this only gives you information about the total physical memory of the system Allegro runs on. The memory available to your program may be less or more than what this function returns due to circumstances such as virtual memory, and other programs that are currently running.

Therefore, it’s best to use this for advisory purposes only. It is certainly a bad idea to make your program exclusive to systems for which this function returns a certain “desirable” number.

This function may be called prior to al_install_system or al_init.

Since: 5.1.12

Examples:

ex_cpu.c

ALLEGRO_SYSTEM_ID

enum ALLEGRO_SYSTEM_ID {

Source Code

The system Allegro is running on.

ALLEGRO_SYSTEM_ID_UNKNOWN - Unknown system.
ALLEGRO_SYSTEM_ID_XGLX - Xglx
ALLEGRO_SYSTEM_ID_WINDOWS - Windows
ALLEGRO_SYSTEM_ID_MACOSX - macOS
ALLEGRO_SYSTEM_ID_ANDROID - Android
ALLEGRO_SYSTEM_ID_IPHONE - iOS
ALLEGRO_SYSTEM_ID_GP2XWIZ - GP2XWIZ
ALLEGRO_SYSTEM_ID_RASPBERRYPI - Raspberry Pi
ALLEGRO_SYSTEM_ID_SDL - SDL

Since: 5.2.5