Audio codecs addon

  • Contents
  • Configuration files
  • Display
  • Events
  • File I/O
  • Filesystem
  • Fixed point math
  • Fullscreen modes
  • Graphics
  • Haptic
  • Joystick
  • Keyboard
  • Memory
  • Monitor
  • Mouse
  • Path
  • Shader
  • State
  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Audio codecs addon

  • al_init_acodec_addon
  • al_get_allegro_acodec_version

These functions are declared in the following header file. Link with allegro_acodec.

 #include <allegro5/allegro_acodec.h>

al_init_acodec_addon

bool al_init_acodec_addon(void)

Source Code

This function registers all the known audio file type handlers for al_load_sample, al_save_sample, al_load_audio_stream, etc.

Depending on what libraries are available, the full set of recognised extensions is: .wav, .flac, .ogg, .opus, .it, .mod, .s3m, .xm, .voc.

Limitations:

  • Saving is only supported for wav files.

  • The wav file loader currently only supports 8/16 bit little endian PCM files. 16 bits are used when saving wav files. Use flac files if more precision is required.

  • Module files (.it, .mod, .s3m, .xm) are often composed with streaming in mind, and sometimes cannot be easily rendered into a finite length sample. Therefore they cannot be loaded with al_load_sample/al_load_sample_f and must be streamed with al_load_audio_stream or al_load_audio_stream_f.

  • .voc file streaming is unimplemented.

Return true on success.

al_get_allegro_acodec_version

uint32_t al_get_allegro_acodec_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:18 UTC


Audio addon

  • Events
  • File I/O
  • Filesystem
  • Fixed point math
  • Fullscreen modes
  • Graphics
  • Haptic
  • Joystick
  • Keyboard
  • Memory
  • Monitor
  • Mouse
  • Path
  • Shader
  • State
  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Audio addon

  • Audio types
    • ALLEGRO_AUDIO_EVENT_TYPE
      • ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT
      • ALLEGRO_EVENT_AUDIO_STREAM_FINISHED
      • ALLEGRO_EVENT_AUDIO_RECORDER_FRAGMENT
    • ALLEGRO_AUDIO_DEPTH
    • ALLEGRO_AUDIO_PAN_NONE
    • ALLEGRO_CHANNEL_CONF
    • ALLEGRO_MIXER
    • ALLEGRO_MIXER_QUALITY
    • ALLEGRO_PLAYMODE
    • ALLEGRO_SAMPLE_ID
    • ALLEGRO_SAMPLE
    • ALLEGRO_SAMPLE_INSTANCE
    • ALLEGRO_AUDIO_STREAM
    • ALLEGRO_VOICE
  • Setting up audio
    • al_install_audio
    • al_uninstall_audio
    • al_is_audio_installed
    • al_reserve_samples
  • Misc audio functions
    • al_get_allegro_audio_version
    • al_get_audio_depth_size
    • al_get_channel_count
    • al_fill_silence
  • Voice functions
    • al_create_voice
    • al_destroy_voice
    • al_detach_voice
    • al_attach_audio_stream_to_voice
    • al_attach_mixer_to_voice
    • al_attach_sample_instance_to_voice
    • al_get_voice_frequency
    • al_get_voice_channels
    • al_get_voice_depth
    • al_get_voice_playing
    • al_set_voice_playing
    • al_get_voice_position
    • al_set_voice_position
  • Sample functions
    • al_create_sample
    • al_destroy_sample
    • al_play_sample
    • al_stop_sample
    • al_lock_sample_id
    • al_unlock_sample_id
    • al_stop_samples
    • al_get_sample_channels
    • al_get_sample_depth
    • al_get_sample_frequency
    • al_get_sample_length
    • al_get_sample_data
  • Sample instance functions
    • al_create_sample_instance
    • al_destroy_sample_instance
    • al_play_sample_instance
    • al_stop_sample_instance
    • al_get_sample_instance_channels
    • al_get_sample_instance_depth
    • al_get_sample_instance_frequency
    • al_get_sample_instance_length
    • al_set_sample_instance_length
    • al_get_sample_instance_position
    • al_set_sample_instance_position
    • al_get_sample_instance_speed
    • al_set_sample_instance_speed
    • al_get_sample_instance_gain
    • al_set_sample_instance_gain
    • al_get_sample_instance_pan
    • al_set_sample_instance_pan
    • al_get_sample_instance_time
    • al_get_sample_instance_playmode
    • al_set_sample_instance_playmode
    • al_get_sample_instance_playing
    • al_set_sample_instance_playing
    • al_get_sample_instance_attached
    • al_detach_sample_instance
    • al_get_sample
    • al_set_sample
    • al_set_sample_instance_channel_matrix
  • Mixer functions
    • al_create_mixer
    • al_destroy_mixer
    • al_get_default_mixer
    • al_set_default_mixer
    • al_restore_default_mixer
    • al_get_default_voice
    • al_set_default_voice
    • al_attach_mixer_to_mixer
    • al_attach_sample_instance_to_mixer
    • al_attach_audio_stream_to_mixer
    • al_get_mixer_frequency
    • al_set_mixer_frequency
    • al_get_mixer_channels
    • al_get_mixer_depth
    • al_get_mixer_gain
    • al_set_mixer_gain
    • al_get_mixer_quality
    • al_set_mixer_quality
    • al_get_mixer_playing
    • al_set_mixer_playing
    • al_get_mixer_attached
    • al_detach_mixer
    • al_set_mixer_postprocess_callback
  • Stream functions
    • al_create_audio_stream
    • al_destroy_audio_stream
    • al_get_audio_stream_event_source
    • al_drain_audio_stream
    • al_rewind_audio_stream
    • al_get_audio_stream_frequency
    • al_get_audio_stream_channels
    • al_get_audio_stream_depth
    • al_get_audio_stream_length
    • al_get_audio_stream_speed
    • al_set_audio_stream_speed
    • al_get_audio_stream_gain
    • al_set_audio_stream_gain
    • al_get_audio_stream_pan
    • al_set_audio_stream_pan
    • al_get_audio_stream_playing
    • al_set_audio_stream_playing
    • al_get_audio_stream_playmode
    • al_set_audio_stream_playmode
    • al_get_audio_stream_attached
    • al_detach_audio_stream
    • al_get_audio_stream_played_samples
    • al_get_audio_stream_fragment
    • al_set_audio_stream_fragment
    • al_get_audio_stream_fragments
    • al_get_available_audio_stream_fragments
    • al_seek_audio_stream_secs
    • al_get_audio_stream_position_secs
    • al_get_audio_stream_length_secs
    • al_set_audio_stream_loop_secs
    • al_set_audio_stream_channel_matrix
  • Audio file I/O
    • al_register_sample_loader
    • al_register_sample_loader_f
    • al_register_sample_saver
    • al_register_sample_saver_f
    • al_register_audio_stream_loader
    • al_register_audio_stream_loader_f
    • al_load_sample
    • al_load_sample_f
    • al_load_audio_stream
    • al_load_audio_stream_f
    • al_save_sample
    • al_save_sample_f
  • Audio recording
    • ALLEGRO_AUDIO_RECORDER
    • ALLEGRO_AUDIO_RECORDER_EVENT
    • al_create_audio_recorder
    • al_start_audio_recorder
    • al_stop_audio_recorder
    • al_is_audio_recorder_recording
    • al_get_audio_recorder_event
    • al_get_audio_recorder_event_source
    • al_destroy_audio_recorder

These functions are declared in the following header file. Link with allegro_audio.

 #include <allegro5/allegro_audio.h>

In order to just play some samples, here's how to quick start with Allegro's audio addon: Call al_reserve_samples with the number of samples you'd like to be able to play simultaneously (don't forget to call al_install_audio beforehand). If these succeed, you can now call al_play_sample, with data obtained by al_load_sample, for example (don't forget to initialize the acodec addon). You don't need to worry about voices, mixers or sample instances when using this approach. In order to stop samples, you can use the ALLEGRO_SAMPLE_ID that al_play_sample returns.

If you want to play large audio files (e.g. background music) without loading the whole file at once or if you want to output audio generated in real-time, you can use Allegro's audio streams. The easiest way to setup an audio stream is to attach it to the default mixer (created for you by al_reserve_samples) using al_attach_audio_stream_to_mixer on the return value of al_get_default_mixer. Allegro will feed streams created from files using al_load_audio_stream automatically. However, you can also stream audio data you generate on the fly. In this case, audio streams will emit an event when it's time to provide the next fragment (chunk) of audio data. You can control several playback parameters of audio streams (speed, gain, pan, playmode, played/paused; additionally position and loop points when streaming a file).

For more fine-grained control over audio output, here's a short description of the basic concepts:

Voices represent audio devices on the system. Basically, every audio output chain that you want to be heard needs to end up in a voice. As voices are on the hardware/driver side of things, there is only limited control over their parameters (frequency, sample format, channel configuration). The number of available voices is limited as well. Typically, you will only use one voice and attach a mixer to it. Calling al_reserve_samples will do this for you by setting up a default voice and mixer; it can also be achieved by calling al_restore_default_mixer. Although you can attach sample instances and audio streams directly to a voice without using a mixer, it is, as of now, not recommended. In contrast to mixers, you can only attach a single object to a voice anyway.

Mixers mix several sample instances and/or audio streams into a single output buffer, converting sample data with differing formats according to their output parameters (frequency, depth, channels) in the process. In order to play several samples/streams at once reliably, you will need at least one mixer. A mixer that is not (indirectly) attached to a voice will remain silent. For most use cases, one (default) mixer attached to a single voice will be sufficient. You may attach mixers to other mixers in order to create complex audio chains.

Samples (ALLEGRO_SAMPLE) just represent "passive" buffers for sample data in memory. In order to play a sample, a sample instance (ALLEGRO_SAMPLE_INSTANCE) needs to be created and attached to a mixer (or voice). Sample instances control how the underlying samples are played. Several playback parameters (position, speed, gain, pan, playmode, playing/paused) can be adjusted. Particularly, multiple instances may be created from the same sample, e.g. with different parameters.

Audio streams (see above) are similar to sample instances insofar as they respond to the same playback parameters and have to be attached to mixers or voices. A single audio stream can only be played once simultaneously.

For example, consider the following configuration of the audio system.

ALLEGRO_VOICE* voice = al_create_voice(44100, ALLEGRO_AUDIO_DEPTH_INT16,
    ALLEGRO_CHANNEL_CONF_2);

ALLEGRO_MIXER* mixer_1 = al_create_mixer(44100, ALLEGRO_AUDIO_DEPTH_FLOAT32,
    ALLEGRO_CHANNEL_CONF_2);
ALLEGRO_MIXER* mixer_2 = al_create_mixer(44100, ALLEGRO_AUDIO_DEPTH_FLOAT32,
    ALLEGRO_CHANNEL_CONF_2);

/* Load a stream, the stream starts in a playing state and just needs
 * to be attached to actually output sound. */
ALLEGRO_AUDIO_STREAM* stream = al_load_audio_stream("music.ogg", 4, 2048);

/* The sample needs sample instances to output sound. */
ALLEGRO_SAMPLE* sample = al_load_sample("sound.wav")
ALLEGRO_SAMPLE_INSTANCE* instance_1 = al_create_sample_instance(sample);
ALLEGRO_SAMPLE_INSTANCE* instance_2 = al_create_sample_instance(sample);

/* Attach everything up (see diagram). */
al_attach_mixer_to_voice(mixer_1, voice);
al_attach_mixer_to_mixer(mixer_2, mixer_1);
al_attach_audio_stream_to_mixer(stream, mixer_1);
al_attach_sample_instance_to_mixer(instance_1, mixer_2);
al_attach_sample_instance_to_mixer(instance_2, mixer_2);

/* Play two copies of the sound simultaneously. */
al_set_sample_instance_playing(instance_1, true);
al_set_sample_instance_playing(instance_2, true);
An example configuration of the audio system to play music and a sound.

An example configuration of the audio system to play music and a sound.

Since we have two mixers, with the sample instances connected to a different mixer than the audio stream, you can control the volume of all the instances independently from the music by setting the gain of the mixer / stream. Having two sample instances lets you play two copies of the sample simultaneously.

With this in mind, another look at al_reserve_samples and al_play_sample is due: What the former does internally is to create a specified number of sample instances that are "empty" at first, i.e. with no sample data set. When al_play_sample is called, it'll use one of these internal sample instances that is not currently playing to play the requested sample. All of these sample instances will be attached to the default mixer, which can be changed via al_set_default_mixer.

See Audio recording for Allegro's audio recording API, which is, as of now, still unstable and subject to change.

Audio types

Events sent by al_get_audio_stream_event_source or al_get_audio_recorder_event_source.

ALLEGRO_AUDIO_EVENT_TYPE

enum ALLEGRO_AUDIO_EVENT_TYPE

Source Code

ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT

Sent when a stream fragment is ready to be filled in. See al_get_audio_stream_fragment.

ALLEGRO_EVENT_AUDIO_STREAM_FINISHED

Sent when a stream is finished.

ALLEGRO_EVENT_AUDIO_RECORDER_FRAGMENT

Sent after a user-specified number of samples have been recorded. Convert this to ALLEGRO_AUDIO_RECORDER_EVENT via al_get_audio_recorder_event.

You must always check the values for the buffer and samples as they are not guaranteed to be exactly what was originally specified.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

ALLEGRO_AUDIO_DEPTH

enum ALLEGRO_AUDIO_DEPTH

Source Code

Sample depth and type as well as signedness. Mixers only use 32-bit signed float (-1..+1), or 16-bit signed integers. Signedness is determined by an "unsigned" bit-flag applied to the depth value.

  • ALLEGRO_AUDIO_DEPTH_INT8
  • ALLEGRO_AUDIO_DEPTH_INT16
  • ALLEGRO_AUDIO_DEPTH_INT24
  • ALLEGRO_AUDIO_DEPTH_FLOAT32
  • ALLEGRO_AUDIO_DEPTH_UNSIGNED

For convenience:

  • ALLEGRO_AUDIO_DEPTH_UINT8
  • ALLEGRO_AUDIO_DEPTH_UINT16
  • ALLEGRO_AUDIO_DEPTH_UINT24

ALLEGRO_AUDIO_PAN_NONE

#define ALLEGRO_AUDIO_PAN_NONE      (-1000.0f)

Source Code

A special value for the pan property of sample instances and audio streams. Use this value to disable panning on sample instances and audio streams, and play them without attentuation implied by panning support.

ALLEGRO_AUDIO_PAN_NONE is different from a pan value of 0.0 (centered) because, when panning is enabled, we try to maintain a constant sound power level as a sample is panned from left to right. A sound coming out of one speaker should sound as loud as it does when split over two speakers. As a consequence, a sample with pan value 0.0 will be 3 dB softer than the original level.

(Please correct us if this is wrong.)

ALLEGRO_CHANNEL_CONF

enum ALLEGRO_CHANNEL_CONF

Source Code

Speaker configuration (mono, stereo, 2.1, etc).

  • ALLEGRO_CHANNEL_CONF_1
  • ALLEGRO_CHANNEL_CONF_2
  • ALLEGRO_CHANNEL_CONF_3
  • ALLEGRO_CHANNEL_CONF_4
  • ALLEGRO_CHANNEL_CONF_5_1
  • ALLEGRO_CHANNEL_CONF_6_1
  • ALLEGRO_CHANNEL_CONF_7_1

ALLEGRO_MIXER

typedef struct ALLEGRO_MIXER ALLEGRO_MIXER;

Source Code

A mixer mixes together attached streams into a single buffer. In the process, it converts channel configurations, sample frequencies and audio depths of the attached sample instances and audio streams accordingly. You can control the quality of this conversion using ALLEGRO_MIXER_QUALITY.

When going from mono to stereo (and above), the mixer reduces the volume of both channels by sqrt(2). When going from stereo (and above) to mono, the mixer reduces the volume of the left and right channels by sqrt(2) before adding them to the center channel (if present).

ALLEGRO_MIXER_QUALITY

enum ALLEGRO_MIXER_QUALITY

Source Code

  • ALLEGRO_MIXER_QUALITY_POINT - point sampling
  • ALLEGRO_MIXER_QUALITY_LINEAR - linear interpolation
  • ALLEGRO_MIXER_QUALITY_CUBIC - cubic interpolation (since: 5.0.8, 5.1.4)

ALLEGRO_PLAYMODE

enum ALLEGRO_PLAYMODE

Source Code

Sample and stream playback mode.

  • ALLEGRO_PLAYMODE_ONCE
  • ALLEGRO_PLAYMODE_LOOP
  • ALLEGRO_PLAYMODE_BIDIR

ALLEGRO_SAMPLE_ID

typedef struct ALLEGRO_SAMPLE_ID ALLEGRO_SAMPLE_ID;

Source Code

An ALLEGRO_SAMPLE_ID represents a sample being played via al_play_sample. It can be used to later stop the sample with al_stop_sample. The underlying ALLEGRO_SAMPLE_INSTANCE can be extracted using al_lock_sample_id.

ALLEGRO_SAMPLE

typedef struct ALLEGRO_SAMPLE ALLEGRO_SAMPLE;

Source Code

An ALLEGRO_SAMPLE object stores the data necessary for playing pre-defined digital audio. It holds a user-specified PCM data buffer and information about its format (data length, depth, frequency, channel configuration). You can have the same ALLEGRO_SAMPLE playing multiple times simultaneously.

See also: ALLEGRO_SAMPLE_INSTANCE

ALLEGRO_SAMPLE_INSTANCE

typedef struct ALLEGRO_SAMPLE_INSTANCE ALLEGRO_SAMPLE_INSTANCE;

Source Code

An ALLEGRO_SAMPLE_INSTANCE object represents a playable instance of a predefined sound effect. It holds information about how the effect should be played: These playback parameters consist of the looping mode, loop start/end points, playing position, speed, gain, pan and the playmode. Whether a sample instance is currently playing or paused is also one of its properties.

An instance uses the data from an ALLEGRO_SAMPLE object. Multiple instances may be created from the same ALLEGRO_SAMPLE. An ALLEGRO_SAMPLE must not be destroyed while there are instances which reference it.

To actually produce audio output, an ALLEGRO_SAMPLE_INSTANCE must be attached to an ALLEGRO_MIXER which eventually reaches an ALLEGRO_VOICE object.

See also: ALLEGRO_SAMPLE

ALLEGRO_AUDIO_STREAM

typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;

Source Code

An ALLEGRO_AUDIO_STREAM object is used to stream generated audio to the sound device, in real-time. This is done by reading from a buffer, which is split into a number of fragments. Whenever a fragment has finished playing, the user can refill it with new data.

As with ALLEGRO_SAMPLE_INSTANCE objects, streams store information necessary for playback, so you may not play the same stream multiple times simultaneously. Streams also need to be attached to an ALLEGRO_MIXER, which, eventually, reaches an ALLEGRO_VOICE object.

While playing, you must periodically fill fragments with new audio data. To know when a new fragment is ready to be filled, you can either directly check with al_get_available_audio_stream_fragments, or listen to events from the stream.

You can register an audio stream event source to an event queue; see al_get_audio_stream_event_source. An ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT event is generated whenever a new fragment is ready. When you receive an event, use al_get_audio_stream_fragment to obtain a pointer to the fragment to be filled. The size and format are determined by the parameters passed to al_create_audio_stream.

If you're late with supplying new data, the stream will be silent until new data is provided. You must call al_drain_audio_stream when you're finished with supplying data to the stream.

If the stream is created by al_load_audio_stream then it will also generate an ALLEGRO_EVENT_AUDIO_STREAM_FINISHED event if it reaches the end of the file and is not set to loop.

ALLEGRO_VOICE

typedef struct ALLEGRO_VOICE ALLEGRO_VOICE;

Source Code

A voice represents an audio device on the system, which may be a real device, or an abstract device provided by the operating system. To play back audio, you would attach a mixer, sample instance or audio stream to a voice.

See also: ALLEGRO_MIXER, ALLEGRO_SAMPLE, ALLEGRO_AUDIO_STREAM

Setting up audio

al_install_audio

bool al_install_audio(void)

Source Code

Install the audio subsystem.

Returns true on success, false on failure.

Note: most users will call al_reserve_samples and al_init_acodec_addon after this.

See also: al_reserve_samples, al_uninstall_audio, al_is_audio_installed, al_init_acodec_addon

al_uninstall_audio

void al_uninstall_audio(void)

Source Code

Uninstalls the audio subsystem.

See also: al_install_audio

al_is_audio_installed

bool al_is_audio_installed(void)

Source Code

Returns true if al_install_audio was called previously and returned successfully.

al_reserve_samples

bool al_reserve_samples(int reserve_samples)

Source Code

Reserves a number of sample instances, attaching them to the default mixer. If no default mixer is set when this function is called, then it will create one and attach it to the default voice. If no default voice has been set, it, too, will be created.

If you call this function a second time with a smaller number of samples, then the excess internal sample instances will be destroyed causing some sounds to stop and some instances returned by al_lock_sample_id to be invalidated.

This diagram illustrates the structures that are set up:

                                      sample instance 1
                                    / sample instance 2
default voice <-- default mixer <---         .
                                    \        .
                                      sample instance N

Returns true on success, false on error. al_install_audio must have been called first.

See also: al_set_default_mixer, al_play_sample

Misc audio functions

al_get_allegro_audio_version

uint32_t al_get_allegro_audio_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

al_get_audio_depth_size

size_t al_get_audio_depth_size(ALLEGRO_AUDIO_DEPTH depth)

Source Code

Return the size of a sample, in bytes, for the given format. The format is one of the values listed under ALLEGRO_AUDIO_DEPTH.

al_get_channel_count

size_t al_get_channel_count(ALLEGRO_CHANNEL_CONF conf)

Source Code

Return the number of channels for the given channel configuration, which is one of the values listed under ALLEGRO_CHANNEL_CONF.

al_fill_silence

void al_fill_silence(void *buf, unsigned int samples,
   ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)

Source Code

Fill a buffer with silence, for the given format and channel configuration. The buffer must have enough space for the given number of samples, and be properly aligned.

Since: 5.1.8

Voice functions

al_create_voice

ALLEGRO_VOICE *al_create_voice(unsigned int freq,
   ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)

Source Code

Creates a voice structure and allocates a voice from the digital sound driver. The passed frequency (in Hz), sample format and channel configuration are used as a hint to what kind of data will be sent to the voice. However, the underlying sound driver is free to use non-matching values. For example, it may be the native format of the sound hardware.

If a mixer is attached to the voice, the mixer will handle the conversion of all its input streams to the voice format and care does not have to be taken for this. However if you access the voice directly, make sure to not rely on the parameters passed to this function, but instead query the returned voice for the actual settings.

See also: al_destroy_voice

al_destroy_voice

void al_destroy_voice(ALLEGRO_VOICE *voice)

Source Code

Destroys the voice and deallocates it from the digital driver. Does nothing if the voice is NULL.

See also: al_create_voice

al_detach_voice

void al_detach_voice(ALLEGRO_VOICE *voice)

Source Code

Detaches the mixer, sample instance or audio stream from the voice.

See also: al_attach_mixer_to_voice, al_attach_sample_instance_to_voice, al_attach_audio_stream_to_voice

al_attach_audio_stream_to_voice

bool al_attach_audio_stream_to_voice(ALLEGRO_AUDIO_STREAM *stream,
   ALLEGRO_VOICE *voice)

Source Code

Attaches an audio stream to a voice. The same rules as al_attach_sample_instance_to_voice apply. This may fail if the driver can't create a voice with the buffer count and buffer size the stream uses.

An audio stream attached directly to a voice has a number of limitations: The audio stream plays immediately and cannot be stopped. The stream position, speed, gain and panning cannot be changed. At this time, we don't recommend attaching audio streams directly to voices. Use a mixer inbetween.

Returns true on success, false on failure.

See also: al_detach_voice

al_attach_mixer_to_voice

bool al_attach_mixer_to_voice(ALLEGRO_MIXER *mixer, ALLEGRO_VOICE *voice)

Source Code

Attaches a mixer to a voice. It must have the same frequency and channel configuration, but the depth may be different.

Returns true on success, false on failure.

See also: al_detach_voice

al_attach_sample_instance_to_voice

bool al_attach_sample_instance_to_voice(ALLEGRO_SAMPLE_INSTANCE *spl,
   ALLEGRO_VOICE *voice)

Source Code

Attaches a sample instance to a voice, and allows it to play. The instance's gain and loop mode will be ignored, and it must have the same frequency, channel configuration and depth (including signed-ness) as the voice. This function may fail if the selected driver doesn't support preloading sample data.

At this time, we don't recommend attaching sample instances directly to voices. Use a mixer inbetween.

Returns true on success, false on failure.

See also: al_detach_voice

al_get_voice_frequency

unsigned int al_get_voice_frequency(const ALLEGRO_VOICE *voice)

Source Code

Return the frequency of the voice (in Hz), e.g. 44100.

al_get_voice_channels

ALLEGRO_CHANNEL_CONF al_get_voice_channels(const ALLEGRO_VOICE *voice)

Source Code

Return the channel configuration of the voice.

See also: ALLEGRO_CHANNEL_CONF.

al_get_voice_depth

ALLEGRO_AUDIO_DEPTH al_get_voice_depth(const ALLEGRO_VOICE *voice)

Source Code

Return the audio depth of the voice.

See also: ALLEGRO_AUDIO_DEPTH.

al_get_voice_playing

bool al_get_voice_playing(const ALLEGRO_VOICE *voice)

Source Code

Return true if the voice is currently playing.

See also: al_set_voice_playing

al_set_voice_playing

bool al_set_voice_playing(ALLEGRO_VOICE *voice, bool val)

Source Code

Change whether a voice is playing or not. This can only work if the voice has a non-streaming object attached to it, e.g. a sample instance. On success the voice's current sample position is reset.

Returns true on success, false on failure.

See also: al_get_voice_playing

al_get_voice_position

unsigned int al_get_voice_position(const ALLEGRO_VOICE *voice)

Source Code

When the voice has a non-streaming object attached to it, e.g. a sample, returns the voice's current sample position. Otherwise, returns zero.

See also: al_set_voice_position.

al_set_voice_position

bool al_set_voice_position(ALLEGRO_VOICE *voice, unsigned int val)

Source Code

Set the voice position. This can only work if the voice has a non-streaming object attached to it, e.g. a sample instance.

Returns true on success, false on failure.

See also: al_get_voice_position.

Sample functions

al_create_sample

ALLEGRO_SAMPLE *al_create_sample(void *buf, unsigned int samples,
   unsigned int freq, ALLEGRO_AUDIO_DEPTH depth,
   ALLEGRO_CHANNEL_CONF chan_conf, bool free_buf)

Source Code

Create a sample data structure from the supplied buffer. If free_buf is true then the buffer will be freed with al_free when the sample data structure is destroyed. For portability (especially Windows), the buffer should have been allocated with al_malloc. Otherwise you should free the sample data yourself.

A sample that is referred to by the samples parameter refers to a sequence channel intensities. E.g. if you're making a stereo sample with the samples set to 4, then the layout of the data in buf will be:

LRLRLRLR

Where L and R are the intensities for the left and right channels respectively. A single sample, then, refers to the LR pair in this example.

To allocate a buffer of the correct size, you can use something like this:

int sample_size = al_get_channel_count(chan_conf)
                  * al_get_audio_depth_size(depth);
int bytes = samples * sample_size;
void *buffer = al_malloc(bytes);

See also: al_destroy_sample, ALLEGRO_AUDIO_DEPTH, ALLEGRO_CHANNEL_CONF

al_destroy_sample

void al_destroy_sample(ALLEGRO_SAMPLE *spl)

Source Code

Free the sample data structure. If it was created with the free_buf parameter set to true, then the buffer will be freed with al_free.

This function will stop any sample instances which may be playing the buffer referenced by the ALLEGRO_SAMPLE.

See also: al_destroy_sample_instance, al_stop_sample, al_stop_samples

al_play_sample

bool al_play_sample(ALLEGRO_SAMPLE *spl, float gain, float pan, float speed,
   ALLEGRO_PLAYMODE loop, ALLEGRO_SAMPLE_ID *ret_id)

Source Code

Plays a sample on one of the sample instances created by al_reserve_samples. Returns true on success, false on failure. Playback may fail because all the reserved sample instances are currently used.

Parameters:

  • gain - relative volume at which the sample is played; 1.0 is normal.
  • pan - 0.0 is centred, -1.0 is left, 1.0 is right, or ALLEGRO_AUDIO_PAN_NONE.
  • speed - relative speed at which the sample is played; 1.0 is normal.
  • loop - ALLEGRO_PLAYMODE_ONCE, ALLEGRO_PLAYMODE_LOOP, or ALLEGRO_PLAYMODE_BIDIR
  • ret_id - if non-NULL the variable which this points to will be assigned an id representing the sample being played. If al_play_sample returns false, then the contents of ret_id are invalid and must not be used as argument to other functions.

See also: ALLEGRO_PLAYMODE, ALLEGRO_AUDIO_PAN_NONE, ALLEGRO_SAMPLE_ID, al_stop_sample, al_stop_samples, al_lock_sample_id.

al_stop_sample

void al_stop_sample(ALLEGRO_SAMPLE_ID *spl_id)

Source Code

Stop the sample started by al_play_sample.

See also: al_stop_samples

al_lock_sample_id

ALLEGRO_SAMPLE_INSTANCE* al_lock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)

Source Code

Locks a ALLEGRO_SAMPLE_ID, returning the underlying ALLEGRO_SAMPLE_INSTANCE. This allows you to adjust the various properties of the instance (such as volume, pan, etc) while the sound is playing.

This function will return NULL if the sound corresponding to the id is no longer playing.

While locked, ALLEGRO_SAMPLE_ID will be unavailable to additional calls to al_play_sample, even if the sound stops while locked. To put the ALLEGRO_SAMPLE_ID back into the pool for reuse, make sure to call al_unlock_sample_id when you're done with the instance.

See also: al_play_sample, al_unlock_sample_id

Since: 5.2.3

Unstable API: New API.

al_unlock_sample_id

void al_unlock_sample_id(ALLEGRO_SAMPLE_ID *spl_id)

Source Code

Unlocks a ALLEGRO_SAMPLE_ID, allowing future calls to al_play_sample to reuse it if possible. Note that after the id is unlocked, the ALLEGRO_SAMPLE_INSTANCE that was previously returned by al_lock_sample_id will possibly be playing a different sound, so you should only use it after locking the id again.

See also: al_play_sample, al_lock_sample_id

Since: 5.2.3

Unstable API: New API.

al_stop_samples

void al_stop_samples(void)

Source Code

Stop all samples started by al_play_sample.

See also: al_stop_sample

al_get_sample_channels

ALLEGRO_CHANNEL_CONF al_get_sample_channels(const ALLEGRO_SAMPLE *spl)

Source Code

Return the channel configuration of the sample.

See also: ALLEGRO_CHANNEL_CONF, al_get_sample_depth, al_get_sample_frequency, al_get_sample_length, al_get_sample_data

al_get_sample_depth

ALLEGRO_AUDIO_DEPTH al_get_sample_depth(const ALLEGRO_SAMPLE *spl)

Source Code

Return the audio depth of the sample.

See also: ALLEGRO_AUDIO_DEPTH, al_get_sample_channels, al_get_sample_frequency, al_get_sample_length, al_get_sample_data

al_get_sample_frequency

unsigned int al_get_sample_frequency(const ALLEGRO_SAMPLE *spl)

Source Code

Return the frequency (in Hz) of the sample.

See also: al_get_sample_channels, al_get_sample_depth, al_get_sample_length, al_get_sample_data

al_get_sample_length

unsigned int al_get_sample_length(const ALLEGRO_SAMPLE *spl)

Source Code

Return the length of the sample in sample values.

See also: al_get_sample_channels, al_get_sample_depth, al_get_sample_frequency, al_get_sample_data

al_get_sample_data

void *al_get_sample_data(const ALLEGRO_SAMPLE *spl)

Source Code

Return a pointer to the raw sample data.

See also: al_get_sample_channels, al_get_sample_depth, al_get_sample_frequency, al_get_sample_length

Sample instance functions

al_create_sample_instance

ALLEGRO_SAMPLE_INSTANCE *al_create_sample_instance(ALLEGRO_SAMPLE *sample_data)

Source Code

Creates a sample instance, using the supplied sample data. The instance must be attached to a mixer (or voice) in order to actually produce output.

The argument may be NULL. You can then set the sample data later with al_set_sample.

See also: al_destroy_sample_instance

al_destroy_sample_instance

void al_destroy_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Detaches the sample instance from anything it may be attached to and frees it (the sample data, i.e. its ALLEGRO_SAMPLE, is not freed!).

See also: al_create_sample_instance

al_play_sample_instance

bool al_play_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Play the sample instance. Returns true on success, false on failure.

See also: al_stop_sample_instance

al_stop_sample_instance

bool al_stop_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Stop an sample instance playing.

See also: al_play_sample_instance

al_get_sample_instance_channels

ALLEGRO_CHANNEL_CONF al_get_sample_instance_channels(
   const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the channel configuration of the sample instance's sample data.

See also: ALLEGRO_CHANNEL_CONF.

al_get_sample_instance_depth

ALLEGRO_AUDIO_DEPTH al_get_sample_instance_depth(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the audio depth of the sample instance's sample data.

See also: ALLEGRO_AUDIO_DEPTH.

al_get_sample_instance_frequency

unsigned int al_get_sample_instance_frequency(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the frequency (in Hz) of the sample instance's sample data.

al_get_sample_instance_length

unsigned int al_get_sample_instance_length(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the length of the sample instance in sample values. This property may differ from the length of the instance's sample data.

See also: al_set_sample_instance_length, al_get_sample_instance_time

al_set_sample_instance_length

bool al_set_sample_instance_length(ALLEGRO_SAMPLE_INSTANCE *spl,
   unsigned int val)

Source Code

Set the length of the sample instance in sample values. This can be used to play only parts of the underlying sample. Be careful not to exceed the actual length of the sample data, though.

Return true on success, false on failure. Will fail if the sample instance is currently playing.

See also: al_get_sample_instance_length

al_get_sample_instance_position

unsigned int al_get_sample_instance_position(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Get the playback position of a sample instance.

See also: al_set_sample_instance_position

al_set_sample_instance_position

bool al_set_sample_instance_position(ALLEGRO_SAMPLE_INSTANCE *spl,
   unsigned int val)

Source Code

Set the playback position of a sample instance.

Returns true on success, false on failure.

See also: al_get_sample_instance_position

al_get_sample_instance_speed

float al_get_sample_instance_speed(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the relative playback speed of the sample instance.

See also: al_set_sample_instance_speed

al_set_sample_instance_speed

bool al_set_sample_instance_speed(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

Source Code

Set the relative playback speed of the sample instance. 1.0 means normal speed.

Return true on success, false on failure. Will fail if the sample instance is attached directly to a voice.

See also: al_get_sample_instance_speed

al_get_sample_instance_gain

float al_get_sample_instance_gain(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the playback gain of the sample instance.

See also: al_set_sample_instance_gain

al_set_sample_instance_gain

bool al_set_sample_instance_gain(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

Source Code

Set the playback gain of the sample instance.

Returns true on success, false on failure. Will fail if the sample instance is attached directly to a voice.

See also: al_get_sample_instance_gain

al_get_sample_instance_pan

float al_get_sample_instance_pan(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Get the pan value of the sample instance.

See also: al_set_sample_instance_pan.

al_set_sample_instance_pan

bool al_set_sample_instance_pan(ALLEGRO_SAMPLE_INSTANCE *spl, float val)

Source Code

Set the pan value on a sample instance. A value of -1.0 means to play the sample only through the left speaker; +1.0 means only through the right speaker; 0.0 means the sample is centre balanced. A special value ALLEGRO_AUDIO_PAN_NONE disables panning and plays the sample at its original level. This will be louder than a pan value of 0.0.

Note: panning samples with more than two channels doesn't work yet.

Returns true on success, false on failure. Will fail if the sample instance is attached directly to a voice.

See also: al_get_sample_instance_pan, ALLEGRO_AUDIO_PAN_NONE

al_get_sample_instance_time

float al_get_sample_instance_time(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the length of the sample instance in seconds, assuming a playback speed of 1.0.

See also: al_get_sample_instance_length

al_get_sample_instance_playmode

ALLEGRO_PLAYMODE al_get_sample_instance_playmode(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the playback mode of the sample instance.

See also: ALLEGRO_PLAYMODE, al_set_sample_instance_playmode

al_set_sample_instance_playmode

bool al_set_sample_instance_playmode(ALLEGRO_SAMPLE_INSTANCE *spl,
   ALLEGRO_PLAYMODE val)

Source Code

Set the playback mode of the sample instance.

Returns true on success, false on failure.

See also: ALLEGRO_PLAYMODE, al_get_sample_instance_playmode

al_get_sample_instance_playing

bool al_get_sample_instance_playing(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return true if the sample instance is in the playing state. This may be true even if the instance is not attached to anything.

See also: al_set_sample_instance_playing

al_set_sample_instance_playing

bool al_set_sample_instance_playing(ALLEGRO_SAMPLE_INSTANCE *spl, bool val)

Source Code

Change whether the sample instance is playing.

The instance does not need to be attached to anything (since: 5.1.8).

Returns true on success, false on failure.

See also: al_get_sample_instance_playing

al_get_sample_instance_attached

bool al_get_sample_instance_attached(const ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return whether the sample instance is attached to something.

See also: al_attach_sample_instance_to_mixer, al_attach_sample_instance_to_voice, al_detach_sample_instance

al_detach_sample_instance

bool al_detach_sample_instance(ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Detach the sample instance from whatever it's attached to, if anything.

Returns true on success.

See also: al_attach_sample_instance_to_mixer, al_attach_sample_instance_to_voice, al_get_sample_instance_attached

al_get_sample

ALLEGRO_SAMPLE *al_get_sample(ALLEGRO_SAMPLE_INSTANCE *spl)

Source Code

Return the sample data that the sample instance plays.

Note this returns a pointer to an internal structure, not the ALLEGRO_SAMPLE that you may have passed to al_set_sample. However, the sample buffer of the returned ALLEGRO_SAMPLE will be the same as the one that was used to create the sample (passed to al_create_sample). You can use al_get_sample_data on the return value to retrieve and compare it.

See also: al_set_sample

al_set_sample

bool al_set_sample(ALLEGRO_SAMPLE_INSTANCE *spl, ALLEGRO_SAMPLE *data)

Source Code

Change the sample data that a sample instance plays. This can be quite an involved process.

First, the sample is stopped if it is not already.

Next, if data is NULL, the sample is detached from its parent (if any).

If data is not NULL, the sample may be detached and reattached to its parent (if any). This is not necessary if the old sample data and new sample data have the same frequency, depth and channel configuration. Reattaching may not always succeed.

On success, the sample remains stopped. The playback position and loop end points are reset to their default values. The loop mode remains unchanged.

Returns true on success, false on failure. On failure, the sample will be stopped and detached from its parent.

See also: al_get_sample

al_set_sample_instance_channel_matrix

bool al_set_sample_instance_channel_matrix(ALLEGRO_SAMPLE_INSTANCE *spl, const float *matrix)

Source Code

Set the matrix used to mix the channels coming from this instance into the mixer it is attached to. Normally Allegro derives the values of this matrix from the gain and pan settings, as well as the channel configurations of this instance and the mixer it is attached to, but this allows you override that default value. Note that if you do set gain or pan of this instance or the mixer it is attached to, you'll need to call this function again.

The matrix has mixer channel rows and sample channel columns, and is row major. For example, if you have a stereo sample instance and want to mix it to a 5.1 mixer you could use this code:

float matrix[] = {
    0.5, 0.0, /* Half left to front left */
    0.0, 0.5, /* Half right to front right */
    0.5, 0.0, /* Half left to rear left */
    0.0, 0.5, /* Half right to rear right */
    0.1, 0.1, /* Mix left and right for center */
    0.1, 0.1, /* Mix left and right for center */
};

al_set_sample_instance_channel_matrix(instance, matrix);

Returns true on success, false on failure (e.g. if this is not attached to a mixer).

Since: 5.2.3

Unstable API: New API.

Mixer functions

al_create_mixer

ALLEGRO_MIXER *al_create_mixer(unsigned int freq,
   ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)

Source Code

Creates a mixer to attach sample instances, audio streams, or other mixers to. It will mix into a buffer at the requested frequency (in Hz) and channel count.

The only supported audio depths are ALLEGRO_AUDIO_DEPTH_FLOAT32 and ALLEGRO_AUDIO_DEPTH_INT16 (not yet complete).

To actually produce any output, the mixer will have to be attached to a voice.

Returns true on success, false on error.

See also: al_destroy_mixer, ALLEGRO_AUDIO_DEPTH, ALLEGRO_CHANNEL_CONF

al_destroy_mixer

void al_destroy_mixer(ALLEGRO_MIXER *mixer)

Source Code

Destroys the mixer.

See also: al_create_mixer

al_get_default_mixer

ALLEGRO_MIXER *al_get_default_mixer(void)

Source Code

Return the default mixer, or NULL if one has not been set. Although different configurations of mixers and voices can be used, in most cases a single mixer attached to a voice is what you want. The default mixer is used by al_play_sample.

See also: al_reserve_samples, al_play_sample, al_set_default_mixer, al_restore_default_mixer

al_set_default_mixer

bool al_set_default_mixer(ALLEGRO_MIXER *mixer)

Source Code

Sets the default mixer. All samples started with al_play_sample will be stopped and all sample instances returned by al_lock_sample_id will be invalidated. If you are using your own mixer, this should be called before al_reserve_samples.

Returns true on success, false on error.

See also: al_reserve_samples, al_play_sample, al_get_default_mixer, al_restore_default_mixer

al_restore_default_mixer

bool al_restore_default_mixer(void)

Source Code

Restores Allegro's default mixer and attaches it to the default voice. If the default mixer hasn't been created before, it will be created. If the default voice hasn't been set via al_set_default_voice or created before, it will also be created. All samples started with al_play_sample will be stopped and all sample instances returned by al_lock_sample_id will be invalidated.

Returns true on success, false on error.

See also: al_get_default_mixer, al_set_default_mixer, al_reserve_samples.

al_get_default_voice

ALLEGRO_VOICE *al_get_default_voice(void)

Source Code

Returns the default voice or NULL if there is none.

Since: 5.1.13

See also: al_get_default_mixer

al_set_default_voice

void al_set_default_voice(ALLEGRO_VOICE *voice)

Source Code

You can call this before calling al_restore_default_mixer to provide the voice which should be used. Any previous voice will be destroyed. You can also pass NULL to destroy the current default voice.

Since: 5.1.13

See also: al_get_default_mixer

al_attach_mixer_to_mixer

bool al_attach_mixer_to_mixer(ALLEGRO_MIXER *stream, ALLEGRO_MIXER *mixer)

Source Code

Attaches the mixer passed as the first argument onto the mixer passed as the second argument. The first mixer (that is going to be attached) must not already be attached to anything. Both mixers must use the same frequency, audio depth and channel configuration.

Returns true on success, false on error.

It is invalid to attach a mixer to itself.

See also: al_detach_mixer.

al_attach_sample_instance_to_mixer

bool al_attach_sample_instance_to_mixer(ALLEGRO_SAMPLE_INSTANCE *spl,
   ALLEGRO_MIXER *mixer)

Source Code

Attach a sample instance to a mixer. The instance must not already be attached to anything.

Returns true on success, false on failure.

See also: al_detach_sample_instance.

al_attach_audio_stream_to_mixer

bool al_attach_audio_stream_to_mixer(ALLEGRO_AUDIO_STREAM *stream, ALLEGRO_MIXER *mixer)

Source Code

Attach an audio stream to a mixer. The stream must not already be attached to anything.

Returns true on success, false on failure.

See also: al_detach_audio_stream.

al_get_mixer_frequency

unsigned int al_get_mixer_frequency(const ALLEGRO_MIXER *mixer)

Source Code

Return the mixer frequency (in Hz).

See also: al_set_mixer_frequency

al_set_mixer_frequency

bool al_set_mixer_frequency(ALLEGRO_MIXER *mixer, unsigned int val)

Source Code

Set the mixer frequency (in Hz). This will only work if the mixer is not attached to anything.

Returns true on success, false on failure.

See also: al_get_mixer_frequency

al_get_mixer_channels

ALLEGRO_CHANNEL_CONF al_get_mixer_channels(const ALLEGRO_MIXER *mixer)

Source Code

Return the mixer channel configuration.

See also: ALLEGRO_CHANNEL_CONF.

al_get_mixer_depth

ALLEGRO_AUDIO_DEPTH al_get_mixer_depth(const ALLEGRO_MIXER *mixer)

Source Code

Return the mixer audio depth.

See also: ALLEGRO_AUDIO_DEPTH.

al_get_mixer_gain

float al_get_mixer_gain(const ALLEGRO_MIXER *mixer)

Source Code

Return the mixer gain (amplification factor). The default is 1.0.

Since: 5.0.6, 5.1.0

See also: al_set_mixer_gain.

al_set_mixer_gain

bool al_set_mixer_gain(ALLEGRO_MIXER *mixer, float new_gain)

Source Code

Set the mixer gain (amplification factor).

Returns true on success, false on failure.

Since: 5.0.6, 5.1.0

See also: al_get_mixer_gain

al_get_mixer_quality

ALLEGRO_MIXER_QUALITY al_get_mixer_quality(const ALLEGRO_MIXER *mixer)

Source Code

Return the mixer quality.

See also: ALLEGRO_MIXER_QUALITY, al_set_mixer_quality

al_set_mixer_quality

bool al_set_mixer_quality(ALLEGRO_MIXER *mixer, ALLEGRO_MIXER_QUALITY new_quality)

Source Code

Set the mixer quality. This can only succeed if the mixer does not have anything attached to it.

Returns true on success, false on failure.

See also: ALLEGRO_MIXER_QUALITY, al_get_mixer_quality

al_get_mixer_playing

bool al_get_mixer_playing(const ALLEGRO_MIXER *mixer)

Source Code

Return true if the mixer is playing.

See also: al_set_mixer_playing.

al_set_mixer_playing

bool al_set_mixer_playing(ALLEGRO_MIXER *mixer, bool val)

Source Code

Change whether the mixer is playing.

Returns true on success, false on failure.

See also: al_get_mixer_playing.

al_get_mixer_attached

bool al_get_mixer_attached(const ALLEGRO_MIXER *mixer)

Source Code

Return true if the mixer is attached to something.

See also: al_attach_sample_instance_to_mixer, al_attach_audio_stream_to_mixer, al_attach_mixer_to_mixer, al_detach_mixer

al_detach_mixer

bool al_detach_mixer(ALLEGRO_MIXER *mixer)

Source Code

Detach the mixer from whatever it is attached to, if anything.

See also: al_attach_mixer_to_mixer.

al_set_mixer_postprocess_callback

bool al_set_mixer_postprocess_callback(ALLEGRO_MIXER *mixer,
   void (*pp_callback)(void *buf, unsigned int samples, void *data),
   void *pp_callback_userdata)

Source Code

Sets a post-processing filter function that's called after the attached streams have been mixed. The buffer's format will be whatever the mixer was created with. The sample count and user-data pointer is also passed.

Note: The callback is called from a dedicated audio thread.

Stream functions

al_create_audio_stream

ALLEGRO_AUDIO_STREAM *al_create_audio_stream(size_t fragment_count,
   unsigned int frag_samples, unsigned int freq, ALLEGRO_AUDIO_DEPTH depth,
   ALLEGRO_CHANNEL_CONF chan_conf)

Source Code

Creates an ALLEGRO_AUDIO_STREAM. The stream will be set to play by default. It will feed audio data from a buffer, which is split into a number of fragments.

Parameters:

  • fragment_count - How many fragments to use for the audio stream. Usually only two fragments are required - splitting the audio buffer in two halves. But it means that the only time when new data can be supplied is whenever one half has finished playing. When using many fragments, you usually will use fewer samples for one, so there always will be (small) fragments available to be filled with new data.

  • frag_samples - The size of a fragment in samples. See note and explanation below.

  • freq - The frequency, in Hertz.

  • depth - Must be one of the values listed for ALLEGRO_AUDIO_DEPTH.

  • chan_conf - Must be one of the values listed for ALLEGRO_CHANNEL_CONF.

A sample that is referred to by the frag_samples parameter refers to a sequence channel intensities. E.g. if you're making a stereo stream with the frag_samples set to 4, then the layout of the data in the fragment will be:

LRLRLRLR

Where L and R are the intensities for the left and right channels respectively. A single sample, then, refers to the LR pair in this example.

The choice of fragment_count, frag_samples and freq directly influences the audio delay. The delay in seconds can be expressed as:

delay = fragment_count * frag_samples / freq

This is only the delay due to Allegro's streaming, there may be additional delay caused by sound drivers and/or hardware.

Note: If you know the fragment size in bytes, you can get the size in samples like this:

sample_size = al_get_channel_count(chan_conf) * al_get_audio_depth_size(depth);
samples = bytes_per_fragment / sample_size;

The size of the complete buffer is:

buffer_size = bytes_per_fragment * fragment_count

Note: Unlike many Allegro objects, audio streams are not implicitly destroyed when Allegro is shut down. You must destroy them manually with al_destroy_audio_stream before the audio system is shut down.

al_destroy_audio_stream

void al_destroy_audio_stream(ALLEGRO_AUDIO_STREAM *stream)

Source Code

Destroy an audio stream which was created with al_create_audio_stream or al_load_audio_stream.

Note: If the stream is still attached to a mixer or voice, al_detach_audio_stream is automatically called on it first.

See also: al_drain_audio_stream.

al_get_audio_stream_event_source

ALLEGRO_EVENT_SOURCE *al_get_audio_stream_event_source(
   ALLEGRO_AUDIO_STREAM *stream)

Source Code

Retrieve the associated event source.

See al_get_audio_stream_fragment for a description of the ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT event that audio streams emit.

al_drain_audio_stream

void al_drain_audio_stream(ALLEGRO_AUDIO_STREAM *stream)

Source Code

You should call this to finalise an audio stream that you will no longer be feeding, to wait for all pending buffers to finish playing. The stream's playing state will change to false.

See also: al_destroy_audio_stream

al_rewind_audio_stream

bool al_rewind_audio_stream(ALLEGRO_AUDIO_STREAM *stream)

Source Code

Set the streaming file playing position to the beginning. Returns true on success. Currently this can only be called on streams created with al_load_audio_stream, al_load_audio_stream_f and the format-specific functions underlying those functions.

al_get_audio_stream_frequency

unsigned int al_get_audio_stream_frequency(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the stream frequency (in Hz).

al_get_audio_stream_channels

ALLEGRO_CHANNEL_CONF al_get_audio_stream_channels(
   const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the stream channel configuration.

See also: ALLEGRO_CHANNEL_CONF.

al_get_audio_stream_depth

ALLEGRO_AUDIO_DEPTH al_get_audio_stream_depth(
   const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the stream audio depth.

See also: ALLEGRO_AUDIO_DEPTH.

al_get_audio_stream_length

unsigned int al_get_audio_stream_length(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the stream length in samples.

al_get_audio_stream_speed

float al_get_audio_stream_speed(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the relative playback speed of the stream.

See also: al_set_audio_stream_speed.

al_set_audio_stream_speed

bool al_set_audio_stream_speed(ALLEGRO_AUDIO_STREAM *stream, float val)

Source Code

Set the relative playback speed of the stream. 1.0 means normal speed.

Return true on success, false on failure. Will fail if the audio stream is attached directly to a voice.

See also: al_get_audio_stream_speed.

al_get_audio_stream_gain

float al_get_audio_stream_gain(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the playback gain of the stream.

See also: al_set_audio_stream_gain.

al_set_audio_stream_gain

bool al_set_audio_stream_gain(ALLEGRO_AUDIO_STREAM *stream, float val)

Source Code

Set the playback gain of the stream.

Returns true on success, false on failure. Will fail if the audio stream is attached directly to a voice.

See also: al_get_audio_stream_gain.

al_get_audio_stream_pan

float al_get_audio_stream_pan(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Get the pan value of the stream.

See also: al_set_audio_stream_pan.

al_set_audio_stream_pan

bool al_set_audio_stream_pan(ALLEGRO_AUDIO_STREAM *stream, float val)

Source Code

Set the pan value on an audio stream. A value of -1.0 means to play the stream only through the left speaker; +1.0 means only through the right speaker; 0.0 means the sample is centre balanced. A special value ALLEGRO_AUDIO_PAN_NONE disables panning and plays the stream at its original level. This will be louder than a pan value of 0.0.

Returns true on success, false on failure. Will fail if the audio stream is attached directly to a voice.

See also: al_get_audio_stream_pan, ALLEGRO_AUDIO_PAN_NONE

al_get_audio_stream_playing

bool al_get_audio_stream_playing(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return true if the stream is playing.

See also: al_set_audio_stream_playing.

al_set_audio_stream_playing

bool al_set_audio_stream_playing(ALLEGRO_AUDIO_STREAM *stream, bool val)

Source Code

Change whether the stream is playing.

Returns true on success, false on failure.

See also: al_get_audio_stream_playing

al_get_audio_stream_playmode

ALLEGRO_PLAYMODE al_get_audio_stream_playmode(
   const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the playback mode of the stream.

See also: ALLEGRO_PLAYMODE, al_set_audio_stream_playmode.

al_set_audio_stream_playmode

bool al_set_audio_stream_playmode(ALLEGRO_AUDIO_STREAM *stream,
   ALLEGRO_PLAYMODE val)

Source Code

Set the playback mode of the stream.

Returns true on success, false on failure.

See also: ALLEGRO_PLAYMODE, al_get_audio_stream_playmode.

al_get_audio_stream_attached

bool al_get_audio_stream_attached(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return whether the stream is attached to something.

See also: al_attach_audio_stream_to_mixer, al_attach_audio_stream_to_voice, al_detach_audio_stream.

al_detach_audio_stream

bool al_detach_audio_stream(ALLEGRO_AUDIO_STREAM *stream)

Source Code

Detach the stream from whatever it's attached to, if anything.

See also: al_attach_audio_stream_to_mixer, al_attach_audio_stream_to_voice, al_get_audio_stream_attached.

al_get_audio_stream_played_samples

uint64_t al_get_audio_stream_played_samples(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Get the number of samples consumed by the parent since the audio stream was started.

Since: 5.1.8

al_get_audio_stream_fragment

void *al_get_audio_stream_fragment(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

When using Allegro's audio streaming, you will use this function to continuously provide new sample data to a stream.

If the stream is ready for new data, the function will return the address of an internal buffer to be filled with audio data. The length and format of the buffer are specified with al_create_audio_stream or can be queried with the various functions described here. Once the buffer is filled, you must signal this to Allegro by passing the buffer to al_set_audio_stream_fragment.

If the stream is not ready for new data, the function will return NULL.

Note: If you listen to events from the stream, an ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT event will be generated whenever a new fragment is ready. However, getting an event is not a guarantee that al_get_audio_stream_fragment will not return NULL, so you still must check for it.

See also: al_set_audio_stream_fragment, al_get_audio_stream_event_source, al_get_audio_stream_frequency, al_get_audio_stream_channels, al_get_audio_stream_depth, al_get_audio_stream_length

al_set_audio_stream_fragment

bool al_set_audio_stream_fragment(ALLEGRO_AUDIO_STREAM *stream, void *val)

Source Code

This function needs to be called for every successful call of al_get_audio_stream_fragment to indicate that the buffer (pointed to by val) is filled with new data.

See also: al_get_audio_stream_fragment

al_get_audio_stream_fragments

unsigned int al_get_audio_stream_fragments(const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Returns the number of fragments this stream uses. This is the same value as passed to al_create_audio_stream when a new stream is created.

See also: al_get_available_audio_stream_fragments

al_get_available_audio_stream_fragments

unsigned int al_get_available_audio_stream_fragments(
   const ALLEGRO_AUDIO_STREAM *stream)

Source Code

Returns the number of available fragments in the stream, that is, fragments which are not currently filled with data for playback.

See also: al_get_audio_stream_fragment, al_get_audio_stream_fragments

al_seek_audio_stream_secs

bool al_seek_audio_stream_secs(ALLEGRO_AUDIO_STREAM *stream, double time)

Source Code

Set the streaming file playing position to time. Returns true on success. Currently this can only be called on streams created with al_load_audio_stream, al_load_audio_stream_f and the format-specific functions underlying those functions.

See also: al_get_audio_stream_position_secs, al_get_audio_stream_length_secs

al_get_audio_stream_position_secs

double al_get_audio_stream_position_secs(ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the position of the stream in seconds. Currently this can only be called on streams created with al_load_audio_stream.

See also: al_get_audio_stream_length_secs

al_get_audio_stream_length_secs

double al_get_audio_stream_length_secs(ALLEGRO_AUDIO_STREAM *stream)

Source Code

Return the length of the stream in seconds, if known. Otherwise returns zero.

Currently this can only be called on streams created with al_load_audio_stream, al_load_audio_stream_f and the format-specific functions underlying those functions.

See also: al_get_audio_stream_position_secs

al_set_audio_stream_loop_secs

bool al_set_audio_stream_loop_secs(ALLEGRO_AUDIO_STREAM *stream,
   double start, double end)

Source Code

Sets the loop points for the stream in seconds. Currently this can only be called on streams created with al_load_audio_stream, al_load_audio_stream_f and the format-specific functions underlying those functions.

al_set_audio_stream_channel_matrix

Source Code

Like al_set_sample_instance_channel_matrix but for streams.

Since: 5.2.3

Unstable API: New API.

Audio file I/O

al_register_sample_loader

bool al_register_sample_loader(const char *ext,
   ALLEGRO_SAMPLE *(*loader)(const char *filename))

Source Code

Register a handler for al_load_sample. The given function will be used to handle the loading of sample files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The loader argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_sample_loader_f, al_register_sample_saver

al_register_sample_loader_f

bool al_register_sample_loader_f(const char *ext,
   ALLEGRO_SAMPLE *(*loader)(ALLEGRO_FILE* fp))

Source Code

Register a handler for al_load_sample_f. The given function will be used to handle the loading of sample files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The loader argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_sample_loader

al_register_sample_saver

bool al_register_sample_saver(const char *ext,
   bool (*saver)(const char *filename, ALLEGRO_SAMPLE *spl))

Source Code

Register a handler for al_save_sample. The given function will be used to handle the saving of sample files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The saver argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_sample_saver_f, al_register_sample_loader

al_register_sample_saver_f

bool al_register_sample_saver_f(const char *ext,
   bool (*saver)(ALLEGRO_FILE* fp, ALLEGRO_SAMPLE *spl))

Source Code

Register a handler for al_save_sample_f. The given function will be used to handle the saving of sample files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The saver argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_sample_saver

al_register_audio_stream_loader

bool al_register_audio_stream_loader(const char *ext,
   ALLEGRO_AUDIO_STREAM *(*stream_loader)(const char *filename,
      size_t buffer_count, unsigned int samples))

Source Code

Register a handler for al_load_audio_stream. The given function will be used to open streams from files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The stream_loader argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_audio_stream_loader_f

al_register_audio_stream_loader_f

bool al_register_audio_stream_loader_f(const char *ext,
   ALLEGRO_AUDIO_STREAM *(*stream_loader)(ALLEGRO_FILE* fp,
      size_t buffer_count, unsigned int samples))

Source Code

Register a handler for al_load_audio_stream_f. The given function will be used to open streams from files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The stream_loader argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_audio_stream_loader

al_load_sample

ALLEGRO_SAMPLE *al_load_sample(const char *filename)

Source Code

Loads a few different audio file formats based on their extension.

Note that this stores the entire file in memory at once, which may be time consuming. To read the file as it is needed, use al_load_audio_stream.

Returns the sample on success, NULL on failure.

Note: the allegro_audio library does not support any audio file formats by default. You must use the allegro_acodec addon, or register your own format handler.

See also: al_register_sample_loader, al_init_acodec_addon

al_load_sample_f

ALLEGRO_SAMPLE *al_load_sample_f(ALLEGRO_FILE* fp, const char *ident)

Source Code

Loads an audio file from an ALLEGRO_FILE stream into an ALLEGRO_SAMPLE. The file type is determined by the passed 'ident' parameter, which is a file name extension including the leading dot.

Note that this stores the entire file in memory at once, which may be time consuming. To read the file as it is needed, use al_load_audio_stream_f.

Returns the sample on success, NULL on failure. The file remains open afterwards.

Note: the allegro_audio library does not support any audio file formats by default. You must use the allegro_acodec addon, or register your own format handler.

See also: al_register_sample_loader_f, al_init_acodec_addon

al_load_audio_stream

ALLEGRO_AUDIO_STREAM *al_load_audio_stream(const char *filename,
   size_t buffer_count, unsigned int samples)

Source Code

Loads an audio file from disk as it is needed.

Unlike regular streams, the one returned by this function need not be fed by the user; the library will automatically read more of the file as it is needed. The stream will contain buffer_count buffers with samples samples.

The audio stream will start in the playing state. It should be attached to a voice or mixer to generate any output. See ALLEGRO_AUDIO_STREAM for more details.

Returns the stream on success, NULL on failure.

Note: the allegro_audio library does not support any audio file formats by default. You must use the allegro_acodec addon, or register your own format handler.

See also: al_load_audio_stream_f, al_register_audio_stream_loader, al_init_acodec_addon

al_load_audio_stream_f

ALLEGRO_AUDIO_STREAM *al_load_audio_stream_f(ALLEGRO_FILE* fp, const char *ident,
   size_t buffer_count, unsigned int samples)

Source Code

Loads an audio file from ALLEGRO_FILE stream as it is needed.

Unlike regular streams, the one returned by this function need not be fed by the user; the library will automatically read more of the file as it is needed. The stream will contain buffer_count buffers with samples samples.

The file type is determined by the passed 'ident' parameter, which is a file name extension including the leading dot.

The audio stream will start in the playing state. It should be attached to a voice or mixer to generate any output. See ALLEGRO_AUDIO_STREAM for more details.

Returns the stream on success, NULL on failure. On success the file should be considered owned by the audio stream, and will be closed when the audio stream is destroyed. On failure the file will be closed.

Note: the allegro_audio library does not support any audio file formats by default. You must use the allegro_acodec addon, or register your own format handler.

See also: al_load_audio_stream, al_register_audio_stream_loader_f, al_init_acodec_addon

al_save_sample

bool al_save_sample(const char *filename, ALLEGRO_SAMPLE *spl)

Source Code

Writes a sample into a file. Currently, wav is the only supported format, and the extension must be ".wav".

Returns true on success, false on error.

Note: the allegro_audio library does not support any audio file formats by default. You must use the allegro_acodec addon, or register your own format handler.

See also: al_save_sample_f, al_register_sample_saver, al_init_acodec_addon

al_save_sample_f

bool al_save_sample_f(ALLEGRO_FILE *fp, const char *ident, ALLEGRO_SAMPLE *spl)

Source Code

Writes a sample into a ALLEGRO_FILE filestream. Currently, wav is the only supported format, and the extension must be ".wav".

Returns true on success, false on error. The file remains open afterwards.

Note: the allegro_audio library does not support any audio file formats by default. You must use the allegro_acodec addon, or register your own format handler.

See also: al_save_sample, al_register_sample_saver_f, al_init_acodec_addon

Audio recording

Allegro's audio recording routines give you real-time access to raw, uncompressed audio input streams. Since Allegro hides all of the platform specific implementation details with its own buffering, it will add a small amount of latency. However, for most applications that small overhead will not adversely affect performance.

Recording is supported by the ALSA, AudioQueue, DirectSound8, and PulseAudio drivers. Enumerating or choosing other recording devices is not yet supported.

ALLEGRO_AUDIO_RECORDER

typedef struct ALLEGRO_AUDIO_RECORDER ALLEGRO_AUDIO_RECORDER;

Source Code

An opaque datatype that represents a recording device.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

ALLEGRO_AUDIO_RECORDER_EVENT

typedef struct ALLEGRO_AUDIO_RECORDER_EVENT ALLEGRO_AUDIO_RECORDER_EVENT;

Source Code

Structure that holds the audio recorder event data. Every event type will contain:

  • .source: pointer to the audio recorder

The following will be available depending on the event type:

  • .buffer: pointer to buffer containing the audio samples
  • .samples: number of samples (not bytes) that are available

Since 5.1.1

See also: al_get_audio_recorder_event

Unstable API: The API may need a slight redesign.

al_create_audio_recorder

ALLEGRO_AUDIO_RECORDER *al_create_audio_recorder(size_t fragment_count,
   unsigned int samples, unsigned int frequency,
   ALLEGRO_AUDIO_DEPTH depth, ALLEGRO_CHANNEL_CONF chan_conf)

Source Code

Creates an audio recorder using the system's default recording device. (So if the returned device does not work, try updating the system's default recording device.)

Allegro will internally buffer several seconds of captured audio with minimal latency. (XXX: These settings need to be exposed via config or API calls.) Audio will be copied out of that private buffer into a fragment buffer of the size specified by the samples parameter. Whenever a new fragment is ready an event will be generated.

The total size of the fragment buffer is fragment_count * samples * bytes_per_sample. It is treated as a circular, never ending buffer. If you do not process the information fast enough, it will be overrun. Because of that, even if you only ever need to process one small fragment at a time, you should still use a large enough value for fragment_count to hold a few seconds of audio.

frequency is the number of samples per second to record. Common values are:

  • 8000 - telephone quality speech
  • 11025
  • 22050
  • 44100 - CD quality music (if 16-bit, stereo)

For maximum compatibility, use a depth of ALLEGRO_AUDIO_DEPTH_UINT8 or ALLEGRO_AUDIO_DEPTH_INT16, and a single (mono) channel.

The recorder will not record until you start it with al_start_audio_recorder.

On failure, returns NULL.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

al_start_audio_recorder

bool al_start_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)

Source Code

Begin recording into the fragment buffer. Once a complete fragment has been captured (as specified in al_create_audio_recorder), an ALLEGRO_EVENT_AUDIO_RECORDER_FRAGMENT event will be triggered.

Returns true if it was able to begin recording.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

al_stop_audio_recorder

void al_stop_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)

Source Code

Stop capturing audio data. Note that the audio recorder is still active and consuming resources, so if you are finished recording you should destroy it with al_destroy_audio_recorder.

You may still receive a few events after you call this function as the device flushes the buffer.

If you restart the recorder, it will begin recording at the beginning of the next fragment buffer.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

al_is_audio_recorder_recording

bool al_is_audio_recorder_recording(ALLEGRO_AUDIO_RECORDER *r)

Source Code

Returns true if the audio recorder is currently capturing data and generating events.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

al_get_audio_recorder_event

ALLEGRO_AUDIO_RECORDER_EVENT *al_get_audio_recorder_event(ALLEGRO_EVENT *event)

Source Code

Returns the event as an ALLEGRO_AUDIO_RECORDER_EVENT.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

al_get_audio_recorder_event_source

ALLEGRO_EVENT_SOURCE *al_get_audio_recorder_event_source(ALLEGRO_AUDIO_RECORDER *r)

Source Code

Returns the event source for the recorder that generates the various recording events.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

al_destroy_audio_recorder

void al_destroy_audio_recorder(ALLEGRO_AUDIO_RECORDER *r)

Source Code

Destroys the audio recorder and frees all resources associated with it. It is safe to destroy a recorder that is recording.

You may receive events after the recorder has been destroyed. They must be ignored, as the fragment buffer will no longer be valid.

Since: 5.1.1

Unstable API: The API may need a slight redesign.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:18 UTC


Color addon

  • Fixed point math
  • Fullscreen modes
  • Graphics
  • Haptic
  • Joystick
  • Keyboard
  • Memory
  • Monitor
  • Mouse
  • Path
  • Shader
  • State
  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Color addon

  • al_color_cmyk
  • al_color_cmyk_to_rgb
  • al_color_hsl
  • al_color_hsl_to_rgb
  • al_color_hsv
  • al_color_hsv_to_rgb
  • al_color_html
  • al_color_html_to_rgb
  • al_color_rgb_to_html
  • al_color_name
  • al_color_name_to_rgb
  • al_color_rgb_to_cmyk
  • al_color_rgb_to_hsl
  • al_color_rgb_to_hsv
  • al_color_rgb_to_name
  • al_color_rgb_to_xyz
  • al_color_xyz
  • al_color_xyz_to_rgb
  • al_color_rgb_to_xyy
  • al_color_xyy
  • al_color_xyy_to_rgb
  • al_color_rgb_to_lab
  • al_color_lab
  • al_color_lab_to_rgb
  • al_color_rgb_to_lch
  • al_color_lch
  • al_color_lch_to_rgb
  • al_color_distance_ciede2000_lab
  • al_color_rgb_to_yuv
  • al_color_yuv
  • al_color_yuv_to_rgb
  • al_get_allegro_color_version
  • al_is_color_valid

These functions are declared in the following header file. Link with allegro_color.

 #include <allegro5/allegro_color.h>

When converting between certain color spaces, RGB colors are implicitly assumed to mean sRGB.

sRGB is a standard which maps RGB colors to absolute colors. sRGB is very close to RGB values on a monitor which has a gamma value of 2.2. For example when the red component of a color is 0.5, the monitor will use a brightness of pow(0.5, 2.2) or about 22% - and not 50%. The reason is that human eyes can distinguish better between dark colors than between bright colors, and so if a pixel of the monitor is lit up to 22% of its maximum power it already will appear at half brightness to a human eye.

sRGB improves upon simple gamma correction by taking differences between the three color channels into account as well. In general, most monitors nowadays try to be close to the sRGB specification. And so if in an Allegro game you display something with color

al_map_rgb_f(0.5, 0.5, 0,5)

then it will appear at about half brightness (even though the actual brightness output of the monitor will be less than half).

al_color_cmyk

ALLEGRO_COLOR al_color_cmyk(float c, float m, float y, float k)

Source Code

Return an ALLEGRO_COLOR structure from CMYK values (cyan, magenta, yellow, black).

See also: al_color_cmyk_to_rgb, al_color_rgb_to_cmyk

al_color_cmyk_to_rgb

void al_color_cmyk_to_rgb(float cyan, float magenta, float yellow,
    float key, float *red, float *green, float *blue)

Source Code

Convert CMYK values to RGB values.

See also: al_color_cmyk, al_color_rgb_to_cmyk

al_color_hsl

ALLEGRO_COLOR al_color_hsl(float h, float s, float l)

Source Code

Return an ALLEGRO_COLOR structure from HSL (hue, saturation, lightness) values.

Parameters:

  • hue - Color hue angle in the range 0..360
  • saturation - Color saturation in the range 0..1
  • lightness - Color lightness in the range 0..1

See also: al_color_hsl_to_rgb, al_color_hsv

al_color_hsl_to_rgb

void al_color_hsl_to_rgb(float hue, float saturation, float lightness,
   float *red, float *green, float *blue)

Source Code

Convert values in HSL color model to RGB color model.

Parameters:

  • hue - Color hue angle in the range 0..360
  • saturation - Color saturation in the range 0..1
  • lightness - Color lightness in the range 0..1
  • red, green, blue - returned RGB values in the range 0..1

See also: al_color_rgb_to_hsl, al_color_hsl, al_color_hsv_to_rgb

al_color_hsv

ALLEGRO_COLOR al_color_hsv(float h, float s, float v)

Source Code

Return an ALLEGRO_COLOR structure from HSV (hue, saturation, value) values.

Parameters:

  • hue - Color hue angle in the range 0..360
  • saturation - Color saturation in the range 0..1
  • value - Color value in the range 0..1

See also: al_color_hsv_to_rgb, al_color_hsl

al_color_hsv_to_rgb

void al_color_hsv_to_rgb(float hue, float saturation, float value,
   float *red, float *green, float *blue)

Source Code

Convert values in HSV color model to RGB color model.

Parameters:

  • hue - Color hue angle in the range 0..360
  • saturation - Color saturation in the range 0..1
  • value - Color value in the range 0..1
  • red, green, blue - returned RGB values in the range 0..1

See also: al_color_rgb_to_hsv, al_color_hsv, al_color_hsl_to_rgb

al_color_html

ALLEGRO_COLOR al_color_html(char const *string)

Source Code

Interprets an HTML-style hex number (e.g. #00faff) as a color. The accepted format is the same as al_color_html_to_rgb.

Returns the interpreted color, or al_map_rgba(0, 0, 0, 0) if the string could not be parsed.

Note: the behaviour on invalid strings is different from Allegro 5.0.x.

See also: al_color_html_to_rgb, al_color_rgb_to_html

al_color_html_to_rgb

bool al_color_html_to_rgb(char const *string,
   float *red, float *green, float *blue)

Source Code

Interprets an HTML-style hex number (e.g. #00faff) as a color. The only accepted formats are "#RRGGBB" and "RRGGBB" where R, G, B are hexadecimal digits [0-9A-Fa-f].

Returns true on success, false on failure. On failure all components are set to zero.

Note: the behaviour on invalid strings is different from Allegro 5.0.x.

See also: al_color_html, al_color_rgb_to_html

al_color_rgb_to_html

void al_color_rgb_to_html(float red, float green, float blue,
    char *string)

Source Code

Create an HTML-style string representation of an ALLEGRO_COLOR, e.g. #00faff.

Parameters:

  • red, green, blue - The color components in the range 0..1.
  • string - A pointer to a buffer of at least 8 bytes, into which the result will be written (including the NUL terminator).

Example:

char html[8];
al_color_rgb_to_html(1, 0, 0, html);

Now html will contain "#ff0000".

See also: al_color_html, al_color_html_to_rgb

al_color_name

ALLEGRO_COLOR al_color_name(char const *name)

Source Code

Return an ALLEGRO_COLOR with the given name. If the color is not found then black is returned.

See al_color_name_to_rgb for the list of names.

al_color_name_to_rgb

bool al_color_name_to_rgb(char const *name, float *r, float *g, float *b)

Source Code

Parameters:

  • name - The (lowercase) name of the color.
  • r, g, b - If one of the recognized color names below is passed, the corresponding RGB values in the range 0..1 are written.

The 148 recognized names are:

aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black, blanchedalmond, blue, blueviolet, brown, burlywood, cadetblue, chartreuse, chocolate, coral, cornflowerblue, cornsilk, crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray, darkgreen, darkkhaki, darkmagenta, darkolivegreen, darkorange, darkorchid, darkred, darksalmon, darkseagreen, darkslateblue, darkslategray, darkturquoise, darkviolet, deeppink, deepskyblue, dimgray, dodgerblue, firebrick, floralwhite, forestgreen, fuchsia, gainsboro, ghostwhite, goldenrod, gold, gray, green, greenyellow, honeydew, hotpink, indianred, indigo, ivory, khaki, lavenderblush, lavender, lawngreen, lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow, lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue, lightslategray, lightsteelblue, lightyellow, lime, limegreen, linen, magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple, mediumseagreen, mediumslateblue, mediumspringgreen, mediumturquoise, mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, avajowhite, navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen, paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue, purple, rebeccapurple, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen, seashell, sienna, silver, skyblue, slateblue, slategray, snow, springgreen, steelblue, tan, teal, thistle, tomato, turquoise, violet, wheat, white, whitesmoke, yellow, yellowgreen

They are taken from CSS: https://www.w3.org/TR/css-color-4/

Note that these 9 colors have two names and so there are only 139 distinct colors: aqua = cyan, darkgray = darkgrey, darkslategray = darkslategrey, dimgray = dimgrey, fuchsia = purple, gray = grey, lightgray = lightgrey, lightslategray = lightslategrey, slategray = slategrey

Returns: true if a name from the list above was passed, else false.

See also: al_color_name

al_color_rgb_to_cmyk

void al_color_rgb_to_cmyk(float red, float green, float blue,
   float *cyan, float *magenta, float *yellow, float *key)

Source Code

Each RGB color can be represented in CMYK with a K component of 0 with the following formula:

C = 1 - R
M = 1 - G
Y = 1 - B
K = 0

This function will instead find the representation with the maximal value for K and minimal color components.

See also: al_color_cmyk, al_color_cmyk_to_rgb

al_color_rgb_to_hsl

void al_color_rgb_to_hsl(float red, float green, float blue,
   float *hue, float *saturation, float *lightness)

Source Code

Given an RGB triplet with components in the range 0..1, return the hue in degrees from 0..360 and saturation and lightness in the range 0..1.

See also: al_color_hsl_to_rgb, al_color_hsl

al_color_rgb_to_hsv

void al_color_rgb_to_hsv(float red, float green, float blue,
   float *hue, float *saturation, float *value)

Source Code

Given an RGB triplet with components in the range 0..1, return the hue in degrees from 0..360 and saturation and value in the range 0..1.

See also: al_color_hsv_to_rgb, al_color_hsv

al_color_rgb_to_name

char const *al_color_rgb_to_name(float r, float g, float b)

Source Code

Given an RGB triplet with components in the range 0..1, find a color name describing it approximately.

See also: al_color_name_to_rgb, al_color_name

al_color_rgb_to_xyz

void al_color_rgb_to_xyz(float red, float green, float blue,
   float *x, float *y, float *z)

Source Code

Convert RGB values to XYZ color space.

Since: 5.2.3

See also: al_color_xyz, al_color_xyz_to_rgb

al_color_xyz

ALLEGRO_COLOR al_color_xyz(float x, float y, float z)

Source Code

Return an ALLEGRO_COLOR structure from XYZ values. The CIE 1931 XYZ color space consists of three components in the range 0..1. The Y component corresponds to luminance and the X and Z components define the color.

RGB components are always assumed to be in sRGB space.

Note:

The XYZ color space can represent more colors than are visible in sRGB and therefore conversion may result in RGB values outside of the 0..1 range. You can check for that case with al_is_color_valid.

Since: 5.2.3

See also: al_color_xyz_to_rgb, al_color_rgb_to_xyz

al_color_xyz_to_rgb

void al_color_xyz_to_rgb(float x, float y, float z,
    float *red, float *green, float *blue)

Source Code

Convert XYZ color values to RGB color space.

Since: 5.2.3

See also: al_color_xyz, al_color_rgb_to_xyz

al_color_rgb_to_xyy

void al_color_rgb_to_xyy(float red, float green, float blue,
   float *x, float *y, float *y2)

Source Code

Convert RGB values to xyY color space.

Since: 5.2.3

See also: al_color_xyy, al_color_xyy_to_rgb

al_color_xyy

ALLEGRO_COLOR al_color_xyy(float x, float y, float y2)

Source Code

Return an ALLEGRO_COLOR structure from xyY values. The Y component in the xyY color space is the same as the Y in XYZ.

However the x and y values are computed from XYZ like this:

x = X / (X + Y + Z)
y = Y / (X + Y + Z)

Since: 5.2.3

See also: al_color_xyy_to_rgb, al_color_rgb_to_xyy

al_color_xyy_to_rgb

void al_color_xyy_to_rgb(float x, float y, float y2,
    float *red, float *green, float *blue)

Source Code

Convert xyY color values to RGB color space.

Since: 5.2.3

See also: al_color_xyy, al_color_rgb_to_xyy

al_color_rgb_to_lab

void al_color_rgb_to_lab(float red, float green, float blue,
   float *l, float *a, float *b)

Source Code

Convert RGB values to L*a*b* color space.

Since: 5.2.3

See also: al_color_lab, al_color_lab_to_rgb

al_color_lab

ALLEGRO_COLOR al_color_lab(float l, float a, float b)

Source Code

Return an ALLEGRO_COLOR structure from CIE L*a*b* values. The L* component corresponds to luminance from 0..1. The a* and b* components are in the range -1..+1.

Note:

The L*a*b* color space can represent more colors than are visible in sRGB and therefore conversion may result in RGB values outside of the 0..1 range. You can check for that case with al_is_color_valid.

Note:

In some literature the range of L* is 0 to 100 and a* and b* are from -100 to +100. In that case divide all components by 100 before passing them to this function.

Since: 5.2.3

See also: al_color_lab_to_rgb, al_color_rgb_to_lab

al_color_lab_to_rgb

void al_color_lab_to_rgb(float l, float a, float b,
    float *red, float *green, float *blue)

Source Code

Convert CIE L*a*b* color values to RGB color space.

Since: 5.2.3

See also: al_color_lab, al_color_rgb_to_lab

al_color_rgb_to_lch

void al_color_rgb_to_lch(float red, float green, float blue,
   float *l, float *c, float *h)

Source Code

Convert RGB values to CIE LCH color space.

Since: 5.2.3

See also: al_color_lch, al_color_lch_to_rgb

al_color_lch

ALLEGRO_COLOR al_color_lch(float l, float c, float h)

Source Code

Return an ALLEGRO_COLOR structure from CIE LCH values. LCH colors are very similar to HSL, with the same meaning of L and H and C corresponding to S. However LCH is more visually uniform. Furthermore, this function expects the angle for H in radians and not in degree.

The CIE LCH color space is a cylindrical representation of the L*a*b* color space. The L component is the same and C and H are computed like this:

C = sqrt(a * a + b * b)
H = atan2(b, a)

Since: 5.2.3

See also: al_color_lch_to_rgb, al_color_rgb_to_lch

al_color_lch_to_rgb

void al_color_lch_to_rgb(float l, float c, float h,
    float *red, float *green, float *blue)

Source Code

Convert CIE LCH color values to RGB color space.

Since: 5.2.3

See also: al_color_lch, al_color_rgb_to_lch

al_color_distance_ciede2000_lab

Source Code

This function computes the CIEDE2000 color difference between two RGB colors. This is a visually uniform color difference, unlike for example the RGB distance.

When using the RGB distance (Euklidean distance between two RGB triplets) there can be color pairs with the same distance, where the colors of one pair appear to be almost the same color, while the colors of the other pair look quite different. This is improved by using the L*a*b* color space which was designed with perceptual uniformity in mind. However it still is not completely uniform. The CIEDE2000 formula contains some additional transformations to fix that.

The returned color distance is roughly in the range 0 (identical color) to 1 (completely different color) - but values greater than one are possible.

Note: This function uses al_color_lab internally which defines the L component to be in the range 0..1 (and not 0..100 as is sometimes seen).

Since: 5.2.3

al_color_rgb_to_yuv

void al_color_rgb_to_yuv(float red, float green, float blue,
   float *y, float *u, float *v)

Source Code

Convert RGB values to YUV color space.

See also: al_color_yuv, al_color_yuv_to_rgb

al_color_yuv

ALLEGRO_COLOR al_color_yuv(float y, float u, float v)

Source Code

Return an ALLEGRO_COLOR structure from YUV values.

See also: al_color_yuv_to_rgb, al_color_rgb_to_yuv

al_color_yuv_to_rgb

void al_color_yuv_to_rgb(float y, float u, float v,
    float *red, float *green, float *blue)

Source Code

Convert YUV color values to RGB color space.

See also: al_color_yuv, al_color_rgb_to_yuv

al_get_allegro_color_version

uint32_t al_get_allegro_color_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

al_is_color_valid

Source Code

Checks if all components of the color are between 0 and 1. Some of the color conversions in this addon support color spaces with more colors than can be represented in sRGB and when converted to RGB will result in invalid color components outside the 0..1 range.

Since: 5.2.3

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:18 UTC


Configuration files

  • Haptic
  • Joystick
  • Keyboard
  • Memory
  • Monitor
  • Mouse
  • Path
  • Shader
  • State
  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Configuration files

  • ALLEGRO_CONFIG
  • ALLEGRO_CONFIG_SECTION
  • ALLEGRO_CONFIG_ENTRY
  • al_create_config
  • al_destroy_config
  • al_load_config_file
  • al_load_config_file_f
  • al_save_config_file
  • al_save_config_file_f
  • al_add_config_section
  • al_remove_config_section
  • al_add_config_comment
  • al_get_config_value
  • al_set_config_value
  • al_remove_config_key
  • al_get_first_config_section
  • al_get_next_config_section
  • al_get_first_config_entry
  • al_get_next_config_entry
  • al_merge_config
  • al_merge_config_into

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

Allegro supports reading and writing of configuration files with a simple, INI file-like format.

A configuration file consists of key-value pairs separated by newlines. Keys are separated from values by an equals sign (=). All whitespace before the key, after the value and immediately adjacent to the equals sign is ignored. Keys and values may have whitespace characters within them. Keys do not need to be unique, but all but the last one are ignored.

The hash (#) character is used a comment when it is the first non-whitespace character on the line. All characters following that character are ignored to the end of the line. The hash character anywhere else on the line has no special significance.

Key-value pairs can be optionally grouped into sections, which are declared by surrounding a section name with square brackets ([ and ]) on a single line. Whitespace before the opening bracket is ignored. All characters after the trailing bracket are also ignored.

All key-value pairs that follow a section declaration belong to the last declared section. Key-value pairs that don't follow any section declarations belong to the global section. Sections do not nest.

Here is an example configuration file:

#  Monster description
monster name = Allegro Developer

[weapon 0]
damage = 443

[weapon 1]
damage = 503

It can then be accessed like this (make sure to check for errors in an actual program):

ALLEGRO_CONFIG* cfg = al_load_config_file("test.cfg");
printf("%s\n", al_get_config_value(cfg, "", "monster name")); /* Prints: Allegro Developer */
printf("%s\n", al_get_config_value(cfg, "weapon 0", "damage")); /* Prints: 443 */
printf("%s\n", al_get_config_value(cfg, "weapon 1", "damage")); /* Prints: 503 */
al_destroy_config(cfg);

ALLEGRO_CONFIG

typedef struct ALLEGRO_CONFIG ALLEGRO_CONFIG;

Source Code

An abstract configuration structure.

ALLEGRO_CONFIG_SECTION

typedef struct ALLEGRO_CONFIG_SECTION ALLEGRO_CONFIG_SECTION;

Source Code

An opaque structure used for iterating across sections in a configuration structure.

See also: al_get_first_config_section, al_get_next_config_section

ALLEGRO_CONFIG_ENTRY

typedef struct ALLEGRO_CONFIG_ENTRY ALLEGRO_CONFIG_ENTRY;

Source Code

An opaque structure used for iterating across entries in a configuration section.

See also: al_get_first_config_entry, al_get_next_config_entry

al_create_config

ALLEGRO_CONFIG *al_create_config(void)

Source Code

Create an empty configuration structure.

See also: al_load_config_file, al_destroy_config

al_destroy_config

void al_destroy_config(ALLEGRO_CONFIG *config)

Source Code

Free the resources used by a configuration structure. Does nothing if passed NULL.

See also: al_create_config, al_load_config_file

al_load_config_file

ALLEGRO_CONFIG *al_load_config_file(const char *filename)

Source Code

Read a configuration file from disk. Returns NULL on error. The configuration structure should be destroyed with al_destroy_config.

See also: al_load_config_file_f, al_save_config_file

al_load_config_file_f

ALLEGRO_CONFIG *al_load_config_file_f(ALLEGRO_FILE *file)

Source Code

Read a configuration file from an already open file.

Returns NULL on error. The configuration structure should be destroyed with al_destroy_config. The file remains open afterwards.

See also: al_load_config_file

al_save_config_file

bool al_save_config_file(const char *filename, const ALLEGRO_CONFIG *config)

Source Code

Write out a configuration file to disk. Returns true on success, false on error.

See also: al_save_config_file_f, al_load_config_file

al_save_config_file_f

bool al_save_config_file_f(ALLEGRO_FILE *file, const ALLEGRO_CONFIG *config)

Source Code

Write out a configuration file to an already open file.

Returns true on success, false on error. The file remains open afterwards.

See also: al_save_config_file

al_add_config_section

void al_add_config_section(ALLEGRO_CONFIG *config, const char *name)

Source Code

Add a section to a configuration structure with the given name. If the section already exists then nothing happens.

al_remove_config_section

bool al_remove_config_section(ALLEGRO_CONFIG *config, char const *section)

Source Code

Remove a section of a configuration.

Returns true if the section was removed, or false if the section did not exist.

Since: 5.1.5

al_add_config_comment

void al_add_config_comment(ALLEGRO_CONFIG *config,
   const char *section, const char *comment)

Source Code

Add a comment in a section of a configuration. If the section doesn't yet exist, it will be created. The section can be NULL or "" for the global section.

The comment may or may not begin with a hash character. Any newlines in the comment string will be replaced by space characters.

See also: al_add_config_section

al_get_config_value

const char *al_get_config_value(const ALLEGRO_CONFIG *config,
   const char *section, const char *key)

Source Code

Gets a pointer to an internal character buffer that will only remain valid as long as the ALLEGRO_CONFIG structure is not destroyed. Copy the value if you need a copy. The section can be NULL or "" for the global section. Returns NULL if the section or key do not exist.

See also: al_set_config_value

al_set_config_value

void al_set_config_value(ALLEGRO_CONFIG *config,
   const char *section, const char *key, const char *value)

Source Code

Set a value in a section of a configuration. If the section doesn't yet exist, it will be created. If a value already existed for the given key, it will be overwritten. The section can be NULL or "" for the global section.

For consistency with the on-disk format of config files, any leading and trailing whitespace will be stripped from the value. If you have significant whitespace you wish to preserve, you should add your own quote characters and remove them when reading the values back in.

See also: al_get_config_value

al_remove_config_key

bool al_remove_config_key(ALLEGRO_CONFIG *config, char const *section,
   char const *key)

Source Code

Remove a key and its associated value in a section of a configuration.

Returns true if the entry was removed, or false if the entry did not exist.

Since: 5.1.5

al_get_first_config_section

char const *al_get_first_config_section(ALLEGRO_CONFIG const *config,
   ALLEGRO_CONFIG_SECTION **iterator)

Source Code

Returns the name of the first section in the given config file. Usually this will return an empty string for the global section, even it contains no values. The iterator parameter will receive an opaque iterator which is used by al_get_next_config_section to iterate over the remaining sections.

The returned string and the iterator are only valid as long as no change is made to the passed ALLEGRO_CONFIG.

See also: al_get_next_config_section

al_get_next_config_section

char const *al_get_next_config_section(ALLEGRO_CONFIG_SECTION **iterator)

Source Code

Returns the name of the next section in the given config file or NULL if there are no more sections. The iterator must have been obtained with al_get_first_config_section first.

See also: al_get_first_config_section

al_get_first_config_entry

char const *al_get_first_config_entry(ALLEGRO_CONFIG const *config,
   char const *section, ALLEGRO_CONFIG_ENTRY **iterator)

Source Code

Returns the name of the first key in the given section in the given config or NULL if the section is empty. The iterator works like the one for al_get_first_config_section.

The returned string and the iterator are only valid as long as no change is made to the passed ALLEGRO_CONFIG.

See also: al_get_next_config_entry

al_get_next_config_entry

char const *al_get_next_config_entry(ALLEGRO_CONFIG_ENTRY **iterator)

Source Code

Returns the next key for the iterator obtained by al_get_first_config_entry. The iterator works like the one for al_get_next_config_section.

al_merge_config

ALLEGRO_CONFIG *al_merge_config(const ALLEGRO_CONFIG *cfg1,
    const ALLEGRO_CONFIG *cfg2)

Source Code

Merge two configuration structures, and return the result as a new configuration. Values in configuration 'cfg2' override those in 'cfg1'. Neither of the input configuration structures are modified. Comments from 'cfg2' are not retained.

See also: al_merge_config_into

al_merge_config_into

void al_merge_config_into(ALLEGRO_CONFIG *master, const ALLEGRO_CONFIG *add)

Source Code

Merge one configuration structure into another. Values in configuration 'add' override those in 'master'. 'master' is modified. Comments from 'add' are not retained.

See also: al_merge_config

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:39 UTC


Direct3D integration

  • Memory
  • Monitor
  • Mouse
  • Path
  • Shader
  • State
  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Direct3D integration

  • al_get_d3d_device
  • al_get_d3d_system_texture
  • al_get_d3d_video_texture
  • al_have_d3d_non_pow2_texture_support
  • al_have_d3d_non_square_texture_support
  • al_get_d3d_texture_size
  • al_get_d3d_texture_position
  • al_is_d3d_device_lost
  • al_set_d3d_device_release_callback
  • al_set_d3d_device_restore_callback

These functions are declared in the following header file:

 #include <allegro5/allegro_direct3d.h>

al_get_d3d_device

LPDIRECT3DDEVICE9 al_get_d3d_device(ALLEGRO_DISPLAY *display)

Source Code

Returns the Direct3D device of the display. The return value is undefined if the display was not created with the Direct3D flag.

Returns: A pointer to the Direct3D device.

al_get_d3d_system_texture

LPDIRECT3DTEXTURE9 al_get_d3d_system_texture(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the system texture (stored with the D3DPOOL_SYSTEMMEM flags). This texture is used for the render-to-texture feature set.

Returns: A pointer to the Direct3D system texture.

al_get_d3d_video_texture

LPDIRECT3DTEXTURE9 al_get_d3d_video_texture(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the video texture (stored with the D3DPOOL_DEFAULT or D3DPOOL_MANAGED flags depending on whether render-to-texture is enabled or disabled respectively).

Returns: A pointer to the Direct3D video texture.

al_have_d3d_non_pow2_texture_support

bool al_have_d3d_non_pow2_texture_support(void)

Source Code

Returns whether the Direct3D device supports textures whose dimensions are not powers of two.

Returns: True if device supports NPOT textures, false otherwise.

al_have_d3d_non_square_texture_support

bool al_have_d3d_non_square_texture_support(void)

Source Code

Returns whether the Direct3D device supports textures that are not square.

Returns: True if the Direct3D device supports non-square textures, false otherwise.

al_get_d3d_texture_size

bool al_get_d3d_texture_size(ALLEGRO_BITMAP *bitmap, int *width, int *height)

Source Code

Retrieves the size of the Direct3D texture used for the bitmap.

Returns true on success, false on failure. Zero width and height are returned if the bitmap is not a Direct3D bitmap.

Since: 5.1.0

See also: al_get_d3d_texture_position

al_get_d3d_texture_position

void al_get_d3d_texture_position(ALLEGRO_BITMAP *bitmap, int *u, int *v)

Source Code

Returns the u/v coordinates for the top/left corner of the bitmap within the used texture, in pixels.

Parameters:

  • bitmap - ALLEGRO_BITMAP to examine
  • u - Will hold the returned u coordinate
  • v - Will hold the returned v coordinate

See also: al_get_d3d_texture_size

al_is_d3d_device_lost

bool al_is_d3d_device_lost(ALLEGRO_DISPLAY *display)

Source Code

Returns a boolean indicating whether or not the Direct3D device belonging to the given display is in a lost state.

Parameters:

  • display - The display that the device you wish to check is attached to

al_set_d3d_device_release_callback

void al_set_d3d_device_release_callback(
   void (*callback)(ALLEGRO_DISPLAY *display))

Source Code

The callback will be called whenever a D3D device is reset (minimize, toggle fullscreen window, etc). In the callback you should release any d3d resources you have created yourself. The callback receives the affected display as a parameter.

Pass NULL to disable the callback.

Since: 5.1.0

al_set_d3d_device_restore_callback

void al_set_d3d_device_restore_callback(
   void (*callback)(ALLEGRO_DISPLAY *display))

Source Code

The callback will be called whenever a D3D device that has been reset is restored. In the callback you should restore any d3d resources you have created yourself. The callback receives the affected display as a parameter.

Pass NULL to disable the callback.

Since: 5.1.0

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:18 UTC


Displays

  • Path
  • Shader
  • State
  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Displays

  • Display creation
    • ALLEGRO_DISPLAY
    • al_create_display
    • al_destroy_display
    • al_get_new_display_flags
    • al_set_new_display_flags
    • al_get_new_display_option
    • al_set_new_display_option
    • al_reset_new_display_options
    • al_get_new_window_position
    • al_set_new_window_position
    • al_get_new_display_refresh_rate
    • al_set_new_display_refresh_rate
  • Display operations
    • al_get_display_event_source
    • al_get_backbuffer
    • al_flip_display
    • al_update_display_region
    • al_wait_for_vsync
  • Display size and position
    • al_get_display_width
    • al_get_display_height
    • al_resize_display
    • al_acknowledge_resize
    • al_get_window_position
    • al_set_window_position
    • al_get_window_constraints
    • al_set_window_constraints
    • al_apply_window_constraints
  • Display settings
    • al_get_display_flags
    • al_set_display_flag
    • al_get_display_option
    • al_set_display_option
    • al_get_display_format
    • al_get_display_orientation
    • al_get_display_refresh_rate
    • al_set_window_title
    • al_set_new_window_title
    • ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE
    • al_get_new_window_title
    • al_set_display_icon
    • al_set_display_icons
  • Drawing halts
    • al_acknowledge_drawing_halt
    • al_acknowledge_drawing_resume
  • Screensaver
    • al_inhibit_screensaver
  • Clipboard
    • al_get_clipboard_text
    • al_set_clipboard_text
    • al_clipboard_has_text

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

All drawing operations end up being visible on a display which is the same as a window in windowed environments. Thus, before anything is displayed, a display needs to be created.

Before creating a display with al_create_display, flags and options can be set with al_set_new_display_flags and al_set_new_display_option. For example, you can enable the use of shaders or choose between the OpenGL and Direct3D backends (on platforms that support both) with al_set_new_display_flags. Display options are rather optional settings that do not affect Allegro itself, e.g. they allow you to specify whether you want a depth buffer or enable multisampling.

The actual properties of a display that has been successfully created can be queried via al_get_display_option, al_get_display_flags, al_get_display_width etc. Note that you can query some additional read-only properties such as the maximum allowed bitmap (i.e. texture) size via al_get_display_option.

Each display has a backbuffer associated to it which is the default target for any drawing operations. In order to make visible what has been drawn previously, you have to to call al_flip_display. Note that it is generally advisable to redraw the whole screen (or clear it in advance) to avoid artefacts of uninitialised memory becoming visible with some drivers.

You don't have to use Allegro's drawing routines, however: since creating a display implies the creation of an OpenGL context or Direct3D device respectively, you can use these APIs directly if you prefer to do so. Allegro provides integration for both (see the OpenGL / Direct3D sections), so you can retrieve the underlying textures of ALLEGRO_BITMAPs, for example.

In order to write a well-behaved application, it is necessary to remember that displays will also inform you about important events via their event sources.

Display creation

ALLEGRO_DISPLAY

typedef struct ALLEGRO_DISPLAY ALLEGRO_DISPLAY;

Source Code

An opaque type representing an open display or window.

al_create_display

ALLEGRO_DISPLAY *al_create_display(int w, int h)

Source Code

Create a display, or window, with the specified dimensions. The parameters of the display are determined by the last calls to al_set_new_display_*. Default parameters are used if none are set explicitly. Creating a new display will automatically make it the active one, with the backbuffer selected for drawing.

Returns NULL on error.

Each display that uses OpenGL as a backend has a distinct OpenGL rendering context associated with it. See al_set_target_bitmap for the discussion about rendering contexts.

See also: al_set_new_display_flags, al_set_new_display_option, al_set_new_display_refresh_rate, al_set_new_display_adapter, al_set_new_window_title

al_destroy_display

void al_destroy_display(ALLEGRO_DISPLAY *display)

Source Code

Destroy a display.

If the target bitmap of the calling thread is tied to the display, then it implies a call to "al_set_target_bitmap(NULL);" before the display is destroyed.

That special case notwithstanding, you should make sure no threads are currently targeting a bitmap which is tied to the display before you destroy it.

See also: al_set_target_bitmap

al_get_new_display_flags

int al_get_new_display_flags(void)

Source Code

Get the display flags to be used when creating new displays on the calling thread.

See also: al_set_new_display_flags, al_set_display_flag

al_set_new_display_flags

void al_set_new_display_flags(int flags)

Source Code

Sets various flags to be used when creating new displays on the calling thread. flags is a bitfield containing any reasonable combination of the following:

ALLEGRO_WINDOWED

Prefer a windowed mode.

Under multi-head X (not XRandR/TwinView), the use of more than one adapter is impossible due to bugs in X and GLX. al_create_display will fail if more than one adapter is attempted to be used.

ALLEGRO_FULLSCREEN_WINDOW

Make the window span the entire screen. Unlike ALLEGRO_FULLSCREEN this will never attempt to modify the screen resolution. Instead the pixel dimensions of the created display will be the same as the desktop.

The passed width and height are only used if the window is switched out of fullscreen mode later but will be ignored initially.

Under Windows and X11 a fullscreen display created with this flag will behave differently from one created with the ALLEGRO_FULLSCREEN flag - even if the ALLEGRO_FULLSCREEN display is passed the desktop dimensions. The exact difference is platform dependent, but some things which may be different is how alt-tab works, how fast you can toggle between fullscreen/windowed mode or how additional monitors behave while your display is in fullscreen mode.

Additionally under X, the use of more than one adapter in multi-head mode or with true Xinerama enabled is impossible due to bugs in X/GLX, creation will fail if more than one adapter is attempted to be used.

ALLEGRO_FULLSCREEN

Prefer a fullscreen mode.

Under X the use of more than one FULLSCREEN display when using multi-head X, or true Xinerama is not possible due to bugs in X and GLX, display creation will fail if more than one adapter is attempted to be used.

Note: Prefer using ALLEGRO_FULLSCREEN_WINDOW as it typically provides a better user experience as the monitor doesn't change resolution and switching away from your game via Alt-Tab works smoothly. ALLEGRO_FULLSCREEN is typically less well supported compared to ALLEGRO_FULLSCREEN_WINDOW.

ALLEGRO_RESIZABLE
The display is resizable (only applicable if combined with ALLEGRO_WINDOWED).
ALLEGRO_MAXIMIZED
The display window will be maximized (only applicable if combined with ALLEGRO_RESIZABLE). Since: 5.1.12
ALLEGRO_OPENGL
Require the driver to provide an initialized OpenGL context after returning successfully.
ALLEGRO_OPENGL_3_0
Require the driver to provide an initialized OpenGL context compatible with OpenGL version 3.0.
ALLEGRO_OPENGL_FORWARD_COMPATIBLE
If this flag is set, the OpenGL context created with ALLEGRO_OPENGL_3_0 will be forward compatible only, meaning that all of the OpenGL API declared deprecated in OpenGL 3.0 will not be supported. Currently, a display created with this flag will not be compatible with Allegro drawing routines; the display option ALLEGRO_COMPATIBLE_DISPLAY will be set to false.
ALLEGRO_OPENGL_ES_PROFILE
Used together with ALLEGRO_OPENGL, requests that the OpenGL context uses the OpenGL ES profile. A specific version can be requested with al_set_new_display_option. Note: Currently this is only supported by the X11/GLX driver. Since: 5.1.13
ALLEGRO_DIRECT3D
Require the driver to do rendering with Direct3D and provide a Direct3D device.
ALLEGRO_PROGRAMMABLE_PIPELINE
Require a programmable graphics pipeline. This flag is required to use ALLEGRO_SHADER objects. Since: 5.1.6
ALLEGRO_FRAMELESS
Try to create a window without a frame (i.e. no border or titlebar). This usually does nothing for fullscreen modes, and even in windowed modes it depends on the underlying platform whether it is supported or not. Since: 5.0.7, 5.1.2
ALLEGRO_NOFRAME
Original name for ALLEGRO_FRAMELESS. This works with older versions of Allegro.
ALLEGRO_GENERATE_EXPOSE_EVENTS
Let the display generate expose events.
ALLEGRO_GTK_TOPLEVEL
Create a GTK toplevel window for the display, on X. This flag is conditionally defined by the native dialog addon. You must call al_init_native_dialog_addon for it to succeed. ALLEGRO_GTK_TOPLEVEL is incompatible with ALLEGRO_FULLSCREEN. Since: 5.1.5

0 can be used for default values.

See also: al_set_new_display_option, al_get_display_option, al_set_display_option

al_get_new_display_option

int al_get_new_display_option(int option, int *importance)

Source Code

Retrieve an extra display setting which was previously set with al_set_new_display_option.

al_set_new_display_option

void al_set_new_display_option(int option, int value, int importance)

Source Code

Set an extra display option, to be used when creating new displays on the calling thread. Display options differ from display flags, and specify some details of the context to be created within the window itself. These mainly have no effect on Allegro itself, but you may want to specify them, for example if you want to use multisampling.

The 'importance' parameter can be either:

  • ALLEGRO_REQUIRE - The display will not be created if the setting can not be met.
  • ALLEGRO_SUGGEST - If the setting is not available, the display will be created anyway with a setting as close as possible to the requested one. You can query the actual value used in that case by calling al_get_display_option after the display has been created.
  • ALLEGRO_DONTCARE - If you added a display option with one of the above two settings before, it will be removed again. Else this does nothing.

The supported options are:

ALLEGRO_COLOR_SIZE
This can be used to ask for a specific bit depth. For example to force a 16-bit framebuffer set this to 16.
ALLEGRO_RED_SIZE, ALLEGRO_GREEN_SIZE, ALLEGRO_BLUE_SIZE, ALLEGRO_ALPHA_SIZE
Individual color component size in bits.
ALLEGRO_RED_SHIFT, ALLEGRO_GREEN_SHIFT, ALLEGRO_BLUE_SHIFT, ALLEGRO_ALPHA_SHIFT
Together with the previous settings these can be used to specify the exact pixel layout the display should use. Normally there is no reason to use these.
ALLEGRO_ACC_RED_SIZE, ALLEGRO_ACC_GREEN_SIZE, ALLEGRO_ACC_BLUE_SIZE, ALLEGRO_ACC_ALPHA_SIZE
This can be used to define the required accumulation buffer size.
ALLEGRO_STEREO
Whether the display is a stereo display.
ALLEGRO_AUX_BUFFERS
Number of auxiliary buffers the display should have.
ALLEGRO_DEPTH_SIZE
How many depth buffer (z-buffer) bits to use.
ALLEGRO_STENCIL_SIZE
How many bits to use for the stencil buffer.
ALLEGRO_SAMPLE_BUFFERS
Whether to use multisampling (1) or not (0).
ALLEGRO_SAMPLES
If the above is 1, the number of samples to use per pixel. Else 0.
ALLEGRO_RENDER_METHOD:
0 if hardware acceleration is not used with this display.
ALLEGRO_FLOAT_COLOR
Whether to use floating point color components.
ALLEGRO_FLOAT_DEPTH
Whether to use a floating point depth buffer.
ALLEGRO_SINGLE_BUFFER
Whether the display uses a single buffer (1) or another update method (0).
ALLEGRO_SWAP_METHOD
If the above is 0, this is set to 1 to indicate the display is using a copying method to make the next buffer in the flip chain available, or to 2 to indicate a flipping or other method.
ALLEGRO_COMPATIBLE_DISPLAY
Indicates if Allegro's graphics functions can use this display. If you request a display not useable by Allegro, you can still use for example OpenGL to draw graphics.
ALLEGRO_UPDATE_DISPLAY_REGION
Set to 1 if the display is capable of updating just a region, and 0 if calling al_update_display_region is equivalent to al_flip_display.
ALLEGRO_VSYNC
Set to 1 to tell the driver to wait for vsync in al_flip_display, or to 2 to force vsync off. The default of 0 means that Allegro does not try to modify the vsync behavior so it may be on or off. Note that even in the case of 1 or 2 it is possible to override the vsync behavior in the graphics driver so you should not rely on it.
ALLEGRO_MAX_BITMAP_SIZE
When queried this returns the maximum size (width as well as height) a bitmap can have for this display. Calls to al_create_bitmap or al_load_bitmap for bitmaps larger than this size will fail. It does not apply to memory bitmaps which always can have arbitrary size (but are slow for drawing).
ALLEGRO_SUPPORT_NPOT_BITMAP
Set to 1 if textures used for bitmaps on this display can have a size which is not a power of two. This is mostly useful if you use Allegro to load textures as otherwise only power-of-two textures will be used internally as bitmap storage.
ALLEGRO_CAN_DRAW_INTO_BITMAP
Set to 1 if you can use al_set_target_bitmap on bitmaps of this display to draw into them. If this is not the case software emulation will be used when drawing into display bitmaps (which can be very slow).
ALLEGRO_SUPPORT_SEPARATE_ALPHA
This is set to 1 if the al_set_separate_blender function is supported. Otherwise the alpha parameters will be ignored.
ALLEGRO_AUTO_CONVERT_BITMAPS

This is on by default. It causes any existing memory bitmaps with the ALLEGRO_CONVERT_BITMAP flag to be converted to a display bitmap of the newly created display with the option set.

Since: 5.1.0

ALLEGRO_SUPPORTED_ORIENTATIONS

This is a bit-combination of the orientations supported by the application. The orientations are the same as for al_get_display_orientation with the additional possibilities:

  • ALLEGRO_DISPLAY_ORIENTATION_PORTRAIT
  • ALLEGRO_DISPLAY_ORIENTATION_LANDSCAPE
  • ALLEGRO_DISPLAY_ORIENTATION_ALL

PORTRAIT means only the two portrait orientations are supported, LANDSCAPE means only the two landscape orientations and ALL allows all four orientations. When the orientation changes between a portrait and a landscape orientation the display needs to be resized. This is done by sending an ALLEGRO_EVENT_DISPLAY_RESIZE message which should be handled by calling al_acknowledge_resize.

Since: 5.1.0

ALLEGRO_OPENGL_MAJOR_VERSION

Request a specific OpenGL major version.

Since: 5.1.13

ALLEGRO_OPENGL_MINOR_VERSION

Request a specific OpenGL minor version.

Since: 5.1.13

See also: al_set_new_display_flags, al_get_display_option

al_reset_new_display_options

void al_reset_new_display_options(void)

Source Code

This undoes any previous call to al_set_new_display_option on the calling thread.

al_get_new_window_position

void al_get_new_window_position(int *x, int *y)

Source Code

Get the position where new non-fullscreen displays created by the calling thread will be placed.

See also: al_set_new_window_position

al_set_new_window_position

void al_set_new_window_position(int x, int y)

Source Code

Sets where the top left pixel of the client area of newly created windows (non-fullscreen) will be on screen, for displays created by the calling thread. Negative values are allowed on some multihead systems.

To reset to the default behaviour, pass (INT_MAX, INT_MAX).

See also: al_get_new_window_position

al_get_new_display_refresh_rate

int al_get_new_display_refresh_rate(void)

Source Code

Get the requested refresh rate to be used when creating new displays on the calling thread.

See also: al_set_new_display_refresh_rate

al_set_new_display_refresh_rate

void al_set_new_display_refresh_rate(int refresh_rate)

Source Code

Sets the refresh rate to use when creating new displays on the calling thread. If the refresh rate is not available, al_create_display will fail. A list of modes with refresh rates can be found with al_get_num_display_modes and al_get_display_mode.

The default setting is zero (don't care).

See also: al_get_new_display_refresh_rate

Display operations

al_get_display_event_source

ALLEGRO_EVENT_SOURCE *al_get_display_event_source(ALLEGRO_DISPLAY *display)

Source Code

Retrieve the associated event source. See the documentation on events for a list of the events displays will generate.

al_get_backbuffer

ALLEGRO_BITMAP *al_get_backbuffer(ALLEGRO_DISPLAY *display)

Source Code

Return a special bitmap representing the back-buffer of the display.

Care should be taken when using the backbuffer bitmap (and its sub-bitmaps) as the source bitmap (e.g as the bitmap argument to al_draw_bitmap). Only untransformed operations are hardware accelerated. These consist of al_draw_bitmap and al_draw_bitmap_region when the current transformation is the identity. If the transformation is not the identity, or some other drawing operation is used, the call will be routed through the memory bitmap routines, which are slow. If you need those operations to be accelerated, then first copy a region of the backbuffer into a temporary bitmap (via the al_draw_bitmap and al_draw_bitmap_region), and then use that temporary bitmap as the source bitmap.

al_flip_display

void al_flip_display(void)

Source Code

Copies or updates the front and back buffers so that what has been drawn previously on the currently selected display becomes visible on screen. Pointers to the special back buffer bitmap remain valid and retain their semantics as the back buffer, although the contents may have changed.

Several display options change how this function behaves:

  • With ALLEGRO_SINGLE_BUFFER, no flipping is done. You still have to call this function to display graphics, depending on how the used graphics system works.

  • The ALLEGRO_SWAP_METHOD option may have additional information about what kind of operation is used internally to flip the front and back buffers.

  • If ALLEGRO_VSYNC is 1, this function will force waiting for vsync. If ALLEGRO_VSYNC is 2, this function will not wait for vsync. With many drivers the vsync behavior is controlled by the user and not the application, and ALLEGRO_VSYNC will not be set; in this case al_flip_display will wait for vsync depending on the settings set in the system's graphics preferences.

See also: al_set_new_display_flags, al_set_new_display_option

al_update_display_region

void al_update_display_region(int x, int y, int width, int height)

Source Code

Does the same as al_flip_display, but tries to update only the specified region. With many drivers this is not possible, but for some it can improve performance. If this is not supported, this function falls back to the behavior of al_flip_display. You can query the support for this function using al_get_display_option(display, ALLEGRO_UPDATE_DISPLAY_REGION).

See also: al_flip_display, al_get_display_option

al_wait_for_vsync

bool al_wait_for_vsync(void)

Source Code

Wait for the beginning of a vertical retrace. Some driver/card/monitor combinations may not be capable of this.

Note how al_flip_display usually already waits for the vertical retrace, so unless you are doing something special, there is no reason to call this function.

Returns false if not possible, true if successful.

See also: al_flip_display

Display size and position

al_get_display_width

int al_get_display_width(ALLEGRO_DISPLAY *display)

Source Code

Gets the width of the display. This is like SCREEN_W in Allegro 4.x.

See also: al_get_display_height

al_get_display_height

int al_get_display_height(ALLEGRO_DISPLAY *display)

Source Code

Gets the height of the display. This is like SCREEN_H in Allegro 4.x.

See also: al_get_display_width

al_resize_display

bool al_resize_display(ALLEGRO_DISPLAY *display, int width, int height)

Source Code

Resize the display. Returns true on success, or false on error. This works on both fullscreen and windowed displays, regardless of the ALLEGRO_RESIZABLE flag.

Adjusts the clipping rectangle to the full size of the backbuffer.

See also: al_acknowledge_resize

al_acknowledge_resize

bool al_acknowledge_resize(ALLEGRO_DISPLAY *display)

Source Code

When the user receives a resize event from a resizable display, if they wish the display to be resized they must call this function to let the graphics driver know that it can now resize the display. Returns true on success.

Adjusts the clipping rectangle to the full size of the backbuffer. This also resets the backbuffers projection transform to default orthographic transform (see al_use_projection_transform).

Note that a resize event may be outdated by the time you acknowledge it; there could be further resize events generated in the meantime.

See also: al_resize_display, ALLEGRO_EVENT

al_get_window_position

void al_get_window_position(ALLEGRO_DISPLAY *display, int *x, int *y)

Source Code

Gets the position of a non-fullscreen display.

See also: al_set_window_position

al_set_window_position

void al_set_window_position(ALLEGRO_DISPLAY *display, int x, int y)

Source Code

Sets the position on screen of a non-fullscreen display.

See also: al_get_window_position

al_get_window_constraints

bool al_get_window_constraints(ALLEGRO_DISPLAY *display,
   int *min_w, int *min_h, int *max_w, int *max_h)

Source Code

Gets the constraints for a non-fullscreen resizable display.

Since: 5.1.0

See also: al_set_window_constraints

al_set_window_constraints

bool al_set_window_constraints(ALLEGRO_DISPLAY *display,
   int min_w, int min_h, int max_w, int max_h)

Source Code

Constrains a non-fullscreen resizable display. The constraints are a hint only, and are not necessarily respected by the window environment. A value of 0 for any of the parameters indicates no constraint for that parameter.

The constraints will be applied to a display only after the al_apply_window_constraints function call.

Since: 5.1.0

See also: al_apply_window_constraints, al_get_window_constraints

al_apply_window_constraints

void al_apply_window_constraints(ALLEGRO_DISPLAY *display, bool onoff)

Source Code

Enable or disable previously set constraints by al_set_window_constraints function.

If enabled, the specified display will be automatically resized to new sizes to conform constraints in next cases:

  • The specified display is resizable, not maximized and is not in fullscreen mode.
  • If the appropriate current display size (width or height) is less than the value of constraint. Applied to minimum constraints.
  • If the appropriate current display size (width or height) is greater than the value of constraint. Applied to maximum constraints.

Constrains are not applied when a display is toggle from windowed to maximized or fullscreen modes. When a display is toggle from maximized/fullscreen to windowed mode, then the display may be resized as described above. The later case is also possible when a user drags the maximized display via mouse.

If disabled, the specified display will stop using constraints.

See also: al_get_window_constraints, al_set_window_constraints

Display settings

al_get_display_flags

int al_get_display_flags(ALLEGRO_DISPLAY *display)

Source Code

Gets the flags of the display.

In addition to the flags set for the display at creation time with al_set_new_display_flags it can also have the ALLEGRO_MINIMIZED flag set, indicating that the window is currently minimized. This flag is very platform-dependent as even a minimized application may still render a preview version so normally you should not care whether it is minimized or not.

See also: al_set_new_display_flags, al_set_display_flag

al_set_display_flag

bool al_set_display_flag(ALLEGRO_DISPLAY *display, int flag, bool onoff)

Source Code

Enable or disable one of the display flags. The flags are the same as for al_set_new_display_flags. The only flags that can be changed after creation are:

  • ALLEGRO_FULLSCREEN_WINDOW
  • ALLEGRO_FRAMELESS
  • ALLEGRO_MAXIMIZED

Returns true if the driver supports toggling the specified flag else false. You can use al_get_display_flags to query whether the given display property actually changed.

Since: 5.0.7, 5.1.2

See also: al_set_new_display_flags, al_get_display_flags

al_get_display_option

int al_get_display_option(ALLEGRO_DISPLAY *display, int option)

Source Code

Return an extra display setting of the display.

See also: al_set_new_display_option

al_set_display_option

void al_set_display_option(ALLEGRO_DISPLAY *display, int option, int value)

Source Code

Change an option that was previously set for a display. After displays are created, they take on the options set with al_set_new_display_option. Calling al_set_new_display_option subsequently only changes options for newly created displays, and doesn't touch the options of already created displays. al_set_display_option allows changing some of these values. Not all display options can be changed or changing them will have no effect. Changing options other than those listed below is undefined.

  • ALLEGRO_SUPPORTED_ORIENTATIONS - This can be changed to allow new or restrict previously enabled orientations of the screen/device. See al_set_new_display_option for more information on this option.

Since: 5.1.5

See also: al_set_new_display_option

al_get_display_format

int al_get_display_format(ALLEGRO_DISPLAY *display)

Source Code

Gets the pixel format of the display.

See also: ALLEGRO_PIXEL_FORMAT

al_get_display_orientation

int al_get_display_orientation(ALLEGRO_DISPLAY* display)

Source Code

Return the display orientation, which can be one of the following:

  • ALLEGRO_DISPLAY_ORIENTATION_UNKNOWN
  • ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
  • ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
  • ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
  • ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
  • ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
  • ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN

Since: 5.1.0

al_get_display_refresh_rate

int al_get_display_refresh_rate(ALLEGRO_DISPLAY *display)

Source Code

Gets the refresh rate of the display.

See also: al_set_new_display_refresh_rate

al_set_window_title

void al_set_window_title(ALLEGRO_DISPLAY *display, const char *title)

Source Code

Set the title on a display.

See also: al_set_display_icon, al_set_display_icons

al_set_new_window_title

void al_set_new_window_title(const char *title)

Source Code

Set the title that will be used when a new display is created. Allegro uses a static buffer of ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE to store this, so the length of the titme you set must be less than this.

See also: al_set_window_title, al_get_new_window_title, al_create_display, ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE

Since: 5.1.12

ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE

#define ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE 255

Source Code

This is the maximum size of the title that can be set with al_set_new_window_title.

See also: al_set_new_window_title

Since: 5.1.12

al_get_new_window_title

const char *al_get_new_window_title(void)

Source Code

Returns the title that will be used when a new display is created. This returns the value that al_set_window_title was called with. If that function wasn't called yet, the value of al_get_app_name is returned as a default. The current implementation returns a pointer to a static buffer of which you should make a copy if you want to modify it.

See also: al_set_window_title, al_set_new_window_title, al_create_display

Since: 5.1.12

al_set_display_icon

void al_set_display_icon(ALLEGRO_DISPLAY *display, ALLEGRO_BITMAP *icon)

Source Code

Changes the icon associated with the display (window). Same as al_set_display_icons with one icon.

See also: al_set_display_icons, al_set_window_title

al_set_display_icons

void al_set_display_icons(ALLEGRO_DISPLAY *display,
   int num_icons, ALLEGRO_BITMAP *icons[])

Source Code

Changes the icons associated with the display (window). Multiple icons can be provided for use in different contexts, e.g. window frame, taskbar, alt-tab popup. The number of icons must be at least one.

Note: If the underlying OS requires an icon of a size not provided then one of the bitmaps will be scaled up or down to the required size. The choice of bitmap is implementation dependent.

Since: 5.0.9, 5.1.5

See also: al_set_display_icon, al_set_window_title

Drawing halts

al_acknowledge_drawing_halt

void al_acknowledge_drawing_halt(ALLEGRO_DISPLAY *display)

Source Code

Call this in response to the ALLEGRO_EVENT_DISPLAY_HALT_DRAWING event. This is currently necessary for Android and iOS as you are not allowed to draw to your display while it is not being shown. If you do not call this function to let the operating system know that you have stopped drawing or if you call it to late the application likely will be considered misbehaving and get terminated.

Since: 5.1.0

See also: ALLEGRO_EVENT_DISPLAY_HALT_DRAWING

al_acknowledge_drawing_resume

void al_acknowledge_drawing_resume(ALLEGRO_DISPLAY *display)

Source Code

Call this in response to the ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event.

Since: 5.1.1

See also: ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING

Screensaver

al_inhibit_screensaver

bool al_inhibit_screensaver(bool inhibit)

Source Code

This function allows the user to stop the system screensaver from starting up if true is passed, or resets the system back to the default state (the state at program start) if false is passed. It returns true if the state was set successfully, otherwise false.

Clipboard

With the clipboard API of Allegro, text can be copied from and to the clipboard. Currentlly, only UTF8 encoded text is supported. It currently works on Linux, Windows, OSX, Android and IOS.

al_get_clipboard_text

char *al_get_clipboard_text(ALLEGRO_DISPLAY *display)

Source Code

This function returns a pointer to a string, allocated with al_malloc with the text contents of the clipboard if available. If no text is available on the clipboard then this function returns NULL. You must call al_free on the returned pointer when you don't need it anymore.

Beware that text on the clipboard on Windows may be in Windows format, that is, it may have carriage return newline combinations for the line endings instead of regular newlines for the line endings on Linux or OSX.

Since: 5.1.12

See also: al_set_clipboard_text, al_clipboard_has_text

al_set_clipboard_text

bool al_set_clipboard_text(ALLEGRO_DISPLAY *display, const char *text)

Source Code

This function pastes the text given as an argument to the clipboard.

Since: 5.1.12

See also: al_get_clipboard_text, al_clipboard_has_text

al_clipboard_has_text

bool al_clipboard_has_text(ALLEGRO_DISPLAY *display)

Source Code

This function returns true if and only if the clipboard has text available.

Since: 5.1.12

See also: al_set_clipboard_text, al_get_clipboard_text

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:39 UTC


Event system and events

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Event system and events

  • ALLEGRO_EVENT
    • ALLEGRO_EVENT_JOYSTICK_AXIS
    • ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN
    • ALLEGRO_EVENT_JOYSTICK_BUTTON_UP
    • ALLEGRO_EVENT_JOYSTICK_CONFIGURATION
    • ALLEGRO_EVENT_KEY_DOWN
    • ALLEGRO_EVENT_KEY_UP
    • ALLEGRO_EVENT_KEY_CHAR
    • ALLEGRO_EVENT_MOUSE_AXES
    • ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
    • ALLEGRO_EVENT_MOUSE_BUTTON_UP
    • ALLEGRO_EVENT_MOUSE_WARPED
    • ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
    • ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
    • ALLEGRO_EVENT_TOUCH_BEGIN
    • ALLEGRO_EVENT_TOUCH_END
    • ALLEGRO_EVENT_TOUCH_MOVE
    • ALLEGRO_EVENT_TOUCH_CANCEL
    • ALLEGRO_EVENT_TIMER
    • ALLEGRO_EVENT_DISPLAY_EXPOSE
    • ALLEGRO_EVENT_DISPLAY_RESIZE
    • ALLEGRO_EVENT_DISPLAY_CLOSE
    • ALLEGRO_EVENT_DISPLAY_LOST
    • ALLEGRO_EVENT_DISPLAY_FOUND
    • ALLEGRO_EVENT_DISPLAY_SWITCH_OUT
    • ALLEGRO_EVENT_DISPLAY_SWITCH_IN
    • ALLEGRO_EVENT_DISPLAY_ORIENTATION
    • ALLEGRO_EVENT_DISPLAY_HALT_DRAWING
    • ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING
    • ALLEGRO_EVENT_DISPLAY_CONNECTED
    • ALLEGRO_EVENT_DISPLAY_DISCONNECTED
  • ALLEGRO_USER_EVENT
  • ALLEGRO_EVENT_QUEUE
  • ALLEGRO_EVENT_SOURCE
  • ALLEGRO_EVENT_TYPE
  • ALLEGRO_GET_EVENT_TYPE
  • ALLEGRO_EVENT_TYPE_IS_USER
  • al_create_event_queue
  • al_destroy_event_queue
  • al_register_event_source
  • al_unregister_event_source
  • al_is_event_source_registered
  • al_pause_event_queue
  • al_is_event_queue_paused
  • al_is_event_queue_empty
  • al_get_next_event
  • al_peek_next_event
  • al_drop_next_event
  • al_flush_event_queue
  • al_wait_for_event
  • al_wait_for_event_timed
  • al_wait_for_event_until
  • al_init_user_event_source
  • al_destroy_user_event_source
  • al_emit_user_event
  • al_unref_user_event
  • al_get_event_source_data
  • al_set_event_source_data

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

Events are generated by event sources. Most notably, each of the input subsystems provides an event source, but also timers, displays, and audio streams will generate events.

Event sources are registered to event queues which aggregate events from multiple sources. A single event source can also be registered to multiple event queues.

Event queues can then be queried for events. In particular, it is possible to wait until events become available in order to save CPU time. You can combine this with timers to make your main-loop run at a specific speed without wasting CPU time or missing events.

In addition to the predefined event types, Allegro also allows for user-defined events that can be generated by user-defined event sources.

The appropriate reaction to an event is determined by examining the fields of the ALLEGRO_EVENT union according to the event type.

In addition to the events sent by Allegro core, there's also events send by the addons, see ALLEGRO_AUDIO_EVENT_TYPE and ALLEGRO_VIDEO_EVENT_TYPE.

ALLEGRO_EVENT

typedef union ALLEGRO_EVENT ALLEGRO_EVENT;

Source Code

An ALLEGRO_EVENT is a union of all builtin event structures, i.e. it is an object large enough to hold the data of any event type. All events have the following fields in common:

type (ALLEGRO_EVENT_TYPE)
Indicates the type of event.
any.source (ALLEGRO_EVENT_SOURCE *)
The event source which generated the event.
any.timestamp (double)
When the event was generated.

By examining the type field you can then access type-specific fields. The any.source field tells you which event source generated that particular event. The any.timestamp field tells you when the event was generated. The time is referenced to the same starting point as al_get_time.

Each event is of one of the following types, with the usable fields given.

ALLEGRO_EVENT_JOYSTICK_AXIS

A joystick axis value changed.

joystick.id (ALLEGRO_JOYSTICK *)
The joystick which generated the event. This is not the same as the event source joystick.source.
joystick.stick (int)
The stick number, counting from zero. Axes on a joystick are grouped into "sticks".
joystick.axis (int)
The axis number on the stick, counting from zero.
joystick.pos (float)
The axis position, from -1.0 to +1.0.

ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN

A joystick button was pressed.

joystick.id (ALLEGRO_JOYSTICK *)
The joystick which generated the event.
joystick.button (int)
The button which was pressed, counting from zero.

ALLEGRO_EVENT_JOYSTICK_BUTTON_UP

A joystick button was released.

joystick.id (ALLEGRO_JOYSTICK *)
The joystick which generated the event.
joystick.button (int)
The button which was released, counting from zero.

ALLEGRO_EVENT_JOYSTICK_CONFIGURATION

A joystick was plugged in or unplugged. See al_reconfigure_joysticks for details.

ALLEGRO_EVENT_KEY_DOWN

A keyboard key was pressed.

keyboard.keycode (int)
The code corresponding to the physical key which was pressed. See the Key codes section for the list of ALLEGRO_KEY_* constants.
keyboard.display (ALLEGRO_DISPLAY *)
The display which had keyboard focus when the event occurred.

Note: this event is about the physical keys being pressed on the keyboard. Look for ALLEGRO_EVENT_KEY_CHAR events for character input.

ALLEGRO_EVENT_KEY_UP

A keyboard key was released.

keyboard.keycode (int)
The code corresponding to the physical key which was released. See the Key codes section for the list of ALLEGRO_KEY_* constants.
keyboard.display (ALLEGRO_DISPLAY *)
The display which had keyboard focus when the event occurred.

ALLEGRO_EVENT_KEY_CHAR

A character was typed on the keyboard, or a character was auto-repeated.

keyboard.keycode (int)
The code corresponding to the physical key which was last pressed. See the Key codes section for the list of ALLEGRO_KEY_* constants.
keyboard.unichar (int)

A Unicode code point (character). This may be zero or negative if the event was generated for a non-visible "character", such as an arrow or Function key. In that case you can act upon the keycode field.

Some special keys will set the unichar field to their standard ASCII values: Tab=9, Return=13, Escape=27. In addition if you press the Control key together with A to Z the unichar field will have the values 1 to 26. For example Ctrl-A will set unichar to 1 and Ctrl-H will set it to 8.

As of Allegro 5.0.2 there are some inconsistencies in the treatment of Backspace (8 or 127) and Delete (127 or 0) keys on different platforms. These can be worked around by checking the keycode field.

keyboard.modifiers (unsigned)
This is a bitfield of the modifier keys which were pressed when the event occurred. See "Keyboard modifier flags" for the constants.
keyboard.repeat (bool)
Indicates if this is a repeated character.
keyboard.display (ALLEGRO_DISPLAY *)
The display which had keyboard focus when the event occurred.

Note: in many input methods, characters are not entered one-for-one with physical key presses. Multiple key presses can combine to generate a single character, e.g. apostrophe + e may produce 'é'. Fewer key presses can also generate more characters, e.g. macro sequences expanding to common phrases.

ALLEGRO_EVENT_MOUSE_AXES

One or more mouse axis values changed.

mouse.x (int)
x-coordinate
mouse.y (int)
y-coordinate
mouse.z (int)
z-coordinate. This usually means the vertical axis of a mouse wheel, where up is positive and down is negative.
mouse.w (int)
w-coordinate. This usually means the horizontal axis of a mouse wheel.
mouse.dx (int)
Change in the x-coordinate value since the previous ALLEGRO_EVENT_MOUSE_AXES event.
mouse.dy (int)
Change in the y-coordinate value since the previous ALLEGRO_EVENT_MOUSE_AXES event.
mouse.dz (int)
Change in the z-coordinate value since the previous ALLEGRO_EVENT_MOUSE_AXES event.
mouse.dw (int)
Change in the w-coordinate value since the previous ALLEGRO_EVENT_MOUSE_AXES event.
mouse.pressure (float)
Pressure, ranging from 0.0 to 1.0.
mouse.display (ALLEGRO_DISPLAY *)
The display which had mouse focus.

Note: Calling al_set_mouse_xy also will result in a change of axis values, but such a change is reported with ALLEGRO_EVENT_MOUSE_WARPED events instead which are identical except for their type.

Note: currently mouse.display may be NULL if an event is generated in response to al_set_mouse_axis.

ALLEGRO_EVENT_MOUSE_BUTTON_DOWN

A mouse button was pressed.

mouse.x (int)
x-coordinate
mouse.y (int)
y-coordinate
mouse.z (int)
z-coordinate
mouse.w (int)
w-coordinate
mouse.button (unsigned)
The mouse button which was pressed, numbering from 1.
mouse.pressure (float)
Pressure, ranging from 0.0 to 1.0.
mouse.display (ALLEGRO_DISPLAY *)
The display which had mouse focus.

ALLEGRO_EVENT_MOUSE_BUTTON_UP

A mouse button was released.

mouse.x (int)
x-coordinate
mouse.y (int)
y-coordinate
mouse.z (int)
z-coordinate
mouse.w (int)
w-coordinate
mouse.button (unsigned)
The mouse button which was released, numbering from 1.
mouse.pressure (float)
Pressure, ranging from 0.0 to 1.0.
mouse.display (ALLEGRO_DISPLAY *)
The display which had mouse focus.

ALLEGRO_EVENT_MOUSE_WARPED

al_set_mouse_xy was called to move the mouse. This event is identical to ALLEGRO_EVENT_MOUSE_AXES otherwise.

ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY

The mouse cursor entered a window opened by the program.

mouse.x (int)
x-coordinate
mouse.y (int)
y-coordinate
mouse.z (int)
z-coordinate
mouse.w (int)
w-coordinate
mouse.display (ALLEGRO_DISPLAY *)
The display which had mouse focus.

ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY

The mouse cursor left the boundaries of a window opened by the program.

mouse.x (int)
x-coordinate
mouse.y (int)
y-coordinate
mouse.z (int)
z-coordinate
mouse.w (int)
w-coordinate
mouse.display (ALLEGRO_DISPLAY *)
The display which had mouse focus.

ALLEGRO_EVENT_TOUCH_BEGIN

The touch input device registered a new touch.

touch.display (ALLEGRO_DISPLAY)
The display which was touched.
touch.id (int)
An identifier for this touch. If supported by the device it will stay the same for events from the same finger until the touch ends.
touch.x (float)
The x coordinate of the touch in pixels.
touch.y (float)
The y coordinate of the touch in pixels.
touch.dx (float)
Movement speed in pixels in x direction.
touch.dy (float)
Movement speed in pixels in y direction.
touch.primary (bool)
Whether this is the only/first touch or an additional touch.

Since: 5.1.0

ALLEGRO_EVENT_TOUCH_END

A touch ended.

Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN.

Since: 5.1.0

ALLEGRO_EVENT_TOUCH_MOVE

The position of a touch changed.

Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN.

Since: 5.1.0

ALLEGRO_EVENT_TOUCH_CANCEL

A touch was cancelled. This is device specific but could for example mean that a finger moved off the border of the device or moved so fast that it could not be tracked any longer.

Has the same fields as ALLEGRO_EVENT_TOUCH_BEGIN.

Since: 5.1.0

ALLEGRO_EVENT_TIMER

A timer counter incremented.

timer.source (ALLEGRO_TIMER *)
The timer which generated the event.
timer.count (int64_t)
The timer count value.

ALLEGRO_EVENT_DISPLAY_EXPOSE

The display (or a portion thereof) has become visible.

display.source (ALLEGRO_DISPLAY *)
The display which was exposed.
display.x (int)
display.y (int)
The top-left corner of the rectangle which was exposed.
display.width (int)
display.height (int)
The width and height of the rectangle which was exposed.

Note: The display needs to be created with ALLEGRO_GENERATE_EXPOSE_EVENTS flag for these events to be generated.

ALLEGRO_EVENT_DISPLAY_RESIZE

The window has been resized.

display.source (ALLEGRO_DISPLAY *)
The display which was resized.
display.x (int)
display.y (int)
The position of the top-level corner of the display.
display.width (int)
The new width of the display.
display.height (int)
The new height of the display.

You should normally respond to these events by calling al_acknowledge_resize. Note that further resize events may be generated by the time you process the event, so these fields may hold outdated information.

ALLEGRO_EVENT_DISPLAY_CLOSE

The close button of the window has been pressed.

display.source (ALLEGRO_DISPLAY *)
The display which was closed.

ALLEGRO_EVENT_DISPLAY_LOST

When using Direct3D, displays can enter a "lost" state. In that state, drawing calls are ignored, and upon entering the state, bitmap's pixel data can become undefined. Allegro does its best to preserve the correct contents of bitmaps (see the ALLEGRO_NO_PRESERVE_TEXTURE flag) and restore them when the device is "found" (see ALLEGRO_EVENT_DISPLAY_FOUND). However, this is not 100% fool proof (see discussion in al_create_bitmap's documentation).

Note: This event merely means that the display was lost, that is, DirectX suddenly lost the contents of all video bitmaps. In particular, you can keep calling drawing functions -- they just most likely won't do anything. If Allegro's restoration of the bitmaps works well for you then no further action is required when you receive this event.

display.source (ALLEGRO_DISPLAY *)
The display which was lost.

ALLEGRO_EVENT_DISPLAY_FOUND

Generated when a lost device is restored to operating state. See ALLEGRO_EVENT_DISPLAY_LOST.

display.source (ALLEGRO_DISPLAY *)
The display which was found.

ALLEGRO_EVENT_DISPLAY_SWITCH_OUT

The window is no longer active, that is the user might have clicked into another window or "tabbed" away. In response to this event you might want to call al_clear_keyboard_state (possibly passing display.source as its argument) in order to prevent Allegro's keyboard state from getting out of sync.

display.source (ALLEGRO_DISPLAY *)
The display which was switched out of.

ALLEGRO_EVENT_DISPLAY_SWITCH_IN

The window is the active one again.

display.source (ALLEGRO_DISPLAY *)
The display which was switched into.

ALLEGRO_EVENT_DISPLAY_ORIENTATION

Generated when the rotation or orientation of a display changes.

display.source (ALLEGRO_DISPLAY *)
The display which generated the event.
event.display.orientation

Contains one of the following values:

  • ALLEGRO_DISPLAY_ORIENTATION_0_DEGREES
  • ALLEGRO_DISPLAY_ORIENTATION_90_DEGREES
  • ALLEGRO_DISPLAY_ORIENTATION_180_DEGREES
  • ALLEGRO_DISPLAY_ORIENTATION_270_DEGREES
  • ALLEGRO_DISPLAY_ORIENTATION_FACE_UP
  • ALLEGRO_DISPLAY_ORIENTATION_FACE_DOWN

ALLEGRO_EVENT_DISPLAY_HALT_DRAWING

When a display receives this event it should stop doing any drawing and then call al_acknowledge_drawing_halt immediately.

This is currently only relevant for Android and iOS. It will be sent when the application is switched to background mode, in addition to ALLEGRO_EVENT_DISPLAY_SWITCH_OUT. The latter may also be sent in situations where the application is not active but still should continue drawing, for example when a popup is displayed in front of it.

Note: This event means that the next time you call a drawing function, your program will crash. So you must stop drawing and you must immediately reply with al_acknowledge_drawing_halt. Allegro sends this event because it cannot handle this automatically. Your program might be doing the drawing in a different thread from the event handling, in which case the drawing thread needs to be signaled to stop drawing before acknowledging this event.

Note: Mobile devices usually never quit an application, so to prevent the battery from draining while your application is halted it can be a good idea to call al_stop_timer on all your timers, otherwise they will keep generating events. If you are using audio, you can also stop all audio voices (or pass NULL to al_set_default_voice if you use the default mixer), otherwise Allegro will keep streaming silence to the voice even if the stream or mixer are stopped or detached.

Since: 5.1.0

See also: ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING

ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING

When a display receives this event, it may resume drawing again, and it must call al_acknowledge_drawing_resume immediately.

This is currently only relevant for Android and iOS. The event will be sent when an application returns from background mode and is allowed to draw to the display again, in addition to ALLEGRO_EVENT_DISPLAY_SWITCH_IN. The latter event may also be sent in a situation where the application is already active, for example when a popup in front of it closes.

Note: Unlike ALLEGRO_EVENT_DISPLAY_FOUND it is not necessary to reload any bitmaps when you receive this event.

Since: 5.1.0

See also: ALLEGRO_EVENT_DISPLAY_HALT_DRAWING

ALLEGRO_EVENT_DISPLAY_CONNECTED

This event is sent when a physical display is connected to the device Allegro runs on. Currently, on most platforms, Allegro supports only a single physical display. However, on iOS, a secondary physical display is supported.

display.source (ALLEGRO_DISPLAY *)
The display which was connected.

Since: 5.1.1

ALLEGRO_EVENT_DISPLAY_DISCONNECTED

This event is sent when a physical display is disconnected from the device Allegro runs on. Currently, on most platforms, Allegro supports only a single physical display. However, on iOS, a secondary physical display is supported.

display.source (ALLEGRO_DISPLAY *)
The display which was disconnected.

ALLEGRO_USER_EVENT

typedef struct ALLEGRO_USER_EVENT ALLEGRO_USER_EVENT;

Source Code

An event structure that can be emitted by user event sources. These are the public fields:

  • ALLEGRO_EVENT_SOURCE *source;
  • intptr_t data1;
  • intptr_t data2;
  • intptr_t data3;
  • intptr_t data4;

Like all other event types this structure is a part of the ALLEGRO_EVENT union. To access the fields in an ALLEGRO_EVENT variable ev, you would use:

  • ev.user.source
  • ev.user.data1
  • ev.user.data2
  • ev.user.data3
  • ev.user.data4

To create a new user event you would do this:

ALLEGRO_EVENT_SOURCE my_event_source;
ALLEGRO_EVENT my_event;
float some_var;

al_init_user_event_source(&my_event_source);

my_event.user.type = ALLEGRO_GET_EVENT_TYPE('M','I','N','E');
my_event.user.data1 = 1;
my_event.user.data2 = &some_var;

al_emit_user_event(&my_event_source, &my_event, NULL);

Event type identifiers for user events are assigned by the user. Please see the documentation for ALLEGRO_GET_EVENT_TYPE for the rules you should follow when assigning identifiers.

See also: al_emit_user_event, ALLEGRO_GET_EVENT_TYPE, al_init_user_event_source

ALLEGRO_EVENT_QUEUE

typedef struct ALLEGRO_EVENT_QUEUE ALLEGRO_EVENT_QUEUE;

Source Code

An event queue holds events that have been generated by event sources that are registered with the queue. Events are stored in the order they are generated. Access is in a strictly FIFO (first-in-first-out) order.

See also: al_create_event_queue, al_destroy_event_queue

ALLEGRO_EVENT_SOURCE

typedef struct ALLEGRO_EVENT_SOURCE ALLEGRO_EVENT_SOURCE;

Source Code

An event source is any object which can generate events. For example, an ALLEGRO_DISPLAY can generate events, and you can get the ALLEGRO_EVENT_SOURCE pointer from an ALLEGRO_DISPLAY with al_get_display_event_source.

You may create your own "user" event sources that emit custom events.

See also: ALLEGRO_EVENT, al_init_user_event_source, al_emit_user_event

ALLEGRO_EVENT_TYPE

typedef unsigned int ALLEGRO_EVENT_TYPE;

Source Code

An integer used to distinguish between different types of events.

See also: ALLEGRO_EVENT, ALLEGRO_GET_EVENT_TYPE, ALLEGRO_EVENT_TYPE_IS_USER

ALLEGRO_GET_EVENT_TYPE

#define ALLEGRO_GET_EVENT_TYPE(a, b, c, d)   AL_ID(a, b, c, d)

Source Code

Make an event type identifier, which is a 32-bit integer. Usually, but not necessarily, this will be made from four 8-bit character codes, for example:

#defin  MY_EVENT_TYPE   ALLEGRO_GET_EVENT_TYPE('M','I','N','E')

IDs less than 1024 are reserved for Allegro or its addons. Don't use anything lower than ALLEGRO_GET_EVENT_TYPE(0, 0, 4, 0).

You should try to make your IDs unique so they don't clash with any 3rd party code you may be using. Be creative. Numbering from 1024 is not creative.

If you need multiple identifiers, you could define them like this:

#defin  BASE_EVENT   ALLEGRO_GET_EVENT_TYPE('M','I','N','E')
#defin  BARK_EVENT   (BASE_EVENT + 0)
#defin  MEOW_EVENT   (BASE_EVENT + 1)
#defin  SQUAWK_EVENT (BASE_EVENT + 2)

/* Alternatively */
enum {
   BARK_EVENT = ALLEGRO_GET_EVENT_TYPE('M','I','N','E'),
   MEOW_EVENT,
   SQUAWK_EVENT
};

See also: ALLEGRO_EVENT, ALLEGRO_USER_EVENT, ALLEGRO_EVENT_TYPE_IS_USER

ALLEGRO_EVENT_TYPE_IS_USER

#define ALLEGRO_EVENT_TYPE_IS_USER(t)        ((t) >= 512)

Source Code

A macro which evaluates to true if the event type is not a builtin event type, i.e. one of those described in ALLEGRO_EVENT_TYPE.

al_create_event_queue

ALLEGRO_EVENT_QUEUE *al_create_event_queue(void)

Source Code

Create a new, empty event queue, returning a pointer to the newly created object if successful. Returns NULL on error.

See also: al_register_event_source, al_destroy_event_queue, ALLEGRO_EVENT_QUEUE

al_destroy_event_queue

void al_destroy_event_queue(ALLEGRO_EVENT_QUEUE *queue)

Source Code

Destroy the event queue specified. All event sources currently registered with the queue will be automatically unregistered before the queue is destroyed.

See also: al_create_event_queue, ALLEGRO_EVENT_QUEUE

al_register_event_source

void al_register_event_source(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT_SOURCE *source)

Source Code

Register the event source with the event queue specified. An event source may be registered with any number of event queues simultaneously, or none. Trying to register an event source with the same event queue more than once does nothing.

See also: al_unregister_event_source, ALLEGRO_EVENT_SOURCE

al_unregister_event_source

void al_unregister_event_source(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT_SOURCE *source)

Source Code

Unregister an event source with an event queue. If the event source is not actually registered with the event queue, nothing happens.

If the queue had any events in it which originated from the event source, they will no longer be in the queue after this call.

See also: al_register_event_source

al_is_event_source_registered

bool al_is_event_source_registered(ALLEGRO_EVENT_QUEUE *queue,
      ALLEGRO_EVENT_SOURCE *source)

Source Code

Return true if the event source is registered.

See also: al_register_event_source

Since: 5.2.0

al_pause_event_queue

void al_pause_event_queue(ALLEGRO_EVENT_QUEUE *queue, bool pause)

Source Code

Pause or resume accepting new events into the event queue (to resume, pass false for pause). Events already in the queue are unaffected.

While a queue is paused, any events which would be entered into the queue are simply ignored. This is an alternative to unregistering then re-registering all event sources from the event queue, if you just need to prevent events piling up in the queue for a while.

See also: al_is_event_queue_paused

Since: 5.1.0

al_is_event_queue_paused

bool al_is_event_queue_paused(const ALLEGRO_EVENT_QUEUE *queue)

Source Code

Return true if the event queue is paused.

See also: al_pause_event_queue

Since: 5.1.0

al_is_event_queue_empty

bool al_is_event_queue_empty(ALLEGRO_EVENT_QUEUE *queue)

Source Code

Return true if the event queue specified is currently empty.

See also: al_get_next_event, al_peek_next_event

al_get_next_event

bool al_get_next_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

Source Code

Take the next event out of the event queue specified, and copy the contents into ret_event, returning true. The original event will be removed from the queue. If the event queue is empty, return false and the contents of ret_event are unspecified.

See also: ALLEGRO_EVENT, al_peek_next_event, al_wait_for_event

al_peek_next_event

bool al_peek_next_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

Source Code

Copy the contents of the next event in the event queue specified into ret_event and return true. The original event packet will remain at the head of the queue. If the event queue is actually empty, this function returns false and the contents of ret_event are unspecified.

See also: ALLEGRO_EVENT, al_get_next_event, al_drop_next_event

al_drop_next_event

bool al_drop_next_event(ALLEGRO_EVENT_QUEUE *queue)

Source Code

Drop (remove) the next event from the queue. If the queue is empty, nothing happens. Returns true if an event was dropped.

See also: al_flush_event_queue, al_is_event_queue_empty

al_flush_event_queue

void al_flush_event_queue(ALLEGRO_EVENT_QUEUE *queue)

Source Code

Drops all events, if any, from the queue.

See also: al_drop_next_event, al_is_event_queue_empty

al_wait_for_event

void al_wait_for_event(ALLEGRO_EVENT_QUEUE *queue, ALLEGRO_EVENT *ret_event)

Source Code

Wait until the event queue specified is non-empty. If ret_event is not NULL, the first event in the queue will be copied into ret_event and removed from the queue. If ret_event is NULL the first event is left at the head of the queue.

See also: ALLEGRO_EVENT, al_wait_for_event_timed, al_wait_for_event_until, al_get_next_event

al_wait_for_event_timed

bool al_wait_for_event_timed(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT *ret_event, float secs)

Source Code

Wait until the event queue specified is non-empty. If ret_event is not NULL, the first event in the queue will be copied into ret_event and removed from the queue. If ret_event is NULL the first event is left at the head of the queue.

secs determines approximately how many seconds to wait. If the call times out, false is returned. Otherwise, if an event ocurred, true is returned.

For compatibility with all platforms, secs must be 2,147,483.647 seconds or less.

See also: ALLEGRO_EVENT, al_wait_for_event, al_wait_for_event_until

al_wait_for_event_until

bool al_wait_for_event_until(ALLEGRO_EVENT_QUEUE *queue,
   ALLEGRO_EVENT *ret_event, ALLEGRO_TIMEOUT *timeout)

Source Code

Wait until the event queue specified is non-empty. If ret_event is not NULL, the first event in the queue will be copied into ret_event and removed from the queue. If ret_event is NULL the first event is left at the head of the queue.

timeout determines how long to wait. If the call times out, false is returned. Otherwise, if an event ocurred, true is returned.

For compatibility with all platforms, timeout must be 2,147,483.647 seconds or less.

See also: ALLEGRO_EVENT, ALLEGRO_TIMEOUT, al_init_timeout, al_wait_for_event, al_wait_for_event_timed

al_init_user_event_source

void al_init_user_event_source(ALLEGRO_EVENT_SOURCE *src)

Source Code

Initialise an event source for emitting user events. The space for the event source must already have been allocated.

One possible way of creating custom event sources is to derive other structures with ALLEGRO_EVENT_SOURCE at the head, e.g.

typedef struct THING THING;

struct THING {
    ALLEGRO_EVENT_SOURCE event_source;
    int field1;
    int field2;
    /* etc. */
};

THING *create_thing(void)
{
    THING *thing = malloc(sizeof(THING));

    if (thing) {
        al_init_user_event_source(&thing->event_source);
        thing->field1 = 0;
        thing->field2 = 0;
    }

    return thing;
}

The advantage here is that the THING pointer will be the same as the ALLEGRO_EVENT_SOURCE pointer. Events emitted by the event source will have the event source pointer as the source field, from which you can get a pointer to a THING by a simple cast (after ensuring checking the event is of the correct type).

However, it is only one technique and you are not obliged to use it.

The user event source will never be destroyed automatically. You must destroy it manually with al_destroy_user_event_source.

See also: ALLEGRO_EVENT_SOURCE, al_destroy_user_event_source, al_emit_user_event, ALLEGRO_USER_EVENT

al_destroy_user_event_source

void al_destroy_user_event_source(ALLEGRO_EVENT_SOURCE *src)

Source Code

Destroy an event source initialised with al_init_user_event_source.

This does not free the memory, as that was user allocated to begin with.

See also: ALLEGRO_EVENT_SOURCE

al_emit_user_event

bool al_emit_user_event(ALLEGRO_EVENT_SOURCE *src,
   ALLEGRO_EVENT *event, void (*dtor)(ALLEGRO_USER_EVENT *))

Source Code

Emit an event from a user event source. The event source must have been initialised with al_init_user_event_source. Returns false if the event source isn't registered with any queues, hence the event wouldn't have been delivered into any queues.

Events are copied in and out of event queues, so after this function returns the memory pointed to by event may be freed or reused. Some fields of the event being passed in may be modified by the function.

Reference counting will be performed if dtor is not NULL. Whenever a copy of the event is made, the reference count increases. You need to call al_unref_user_event to decrease the reference count once you are done with a user event that you have received from al_get_next_event, al_peek_next_event, al_wait_for_event, etc.

Once the reference count drops to zero dtor will be called with a copy of the event as an argument. It should free the resources associated with the event, but not the event itself (since it is just a copy).

If dtor is NULL then reference counting will not be performed. It is safe, but unnecessary, to call al_unref_user_event on non-reference counted user events.

You can use al_emit_user_event to emit both user and non-user events from your user event source. Note that emitting input events will not update the corresponding input device states. For example, you may emit an event of type ALLEGRO_EVENT_KEY_DOWN, but it will not update the ALLEGRO_KEYBOARD_STATE returned by al_get_keyboard_state.

See also: ALLEGRO_USER_EVENT, al_unref_user_event

al_unref_user_event

void al_unref_user_event(ALLEGRO_USER_EVENT *event)

Source Code

Decrease the reference count of a user-defined event. This must be called on any user event that you get from al_get_next_event, al_peek_next_event, al_wait_for_event, etc. which is reference counted. This function does nothing if the event is not reference counted.

See also: al_emit_user_event, ALLEGRO_USER_EVENT

al_get_event_source_data

intptr_t al_get_event_source_data(const ALLEGRO_EVENT_SOURCE *source)

Source Code

Returns the abstract user data associated with the event source. If no data was previously set, returns NULL.

See also: al_set_event_source_data

al_set_event_source_data

void al_set_event_source_data(ALLEGRO_EVENT_SOURCE *source, intptr_t data)

Source Code

Assign the abstract user data to the event source. Allegro does not use the data internally for anything; it is simply meant as a convenient way to associate your own data or objects with events.

See also: al_get_event_source_data

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:40 UTC


File I/O

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

File I/O

  • ALLEGRO_FILE
  • ALLEGRO_FILE_INTERFACE
  • ALLEGRO_SEEK
  • al_fopen
  • al_fopen_interface
  • al_fopen_slice
  • al_fclose
  • al_fread
  • al_fwrite
  • al_fflush
  • al_ftell
  • al_fseek
  • al_feof
  • al_ferror
  • al_ferrmsg
  • al_fclearerr
  • al_fungetc
  • al_fsize
  • al_fgetc
  • al_fputc
  • al_fprintf
  • al_vfprintf
  • al_fread16le
  • al_fread16be
  • al_fwrite16le
  • al_fwrite16be
  • al_fread32le
  • al_fread32be
  • al_fwrite32le
  • al_fwrite32be
  • al_fgets
  • al_fget_ustr
  • al_fputs
  • Standard I/O specific routines
    • al_fopen_fd
    • al_make_temp_file
  • Alternative file streams
    • al_set_new_file_interface
    • al_set_standard_file_interface
    • al_get_new_file_interface
    • al_create_file_handle
    • al_get_file_userdata

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_FILE

typedef struct ALLEGRO_FILE ALLEGRO_FILE;

Source Code

An opaque object representing an open file. This could be a real file on disk or a virtual file.

ALLEGRO_FILE_INTERFACE

typedef struct ALLEGRO_FILE_INTERFACE

Source Code

A structure containing function pointers to handle a type of "file", real or virtual. See the full discussion in al_set_new_file_interface.

The fields are:

void*         (*fi_fopen)(const char *path, const char *mode);
bool          (*fi_fclose)(ALLEGRO_FILE *f);
size_t        (*fi_fread)(ALLEGRO_FILE *f, void *ptr, size_t size);
size_t        (*fi_fwrite)(ALLEGRO_FILE *f, const void *ptr, size_t size);
bool          (*fi_fflush)(ALLEGRO_FILE *f);
int64_t       (*fi_ftell)(ALLEGRO_FILE *f);
bool          (*fi_fseek)(ALLEGRO_FILE *f, int64_t offset, int whence);
bool          (*fi_feof)(ALLEGRO_FILE *f);
int           (*fi_ferror)(ALLEGRO_FILE *f);
const char *  (*fi_ferrmsg)(ALLEGRO_FILE *f);
void          (*fi_fclearerr)(ALLEGRO_FILE *f);
int           (*fi_fungetc)(ALLEGRO_FILE *f, int c);
off_t         (*fi_fsize)(ALLEGRO_FILE *f);

The fi_open function must allocate memory for whatever userdata structure it needs. The pointer to that memory must be returned; it will then be associated with the file. The other functions can access that data by calling al_get_file_userdata on the file handle. If fi_open returns NULL then al_fopen will also return NULL.

The fi_fclose function must clean up and free the userdata, but Allegro will free the ALLEGRO_FILE handle.

If fi_fungetc is NULL, then Allegro's default implementation of a 16 char long buffer will be used.

ALLEGRO_SEEK

typedef enum ALLEGRO_SEEK

Source Code

  • ALLEGRO_SEEK_SET - seek relative to beginning of file
  • ALLEGRO_SEEK_CUR - seek relative to current file position
  • ALLEGRO_SEEK_END - seek relative to end of file

See also: al_fseek

al_fopen

ALLEGRO_FILE *al_fopen(const char *path, const char *mode)

Source Code

Creates and opens a file (real or virtual) given the path and mode. The current file interface is used to open the file.

Parameters:

  • path - path to the file to open
  • mode - access mode to open the file in ("r", "w", etc.)

Depending on the stream type and the mode string, files may be opened in "text" mode. The handling of newlines is particularly important. For example, using the default stdio-based streams on DOS and Windows platforms, where the native end-of-line terminators are CR+LF sequences, a call to al_fgetc may return just one character ('\n') where there were two bytes (CR+LF) in the file. When writing out '\n', two bytes would be written instead. (As an aside, '\n' is not defined to be equal to LF either.)

Newline translations can be useful for text files but is disastrous for binary files. To avoid this behaviour you need to open file streams in binary mode by using a mode argument containing a "b", e.g. "rb", "wb".

Returns a file handle on success, or NULL on error.

See also: al_set_new_file_interface, al_fclose.

al_fopen_interface

ALLEGRO_FILE *al_fopen_interface(const ALLEGRO_FILE_INTERFACE *drv,
   const char *path, const char *mode)

Source Code

Opens a file using the specified interface, instead of the interface set with al_set_new_file_interface.

See also: al_fopen

al_fopen_slice

ALLEGRO_FILE *al_fopen_slice(ALLEGRO_FILE *fp, size_t initial_size, const char *mode)

Source Code

Opens a slice (subset) of an already open random access file as if it were a stand alone file. While the slice is open, the parent file handle must not be used in any way.

The slice is opened at the current location of the parent file, up through initial_size bytes. The initial_size may be any non-negative integer that will not exceed the bounds of the parent file.

Seeking with ALLEGRO_SEEK_SET will be relative to this starting location. ALLEGRO_SEEK_END will be relative to the starting location plus the size of the slice.

The mode can be any combination of:

  • r: read access
  • w: write access
  • e: expandable

For example, a mode of "rw" indicates the file can be read and written. (Note that this is slightly different from the stdio modes.) Keep in mind that the parent file must support random access and be open in normal write mode (not append) for the slice to work in a well defined way.

If the slice is marked as expandable, then reads and writes can happen after the initial end point, and the slice will grow accordingly. Otherwise, all activity is restricted to the initial size of the slice.

A slice must be closed with al_fclose. The parent file will then be positioned immediately after the end of the slice.

Since: 5.0.6, 5.1.0

See also: al_fopen

al_fclose

bool al_fclose(ALLEGRO_FILE *f)

Source Code

Close the given file, writing any buffered output data (if any).

Returns true on success, false on failure. errno is set to indicate the error.

al_fread

size_t al_fread(ALLEGRO_FILE *f, void *ptr, size_t size)

Source Code

Read 'size' bytes into the buffer pointed to by 'ptr', from the given file.

Returns the number of bytes actually read. If an error occurs, or the end-of-file is reached, the return value is a short byte count (or zero).

al_fread() does not distinguish between EOF and other errors. Use al_feof and al_ferror to determine which occurred.

See also: al_fgetc, al_fread16be, al_fread16le, al_fread32be, al_fread32le

al_fwrite

size_t al_fwrite(ALLEGRO_FILE *f, const void *ptr, size_t size)

Source Code

Write 'size' bytes from the buffer pointed to by 'ptr' into the given file.

Returns the number of bytes actually written. If an error occurs, the return value is a short byte count (or zero).

See also: al_fputc, al_fputs, al_fwrite16be, al_fwrite16le, al_fwrite32be, al_fwrite32le

al_fflush

bool al_fflush(ALLEGRO_FILE *f)

Source Code

Flush any pending writes to the given file.

Returns true on success, false otherwise. errno is set to indicate the error.

See also: al_get_errno

al_ftell

int64_t al_ftell(ALLEGRO_FILE *f)

Source Code

Returns the current position in the given file, or -1 on error. errno is set to indicate the error.

On some platforms this function may not support large files.

See also: al_fseek, al_get_errno

al_fseek

bool al_fseek(ALLEGRO_FILE *f, int64_t offset, int whence)

Source Code

Set the current position of the given file to a position relative to that specified by 'whence', plus 'offset' number of bytes.

'whence' can be:

  • ALLEGRO_SEEK_SET - seek relative to beginning of file
  • ALLEGRO_SEEK_CUR - seek relative to current file position
  • ALLEGRO_SEEK_END - seek relative to end of file

Returns true on success, false on failure. errno is set to indicate the error.

After a successful seek, the end-of-file indicator is cleared and all pushback bytes are forgotten.

On some platforms this function may not support large files.

See also: al_ftell, al_get_errno

al_feof

bool al_feof(ALLEGRO_FILE *f)

Source Code

Returns true if the end-of-file indicator has been set on the file, i.e. we have attempted to read past the end of the file.

This does not return true if we simply are at the end of the file. The following code correctly reads two bytes, even when the file contains exactly two bytes:

int b1 = al_fgetc(f);
int b2 = al_fgetc(f);
if (al_feof(f)) {
   /* At least one byte was unsuccessfully read. */
   report_error();
}

See also: al_ferror, al_fclearerr

al_ferror

int al_ferror(ALLEGRO_FILE *f)

Source Code

Returns non-zero if the error indicator is set on the given file, i.e. there was some sort of previous error. The error code may be system or file interface specific.

See also: al_feof, al_fclearerr, al_ferrmsg

al_ferrmsg

const char *al_ferrmsg(ALLEGRO_FILE *f)

Source Code

Return a message string with details about the last error that occurred on the given file handle. The returned string is empty if there was no error, or if the file interface does not provide more information.

See also: al_fclearerr, al_ferror

al_fclearerr

void al_fclearerr(ALLEGRO_FILE *f)

Source Code

Clear the error indicator for the given file.

The standard I/O backend also clears the end-of-file indicator, and other backends should try to do this. However, they may not if it would require too much effort (e.g. PhysicsFS backend), so your code should not rely on it if you need your code to be portable to other backends.

See also: al_ferror, al_feof

al_fungetc

int al_fungetc(ALLEGRO_FILE *f, int c)

Source Code

Ungets a single byte from a file. Pushed-back bytes are not written to the file, only made available for subsequent reads, in reverse order.

The number of pushbacks depends on the backend. The standard I/O backend only guarantees a single pushback; this depends on the libc implementation.

For backends that follow the standard behavior, the pushback buffer will be cleared after any seeking or writing; also calls to al_fseek and al_ftell are relative to the number of pushbacks. If a pushback causes the position to become negative, the behavior of al_fseek and al_ftell are undefined.

See also: al_fgetc, al_get_errno

al_fsize

int64_t al_fsize(ALLEGRO_FILE *f)

Source Code

Return the size of the file, if it can be determined, or -1 otherwise.

al_fgetc

int al_fgetc(ALLEGRO_FILE *f)

Source Code

Read and return next byte in the given file. Returns EOF on end of file or if an error occurred.

See also: al_fungetc

al_fputc

int al_fputc(ALLEGRO_FILE *f, int c)

Source Code

Write a single byte to the given file. The byte written is the value of c cast to an unsigned char.

Parameters:

  • c - byte value to write
  • f - file to write to

Returns the written byte (cast back to an int) on success, or EOF on error.

al_fprintf

int al_fprintf(ALLEGRO_FILE *pfile, const char *format, ...)

Source Code

Writes to a file with stdio "printf"-like formatting. Returns the number of bytes written, or a negative number on error.

See also: al_vfprintf

al_vfprintf

int al_vfprintf(ALLEGRO_FILE *pfile, const char *format, va_list args)

Source Code

Like al_fprintf but takes a va_list. Useful for creating your own variations of formatted printing. Returns the number of bytes written, or a negative number on error.

See also: al_fprintf

al_fread16le

int16_t al_fread16le(ALLEGRO_FILE *f)

Source Code

Reads a 16-bit word in little-endian format (LSB first).

On success, returns the 16-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

See also: al_fread16be

al_fread16be

int16_t al_fread16be(ALLEGRO_FILE *f)

Source Code

Reads a 16-bit word in big-endian format (MSB first).

On success, returns the 16-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

See also: al_fread16le

al_fwrite16le

size_t al_fwrite16le(ALLEGRO_FILE *f, int16_t w)

Source Code

Writes a 16-bit word in little-endian format (LSB first).

Returns the number of bytes written: 2 on success, less than 2 on an error.

See also: al_fwrite16be

al_fwrite16be

size_t al_fwrite16be(ALLEGRO_FILE *f, int16_t w)

Source Code

Writes a 16-bit word in big-endian format (MSB first).

Returns the number of bytes written: 2 on success, less than 2 on an error.

See also: al_fwrite16le

al_fread32le

int32_t al_fread32le(ALLEGRO_FILE *f)

Source Code

Reads a 32-bit word in little-endian format (LSB first).

On success, returns the 32-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

See also: al_fread32be

al_fread32be

int32_t al_fread32be(ALLEGRO_FILE *f)

Source Code

Read a 32-bit word in big-endian format (MSB first).

On success, returns the 32-bit word. On failure, returns EOF (-1). Since -1 is also a valid return value, use al_feof to check if the end of the file was reached prematurely, or al_ferror to check if an error occurred.

See also: al_fread32le

al_fwrite32le

size_t al_fwrite32le(ALLEGRO_FILE *f, int32_t l)

Source Code

Writes a 32-bit word in little-endian format (LSB first).

Returns the number of bytes written: 4 on success, less than 4 on an error.

See also: al_fwrite32be

al_fwrite32be

size_t al_fwrite32be(ALLEGRO_FILE *f, int32_t l)

Source Code

Writes a 32-bit word in big-endian format (MSB first).

Returns the number of bytes written: 4 on success, less than 4 on an error.

See also: al_fwrite32le

al_fgets

char *al_fgets(ALLEGRO_FILE *f, char * const buf, size_t max)

Source Code

Read a string of bytes terminated with a newline or end-of-file into the buffer given. The line terminator(s), if any, are included in the returned string. A maximum of max-1 bytes are read, with one byte being reserved for a NUL terminator.

Parameters:

  • f - file to read from
  • buf - buffer to fill
  • max - maximum size of buffer

Returns the pointer to buf on success. Returns NULL if an error occurred or if the end of file was reached without reading any bytes.

See al_fopen about translations of end-of-line characters.

See also: al_fget_ustr

al_fget_ustr

ALLEGRO_USTR *al_fget_ustr(ALLEGRO_FILE *f)

Source Code

Read a string of bytes terminated with a newline or end-of-file. The line terminator(s), if any, are included in the returned string.

On success returns a pointer to a new ALLEGRO_USTR structure. This must be freed eventually with al_ustr_free. Returns NULL if an error occurred or if the end of file was reached without reading any bytes.

See al_fopen about translations of end-of-line characters.

See also: al_fgetc, al_fgets

al_fputs

int al_fputs(ALLEGRO_FILE *f, char const *p)

Source Code

Writes a string to file. Apart from the return value, this is equivalent to:

al_fwrite(f, p, strlen(p));

Parameters:

  • f - file handle to write to
  • p - string to write

Returns a non-negative integer on success, EOF on error.

Note: depending on the stream type and the mode passed to al_fopen, newline characters in the string may or may not be automatically translated to native end-of-line sequences, e.g. CR/LF instead of LF.

See also: al_fwrite

Standard I/O specific routines

al_fopen_fd

ALLEGRO_FILE *al_fopen_fd(int fd, const char *mode)

Source Code

Create an ALLEGRO_FILE object that operates on an open file descriptor using stdio routines. See the documentation of fdopen() for a description of the 'mode' argument.

Returns an ALLEGRO_FILE object on success or NULL on an error. On an error, the Allegro errno will be set and the file descriptor will not be closed.

The file descriptor will be closed by al_fclose so you should not call close() on it.

See also: al_fopen

al_make_temp_file

ALLEGRO_FILE *al_make_temp_file(const char *template, ALLEGRO_PATH **ret_path)

Source Code

Make a temporary randomly named file given a filename 'template'.

'template' is a string giving the format of the generated filename and should include one or more capital Xs. The Xs are replaced with random alphanumeric characters, produced using a simple pseudo-random number generator only. There should be no path separators.

If 'ret_path' is not NULL, the address it points to will be set to point to a new path structure with the name of the temporary file.

Returns the opened ALLEGRO_FILE on success, NULL on failure.

Alternative file streams

By default, the Allegro file I/O routines use the C library I/O routines, hence work with files on the local filesystem, but can be overridden so that you can read and write to other streams. For example, you can work with blocks of memory or sub-files inside .zip files.

There are two ways to get an ALLEGRO_FILE that doesn't use stdio. An addon library may provide a function that returns a new ALLEGRO_FILE directly, after which, all al_f* calls on that object will use overridden functions for that type of stream. Alternatively, al_set_new_file_interface changes which function will handle the following al_fopen calls for the current thread.

al_set_new_file_interface

void al_set_new_file_interface(const ALLEGRO_FILE_INTERFACE *file_interface)

Source Code

Set the ALLEGRO_FILE_INTERFACE table for the calling thread. This will change the handler for later calls to al_fopen.

See also: al_set_standard_file_interface, al_store_state, al_restore_state.

al_set_standard_file_interface

void al_set_standard_file_interface(void)

Source Code

Set the ALLEGRO_FILE_INTERFACE table to the default, for the calling thread. This will change the handler for later calls to al_fopen.

See also: al_set_new_file_interface

al_get_new_file_interface

const ALLEGRO_FILE_INTERFACE *al_get_new_file_interface(void)

Source Code

Return a pointer to the ALLEGRO_FILE_INTERFACE table in effect for the calling thread.

See also: al_store_state, al_restore_state.

al_create_file_handle

ALLEGRO_FILE *al_create_file_handle(const ALLEGRO_FILE_INTERFACE *drv,
   void *userdata)

Source Code

Creates an empty, opened file handle with some abstract user data. This allows custom interfaces to extend the ALLEGRO_FILE struct with their own data. You should close the handle with the standard al_fclose function when you are finished with it.

See also: al_fopen, al_fclose, al_set_new_file_interface

al_get_file_userdata

void *al_get_file_userdata(ALLEGRO_FILE *f)

Source Code

Returns a pointer to the custom userdata that is attached to the file handle. This is intended to be used by functions that extend ALLEGRO_FILE_INTERFACE.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:40 UTC


Fixed point math routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Fixed point math routines

  • al_fixed
  • al_itofix
  • al_fixtoi
  • al_fixfloor
  • al_fixceil
  • al_ftofix
  • al_fixtof
  • al_fixmul
  • al_fixdiv
  • al_fixadd
  • al_fixsub
  • Fixed point trig
    • al_fixtorad_r
    • al_radtofix_r
    • al_fixsin
    • al_fixcos
    • al_fixtan
    • al_fixasin
    • al_fixacos
    • al_fixatan
    • al_fixatan2
    • al_fixsqrt
    • al_fixhypot

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

al_fixed

typedef int32_t al_fixed;

Source Code

A fixed point number.

Allegro provides some routines for working with fixed point numbers, and defines the type al_fixed to be a signed 32-bit integer. The high word is used for the integer part and the low word for the fraction, giving a range of -32768 to 32767 and an accuracy of about four or five decimal places. Fixed point numbers can be assigned, compared, added, subtracted, negated and shifted (for multiplying or dividing by powers of two) using the normal integer operators, but you should take care to use the appropriate conversion routines when mixing fixed point with integer or floating point values. Writing fixed_point_1 + fixed_point_2 is OK, but fixed_point + integer is not.

The only advantage of fixed point math routines is that you don't require a floating point coprocessor to use them. This was great in the time period of i386 and i486 machines, but stopped being so useful with the coming of the Pentium class of processors. From Pentium onwards, CPUs have increased their strength in floating point operations, equaling or even surpassing integer math performance. However, many embedded processors have no FPUs so fixed point maths can still be useful there.

Depending on the type of operations your program may need, using floating point types may be faster than fixed types if you are targeting a specific machine class.

al_itofix

al_fixed al_itofix(int x);

Source Code

Converts an integer to fixed point. This is the same thing as x<<16. Remember that overflows (trying to convert an integer greater than 32767) and underflows (trying to convert an integer lesser than -32768) are not detected even in debug builds! The values simply "wrap around".

Example:

al_fixed number;

/* This conversion is OK. */
number = al_itofix(100);
assert(al_fixtoi(number) == 100);

number = al_itofix(64000);

/* This check will fail in debug builds. */
assert(al_fixtoi(number) == 64000);

Return value: Returns the value of the integer converted to fixed point ignoring overflows.

See also: al_fixtoi, al_ftofix, al_fixtof.

al_fixtoi

int al_fixtoi(al_fixed x);

Source Code

Converts fixed point to integer, rounding as required to the nearest integer.

Example:

int result;

/* This will put 33 into `result'. */
result = al_fixtoi(al_itofix(100) / 3);

/* But this will round up to 17. */
result = al_fixtoi(al_itofix(100) / 6);

See also: al_itofix, al_ftofix, al_fixtof, al_fixfloor, al_fixceil.

al_fixfloor

int al_fixfloor(al_fixed x);

Source Code

Returns the greatest integer not greater than x. That is, it rounds towards negative infinity.

Example:

int result;

/* This will put 33 into `result'. */
result = al_fixfloor(al_itofix(100) / 3);

/* And this will round down to 16. */
result = al_fixfloor(al_itofix(100) / 6);

See also: al_fixtoi, al_fixceil.

al_fixceil

int al_fixceil(al_fixed x);

Source Code

Returns the smallest integer not less than x. That is, it rounds towards positive infinity.

Example:

int result;

/* This will put 34 into `result'. */
result = al_fixceil(al_itofix(100) / 3);

/* This will round up to 17. */
result = al_fixceil(al_itofix(100) / 6);

See also: al_fixtoi, al_fixfloor.

al_ftofix

al_fixed al_ftofix(double x);

Source Code

Converts a floating point value to fixed point. Unlike al_itofix, this function clamps values which could overflow the type conversion, setting Allegro's errno to ERANGE in the process if this happens.

Example:

al_fixed number;

number = al_itofix(-40000);
assert(al_fixfloor(number) == -32768);

number = al_itofix(64000);
assert(al_fixfloor(number) == 32767);
assert(!al_get_errno()); /* This will fail. */

Return value: Returns the value of the floating point value converted to fixed point clamping overflows (and setting Allegro's errno).

See also: al_fixtof, al_itofix, al_fixtoi, al_get_errno

al_fixtof

double al_fixtof(al_fixed x);

Source Code

Converts fixed point to floating point.

Example:

float result;

/* This will put 33.33333 into `result'. */
result = al_fixtof(al_itofix(100) / 3);

/* This will put 16.66666 into `result'. */
result = al_fixtof(al_itofix(100) / 6);

See also: al_ftofix, al_itofix, al_fixtoi.

al_fixmul

al_fixed al_fixmul(al_fixed x, al_fixed y);

Source Code

A fixed point value can be multiplied or divided by an integer with the normal * and / operators. To multiply two fixed point values, though, you must use this function.

If an overflow occurs, Allegro's errno will be set and the maximum possible value will be returned, but errno is not cleared if the operation is successful. This means that if you are going to test for overflow you should call al_set_errno(0) before calling al_fixmul.

Example:

al_fixed result;

/* This will put 30000 into `result'. */
result = al_fixmul(al_itofix(10), al_itofix(3000));

/* But this overflows, and sets errno. */
result = al_fixmul(al_itofix(100), al_itofix(3000));
assert(!al_get_errno());

Return value: Returns the clamped result of multiplying x by y, setting Allegro's errno to ERANGE if there was an overflow.

See also: al_fixadd, al_fixsub, al_fixdiv, al_get_errno.

al_fixdiv

al_fixed al_fixdiv(al_fixed x, al_fixed y);

Source Code

A fixed point value can be divided by an integer with the normal / operator. To divide two fixed point values, though, you must use this function. If a division by zero occurs, Allegro's errno will be set and the maximum possible value will be returned, but errno is not cleared if the operation is successful. This means that if you are going to test for division by zero you should call al_set_errno(0) before calling al_fixdiv.

Example:

al_fixed result;

/* This will put 0.06060 `result'. */
result = al_fixdiv(al_itofix(2), al_itofix(33));

/* This will put 0 into `result'. */
result = al_fixdiv(0, al_itofix(-30));

/* Sets errno and puts -32768 into `result'. */
result = al_fixdiv(al_itofix(-100), al_itofix(0));
assert(!al_get_errno()); /* This will fail. */

Return value: Returns the result of dividing x by y. If y is zero, returns the maximum possible fixed point value and sets Allegro's errno to ERANGE.

See also: al_fixadd, al_fixsub, al_fixmul, al_get_errno.

al_fixadd

al_fixed al_fixadd(al_fixed x, al_fixed y);

Source Code

Although fixed point numbers can be added with the normal + integer operator, that doesn't provide any protection against overflow. If overflow is a problem, you should use this function instead. It is slower than using integer operators, but if an overflow occurs it will set Allegro's errno and clamp the result, rather than just letting it wrap.

Example:

al_fixed result;

/* This will put 5035 into `result'. */
result = al_fixadd(al_itofix(5000), al_itofix(35));

/* Sets errno and puts -32768 into `result'. */
result = al_fixadd(al_itofix(-31000), al_itofix(-3000));
assert(!al_get_errno()); /* This will fail. */

Return value: Returns the clamped result of adding x to y, setting Allegro's errno to ERANGE if there was an overflow.

See also: al_fixsub, al_fixmul, al_fixdiv.

al_fixsub

al_fixed al_fixsub(al_fixed x, al_fixed y);

Source Code

Although fixed point numbers can be subtracted with the normal - integer operator, that doesn't provide any protection against overflow. If overflow is a problem, you should use this function instead. It is slower than using integer operators, but if an overflow occurs it will set Allegro's errno and clamp the result, rather than just letting it wrap.

Example:

al_fixed result;

/* This will put 4965 into `result'. */
result = al_fixsub(al_itofix(5000), al_itofix(35));

/* Sets errno and puts -32768 into `result'. */
result = al_fixsub(al_itofix(-31000), al_itofix(3000));
assert(!al_get_errno()); /* This will fail. */

Return value: Returns the clamped result of subtracting y from x, setting Allegro's errno to ERANGE if there was an overflow.

See also: al_fixadd, al_fixmul, al_fixdiv, al_get_errno.

Fixed point trig

The fixed point square root, sin, cos, tan, inverse sin, and inverse cos functions are implemented using lookup tables, which are very fast but not particularly accurate. At the moment the inverse tan uses an iterative search on the tan table, so it is a lot slower than the others. On machines with good floating point processors using these functions could be slower Always profile your code.

Angles are represented in a binary format with 256 equal to a full circle, 64 being a right angle and so on. This has the advantage that a simple bitwise 'and' can be used to keep the angle within the range zero to a full circle.

al_fixtorad_r

const al_fixed al_fixtorad_r = (al_fixed)1608;

Source Code

This constant gives a ratio which can be used to convert a fixed point number in binary angle format to a fixed point number in radians.

Example:

al_fixed rad_angle, binary_angle;

/* Set the binary angle to 90 degrees. */
binary_angle = 64;

/* Now convert to radians (about 1.57). */
rad_angle = al_fixmul(binary_angle, al_fixtorad_r);

See also: al_fixmul, al_radtofix_r.

al_radtofix_r

const al_fixed al_radtofix_r = (al_fixed)2670177;

Source Code

This constant gives a ratio which can be used to convert a fixed point number in radians to a fixed point number in binary angle format.

Example:

    al_fixed rad_angle, binary_angle;
    ...
    binary_angle = al_fixmul(rad_angle, radtofix_r);

See also: al_fixmul, al_fixtorad_r.

al_fixsin

al_fixed al_fixsin(al_fixed x);

Source Code

This function finds the sine of a value using a lookup table. The input value must be a fixed point binary angle.

Example:

al_fixed angle;
int result;

/* Set the binary angle to 90 degrees. */
angle = al_itofix(64);

/* The sine of 90 degrees is one. */
result = al_fixtoi(al_fixsin(angle));
assert(result == 1);

Return value: Returns the sine of a fixed point binary format angle as a fixed point value.

al_fixcos

al_fixed al_fixcos(al_fixed x);

Source Code

This function finds the cosine of a value using a lookup table. The input value must be a fixed point binary angle.

Example:

al_fixed angle;
float result;

/* Set the binary angle to 45 degrees. */
angle = al_itofix(32);

/* The cosine of 45 degrees is about 0.7071. */
result = al_fixtof(al_fixcos(angle));
assert(result > 0.7 && result < 0.71);

Return value: Returns the cosine of a fixed point binary format angle as a fixed point value.

al_fixtan

al_fixed al_fixtan(al_fixed x);

Source Code

This function finds the tangent of a value using a lookup table. The input value must be a fixed point binary angle.

Example:

al_fixed angle, res_a, res_b;
float dif;

angle = al_itofix(37);
/* Prove that tan(angle) == sin(angle) / cos(angle). */
res_a = al_fixdiv(al_fixsin(angle), al_fixcos(angle));
res_b = al_fixtan(angle);
dif = al_fixtof(al_fixsub(res_a, res_b));
printf("Precision error: %f\n", dif);

Return value: Returns the tangent of a fixed point binary format angle as a fixed point value.

al_fixasin

al_fixed al_fixasin(al_fixed x);

Source Code

This function finds the inverse sine of a value using a lookup table. The input value must be a fixed point value. The inverse sine is defined only in the domain from -1 to 1. Outside of this input range, the function will set Allegro's errno to EDOM and return zero.

Example:

float angle;
al_fixed val;

/* Sets `val' to a right binary angle (64). */
val = al_fixasin(al_itofix(1));

/* Sets `angle' to 0.2405. */
angle = al_fixtof(al_fixmul(al_fixasin(al_ftofix(0.238)), al_fixtorad_r));

/* This will trigger the assert. */
val = al_fixasin(al_ftofix(-1.09));
assert(!al_get_errno());

Return value: Returns the inverse sine of a fixed point value, measured as fixed point binary format angle, or zero if the input was out of the range. All return values of this function will be in the range -64 to 64.

al_fixacos

al_fixed al_fixacos(al_fixed x);

Source Code

This function finds the inverse cosine of a value using a lookup table. The input must be a fixed point value. The inverse cosine is defined only in the domain from -1 to 1. Outside of this input range, the function will set Allegro's errno to EDOM and return zero.

Example:

al_fixed result;

/* Sets result to binary angle 128. */
result = al_fixacos(al_itofix(-1));

Return value: Returns the inverse sine of a fixed point value, measured as fixed point binary format angle, or zero if the input was out of range. All return values of this function will be in the range 0 to 128.

al_fixatan

al_fixed al_fixatan(al_fixed x)

Source Code

This function finds the inverse tangent of a value using a lookup table. The input must be a fixed point value. The inverse tangent is the value whose tangent is x.

Example:

al_fixed result;

/* Sets result to binary angle 13. */
result = al_fixatan(al_ftofix(0.326));

Return value: Returns the inverse tangent of a fixed point value, measured as a fixed point binary format angle.

al_fixatan2

al_fixed al_fixatan2(al_fixed y, al_fixed x)

Source Code

This is a fixed point version of the libc atan2() routine. It computes the arc tangent of y / x, but the signs of both arguments are used to determine the quadrant of the result, and x is permitted to be zero. This function is useful to convert Cartesian coordinates to polar coordinates.

Example:

al_fixed result;

/* Sets `result' to binary angle 64. */
result = al_fixatan2(al_itofix(1), 0);

/* Sets `result' to binary angle -109. */
result = al_fixatan2(al_itofix(-1), al_itofix(-2));

/* Fails the assert. */
result = al_fixatan2(0, 0);
assert(!al_get_errno());

Return value: Returns the arc tangent of y / x in fixed point binary format angle, from -128 to 128. If both x and y are zero, returns zero and sets Allegro's errno to EDOM.

al_fixsqrt

al_fixed al_fixsqrt(al_fixed x)

Source Code

This finds out the non negative square root of x. If x is negative, Allegro's errno is set to EDOM and the function returns zero.

al_fixhypot

al_fixed al_fixhypot(al_fixed x, al_fixed y)

Source Code

Fixed point hypotenuse (returns the square root of x*x + y*y). This should be better than calculating the formula yourself manually, since the error is much smaller.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:40 UTC


Font addons

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Font addons

  • General font routines
    • ALLEGRO_FONT
    • ALLEGRO_GLYPH
    • al_init_font_addon
    • al_shutdown_font_addon
    • al_load_font
    • al_destroy_font
    • al_register_font_loader
    • al_get_font_line_height
    • al_get_font_ascent
    • al_get_font_descent
    • al_get_text_width
    • al_get_ustr_width
    • al_draw_text
    • al_draw_ustr
    • al_draw_justified_text
    • al_draw_justified_ustr
    • al_draw_textf
    • al_draw_justified_textf
    • al_get_text_dimensions
    • al_get_ustr_dimensions
    • al_get_allegro_font_version
    • al_get_font_ranges
    • al_set_fallback_font
    • al_get_fallback_font
  • Per glyph text handling
    • al_draw_glyph
    • al_get_glyph_width
    • al_get_glyph_dimensions
    • al_get_glyph_advance
  • Multiline text drawing
    • al_draw_multiline_text
    • al_draw_multiline_ustr
    • al_draw_multiline_textf
    • al_do_multiline_text
    • al_do_multiline_ustr
  • Bitmap fonts
    • al_grab_font_from_bitmap
    • al_load_bitmap_font
    • al_load_bitmap_font_flags
    • al_create_builtin_font
  • TTF fonts
    • al_init_ttf_addon
    • al_shutdown_ttf_addon
    • al_load_ttf_font
    • al_load_ttf_font_f
    • al_load_ttf_font_stretch
    • al_load_ttf_font_stretch_f
    • al_get_allegro_ttf_version
    • al_get_glyph

These functions are declared in the following header file. Link with allegro_font.

 #include <allegro5/allegro_font.h>

General font routines

ALLEGRO_FONT

typedef struct ALLEGRO_FONT ALLEGRO_FONT;

Source Code

A handle identifying any kind of font. Usually you will create it with al_load_font which supports loading all kinds of TrueType fonts supported by the FreeType library. If you instead pass the filename of a bitmap file, it will be loaded with al_load_bitmap and a font in Allegro's bitmap font format will be created from it with al_grab_font_from_bitmap.

ALLEGRO_GLYPH

typedef struct ALLEGRO_GLYPH ALLEGRO_GLYPH;

Source Code

A structure containing the properties of a character in a font.

typedef struct ALLEGRO_GLYPH {
   ALLEGRO_BITMAP *bitmap;   // the bitmap the character is on
   int x;                    // the x position of the glyph on bitmap
   int y;                    // the y position of the glyph on bitmap
   int w;                    // the width of the glyph in pixels
   int h;                    // the height of the glyph in pixels
   int kerning;              // pixels of kerning (see below)
   int offset_x;             // x offset to draw the glyph at
   int offset_y;             // y offset to draw the glyph at
   int advance;              // number of pixels to advance after this character
} ALLEGRO_GLYPH;

bitmap may be a sub-bitmap in the case of color fonts.

kerning should be added to the x position you draw to if you want your text kerned and depends on which codepoints al_get_glyph was called with.

Glyphs are tightly packed onto the bitmap, so you need to add offset_x and offset_y to your draw position for the text to look right.

advance is the number of pixels to add to your x position to advance to the next character in a string and includes kerning.

Since: 5.2.1

Unstable API: This API is new and subject to refinement.

See also: al_get_glyph

al_init_font_addon

bool al_init_font_addon(void)

Source Code

Initialise the font addon.

Note that if you intend to load bitmap fonts, you will need to initialise allegro_image separately (unless you are using another library to load images).

Similarly, if you wish to load truetype-fonts, do not forget to also call al_init_ttf_addon.

Returns true on success, false on failure. On the 5.0 branch, this function has no return value. You may wish to avoid checking the return value if your code needs to be compatible with Allegro 5.0. Currently, the function will never return false.

See also: al_init_image_addon, al_init_ttf_addon, al_shutdown_font_addon

al_shutdown_font_addon

void al_shutdown_font_addon(void)

Source Code

Shut down the font addon. This is done automatically at program exit, but can be called any time the user wishes as well.

See also: al_init_font_addon

al_load_font

ALLEGRO_FONT *al_load_font(char const *filename, int size, int flags)

Source Code

Loads a font from disk. This will use al_load_bitmap_font_flags if you pass the name of a known bitmap format, or else al_load_ttf_font.

The flags parameter is passed through to either of those functions. Bitmap and TTF fonts are also affected by the current bitmap flags at the time the font is loaded.

See also: al_destroy_font, al_init_font_addon, al_register_font_loader, al_load_bitmap_font_flags, al_load_ttf_font

al_destroy_font

void al_destroy_font(ALLEGRO_FONT *f)

Source Code

Frees the memory being used by a font structure. Does nothing if passed NULL.

See also: al_load_font

al_register_font_loader

bool al_register_font_loader(char const *extension,
   ALLEGRO_FONT *(*load_font)(char const *filename, int size, int flags))

Source Code

Informs Allegro of a new font file type, telling it how to load files of this format.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The load_font argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_init_font_addon

al_get_font_line_height

int al_get_font_line_height(const ALLEGRO_FONT *f)

Source Code

Returns the usual height of a line of text in the specified font. For bitmap fonts this is simply the height of all glyph bitmaps. For truetype fonts it is whatever the font file specifies. In particular, some special glyphs may be higher than the height returned here.

If the X is the position you specify to draw text, the meaning of ascent and descent and the line height is like in the figure below.

X------------------------
    /\         |        |
   /  \        |        |
  /____\       ascent   |
 /      \      |        |
/        \     |        height
----------------        |
               |        |
               descent  |
               |        |
-------------------------

See also: al_get_text_width, al_get_text_dimensions

al_get_font_ascent

int al_get_font_ascent(const ALLEGRO_FONT *f)

Source Code

Returns the ascent of the specified font.

See also: al_get_font_descent, al_get_font_line_height

al_get_font_descent

int al_get_font_descent(const ALLEGRO_FONT *f)

Source Code

Returns the descent of the specified font.

See also: al_get_font_ascent, al_get_font_line_height

al_get_text_width

int al_get_text_width(const ALLEGRO_FONT *f, const char *str)

Source Code

Calculates the length of a string in a particular font, in pixels.

See also: al_get_ustr_width, al_get_font_line_height, al_get_text_dimensions

al_get_ustr_width

int al_get_ustr_width(const ALLEGRO_FONT *f, ALLEGRO_USTR const *ustr)

Source Code

Like al_get_text_width but expects an ALLEGRO_USTR.

See also: al_get_text_width, al_get_ustr_dimensions

al_draw_text

void al_draw_text(const ALLEGRO_FONT *font,
   ALLEGRO_COLOR color, float x, float y, int flags,
   char const *text)

Source Code

Writes the NUL-terminated string text onto the target bitmap at position x, y, using the specified font.

The flags parameter can be 0 or one of the following flags:

  • ALLEGRO_ALIGN_LEFT - Draw the text left-aligned (same as 0).
  • ALLEGRO_ALIGN_CENTRE - Draw the text centered around the given position.
  • ALLEGRO_ALIGN_RIGHT - Draw the text right-aligned to the given position.

It can also be combined with this flag:

  • ALLEGRO_ALIGN_INTEGER - Always draw text aligned to an integer pixel position. This was formerly the default behaviour. Since: 5.0.8, 5.1.4

This function does not support newline characters (\n), but you can use al_draw_multiline_text for multi line text output.

See also: al_draw_ustr, al_draw_textf, al_draw_justified_text, al_draw_multiline_text.

al_draw_ustr

void al_draw_ustr(const ALLEGRO_FONT *font,
   ALLEGRO_COLOR color, float x, float y, int flags,
   const ALLEGRO_USTR *ustr)

Source Code

Like al_draw_text, except the text is passed as an ALLEGRO_USTR instead of a NUL-terminated char array.

See also: al_draw_text, al_draw_justified_ustr, al_draw_multiline_ustr

al_draw_justified_text

void al_draw_justified_text(const ALLEGRO_FONT *font,
   ALLEGRO_COLOR color, float x1, float x2,
   float y, float diff, int flags, const char *text)

Source Code

Like al_draw_text, but justifies the string to the region x1-x2.

The diff parameter is the maximum amount of horizontal space to allow between words. If justisfying the text would exceed diff pixels, or the string contains less than two words, then the string will be drawn left aligned.

The flags parameter can be 0 or one of the following flags:

  • ALLEGRO_ALIGN_INTEGER - Draw text aligned to integer pixel positions. Since: 5.0.8, 5.1.5

See also: al_draw_justified_textf, al_draw_justified_ustr

al_draw_justified_ustr

void al_draw_justified_ustr(const ALLEGRO_FONT *font,
   ALLEGRO_COLOR color, float x1, float x2,
   float y, float diff, int flags, const ALLEGRO_USTR *ustr)

Source Code

Like al_draw_justified_text, except the text is passed as an ALLEGRO_USTR instead of a NUL-terminated char array.

See also: al_draw_justified_text, al_draw_justified_textf.

al_draw_textf

void al_draw_textf(const ALLEGRO_FONT *font, ALLEGRO_COLOR color,
   float x, float y, int flags,
   const char *format, ...)

Source Code

Formatted text output, using a printf() style format string. All parameters have the same meaning as with al_draw_text otherwise.

See also: al_draw_text, al_draw_ustr

al_draw_justified_textf

void al_draw_justified_textf(const ALLEGRO_FONT *f,
   ALLEGRO_COLOR color, float x1, float x2, float y,
   float diff, int flags, const char *format, ...)

Source Code

Formatted text output, using a printf() style format string. All parameters have the same meaning as with al_draw_justified_text otherwise.

See also: al_draw_justified_text, al_draw_justified_ustr.

al_get_text_dimensions

void al_get_text_dimensions(const ALLEGRO_FONT *f,
   char const *text,
   int *bbx, int *bby, int *bbw, int *bbh)

Source Code

Sometimes, the al_get_text_width and al_get_font_line_height functions are not enough for exact text placement, so this function returns some additional information.

Returned variables (all in pixels):

  • x, y - Offset to upper left corner of bounding box.
  • w, h - Dimensions of bounding box.

Note that glyphs may go to the left and upwards of the X, in which case x and y will have negative values.

See also: al_get_text_width, al_get_font_line_height, al_get_ustr_dimensions

al_get_ustr_dimensions

void al_get_ustr_dimensions(const ALLEGRO_FONT *f,
   ALLEGRO_USTR const *ustr,
   int *bbx, int *bby, int *bbw, int *bbh)

Source Code

Like al_get_text_dimensions, except the text is passed as an ALLEGRO_USTR instead of a NUL-terminated char array.

See also: al_get_text_dimensions

al_get_allegro_font_version

uint32_t al_get_allegro_font_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

al_get_font_ranges

int al_get_font_ranges(ALLEGRO_FONT *f, int ranges_count, int *ranges)

Source Code

Gets information about all glyphs contained in a font, as a list of ranges. Ranges have the same format as with al_grab_font_from_bitmap.

ranges_count is the maximum number of ranges that will be returned.

ranges should be an array with room for ranges_count * 2 elements. The even integers are the first unicode point in a range, the odd integers the last unicode point in a range.

Returns the number of ranges contained in the font (even if it is bigger than ranges_count).

Since: 5.1.4

See also: al_grab_font_from_bitmap

al_set_fallback_font

void al_set_fallback_font(ALLEGRO_FONT *font, ALLEGRO_FONT *fallback)

Source Code

Sets a font which is used instead if a character is not present. Can be chained, but make sure there is no loop as that would crash the application! Pass NULL to remove a fallback font again.

Since: 5.1.12

See also: al_get_fallback_font, al_draw_glyph, al_draw_text

al_get_fallback_font

ALLEGRO_FONT *al_get_fallback_font(ALLEGRO_FONT *font)

Source Code

Retrieves the fallback font for this font or NULL.

Since: 5.1.12

See also: al_set_fallback_font

Per glyph text handling

For some applications Allegro's text drawing functions may not be sufficient. For example, you would like to give a different color to every letter in a word, or use different a font for a drop cap.

That is why Allegro supports drawing and getting the dimensions of the individual glyphs of a font. A glyph is a particular visual representation of a letter, character or symbol in a specific font.

And it's also possible to get the kerning to use between two glyphs. These per glyph functions have less overhead than Allegro's per string text drawing and dimensioning functions. So, with these functions you can write your own efficient and precise custom text drawing functions.

al_draw_glyph

void al_draw_glyph(const ALLEGRO_FONT *f, ALLEGRO_COLOR color, float x, float y,
   int codepoint)

Source Code

Draws the glyph that corresponds with codepoint in the given color using the given font. If font does not have such a glyph, nothing will be drawn.

To draw a string as left to right horizontal text you will need to use al_get_glyph_advance to determine the position of each glyph. For drawing strings in other directions, such as top to down, use al_get_glyph_dimensions to determine the size and position of each glyph.

If you have to draw many glyphs at the same time, use al_hold_bitmap_drawing with true as the parameter, before drawing the glyphs, and then call al_hold_bitmap_drawing again with false as a parameter when done drawing the glyphs to further enhance performance.

Since: 5.1.12

See also: al_get_glyph_width, al_get_glyph_dimensions, al_get_glyph_advance.

al_get_glyph_width

int al_get_glyph_width(const ALLEGRO_FONT *f, int codepoint)

Source Code

This function returns the width in pixels of the glyph that corresponds with codepoint in the font font. Returns zero if the font does not have such a glyph.

Since: 5.1.12

See also: al_draw_glyph, al_get_glyph_dimensions, al_get_glyph_advance.

al_get_glyph_dimensions

bool al_get_glyph_dimensions(const ALLEGRO_FONT *f,
   int codepoint, int *bbx, int *bby, int *bbw, int *bbh)

Source Code

Sometimes, the al_get_glyph_width or al_get_glyph_advance functions are not enough for exact glyph placement, so this function returns some additional information, particularly if you want to draw the font vertically.

The function itself returns true if the character was present in font and false if the character was not present in font.

Returned variables (all in pixel):

  • bbx, bby - Offset to upper left corner of bounding box.
  • bbw, bbh - Dimensions of bounding box.

These values are the same as al_get_text_dimensions would return for a string of a single character equal to the glyph passed to this function. Note that glyphs may go to the left and upwards of the X, in which case x and y will have negative values.

If you want to draw a string verticallly, for Japanese or as a game effect, then you should leave bby + bbh space between the glyphs in the y direction for a regular placement.

If you want to draw a string horizontally in an extra compact way,
then you should leave bbx + bbw space between the glyphs in the x direction for a compact placement.

In the figure below is an example of what bbx and bby may be like for a 2 glyph, and a g glyph of the same font compared to the result of al_get_glyph_width().

   al_get_glyph_width()     al_get_glyph_width()
          __|___                   __|__
         /      \                 /     \
     bbx    bbw                 bbx   bbw
    <-->+<------>+           <-->+<----->+   X baseline
    ^   |        |           ^   |       |
bby |   |        |       bby |   |       |
    v   |        |           |   |       |
    +---+--------+           |   |       |
    ^   | *****  |           |   |       |
    |   |*    ** |           v   |       |
bbh |   |    **  |       bbh +---+-------+
    |   |  **    |           ^   | ***** |
    v   |********|           |   |*     *|
    +---+--------+           |   | ***** |
                             |   |      *|
                             |   | *    *|
                             v   |  **** |
                             +---+-------+

Since: 5.1.12

See also: al_draw_glyph, al_get_glyph_width, al_get_glyph_advance.

al_get_glyph_advance

int al_get_glyph_advance(const ALLEGRO_FONT *f, int codepoint1, int codepoint2)

Source Code

This function returns by how much the x position should be advanced for left to right text drawing when the glyph that corresponds to codepoint1 has been drawn, and the glyph that corresponds to codepoint2 will be the next to be drawn. This takes into consideration the horizontal advance width of the glyph that corresponds with codepoint1 as well as the kerning between the glyphs of codepoint1 and codepoint2.

Kerning is the process of adjusting the spacing between glyphs in a font, to obtain a more visually pleasing result. Kerning adjusts the space between two individual glyphs with an offset determined by the author of the font.

If you pass ALLEGRO_NO_KERNING as codepoint1 then al_get_glyph_advance will return 0. this can be useful when drawing the first character of a string in a loop.

Pass ALLEGRO_NO_KERNING as codepoint2 to get the horizontal advance width of the glyph that corresponds to codepoint1 without taking any kerning into consideration. This can be used, for example, when drawing the last character of a string in a loop.

This function will return zero if the glyph of codepoint1 is not present in the font. If the glyph of codepoint2 is not present in the font, the horizontal advance width of the glyph that corresponds to codepoint1 without taking any kerning into consideration is returned.

When drawing a string one glyph at the time from the left to the right with kerning, the x position of the glyph should be incremented by the result of al_get_glyph_advance applied to the previous glyph drawn and the next glyph to draw.

Note that the return value of this function is a recommended advance for optimal readability for left to right text determined by the author of the font. However, if you like, you may want to draw the glyphs of the font narrower or wider to each other than what al_get_glyph_advance returns for style or effect.

In the figure below is an example of what the result of al_get_glyph_advance may be like for two glypphs A and l of the same font that has kerning for the "Al" pair, without and with the ALLEGRO_NO_KERNING flag.

al_get_glyph_advance(font, 'A', 'l')
     ___|___
    /       \
    -------------
        /\   -|
       /  \   |
      /____\  |
     /      \ |
    /        \ \_
    -------------

al_get_glyph_advance(font, 'A', ALLEGRO_NO_KERNING)
     ____|____
    /         \
    ---------------
        /\     -|
       /  \     |
      /____\    |
     /      \   |
    /        \   \_
    ---------------

Since: 5.1.12

See also: al_draw_glyph, al_get_glyph_width, al_get_glyph_dimensions.

Multiline text drawing

al_draw_multiline_text

void al_draw_multiline_text(const ALLEGRO_FONT *font,
     ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,
     int flags, const char *text)

Source Code

Like al_draw_text, but this function supports drawing multiple lines of text. It will break text in lines based on its contents and the max_width parameter. The lines are then layed out vertically depending on the line_height parameter and drawn each as if al_draw_text was called on them.

A newline \n in the text will cause a "hard" line break after its occurrence in the string. The text after a hard break is placed on a new line. Carriage return \r is not supported, will not cause a line break, and will likely be drawn as a square or a space depending on the font.

The max_width parameter controls the maximum desired width of the lines. This function will try to introduce a "soft" line break after the longest possible series of words that will fit in max_length when drawn with the given font. A "soft" line break can occur either on a space or tab (\t) character.

However, it is possible that max_width is too small, or the words in text are too long to fit max_width when drawn with font. In that case, the word that is too wide will simply be drawn completely on a line by itself. If you don't want the text that overflows max_width to be visible, then use al_set_clipping_rectangle to clip it off and hide it.

The lines text was split into will each be drawn using the font, x, color and flags parameters, vertically starting at y and with a distance of line_height between them. If line_height is zero (0), the value returned by calling al_get_font_line_height on font will be used as a default instead.

The flags ALLEGRO_ALIGN_LEFT, ALLEGRO_ALIGN_CENTRE, ALLEGRO_ALIGN_RIGHT and ALLEGRO_ALIGN_INTEGER will be honoured by this function.

If you want to calculate the size of what this function will draw without actually drawing it, or if you need a complex and/or custom layout, you can use al_do_multiline_text.

Since: 5.1.9

See also: al_do_multiline_text, al_draw_multiline_text, al_draw_multiline_textf

al_draw_multiline_ustr

void al_draw_multiline_ustr(const ALLEGRO_FONT *font,
     ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,
     int flags, const ALLEGRO_USTR *ustr)

Source Code

Like al_draw_multiline_text, except the text is passed as an ALLEGRO_USTR instead of a NUL-terminated char array.

Since: 5.1.9

See also: al_draw_multiline_text, al_draw_multiline_textf, al_do_multiline_text

al_draw_multiline_textf

void al_draw_multiline_textf(const ALLEGRO_FONT *font,
     ALLEGRO_COLOR color, float x, float y, float max_width, float line_height,
     int flags, const char *format, ...)

Source Code

Formatted text output, using a printf() style format string. All parameters have the same meaning as with al_draw_multiline_text otherwise.

Since: 5.1.9

See also: al_draw_multiline_text, al_draw_multiline_ustr, al_do_multiline_text

al_do_multiline_text

void al_do_multiline_text(const ALLEGRO_FONT *font,
   float max_width, const char *text,
   bool (*cb)(int line_num, const char *line, int size, void *extra),
   void *extra)

Source Code

This function processes the text and splits it into lines as al_draw_multiline_text would, and then calls the callback cb once for every line. This is useful for custom drawing of multiline text, or for calculating the size of multiline text ahead of time. See the documentation on al_draw_multiline_text for an explanation of the splitting algorithm.

For every line that this function splits text into the callback cb will be called once with the following parameters:

  • line_num - the number of the line starting from zero and counting up
  • line - a pointer to the beginning character of the line (see below)
  • size - the size of the line (0 for empty lines)
  • extra - the same pointer that was passed to al_do_multiline_text

Note that line is not guaranteed to be a NUL-terminated string, but will merely point to a character within text or to an empty string in case of an empty line. If you need a NUL-terminated string, you will have to copy line to a buffer and NUL-terminate it yourself. You will also have to make your own copy if you need the contents of line after cb has returned, as line is not guaranteed to be valid after that.

If the callback cb returns false, al_do_multiline_text will stop immediately, otherwise it will continue on to the next line.

Since: 5.1.9

See also: al_draw_multiline_text

al_do_multiline_ustr

void al_do_multiline_ustr(const ALLEGRO_FONT *font, float max_width,
   const ALLEGRO_USTR *ustr,
   bool (*cb)(int line_num, const ALLEGRO_USTR * line, void *extra),
   void *extra)

Source Code

Like al_do_multiline_text, but using ALLEGRO_USTR instead of a NUL-terminated char array for text.

Since: 5.1.9

See also: al_draw_multiline_ustr

Bitmap fonts

al_grab_font_from_bitmap

ALLEGRO_FONT *al_grab_font_from_bitmap(ALLEGRO_BITMAP *bmp,
   int ranges_n, const int ranges[])

Source Code

Creates a new font from an Allegro bitmap. You can delete the bitmap after the function returns as the font will contain a copy for itself.

Parameters:

  • bmp: The bitmap with the glyphs drawn onto it
  • n: Number of unicode ranges in the bitmap.
  • ranges: 'n' pairs of first and last unicode point to map glyphs to for each range.

The bitmap format is as in the following example, which contains three glyphs for 1, 2 and 3.

.............
. 1 .222.333.
. 1 .  2.  3.
. 1 .222.333.
. 1 .2  .  3.
. 1 .222.333.
.............

In the above illustration, the dot is for pixels having the background color. It is determined by the color of the top left pixel in the bitmap. There should be a border of at least 1 pixel with this color to the bitmap edge and between all glyphs.

Each glyph is inside a rectangle of pixels not containing the background color. The height of all glyph rectangles should be the same, but the width can vary.

The placement of the rectangles does not matter, except that glyphs are scanned from left to right and top to bottom to match them to the specified unicode codepoints.

The glyphs will simply be drawn using al_draw_bitmap, so usually you will want the rectangles filled with full transparency and the glyphs drawn in opaque white.

Examples:

int ranges[] = {32, 126};
al_grab_font_from_bitmap(bitmap, 1, ranges)

int ranges[] = {
    0x0020, 0x007F,  /* ASCII */
    0x00A1, 0x00FF,  /* Latin 1 */
    0x0100, 0x017F,  /* Extended-A */
    0x20AC, 0x20AC}; /* Euro */
al_grab_font_from_bitmap(bitmap, 4, ranges)

The first example will grab glyphs for the 95 standard printable ASCII characters, beginning with the space character (32) and ending with the tilde character (126). The second example will map the first 96 glyphs found in the bitmap to ASCII range, the next 95 glyphs to Latin 1, the next 128 glyphs to Extended-A, and the last glyph to the Euro character. (This is just the characters found in the Allegro 4 font.)

See also: al_load_bitmap, al_grab_font_from_bitmap

al_load_bitmap_font

ALLEGRO_FONT *al_load_bitmap_font(const char *fname)

Source Code

Load a bitmap font from a file. This is done by first calling al_load_bitmap_flags and then al_grab_font_from_bitmap.

If you wanted to load an old A4 font, for example, it would be better to load the bitmap yourself in order to call al_convert_mask_to_alpha on it before passing it to al_grab_font_from_bitmap.

See also: al_load_bitmap_font_flags, al_load_font, al_load_bitmap_flags

al_load_bitmap_font_flags

ALLEGRO_FONT *al_load_bitmap_font_flags(const char *fname, int flags)

Source Code

Like al_load_bitmap_font but additionally takes a flags parameter which is a bitfield containing a combination of the following:

ALLEGRO_NO_PREMULTIPLIED_ALPHA
The same meaning as for al_load_bitmap_flags.

See also: al_load_bitmap_font, al_load_bitmap_flags

al_create_builtin_font

ALLEGRO_FONT *al_create_builtin_font(void)

Source Code

Creates a monochrome bitmap font (8x8 pixels per character).

This font is primarily intended to be used for displaying information in environments or during early runtime states where no external font data is available or loaded (e.g. for debugging).

The builtin font contains the following unicode character ranges:

0x0020 to 0x007F (ASCII)
0x00A1 to 0x00FF (Latin 1)
0x0100 to 0x017F (Extended A)
0x20AC to 0x20AC (euro currency symbol)

Returns NULL on an error.

The font memory must be freed the same way as for any other font, using al_destroy_font.

Since: 5.0.8, 5.1.3

See also: al_load_bitmap_font, al_destroy_font

TTF fonts

These functions are declared in the following header file. Link with allegro_ttf.

 #include <allegro5/allegro_ttf.h>

al_init_ttf_addon

bool al_init_ttf_addon(void)

Source Code

Call this after al_init_font_addon to make al_load_font recognize ".ttf" and other formats supported by al_load_ttf_font.

Returns true on success, false on failure.

al_shutdown_ttf_addon

void al_shutdown_ttf_addon(void)

Source Code

Unloads the ttf addon again. You normally don't need to call this.

al_load_ttf_font

ALLEGRO_FONT *al_load_ttf_font(char const *filename, int size, int flags)

Source Code

Loads a TrueType font from a file using the FreeType library. Quoting from the FreeType FAQ this means support for many different font formats:

TrueType, OpenType, Type1, CID, CFF, Windows FON/FNT, X11 PCF, and others

The size parameter determines the size the font will be rendered at, specified in pixels. The standard font size is measured in units per EM, if you instead want to specify the size as the total height of glyphs in pixels, pass it as a negative value.

Note: If you want to display text at multiple sizes, load the font multiple times with different size parameters.

The following flags are supported:

  • ALLEGRO_TTF_NO_KERNING - Do not use any kerning even if the font file supports it.

  • ALLEGRO_TTF_MONOCHROME - Load as a monochrome font (which means no anti-aliasing of the font is done).

  • ALLEGRO_TTF_NO_AUTOHINT - Disable the Auto Hinter which is enabled by default in newer versions of FreeType. Since: 5.0.6, 5.1.2

See also: al_init_ttf_addon, al_load_ttf_font_f

al_load_ttf_font_f

ALLEGRO_FONT *al_load_ttf_font_f(ALLEGRO_FILE *file,
    char const *filename, int size, int flags)

Source Code

Like al_load_ttf_font, but the font is read from the file handle. The filename is only used to find possible additional files next to a font file.

Note: The file handle is owned by the returned ALLEGRO_FONT object and must not be freed by the caller, as FreeType expects to be able to read from it at a later time.

al_load_ttf_font_stretch

ALLEGRO_FONT *al_load_ttf_font_stretch(char const *filename, int w, int h,
   int flags)

Source Code

Like al_load_ttf_font, except it takes separate width and height parameters instead of a single size parameter.

If the height is a positive value, and the width zero or positive, then font will be stretched according to those parameters. The width must not be negative if the height is positive.

As with al_load_ttf_font, the height may be a negative value to specify the total height in pixels. Then the width must also be a negative value, or zero.

Returns NULL if the height is positive while width is negative, or if the height is negative while the width is positive.

Since: 5.0.6, 5.1.0

See also: al_load_ttf_font, al_load_ttf_font_stretch_f

al_load_ttf_font_stretch_f

ALLEGRO_FONT *al_load_ttf_font_stretch_f(ALLEGRO_FILE *file,
    char const *filename, int w, int h, int flags)

Source Code

Like al_load_ttf_font_stretch, but the font is read from the file handle. The filename is only used to find possible additional files next to a font file.

Note: The file handle is owned by the returned ALLEGRO_FONT object and must not be freed by the caller, as FreeType expects to be able to read from it at a later time.

Since: 5.0.6, 5.1.0

See also: al_load_ttf_font_stretch

al_get_allegro_ttf_version

uint32_t al_get_allegro_ttf_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

al_get_glyph

bool al_get_glyph(const ALLEGRO_FONT *f, int prev_codepoint, int codepoint, ALLEGRO_GLYPH *glyph)

Source Code

Gets all the information about a glyph, including the bitmap, needed to draw it yourself. prev_codepoint is the codepoint in the string before the one you want to draw and is used for kerning. codepoint is the character you want to get info about. You should clear the 'glyph' structure to 0 with memset before passing it to this function for future compatibility.

Since: 5.2.1

Unstable API: This API is new and subject to refinement.

See also: ALLEGRO_GLYPH

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:18 UTC


File system routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

File system routines

  • ALLEGRO_FS_ENTRY
  • ALLEGRO_FILE_MODE
  • al_create_fs_entry
  • al_destroy_fs_entry
  • al_get_fs_entry_name
  • al_update_fs_entry
  • al_get_fs_entry_mode
  • al_get_fs_entry_atime
  • al_get_fs_entry_ctime
  • al_get_fs_entry_mtime
  • al_get_fs_entry_size
  • al_fs_entry_exists
  • al_remove_fs_entry
  • al_filename_exists
  • al_remove_filename
  • Directory functions
    • al_open_directory
    • al_read_directory
    • al_close_directory
    • al_get_current_directory
    • al_change_directory
    • al_make_directory
    • al_open_fs_entry
    • ALLEGRO_FOR_EACH_FS_ENTRY_RESULT
    • al_for_each_fs_entry
  • Alternative filesystem functions
    • ALLEGRO_FS_INTERFACE
    • al_set_fs_interface
    • al_set_standard_fs_interface
    • al_get_fs_interface

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

These functions allow access to the filesystem. This can either be the real filesystem like your harddrive, or a virtual filesystem like a .zip archive (or whatever else you or an addon makes it do).

ALLEGRO_FS_ENTRY

typedef struct ALLEGRO_FS_ENTRY ALLEGRO_FS_ENTRY;

Source Code

Opaque filesystem entry object. Represents a file or a directory (check with al_get_fs_entry_mode). There are no user accessible member variables.

ALLEGRO_FILE_MODE

typedef enum ALLEGRO_FILE_MODE

Source Code

Filesystem modes/types

  • ALLEGRO_FILEMODE_READ - Readable
  • ALLEGRO_FILEMODE_WRITE - Writable
  • ALLEGRO_FILEMODE_EXECUTE - Executable
  • ALLEGRO_FILEMODE_HIDDEN - Hidden
  • ALLEGRO_FILEMODE_ISFILE - Regular file
  • ALLEGRO_FILEMODE_ISDIR - Directory

al_create_fs_entry

ALLEGRO_FS_ENTRY *al_create_fs_entry(const char *path)

Source Code

Creates an ALLEGRO_FS_ENTRY object pointing to path on the filesystem. 'path' can be a file or a directory and must not be NULL.

al_destroy_fs_entry

void al_destroy_fs_entry(ALLEGRO_FS_ENTRY *fh)

Source Code

Destroys a fs entry handle. The file or directory represented by it is not destroyed. If the entry was opened, it is closed before being destroyed.

Does nothing if passed NULL.

al_get_fs_entry_name

const char *al_get_fs_entry_name(ALLEGRO_FS_ENTRY *e)

Source Code

Returns the entry's filename path. Note that the filesystem encoding may not be known and the conversion to UTF-8 could in very rare cases cause this to return an invalid path. Therefore it's always safest to access the file over its ALLEGRO_FS_ENTRY and not the path.

On success returns a read only string which you must not modify or destroy. Returns NULL on failure.

Note: prior to 5.1.5 it was written: "... the path will not be an absolute path if the entry wasn't created from an absolute path". This is no longer true.

al_update_fs_entry

bool al_update_fs_entry(ALLEGRO_FS_ENTRY *e)

Source Code

Updates file status information for a filesystem entry. File status information is automatically updated when the entry is created, however you may update it again with this function, e.g. in case it changed.

Returns true on success, false on failure. Fills in errno to indicate the error.

See also: al_get_errno, al_get_fs_entry_atime, al_get_fs_entry_ctime, al_get_fs_entry_mode

al_get_fs_entry_mode

uint32_t al_get_fs_entry_mode(ALLEGRO_FS_ENTRY *e)

Source Code

Returns the entry's mode flags, i.e. permissions and whether the entry refers to a file or directory.

See also: al_get_errno, ALLEGRO_FILE_MODE

al_get_fs_entry_atime

time_t al_get_fs_entry_atime(ALLEGRO_FS_ENTRY *e)

Source Code

Returns the time in seconds since the epoch since the entry was last accessed.

Warning: some filesystems either don't support this flag, or people turn it off to increase performance. It may not be valid in all circumstances.

See also: al_get_fs_entry_ctime, al_get_fs_entry_mtime, al_update_fs_entry

al_get_fs_entry_ctime

time_t al_get_fs_entry_ctime(ALLEGRO_FS_ENTRY *e)

Source Code

Returns the time in seconds since the epoch this entry was created on the filesystem.

See also: al_get_fs_entry_atime, al_get_fs_entry_mtime, al_update_fs_entry

al_get_fs_entry_mtime

time_t al_get_fs_entry_mtime(ALLEGRO_FS_ENTRY *e)

Source Code

Returns the time in seconds since the epoch since the entry was last modified.

See also: al_get_fs_entry_atime, al_get_fs_entry_ctime, al_update_fs_entry

al_get_fs_entry_size

off_t al_get_fs_entry_size(ALLEGRO_FS_ENTRY *e)

Source Code

Returns the size, in bytes, of the given entry. May not return anything sensible for a directory entry.

See also: al_update_fs_entry

al_fs_entry_exists

bool al_fs_entry_exists(ALLEGRO_FS_ENTRY *e)

Source Code

Check if the given entry exists on in the filesystem. Returns true if it does exist or false if it doesn't exist, or an error occurred. Error is indicated in Allegro's errno.

See also: al_filename_exists

al_remove_fs_entry

bool al_remove_fs_entry(ALLEGRO_FS_ENTRY *e)

Source Code

Delete this filesystem entry from the filesystem. Only files and empty directories may be deleted.

Returns true on success, and false on failure, error is indicated in Allegro's errno.

See also: al_filename_exists

al_filename_exists

bool al_filename_exists(const char *path)

Source Code

Check if the path exists on the filesystem, without creating an ALLEGRO_FS_ENTRY object explicitly.

See also: al_fs_entry_exists

al_remove_filename

bool al_remove_filename(const char *path)

Source Code

Delete the given path from the filesystem, which may be a file or an empty directory. This is the same as al_remove_fs_entry, except it expects the path as a string.

Returns true on success, and false on failure. Allegro's errno is filled in to indicate the error.

See also: al_remove_fs_entry

Directory functions

al_open_directory

bool al_open_directory(ALLEGRO_FS_ENTRY *e)

Source Code

Opens a directory entry object. You must call this before using al_read_directory on an entry and you must call al_close_directory when you no longer need it.

Returns true on success.

See also: al_read_directory, al_close_directory

al_read_directory

ALLEGRO_FS_ENTRY *al_read_directory(ALLEGRO_FS_ENTRY *e)

Source Code

Reads the next directory item and returns a filesystem entry for it.

Returns NULL if there are no more entries or if an error occurs. Call al_destroy_fs_entry on the returned entry when you are done with it.

This function will ignore any files or directories named . or .. which may exist on certain platforms and may signify the current and the parent directory.

See also: al_open_directory, al_close_directory

al_close_directory

bool al_close_directory(ALLEGRO_FS_ENTRY *e)

Source Code

Closes a previously opened directory entry object.

Returns true on success, false on failure and fills in Allegro's errno to indicate the error.

See also: al_open_directory, al_read_directory

al_get_current_directory

char *al_get_current_directory(void)

Source Code

Returns the path to the current working directory, or NULL on failure. The returned path is dynamically allocated and must be destroyed with al_free.

Allegro's errno is filled in to indicate the error if there is a failure. This function may not be implemented on some (virtual) filesystems.

See also: al_get_errno, al_free

al_change_directory

bool al_change_directory(const char *path)

Source Code

Changes the current working directory to 'path'.

Returns true on success, false on error.

al_make_directory

bool al_make_directory(const char *path)

Source Code

Creates a new directory on the filesystem. This function also creates any parent directories as needed.

Returns true on success (including if the directory already exists), otherwise returns false on error. Fills in Allegro's errno to indicate the error.

See also: al_get_errno

al_open_fs_entry

ALLEGRO_FILE *al_open_fs_entry(ALLEGRO_FS_ENTRY *e, const char *mode)

Source Code

Open an ALLEGRO_FILE handle to a filesystem entry, for the given access mode. This is like calling al_fopen with the name of the filesystem entry, but uses the appropriate file interface, not whatever was set with the latest call to al_set_new_file_interface.

Returns the handle on success, NULL on error.

See also: al_fopen

ALLEGRO_FOR_EACH_FS_ENTRY_RESULT

typedef enum ALLEGRO_FOR_EACH_FS_ENTRY_RESULT {

Source Code

Return values for the callbacks of al_for_each_fs_entry and for that function itself.

  • ALLEGRO_FOR_EACH_FS_ENTRY_ERROR - An error ocurred.
  • ALLEGRO_FOR_EACH_FS_ENTRY_OK - Continue normally and recurse into directories.
  • ALLEGRO_FOR_EACH_FS_ENTRY_SKIP - Continue but do NOT recusively descend.
  • ALLEGRO_FOR_EACH_FS_ENTRY_STOP - Stop iterating and return.

See also: al_for_each_fs_entry

Since: 5.1.9

al_for_each_fs_entry

int al_for_each_fs_entry(ALLEGRO_FS_ENTRY *dir,
                         int (*callback)(ALLEGRO_FS_ENTRY *dir, void *extra),
                         void *extra)

Source Code

This function takes the ALLEGRO_FS_ENTRY dir, which should represent a directory, and looks for any other file system entries that are in it. This function will then call the callback function callback once for every filesystem entry in the directory dir.

The callback callback must be of type int callback(ALLEGRO_FS_ENTRY * entry, void * extra). The callback will be called with a pointer to an ALLEGRO_FS_ENTRY that matches one file or directory in dir, and the pointer passed in the extra parameter to al_for_each_fs_entry.

When callback returns ALLEGRO_FOR_EACH_FS_ENTRY_STOP or ALLEGRO_FOR_EACH_FS_ENTRY_ERROR, iteration will stop immediately and al_for_each_fs_entry will return the value the callback returned.

When callback returns ALLEGRO_FOR_EACH_FS_ENTRY_OK iteration will continue normally, and if the ALLEGRO_FS_ENTRY parameter of callback is a directory, al_for_each_fs_entry will call itself on that directory. Therefore the function will recusively descend into that directory.

However, when callback returns ALLEGRO_FOR_EACH_FS_ENTRY_SKIP iteration will continue, but al_for_each_fs_entry will NOT recurse into the ALLEGRO_FS_ENTRY parameter of callback even if it is a directory.

This function will skip any files or directories named . or .. which may exist on certain platforms and may signify the current and the parent directory. The callback will not be called for files or directories with such a name.

Returns ALLEGRO_FOR_EACH_FS_ENTRY_OK if successful, or ALLEGRO_FOR_EACH_FS_ENTRY_ERROR if something went wrong in processing the directory. In that case it will use al_set_errno to indicate the type of error which occurred. This function returns ALLEGRO_FOR_EACH_FS_ENTRY_STOP in case iteration was stopped by making callback return that value. In this case, al_set_errno will not be used.

See also: ALLEGRO_FOR_EACH_FS_ENTRY_RESULT

Since: 5.1.9

Alternative filesystem functions

By default, Allegro uses platform specific filesystem functions for things like directory access. However if for example the files of your game are not in the local filesystem but inside some file archive, you can provide your own set of functions (or use an addon which does this for you, for example our physfs addon allows access to the most common archive formats).

ALLEGRO_FS_INTERFACE

typedef struct ALLEGRO_FS_INTERFACE ALLEGRO_FS_INTERFACE;

Source Code

The available functions you can provide for a filesystem. They are:

   ALLEGRO_FS_ENTRY *  fs_create_entry   (const char *path);
   void                fs_destroy_entry  (ALLEGRO_FS_ENTRY *e);
   const char *        fs_entry_name     (ALLEGRO_FS_ENTRY *e);
   bool                fs_update_entry   (ALLEGRO_FS_ENTRY *e);
   uint32_t            fs_entry_mode     (ALLEGRO_FS_ENTRY *e);
   time_t              fs_entry_atime    (ALLEGRO_FS_ENTRY *e);
   time_t              fs_entry_mtime    (ALLEGRO_FS_ENTRY *e);
   time_t              fs_entry_ctime    (ALLEGRO_FS_ENTRY *e);
   off_t               fs_entry_size     (ALLEGRO_FS_ENTRY *e);
   bool                fs_entry_exists   (ALLEGRO_FS_ENTRY *e);
   bool                fs_remove_entry   (ALLEGRO_FS_ENTRY *e);

   bool                fs_open_directory (ALLEGRO_FS_ENTRY *e);
   ALLEGRO_FS_ENTRY *  fs_read_directory (ALLEGRO_FS_ENTRY *e);
   bool                fs_close_directory(ALLEGRO_FS_ENTRY *e);

   bool                fs_filename_exists(const char *path);
   bool                fs_remove_filename(const char *path);
   char *              fs_get_current_directory(void);
   bool                fs_change_directory(const char *path);
   bool                fs_make_directory(const char *path);

   ALLEGRO_FILE *      fs_open_file(ALLEGRO_FS_ENTRY *e);

al_set_fs_interface

void al_set_fs_interface(const ALLEGRO_FS_INTERFACE *fs_interface)

Source Code

Set the ALLEGRO_FS_INTERFACE table for the calling thread.

See also: al_set_standard_fs_interface, al_store_state, al_restore_state.

al_set_standard_fs_interface

void al_set_standard_fs_interface(void)

Source Code

Return the ALLEGRO_FS_INTERFACE table to the default, for the calling thread.

See also: al_set_fs_interface.

al_get_fs_interface

const ALLEGRO_FS_INTERFACE *al_get_fs_interface(void)

Source Code

Return a pointer to the ALLEGRO_FS_INTERFACE table in effect for the calling thread.

See also: al_store_state, al_restore_state.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:40 UTC


Fullscreen modes

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Fullscreen modes

  • ALLEGRO_DISPLAY_MODE
  • al_get_display_mode
  • al_get_num_display_modes

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_DISPLAY_MODE

typedef struct ALLEGRO_DISPLAY_MODE

Source Code

Used for fullscreen mode queries. Contains information about a supported fullscreen modes.

typedef struct ALLEGRO_DISPLAY_MODE {
   int width;          // Screen width
   int height;         // Screen height
   int format;         // The pixel format of the mode
   int refresh_rate;   // The refresh rate of the mode
} ALLEGRO_DISPLAY_MODE;

The refresh_rate may be zero if unknown.

For an explanation of what format means, see ALLEGRO_PIXEL_FORMAT.

See also: al_get_display_mode

al_get_display_mode

ALLEGRO_DISPLAY_MODE *al_get_display_mode(int index, ALLEGRO_DISPLAY_MODE *mode)

Source Code

Retrieves a fullscreen mode. Display parameters should not be changed between a call of al_get_num_display_modes and al_get_display_mode. index must be between 0 and the number returned from al_get_num_display_modes-1. mode must be an allocated ALLEGRO_DISPLAY_MODE structure. This function will return NULL on failure, and the mode parameter that was passed in on success.

See also: ALLEGRO_DISPLAY_MODE, al_get_num_display_modes

al_get_num_display_modes

int al_get_num_display_modes(void)

Source Code

Get the number of available fullscreen display modes for the current set of display parameters. This will use the values set with al_set_new_display_refresh_rate, and al_set_new_display_flags to find the number of modes that match. Settings the new display parameters to zero will give a list of all modes for the default driver.

See also: al_get_display_mode

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:40 UTC


Getting started guide

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Getting started guide

  • Introduction
  • Structure of the library and its addons
  • The main function
  • Initialisation
  • Opening a window
  • Display an image
  • Changing the drawing target
  • Event queues and input
  • Displaying some text
  • Drawing primitives
  • Blending
  • Sound
  • Unstable API
  • Not the end

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 -> allegro

The 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!

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:39 UTC


Graphics routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Graphics routines

  • Colors
    • ALLEGRO_COLOR
    • al_map_rgb
    • al_map_rgb_f
    • al_map_rgba
    • al_premul_rgba
    • al_map_rgba_f
    • al_premul_rgba_f
    • al_unmap_rgb
    • al_unmap_rgb_f
    • al_unmap_rgba
    • al_unmap_rgba_f
  • Locking and pixel formats
    • ALLEGRO_LOCKED_REGION
    • ALLEGRO_PIXEL_FORMAT
    • al_get_pixel_size
    • al_get_pixel_format_bits
    • al_get_pixel_block_size
    • al_get_pixel_block_width
    • al_get_pixel_block_height
    • al_lock_bitmap
    • al_lock_bitmap_region
    • al_unlock_bitmap
    • al_lock_bitmap_blocked
    • al_lock_bitmap_region_blocked
  • Bitmap creation
    • ALLEGRO_BITMAP
    • al_create_bitmap
    • al_create_sub_bitmap
    • al_clone_bitmap
    • al_convert_bitmap
    • al_convert_memory_bitmaps
    • al_destroy_bitmap
    • al_get_new_bitmap_flags
    • al_get_new_bitmap_format
    • al_set_new_bitmap_flags
    • al_add_new_bitmap_flag
    • al_set_new_bitmap_format
    • al_set_new_bitmap_depth
    • al_get_new_bitmap_depth
    • al_set_new_bitmap_samples
    • al_get_new_bitmap_samples
  • Bitmap properties
    • al_get_bitmap_flags
    • al_get_bitmap_format
    • al_get_bitmap_height
    • al_get_bitmap_width
    • al_get_bitmap_depth
    • al_get_bitmap_samples
    • al_get_pixel
    • al_is_bitmap_locked
    • al_is_compatible_bitmap
    • al_is_sub_bitmap
    • al_get_parent_bitmap
    • al_get_bitmap_x
    • al_get_bitmap_y
    • al_reparent_bitmap
  • Drawing operations
    • al_clear_to_color
    • al_clear_depth_buffer
    • al_draw_bitmap
    • al_draw_tinted_bitmap
    • al_draw_bitmap_region
    • al_draw_tinted_bitmap_region
    • al_draw_pixel
    • al_draw_rotated_bitmap
    • al_draw_tinted_rotated_bitmap
    • al_draw_scaled_rotated_bitmap
    • al_draw_tinted_scaled_rotated_bitmap
    • al_draw_tinted_scaled_rotated_bitmap_region
    • al_draw_scaled_bitmap
    • al_draw_tinted_scaled_bitmap
    • al_get_target_bitmap
    • al_put_pixel
    • al_put_blended_pixel
  • Target bitmap
    • al_set_target_bitmap
    • al_set_target_backbuffer
    • al_get_current_display
  • Blending modes
    • al_get_blender
    • al_get_separate_blender
    • al_get_blend_color
    • al_set_blender
    • al_set_separate_blender
    • al_set_blend_color
  • Clipping
    • al_get_clipping_rectangle
    • al_set_clipping_rectangle
    • al_reset_clipping_rectangle
  • Graphics utility functions
    • al_convert_mask_to_alpha
  • Deferred drawing
    • al_hold_bitmap_drawing
    • al_is_bitmap_drawing_held
  • Image I/O
    • al_register_bitmap_loader
    • al_register_bitmap_saver
    • al_register_bitmap_loader_f
    • al_register_bitmap_saver_f
    • al_load_bitmap
    • al_load_bitmap_flags
    • al_load_bitmap_f
    • al_load_bitmap_flags_f
    • al_save_bitmap
    • al_save_bitmap_f
    • al_register_bitmap_identifier
    • al_identify_bitmap
    • al_identify_bitmap_f
  • Render State
    • ALLEGRO_RENDER_STATE
    • ALLEGRO_RENDER_FUNCTION
    • ALLEGRO_WRITE_MASK_FLAGS
    • al_set_render_state
    • al_backup_dirty_bitmap
    • al_backup_dirty_bitmaps

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

Colors

ALLEGRO_COLOR

typedef struct ALLEGRO_COLOR ALLEGRO_COLOR;

Source Code

An ALLEGRO_COLOR structure describes a color in a device independent way. Use al_map_rgb et al. and al_unmap_rgb et al. to translate from and to various color representations.

al_map_rgb

ALLEGRO_COLOR al_map_rgb(
   unsigned char r, unsigned char g, unsigned char b)

Source Code

Convert r, g, b (ranging from 0-255) into an ALLEGRO_COLOR, using 255 for alpha.

See also: al_map_rgba, al_map_rgba_f, al_map_rgb_f

al_map_rgb_f

ALLEGRO_COLOR al_map_rgb_f(float r, float g, float b)

Source Code

Convert r, g, b, (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR, using 1.0f for alpha.

See also: al_map_rgba, al_map_rgb, al_map_rgba_f

al_map_rgba

ALLEGRO_COLOR al_map_rgba(
   unsigned char r, unsigned char g, unsigned char b, unsigned char a)

Source Code

Convert r, g, b, a (ranging from 0-255) into an ALLEGRO_COLOR.

See also: al_map_rgb, al_premul_rgba, al_map_rgb_f

al_premul_rgba

ALLEGRO_COLOR al_premul_rgba(
   unsigned char r, unsigned char g, unsigned char b, unsigned char a)

Source Code

This is a shortcut for al_map_rgba(r * a / 255, g * a / 255, b * a / 255, a).

By default Allegro uses pre-multiplied alpha for transparent blending of bitmaps and primitives (see al_load_bitmap_flags for a discussion of that feature). This means that if you want to tint a bitmap or primitive to be transparent you need to multiply the color components by the alpha components when you pass them to this function. For example:

int r = 255;
int g = 0;
int b = 0;
int a = 127;
ALLEGRO_COLOR c = al_premul_rgba(r, g, b, a);
/* Draw the bitmap tinted red and half-transparent. */
al_draw_tinted_bitmap(bmp, c, 0, 0, 0);

Since: 5.1.12

See also: al_map_rgba, al_premul_rgba_f

al_map_rgba_f

ALLEGRO_COLOR al_map_rgba_f(float r, float g, float b, float a)

Source Code

Convert r, g, b, a (ranging from 0.0f-1.0f) into an ALLEGRO_COLOR.

See also: al_map_rgba, al_premul_rgba_f, al_map_rgb_f

al_premul_rgba_f

ALLEGRO_COLOR al_premul_rgba_f(float r, float g, float b, float a)

Source Code

This is a shortcut for al_map_rgba_f(r * a, g * a, b * a, a).

By default Allegro uses pre-multiplied alpha for transparent blending of bitmaps and primitives (see al_load_bitmap_flags for a discussion of that feature). This means that if you want to tint a bitmap or primitive to be transparent you need to multiply the color components by the alpha components when you pass them to this function. For example:

float r = 1;
float g = 0;
float b = 0;
float a = 0.5;
ALLEGRO_COLOR c = al_premul_rgba_f(r, g, b, a);
/* Draw the bitmap tinted red and half-transparent. */
al_draw_tinted_bitmap(bmp, c, 0, 0, 0);

Since: 5.1.12

See also: al_map_rgba_f, al_premul_rgba

al_unmap_rgb

void al_unmap_rgb(ALLEGRO_COLOR color,
   unsigned char *r, unsigned char *g, unsigned char *b)

Source Code

Retrieves components of an ALLEGRO_COLOR, ignoring alpha. Components will range from 0-255.

See also: al_unmap_rgba, al_unmap_rgba_f, al_unmap_rgb_f

al_unmap_rgb_f

void al_unmap_rgb_f(ALLEGRO_COLOR color, float *r, float *g, float *b)

Source Code

Retrieves components of an ALLEGRO_COLOR, ignoring alpha. Components will range from 0.0f-1.0f.

See also: al_unmap_rgba, al_unmap_rgb, al_unmap_rgba_f

al_unmap_rgba

void al_unmap_rgba(ALLEGRO_COLOR color,
   unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a)

Source Code

Retrieves components of an ALLEGRO_COLOR. Components will range from 0-255.

See also: al_unmap_rgb, al_unmap_rgba_f, al_unmap_rgb_f

al_unmap_rgba_f

void al_unmap_rgba_f(ALLEGRO_COLOR color,
   float *r, float *g, float *b, float *a)

Source Code

Retrieves components of an ALLEGRO_COLOR. Components will range from 0.0f-1.0f.

See also: al_unmap_rgba, al_unmap_rgb, al_unmap_rgb_f

Locking and pixel formats

ALLEGRO_LOCKED_REGION

typedef struct ALLEGRO_LOCKED_REGION ALLEGRO_LOCKED_REGION;

Source Code

Users who wish to manually edit or read from a bitmap are required to lock it first. The ALLEGRO_LOCKED_REGION structure represents the locked region of the bitmap. This call will work with any bitmap, including memory bitmaps.

typedef struct ALLEGRO_LOCKED_REGION {
   void *data;
   int format;
   int pitch;
   int pixel_size;
} ALLEGRO_LOCKED_REGION;

  • data points to the leftmost pixel of the first row (row 0) of the locked region. For blocked formats, this points to the leftmost block of the first row of blocks.

  • format indicates the pixel format of the data.

  • pitch gives the size in bytes of a single row (also known as the stride). The pitch may be greater than width * pixel_size due to padding; this is not uncommon. It is also not uncommon for the pitch to be negative (the bitmap may be upside down). For blocked formats, 'row' refers to the row of blocks, not of pixels.

  • pixel_size is the number of bytes used to represent a single block of pixels for the pixel format of this locked region. For most formats (and historically, this used to be true for all formats), this is just the size of a single pixel, but for blocked pixel formats this value is different.

See also: al_lock_bitmap, al_lock_bitmap_region, al_unlock_bitmap, ALLEGRO_PIXEL_FORMAT

ALLEGRO_PIXEL_FORMAT

typedef enum ALLEGRO_PIXEL_FORMAT

Source Code

Pixel formats. Each pixel format specifies the exact size and bit layout of a pixel in memory. Components are specified from high bits to low bits, so for example a fully opaque red pixel in ARGB_8888 format is 0xFFFF0000.

Note:

The pixel format is independent of endianness. That is, in the above example you can always get the red component with

(pixel & 0x00ff0000) >> 16

But you can not rely on this code:

*(pixel + 2)

It will return the red component on little endian systems, but the green component on big endian systems.

Also note that Allegro's naming is different from OpenGL naming here, where a format of GL_RGBA8 merely defines the component order and the exact layout including endianness treatment is specified separately. Usually GL_RGBA8 will correspond to ALLEGRO_PIXEL_ABGR_8888 though on little endian systems, so care must be taken (note the reversal of RGBA <-> ABGR).

The only exception to this ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE which will always have the components as 4 bytes corresponding to red, green, blue and alpha, in this order, independent of the endianness.

Some of the pixel formats represent compressed bitmap formats. Compressed bitmaps take up less space in the GPU memory than bitmaps with regular (uncompressed) pixel formats. This smaller footprint means that you can load more resources into GPU memory, and they will be drawn somewhat faster. The compression is lossy, however, so it is not appropriate for all graphical styles: it tends to work best for images with smooth color gradations. It is possible to compress bitmaps at runtime by passing the appropriate bitmap format in al_set_new_bitmap_format and then creating, loading, cloning or converting a non-compressed bitmap. This, however, is not recommended as the compression quality differs between different GPU drivers. It is recommended to compress these bitmaps ahead of time using external tools and then load them compressed.

Unlike regular pixel formats, compressed pixel formats are not laid out in memory one pixel row at a time. Instead, the bitmap is subdivided into rectangular blocks of pixels that are then laid out in block rows. This means that regular locking functions cannot use compressed pixel formats as the destination format. Instead, you can use the blocked versions of the bitmap locking functions which do support these formats.

It is not recommended to use compressed bitmaps as target bitmaps, as that operation cannot be hardware accelerated. Due to proprietary algorithms used, it is typically impossible to create compressed memory bitmaps.

  • ALLEGRO_PIXEL_FORMAT_ANY - Let the driver choose a format. This is the default format at program start.
  • ALLEGRO_PIXEL_FORMAT_ANY_NO_ALPHA - Let the driver choose a format without alpha.
  • ALLEGRO_PIXEL_FORMAT_ANY_WITH_ALPHA - Let the driver choose a format with alpha.
  • ALLEGRO_PIXEL_FORMAT_ANY_15_NO_ALPHA - Let the driver choose a 15 bit format without alpha.
  • ALLEGRO_PIXEL_FORMAT_ANY_16_NO_ALPHA - Let the driver choose a 16 bit format without alpha.
  • ALLEGRO_PIXEL_FORMAT_ANY_16_WITH_ALPHA - Let the driver choose a 16 bit format with alpha.
  • ALLEGRO_PIXEL_FORMAT_ANY_24_NO_ALPHA - Let the driver choose a 24 bit format without alpha.
  • ALLEGRO_PIXEL_FORMAT_ANY_32_NO_ALPHA - Let the driver choose a 32 bit format without alpha.
  • ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA - Let the driver choose a 32 bit format with alpha.
  • ALLEGRO_PIXEL_FORMAT_ARGB_8888 - 32 bit
  • ALLEGRO_PIXEL_FORMAT_RGBA_8888 - 32 bit
  • ALLEGRO_PIXEL_FORMAT_ARGB_4444 - 16 bit
  • ALLEGRO_PIXEL_FORMAT_RGB_888 - 24 bit
  • ALLEGRO_PIXEL_FORMAT_RGB_565 - 16 bit
  • ALLEGRO_PIXEL_FORMAT_RGB_555 - 15 bit
  • ALLEGRO_PIXEL_FORMAT_RGBA_5551 - 16 bit
  • ALLEGRO_PIXEL_FORMAT_ARGB_1555 - 16 bit
  • ALLEGRO_PIXEL_FORMAT_ABGR_8888 - 32 bit
  • ALLEGRO_PIXEL_FORMAT_XBGR_8888 - 32 bit
  • ALLEGRO_PIXEL_FORMAT_BGR_888 - 24 bit
  • ALLEGRO_PIXEL_FORMAT_BGR_565 - 16 bit
  • ALLEGRO_PIXEL_FORMAT_BGR_555 - 15 bit
  • ALLEGRO_PIXEL_FORMAT_RGBX_8888 - 32 bit
  • ALLEGRO_PIXEL_FORMAT_XRGB_8888 - 32 bit
  • ALLEGRO_PIXEL_FORMAT_ABGR_F32 - 128 bit
  • ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE - Like the version without _LE, but the component order is guaranteed to be red, green, blue, alpha. This only makes a difference on big endian systems, on little endian it is just an alias.
  • ALLEGRO_PIXEL_FORMAT_RGBA_4444 - 16bit
  • ALLEGRO_PIXEL_FORMAT_SINGLE_CHANNEL_8 - A single 8-bit channel. A pixel value maps onto the red channel when displayed, but it is undefined how it maps onto green, blue and alpha channels. When drawing to bitmaps of this format, only the red channel is taken into account. Allegro may have to use fallback methods to render to bitmaps of this format. This pixel format is mainly intended for storing the color indices of an indexed (paletted) image, usually in conjunction with a pixel shader that maps indices to RGBA values. Since 5.1.2.
  • ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT1 - Compressed using the DXT1 compression algorithm. Each 4x4 pixel block is encoded in 64 bytes, resulting in 6-8x compression ratio. Only a single bit of alpha per pixel is supported. Since 5.1.9.
  • ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT3 - Compressed using the DXT3 compression algorithm. Each 4x4 pixel block is encoded in 128 bytes, resulting in 4x compression ratio. This format supports sharp alpha transitions. Since 5.1.9.
  • ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT5 - Compressed using the DXT5 compression algorithm. Each 4x4 pixel block is encoded in 128 bytes, resulting in 4x compression ratio. This format supports smooth alpha transitions. Since 5.1.9.

See also: al_set_new_bitmap_format, al_get_bitmap_format

al_get_pixel_size

int al_get_pixel_size(int format)

Source Code

Return the number of bytes that a pixel of the given format occupies. For blocked pixel formats (e.g. compressed formats), this returns 0.

See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_format_bits

al_get_pixel_format_bits

int al_get_pixel_format_bits(int format)

Source Code

Return the number of bits that a pixel of the given format occupies. For blocked pixel formats (e.g. compressed formats), this returns 0.

See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_size

al_get_pixel_block_size

int al_get_pixel_block_size(int format)

Source Code

Return the number of bytes that a block of pixels with this format occupies.

Since: 5.1.9.

See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_block_width, al_get_pixel_block_height

al_get_pixel_block_width

int al_get_pixel_block_width(int format)

Source Code

Return the width of the the pixel block for this format.

Since: 5.1.9.

See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_block_size, al_get_pixel_block_height

al_get_pixel_block_height

int al_get_pixel_block_height(int format)

Source Code

Return the height of the the pixel block for this format.

Since: 5.1.9.

See also: ALLEGRO_PIXEL_FORMAT, al_get_pixel_block_size, al_get_pixel_block_width

al_lock_bitmap

ALLEGRO_LOCKED_REGION *al_lock_bitmap(ALLEGRO_BITMAP *bitmap,
   int format, int flags)

Source Code

Lock an entire bitmap for reading or writing. If the bitmap is a display bitmap it will be updated from system memory after the bitmap is unlocked (unless locked read only). Returns NULL if the bitmap cannot be locked, e.g. the bitmap was locked previously and not unlocked. This function also returns NULL if the format is a compressed format.

Flags are:

  • ALLEGRO_LOCK_READONLY - The locked region will not be written to. This can be faster if the bitmap is a video texture, as it can be discarded after the lock instead of uploaded back to the card.

  • ALLEGRO_LOCK_WRITEONLY - The locked region will not be read from. This can be faster if the bitmap is a video texture, as no data need to be read from the video card. You are required to fill in all pixels before unlocking the bitmap again, so be careful when using this flag.

  • ALLEGRO_LOCK_READWRITE - The locked region can be written to and read from. Use this flag if a partial number of pixels need to be written to, even if reading is not needed.

format indicates the pixel format that the returned buffer will be in. To lock in the same format as the bitmap stores its data internally, call with al_get_bitmap_format(bitmap) as the format or use ALLEGRO_PIXEL_FORMAT_ANY. Locking in the native format will usually be faster. If the bitmap format is compressed, using ALLEGRO_PIXEL_FORMAT_ANY will choose an implementation defined non-compressed format.

On some platforms, Allegro automatically backs up the contents of video bitmaps because they may be occasionally lost (see discussion in al_create_bitmap's documentation). If you're completely recreating the bitmap contents often (e.g. every frame) then you will get much better performance by creating the target bitmap with ALLEGRO_NO_PRESERVE_TEXTURE flag.

Note: While a bitmap is locked, you can not use any drawing operations on it (with the sole exception of al_put_pixel and al_put_blended_pixel).

See also: ALLEGRO_LOCKED_REGION, ALLEGRO_PIXEL_FORMAT, al_unlock_bitmap, al_lock_bitmap_region, al_lock_bitmap_blocked, al_lock_bitmap_region_blocked

al_lock_bitmap_region

ALLEGRO_LOCKED_REGION *al_lock_bitmap_region(ALLEGRO_BITMAP *bitmap,
   int x, int y, int width, int height, int format, int flags)

Source Code

Like al_lock_bitmap, but only locks a specific area of the bitmap. If the bitmap is a video bitmap, only that area of the texture will be updated when it is unlocked. Locking only the region you indend to modify will be faster than locking the whole bitmap.

Note: Using the ALLEGRO_LOCK_WRITEONLY with a blocked pixel format (i.e. formats for which al_get_pixel_block_width or al_get_pixel_block_height do not return 1) requires you to have the region be aligned to the block width for optimal performance. If it is not, then the function will have to lock the region with the ALLEGRO_LOCK_READWRITE instead in order to pad this region with valid data.

See also: ALLEGRO_LOCKED_REGION, ALLEGRO_PIXEL_FORMAT, al_unlock_bitmap

al_unlock_bitmap

void al_unlock_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Unlock a previously locked bitmap or bitmap region. If the bitmap is a video bitmap, the texture will be updated to match the system memory copy (unless it was locked read only).

See also: al_lock_bitmap, al_lock_bitmap_region, al_lock_bitmap_blocked, al_lock_bitmap_region_blocked

al_lock_bitmap_blocked

ALLEGRO_LOCKED_REGION *al_lock_bitmap_blocked(ALLEGRO_BITMAP *bitmap,
   int flags)

Source Code

Like al_lock_bitmap, but allows locking bitmaps with a blocked pixel format (i.e. a format for which al_get_pixel_block_width or al_get_pixel_block_height do not return 1) in that format. To that end, this function also does not allow format conversion. For bitmap formats with a block size of 1, this function is identical to calling al_lock_bitmap(bmp, al_get_bitmap_format(bmp), flags).

Note: Currently there are no drawing functions that work when the bitmap is locked with a compressed format. al_get_pixel will also not work.

Since: 5.1.9

See also: al_lock_bitmap, al_lock_bitmap_region_blocked

al_lock_bitmap_region_blocked

ALLEGRO_LOCKED_REGION *al_lock_bitmap_region_blocked(ALLEGRO_BITMAP *bitmap,
   int x_block, int y_block, int width_block, int height_block, int flags)

Source Code

Like al_lock_bitmap_blocked, but allows locking a sub-region, for performance. Unlike al_lock_bitmap_region the region specified in terms of blocks and not pixels.

Since: 5.1.9

See also: al_lock_bitmap_region, al_lock_bitmap_blocked

Bitmap creation

ALLEGRO_BITMAP

typedef struct ALLEGRO_BITMAP ALLEGRO_BITMAP;

Source Code

Abstract type representing a bitmap (2D image).

al_create_bitmap

ALLEGRO_BITMAP *al_create_bitmap(int w, int h)

Source Code

Creates a new bitmap using the bitmap format and flags for the current thread. Blitting between bitmaps of differing formats, or blitting between memory bitmaps and display bitmaps may be slow.

Unless you set the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created for the current display. Blitting to another display may be slow.

If a display bitmap is created, there may be limitations on the allowed dimensions. For example a DirectX or OpenGL backend usually has a maximum allowed texture size - so if bitmap creation fails for very large dimensions, you may want to re-try with a smaller bitmap. Some platforms also dictate a minimum texture size, which is relevant if you plan to use this bitmap with the primitives addon. If you try to create a bitmap smaller than this, this call will not fail but the returned bitmap will be a section of a larger bitmap with the minimum size. The minimum size that will work on all platforms is 32 by 32.

Some platforms do not directly support display bitmaps whose dimensions are not powers of two. Allegro handles this by creating a larger bitmap that has dimensions that are powers of two and then returning a section of that bitmap with the dimensions you requested. This can be relevant if you plan to use this bitmap with the primitives addon but shouldn't be an issue otherwise.

If you create a bitmap without ALLEGRO_MEMORY_BITMAP set but there is no current display, a temporary memory bitmap will be created instead. You can later convert all such bitmap to video bitmap and assign to a display by calling al_convert_memory_bitmaps.

On some platforms the contents of video bitmaps may be lost when your application loses focus. Allegro has an internal mechanism to restore the contents of these video bitmaps, but it is not foolproof (sometimes bitmap contents can get lost permanently) and has performance implications. If you are using a bitmap as an intermediate buffer this mechanism may be wasteful. In this case, if you do not want Allegro to manage the bitmap contents for you, you can disable this mechanism by creating the bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag. The bitmap contents are lost when you get the ALLEGRO_EVENT_DISPLAY_LOST and ALLEGRO_EVENT_DISPLAY_HALT_DRAWING and a should be restored when you get the ALLEGRO_EVENT_DISPLAY_FOUND and when you call al_acknowledge_drawing_resume (after ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event). You can use those events to implement your own bitmap content restoration mechanism if Allegro's does not work well enough for you (for example, you can reload them all from disk).

Note: The contents of a newly created bitmap are undefined - you need to clear the bitmap or make sure all pixels get overwritten before drawing it.

When you are done with using the bitmap you must call al_destroy_bitmap on it to free any resources allocated for it.

See also: al_set_new_bitmap_format, al_set_new_bitmap_flags, al_clone_bitmap, al_create_sub_bitmap, al_convert_memory_bitmaps, al_destroy_bitmap

al_create_sub_bitmap

ALLEGRO_BITMAP *al_create_sub_bitmap(ALLEGRO_BITMAP *parent,
   int x, int y, int w, int h)

Source Code

Creates a sub-bitmap of the parent, at the specified coordinates and of the specified size. A sub-bitmap is a bitmap that shares drawing memory with a pre-existing (parent) bitmap, but possibly with a different size and clipping settings.

The sub-bitmap may originate off or extend past the parent bitmap.

See the discussion in al_get_backbuffer about using sub-bitmaps of the backbuffer.

The parent bitmap's clipping rectangles are ignored.

If a sub-bitmap was not or cannot be created then NULL is returned.

When you are done with using the sub-bitmap you must call al_destroy_bitmap on it to free any resources allocated for it.

Note that destroying parents of sub-bitmaps will not destroy the sub-bitmaps; instead the sub-bitmaps become invalid and should no longer be used for drawing - they still must be destroyed with al_destroy_bitmap however. It does not matter whether you destroy a sub-bitmap before or after its parent otherwise.

See also: al_create_bitmap

al_clone_bitmap

ALLEGRO_BITMAP *al_clone_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Create a new bitmap with al_create_bitmap, and copy the pixel data from the old bitmap across. The newly created bitmap will be created with the current new bitmap flags, and not the ones that were used to create the original bitmap. If the new bitmap is a memory bitmap, its projection bitmap is reset to be orthographic.

See also: al_create_bitmap, al_set_new_bitmap_format, al_set_new_bitmap_flags, al_convert_bitmap

al_convert_bitmap

void al_convert_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Converts the bitmap to the current bitmap flags and format. The bitmap will be as if it was created anew with al_create_bitmap but retain its contents. All of this bitmap's sub-bitmaps are also converted. If the new bitmap type is memory, then the bitmap's projection bitmap is reset to be orthographic.

If this bitmap is a sub-bitmap, then it, its parent and all the sibling sub-bitmaps are also converted.

Since: 5.1.0

See also: al_create_bitmap, al_set_new_bitmap_format, al_set_new_bitmap_flags, al_clone_bitmap

al_convert_memory_bitmaps

void al_convert_memory_bitmaps(void)

Source Code

If you create a bitmap when there is no current display (for example because you have not called al_create_display in the current thread) and are using the ALLEGRO_CONVERT_BITMAP bitmap flag (which is set by default) then the bitmap will be created successfully, but as a memory bitmap. This function converts all such bitmaps to proper video bitmaps belonging to the current display.

Note that video bitmaps get automatically converted back to memory bitmaps when the last display is destroyed.

This operation will preserve all bitmap flags except ALLEGRO_VIDEO_BITMAP and ALLEGRO_MEMORY_BITMAP.

Since: 5.2.0

See also: al_convert_bitmap, al_create_bitmap

al_destroy_bitmap

void al_destroy_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Destroys the given bitmap, freeing all resources used by it. This function does nothing if the bitmap argument is NULL.

As a convenience, if the calling thread is currently targeting the bitmap then the bitmap will be untargeted first. The new target bitmap is unspecified. (since: 5.0.10, 5.1.6)

Otherwise, it is an error to destroy a bitmap while it (or a sub-bitmap) is the target bitmap of any thread.

See also: al_create_bitmap

al_get_new_bitmap_flags

int al_get_new_bitmap_flags(void)

Source Code

Returns the flags used for newly created bitmaps.

See also: al_set_new_bitmap_flags

al_get_new_bitmap_format

int al_get_new_bitmap_format(void)

Source Code

Returns the format used for newly created bitmaps.

See also: ALLEGRO_PIXEL_FORMAT, al_set_new_bitmap_format

al_set_new_bitmap_flags

void al_set_new_bitmap_flags(int flags)

Source Code

Sets the flags to use for newly created bitmaps. Valid flags are:

ALLEGRO_MEMORY_BITMAP

Create a bitmap residing in system memory. Operations on, and with, memory bitmaps will not be hardware accelerated. However, direct pixel access can be relatively quick compared to video bitmaps, which depend on the display driver in use.

Note: Allegro's software rendering routines are currently somewhat unoptimised.

Note: Combining ALLEGRO_VIDEO_BITMAP and ALLEGRO_MEMORY_BITMAP flags is invalid.

ALLEGRO_VIDEO_BITMAP

Creates a bitmap that resides in the video card memory. These types of bitmaps receive the greatest benefit from hardware acceleration.

Note: Creating a video bitmap will fail if there is no current display or the current display driver cannot create the bitmap. The latter will happen if for example the format or dimensions are not supported.

Note: Bitmaps created with this flag will be converted to memory bitmaps when the last display is destroyed. In most cases it is therefore easier to use the ALLEGRO_CONVERT_BITMAP flag instead.

Note: Combining ALLEGRO_VIDEO_BITMAP and ALLEGRO_MEMORY_BITMAP flags is invalid.

ALLEGRO_CONVERT_BITMAP

This is the default. It will try to create a video bitmap and if that fails create a memory bitmap. Bitmaps created with this flag when there is no active display will be converted to video bitmaps next time a display is created. They also will remain video bitmaps if the last display is destroyed and then another is created again. Since 5.1.0.

Note: You can combine this flag with ALLEGRO_MEMORY_BITMAP or ALLEGRO_VIDEO_BITMAP to force the initial type (and fail in the latter case if no video bitmap can be created) - but usually neither of those combinations is very useful.

You can use the display option ALLEGRO_AUTO_CONVERT_BITMAPS to control which displays will try to auto-convert bitmaps.

ALLEGRO_FORCE_LOCKING
Does nothing since 5.1.8. Kept for backwards compatibility only.
ALLEGRO_NO_PRESERVE_TEXTURE
Normally, every effort is taken to preserve the contents of bitmaps, since some platforms may forget them. This can take extra processing time. If you know it doesn't matter if a bitmap keeps its pixel data, for example when it's a temporary buffer, use this flag to tell Allegro not to attempt to preserve its contents.
ALLEGRO_ALPHA_TEST
This is a driver hint only. It tells the graphics driver to do alpha testing instead of alpha blending on bitmaps created with this flag. Alpha testing is usually faster and preferred if your bitmaps have only one level of alpha (0). This flag is currently not widely implemented (i.e., only for memory bitmaps).
ALLEGRO_MIN_LINEAR
When drawing a scaled down version of the bitmap, use linear filtering. This usually looks better. You can also combine it with the MIPMAP flag for even better quality.
ALLEGRO_MAG_LINEAR

When drawing a magnified version of a bitmap, use linear filtering. This will cause the picture to get blurry instead of creating a big rectangle for each pixel. It depends on how you want things to look like whether you want to use this or not.

ALLEGRO_MIPMAP

This can only be used for bitmaps whose width and height is a power of two. In that case, it will generate mipmaps and use them when drawing scaled down versions. For example if the bitmap is 64x64, then extra bitmaps of sizes 32x32, 16x16, 8x8, 4x4, 2x2 and 1x1 will be created always containing a scaled down version of the original.

See also: al_get_new_bitmap_flags, al_get_bitmap_flags

al_add_new_bitmap_flag

void al_add_new_bitmap_flag(int flag)

Source Code

A convenience function which does the same as

al_set_new_bitmap_flags(al_get_new_bitmap_flags() | flag);

See also: al_set_new_bitmap_flags, al_get_new_bitmap_flags, al_get_bitmap_flags

al_set_new_bitmap_format

void al_set_new_bitmap_format(int format)

Source Code

Sets the pixel format (ALLEGRO_PIXEL_FORMAT) for newly created bitmaps. The default format is 0 and means the display driver will choose the best format.

See also: ALLEGRO_PIXEL_FORMAT, al_get_new_bitmap_format, al_get_bitmap_format

al_set_new_bitmap_depth

void al_set_new_bitmap_depth(int depth)
SETTER(new_bitmap_depth, depth)

Source Code

Sets the depthbuffer depth used by newly created bitmaps (on the current thread) if they are used with al_set_target_bitmap. 0 means no depth-buffer will be created when drawing into the bitmap, which is the default.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_get_new_bitmap_depth

int al_get_new_bitmap_depth(void)
GETTER(new_bitmap_depth, 0)

Source Code

Returns the value currently set with al_set_new_bitmap_depth on the current thread or 0 if none was set.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_set_new_bitmap_samples

void al_set_new_bitmap_samples(int samples)
SETTER(new_bitmap_samples, samples)

Source Code

Sets the multi-sampling samples used by newly created bitmaps (on the current thread) if they are used with al_set_target_bitmap. 0 means multi-sampling will not be used when drawing into the bitmap, which is the default. 1 means multi-sampling will be used but only using a single sample per pixel (so usually there will be no visual difference to not using multi-sampling at all).

Note: Some platforms have restrictions on when the multi-sampling buffer for a bitmap is realized, i.e. down-scaled back to the actual bitmap dimensions. This may only happen after a call to al_set_target_bitmap. So for example:

al_set_target_bitmap(multisample);
al_clear_to_color(blue);
al_draw_line(0, 0, 100, 100, red, 1);
al_lock_bitmap(multisample, ...)
// ERROR: the contents of the bitmap will be undefined

al_set_target_bitmap(backbuffer);
al_lock_bitmap(multisample, ...)
// CORRECT: at this point, the bitmap contents are updated and
// there will be an anti-aliased line in it.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_get_new_bitmap_samples

int al_get_new_bitmap_samples(void)
GETTER(new_bitmap_samples, 0)

Source Code

Returns the value currently set with al_set_new_bitmap_samples on the current thread or 0 if none was set.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

Bitmap properties

al_get_bitmap_flags

int al_get_bitmap_flags(ALLEGRO_BITMAP *bitmap)

Source Code

Return the flags used to create the bitmap.

See also: al_set_new_bitmap_flags

al_get_bitmap_format

int al_get_bitmap_format(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the pixel format of a bitmap.

See also: ALLEGRO_PIXEL_FORMAT, al_set_new_bitmap_flags

al_get_bitmap_height

int al_get_bitmap_height(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the height of a bitmap in pixels.

al_get_bitmap_width

int al_get_bitmap_width(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the width of a bitmap in pixels.

al_get_bitmap_depth

int al_get_bitmap_depth(ALLEGRO_BITMAP *bitmap)

Source Code

Return the depthbuffer depth used by this bitmap if it is used with al_set_target_bitmap.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_get_bitmap_samples

int al_get_bitmap_samples(ALLEGRO_BITMAP *bitmap)

Source Code

Return the multi-sampling samples used by this bitmap if it is used with al_set_target_bitmap.

Since: 5.2.1

Unstable API: This is an experimental feature and currently only works for the OpenGL backend.

al_get_pixel

ALLEGRO_COLOR al_get_pixel(ALLEGRO_BITMAP *bitmap, int x, int y)

Source Code

Get a pixel's color value from the specified bitmap. This operation is slow on non-memory bitmaps. Consider locking the bitmap if you are going to use this function multiple times on the same bitmap.

See also: ALLEGRO_COLOR, al_put_pixel, al_lock_bitmap

al_is_bitmap_locked

bool al_is_bitmap_locked(ALLEGRO_BITMAP *bitmap)

Source Code

Returns whether or not a bitmap is already locked.

See also: al_lock_bitmap, al_lock_bitmap_region, al_unlock_bitmap

al_is_compatible_bitmap

bool al_is_compatible_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

D3D and OpenGL allow sharing a texture in a way so it can be used for multiple windows. Each ALLEGRO_BITMAP created with al_create_bitmap however is usually tied to a single ALLEGRO_DISPLAY. This function can be used to know if the bitmap is compatible with the given display, even if it is a different display to the one it was created with. It returns true if the bitmap is compatible (things like a cached texture version can be used) and false otherwise (blitting in the current display will be slow).

The only time this function is useful is if you are using multiple windows and need accelerated blitting of the same bitmaps to both.

Returns true if the bitmap is compatible with the current display, false otherwise. If there is no current display, false is returned.

al_is_sub_bitmap

bool al_is_sub_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Returns true if the specified bitmap is a sub-bitmap, false otherwise.

See also: al_create_sub_bitmap, al_get_parent_bitmap

al_get_parent_bitmap

ALLEGRO_BITMAP *al_get_parent_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the bitmap this bitmap is a sub-bitmap of. Returns NULL if this bitmap is not a sub-bitmap. This function always returns the real bitmap, and never a sub-bitmap. This might NOT match what was passed to al_create_sub_bitmap. Consider this code, for instance:

ALLEGRO_BITMAP* a = al_create_bitmap(512, 512);
ALLEGRO_BITMAP* b = al_create_sub_bitmap(a, 128, 128, 256, 256);
ALLEGRO_BITMAP* c = al_create_sub_bitmap(b, 64, 64, 128, 128);
ASSERT(al_get_parent_bitmap(b) == a && al_get_parent_bitmap(c) == a);

The assertion will pass because only a is a real bitmap, and both b and c are its sub-bitmaps.

Since: 5.0.6, 5.1.2

See also: al_create_sub_bitmap, al_is_sub_bitmap

al_get_bitmap_x

int al_get_bitmap_x(ALLEGRO_BITMAP *bitmap)

Source Code

For a sub-bitmap, return it's x position within the parent.

See also: al_create_sub_bitmap, al_get_parent_bitmap, al_get_bitmap_y

Since: 5.1.12

al_get_bitmap_y

int al_get_bitmap_y(ALLEGRO_BITMAP *bitmap)

Source Code

For a sub-bitmap, return it's y position within the parent.

See also: al_create_sub_bitmap, al_get_parent_bitmap, al_get_bitmap_x

Since: 5.1.12

al_reparent_bitmap

void al_reparent_bitmap(ALLEGRO_BITMAP *bitmap, ALLEGRO_BITMAP *parent,
   int x, int y, int w, int h)

Source Code

For a sub-bitmap, changes the parent, position and size. This is the same as destroying the bitmap and re-creating it with al_create_sub_bitmap - except the bitmap pointer stays the same. This has many uses, for example an animation player could return a single bitmap which can just be re-parented to different animation frames without having to re-draw the contents. Or a sprite atlas could re-arrange its sprites without having to invalidate all existing bitmaps.

See also: al_create_sub_bitmap, al_get_parent_bitmap

Since: 5.1.12

Drawing operations

All drawing operations draw to the current "target bitmap" of the current thread. Initially, the target bitmap will be the backbuffer of the last display created in a thread.

al_clear_to_color

void al_clear_to_color(ALLEGRO_COLOR color)

Source Code

Clear the complete target bitmap, but confined by the clipping rectangle.

See also: ALLEGRO_COLOR, al_set_clipping_rectangle, al_clear_depth_buffer

al_clear_depth_buffer

void al_clear_depth_buffer(float z)

Source Code

Clear the depth buffer (confined by the clipping rectangle) to the given value. A depth buffer is only available if it was requested with al_set_new_display_option and the requirement could be met by the al_create_display call creating the current display. Operations involving the depth buffer are also affected by al_set_render_state.

For example, if ALLEGRO_DEPTH_FUNCTION is set to ALLEGRO_RENDER_LESS then depth buffer value of 1 represents infinite distance, and thus is a good value to use when clearing the depth buffer.

Since: 5.1.2

See also: al_clear_to_color, al_set_clipping_rectangle, al_set_render_state, al_set_new_display_option

al_draw_bitmap

void al_draw_bitmap(ALLEGRO_BITMAP *bitmap, float dx, float dy, int flags)

Source Code

Draws an unscaled, unrotated bitmap at the given position to the current target bitmap (see al_set_target_bitmap).

flags can be a combination of:

  • ALLEGRO_FLIP_HORIZONTAL - flip the bitmap about the y-axis
  • ALLEGRO_FLIP_VERTICAL - flip the bitmap about the x-axis

Note: The current target bitmap must be a different bitmap. Drawing a bitmap to itself (or to a sub-bitmap of itself) or drawing a sub-bitmap to its parent (or another sub-bitmap of its parent) are not currently supported. To copy part of a bitmap into the same bitmap simply use a temporary bitmap instead.

Note: The backbuffer (or a sub-bitmap thereof) can not be transformed, blended or tinted. If you need to draw the backbuffer draw it to a temporary bitmap first with no active transformation (except translation). Blending and tinting settings/parameters will be ignored. This does not apply when drawing into a memory bitmap.

See also: al_draw_bitmap_region, al_draw_scaled_bitmap, al_draw_rotated_bitmap, al_draw_scaled_rotated_bitmap

al_draw_tinted_bitmap

void al_draw_tinted_bitmap(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR tint,
   float dx, float dy, int flags)

Source Code

Like al_draw_bitmap but multiplies all colors in the bitmap with the given color. For example:

al_draw_tinted_bitmap(bitmap, al_map_rgba_f(0.5, 0.5, 0.5, 0.5), x, y, 0);

The above will draw the bitmap 50% transparently (r/g/b values need to be pre-multiplied with the alpha component with the default blend mode).

al_draw_tinted_bitmap(bitmap, al_map_rgba_f(1, 0, 0, 1), x, y, 0);

The above will only draw the red component of the bitmap.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_bitmap

al_draw_bitmap_region

void al_draw_bitmap_region(ALLEGRO_BITMAP *bitmap,
   float sx, float sy, float sw, float sh, float dx, float dy, int flags)

Source Code

Draws a region of the given bitmap to the target bitmap.

  • sx - source x
  • sy - source y
  • sw - source width (width of region to blit)
  • sh - source height (height of region to blit)
  • dx - destination x
  • dy - destination y
  • flags - same as for al_draw_bitmap

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_bitmap, al_draw_scaled_bitmap, al_draw_rotated_bitmap, al_draw_scaled_rotated_bitmap

al_draw_tinted_bitmap_region

void al_draw_tinted_bitmap_region(ALLEGRO_BITMAP *bitmap,
   ALLEGRO_COLOR tint,
   float sx, float sy, float sw, float sh, float dx, float dy,
   int flags)

Source Code

Like al_draw_bitmap_region but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_tinted_bitmap

al_draw_pixel

void al_draw_pixel(float x, float y, ALLEGRO_COLOR color)

Source Code

Draws a single pixel at x, y. This function, unlike al_put_pixel, does blending and, unlike al_put_blended_pixel, respects the transformations (that is, the pixel's position is transformed, but its size is unaffected - it remains a pixel). This function can be slow if called often; if you need to draw a lot of pixels consider using al_draw_prim with ALLEGRO_PRIM_POINT_LIST from the primitives addon.

  • x - destination x
  • y - destination y
  • color - color of the pixel

Note: This function may not draw exactly where you expect it to. See the pixel-precise output section on the primitives addon documentation for details on how to control exactly where the pixel is drawn.

See also: ALLEGRO_COLOR, al_put_pixel

al_draw_rotated_bitmap

void al_draw_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
   float cx, float cy, float dx, float dy, float angle, int flags)

Source Code

Draws a rotated version of the given bitmap to the target bitmap. The bitmap is rotated by 'angle' radians clockwise.

The point at cx/cy relative to the upper left corner of the bitmap will be drawn at dx/dy and the bitmap is rotated around this point. If cx,cy is 0,0 the bitmap will rotate around its upper left corner.

  • cx - center x (relative to the bitmap)
  • cy - center y (relative to the bitmap)
  • dx - destination x
  • dy - destination y
  • angle - angle by which to rotate (radians)
  • flags - same as for al_draw_bitmap

Example

float w = al_get_bitmap_width(bitmap);
float h = al_get_bitmap_height(bitmap);
al_draw_rotated_bitmap(bitmap, w / 2, h / 2, x, y, ALLEGRO_PI / 2, 0);

The above code draws the bitmap centered on x/y and rotates it 90° clockwise.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_bitmap, al_draw_bitmap_region, al_draw_scaled_bitmap, al_draw_scaled_rotated_bitmap

al_draw_tinted_rotated_bitmap

void al_draw_tinted_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
   ALLEGRO_COLOR tint,
   float cx, float cy, float dx, float dy, float angle, int flags)

Source Code

Like al_draw_rotated_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_tinted_bitmap

al_draw_scaled_rotated_bitmap

void al_draw_scaled_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
   float cx, float cy, float dx, float dy, float xscale, float yscale,
   float angle, int flags)

Source Code

Like al_draw_rotated_bitmap, but can also scale the bitmap.

The point at cx/cy in the bitmap will be drawn at dx/dy and the bitmap is rotated and scaled around this point.

  • cx - center x
  • cy - center y
  • dx - destination x
  • dy - destination y
  • xscale - how much to scale on the x-axis (e.g. 2 for twice the size)
  • yscale - how much to scale on the y-axis
  • angle - angle by which to rotate (radians)
  • flags - same as for al_draw_bitmap

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_bitmap, al_draw_bitmap_region, al_draw_scaled_bitmap, al_draw_rotated_bitmap

al_draw_tinted_scaled_rotated_bitmap

void al_draw_tinted_scaled_rotated_bitmap(ALLEGRO_BITMAP *bitmap,
   ALLEGRO_COLOR tint,
   float cx, float cy, float dx, float dy, float xscale, float yscale,
   float angle, int flags)

Source Code

Like al_draw_scaled_rotated_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_tinted_bitmap

al_draw_tinted_scaled_rotated_bitmap_region

void al_draw_tinted_scaled_rotated_bitmap_region(ALLEGRO_BITMAP *bitmap,
   float sx, float sy, float sw, float sh,
   ALLEGRO_COLOR tint,
   float cx, float cy, float dx, float dy, float xscale, float yscale,
   float angle, int flags)

Source Code

Like al_draw_tinted_scaled_rotated_bitmap but you specify an area within the bitmap to be drawn.

You can get the same effect with a sub bitmap:

al_draw_tinted_scaled_rotated_bitmap(bitmap, sx, sy, sw, sh, tint,
    cx, cy, dx, dy, xscale, yscale, angle, flags);

/* This draws the same: */
sub_bitmap = al_create_sub_bitmap(bitmap, sx, sy, sw, sh);
al_draw_tinted_scaled_rotated_bitmap(sub_bitmap, tint, cx, cy,
    dx, dy, xscale, yscale, angle, flags);

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

Since: 5.0.6, 5.1.0

See also: al_draw_tinted_bitmap

al_draw_scaled_bitmap

void al_draw_scaled_bitmap(ALLEGRO_BITMAP *bitmap,
   float sx, float sy, float sw, float sh,
   float dx, float dy, float dw, float dh, int flags)

Source Code

Draws a scaled version of the given bitmap to the target bitmap.

  • sx - source x
  • sy - source y
  • sw - source width
  • sh - source height
  • dx - destination x
  • dy - destination y
  • dw - destination width
  • dh - destination height
  • flags - same as for al_draw_bitmap

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_bitmap, al_draw_bitmap_region, al_draw_rotated_bitmap, al_draw_scaled_rotated_bitmap,

al_draw_tinted_scaled_bitmap

void al_draw_tinted_scaled_bitmap(ALLEGRO_BITMAP *bitmap,
   ALLEGRO_COLOR tint,
   float sx, float sy, float sw, float sh,
   float dx, float dy, float dw, float dh, int flags)

Source Code

Like al_draw_scaled_bitmap but multiplies all colors in the bitmap with the given color.

See al_draw_bitmap for a note on restrictions on which bitmaps can be drawn where.

See also: al_draw_tinted_bitmap

al_get_target_bitmap

ALLEGRO_BITMAP *al_get_target_bitmap(void)

Source Code

Return the target bitmap of the calling thread.

See also: al_set_target_bitmap

al_put_pixel

void al_put_pixel(int x, int y, ALLEGRO_COLOR color)

Source Code

Draw a single pixel on the target bitmap. This operation is slow on non-memory bitmaps. Consider locking the bitmap if you are going to use this function multiple times on the same bitmap. This function is not affected by the transformations or the color blenders.

See also: ALLEGRO_COLOR, al_get_pixel, al_put_blended_pixel, al_lock_bitmap

al_put_blended_pixel

void al_put_blended_pixel(int x, int y, ALLEGRO_COLOR color)

Source Code

Like al_put_pixel, but the pixel color is blended using the current blenders before being drawn.

See also: ALLEGRO_COLOR, al_put_pixel

Target bitmap

al_set_target_bitmap

void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

This function selects the bitmap to which all subsequent drawing operations in the calling thread will draw to. To return to drawing to a display, set the backbuffer of the display as the target bitmap, using al_get_backbuffer. As a convenience, you may also use al_set_target_backbuffer.

Each allegro bitmap maintains two transformation matrices associated with it for drawing onto the bitmap. There is a view matrix and a projection matrix. When you call al_set_target_bitmap, these will be made current for the bitmap, affecting global OpenGL and DirectX states depending on the driver in use.

Each video bitmap is tied to a display. When a video bitmap is set to as the target bitmap, the display that the bitmap belongs to is automatically made "current" for the calling thread (if it is not current already). Then drawing other bitmaps which are tied to the same display can be hardware accelerated.

A single display cannot be current for multiple threads simultaneously. If you need to release a display, so it is not current for the calling thread, call al_set_target_bitmap(NULL);

Setting a memory bitmap as the target bitmap will not change which display is current for the calling thread.

On some platforms, Allegro automatically backs up the contents of video bitmaps because they may be occasionally lost (see discussion in al_create_bitmap's documentation). If you're completely recreating the bitmap contents often (e.g. every frame) then you will get much better performance by creating the target bitmap with ALLEGRO_NO_PRESERVE_TEXTURE flag.

OpenGL note:

Framebuffer objects (FBOs) allow OpenGL to directly draw to a bitmap, which is very fast. When using an OpenGL display, if all of the following conditions are met an FBO will be created for use with the bitmap:

  • The GL_EXT_framebuffer_object OpenGL extension is available.
  • The bitmap is not a memory bitmap.
  • The bitmap is not currently locked.

In Allegro 5.0.0, you had to be careful as an FBO would be kept around until the bitmap is destroyed or you explicitly called al_remove_opengl_fbo on the bitmap, wasting resources. In newer versions, FBOs will be freed automatically when the bitmap is no longer the target bitmap, unless you have called al_get_opengl_fbo to retrieve the FBO id.

In the following example, no FBO will be created:

lock = al_lock_bitmap(bitmap);
al_set_target_bitmap(bitmap);
al_put_pixel(x, y, color);
al_unlock_bitmap(bitmap);

The above allows using al_put_pixel on a locked bitmap without creating an FBO.

In this example an FBO is created however:

al_set_target_bitmap(bitmap);
al_draw_line(x1, y1, x2, y2, color, 0);

An OpenGL command will be used to directly draw the line into the bitmap's associated texture.

See also: al_get_target_bitmap, al_set_target_backbuffer

al_set_target_backbuffer

void al_set_target_backbuffer(ALLEGRO_DISPLAY *display)

Source Code

Same as al_set_target_bitmap(al_get_backbuffer(display));

See also: al_set_target_bitmap, al_get_backbuffer

al_get_current_display

ALLEGRO_DISPLAY *al_get_current_display(void)

Source Code

Return the display that is "current" for the calling thread, or NULL if there is none.

See also: al_set_target_bitmap

Blending modes

al_get_blender

void al_get_blender(int *op, int *src, int *dst)

Source Code

Returns the active blender for the current thread. You can pass NULL for values you are not interested in.

See also: al_set_blender, al_get_separate_blender

al_get_separate_blender

void al_get_separate_blender(int *op, int *src, int *dst,
   int *alpha_op, int *alpha_src, int *alpha_dst)

Source Code

Returns the active blender for the current thread. You can pass NULL for values you are not interested in.

See also: al_set_separate_blender, al_get_blender

al_get_blend_color

ALLEGRO_COLOR al_get_blend_color(void)

Source Code

Returns the color currently used for constant color blending (white by default).

See also: al_set_blend_color, al_set_blender

Since: 5.1.12

al_set_blender

void al_set_blender(int op, int src, int dst)

Source Code

Sets the function to use for blending for the current thread.

Blending means, the source and destination colors are combined in drawing operations.

Assume the source color (e.g. color of a rectangle to draw, or pixel of a bitmap to draw) is given as its red/green/blue/alpha components (if the bitmap has no alpha it always is assumed to be fully opaque, so 255 for 8-bit or 1.0 for floating point): s = s.r, s.g, s.b, s.a. And this color is drawn to a destination, which already has a color: d = d.r, d.g, d.b, d.a.

The conceptional formula used by Allegro to draw any pixel then depends on the op parameter:

  • ALLEGRO_ADD

     r = d.r * df.r + s.r * sf.r
 g = d.g * df.g + s.g * sf.g
 b = d.b * df.b + s.b * sf.b
 a = d.a * df.a + s.a * sf.a

  • ALLEGRO_DEST_MINUS_SRC

     r = d.r * df.r - s.r * sf.r
 g = d.g * df.g - s.g * sf.g
 b = d.b * df.b - s.b * sf.b
 a = d.a * df.a - s.a * sf.a

  • ALLEGRO_SRC_MINUS_DEST

     r = s.r * sf.r - d.r * df.r
 g = s.g * sf.g - d.g * df.g
 b = s.b * sf.b - d.b * df.b
 a = s.a * sf.a - d.a * df.a

Valid values for the factors sf and df passed to this function are as follows, where s is the source color, d the destination color and cc the color set with al_set_blend_color (white by default)

  • ALLEGRO_ZERO

     f = 0, 0, 0, 0

  • ALLEGRO_ONE

     f = 1, 1, 1, 1

  • ALLEGRO_ALPHA

     f = s.a, s.a, s.a, s.a

  • ALLEGRO_INVERSE_ALPHA

     f = 1 - s.a, 1 - s.a, 1 - s.a, 1 - s.a

  • ALLEGRO_SRC_COLOR (since: 5.0.10, 5.1.0)

     f = s.r, s.g, s.b, s.a

  • ALLEGRO_DEST_COLOR (since: 5.0.10, 5.1.8)

     f = d.r, d.g, d.b, d.a

  • ALLEGRO_INVERSE_SRC_COLOR (since: 5.0.10, 5.1.0)

     f = 1 - s.r, 1 - s.g, 1 - s.b, 1 - s.a

  • ALLEGRO_INVERSE_DEST_COLOR (since: 5.0.10, 5.1.8)

     f = 1 - d.r, 1 - d.g, 1 - d.b, 1 - d.a

  • ALLEGRO_CONST_COLOR (since: 5.1.12, not supported on OpenGLES 1.0)

     f = cc.r, cc.g, cc.b, cc.a

  • ALLEGRO_INVERSE_CONST_COLOR (since: 5.1.12, not supported on OpenGLES 1.0)

     f = 1 - cc.r, 1 - cc.g, 1 - cc.b, 1 - cc.a

Blending examples:

So for example, to restore the default of using premultiplied alpha blending, you would use:

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_INVERSE_ALPHA);

As formula:

r = d.r * (1 - s.a) + s.r * 1
g = d.g * (1 - s.a) + s.g * 1
b = d.b * (1 - s.a) + s.b * 1
a = d.a * (1 - s.a) + s.a * 1

If you are using non-pre-multiplied alpha, you could use

al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA);

Additive blending would be achieved with

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ONE);

Copying the source to the destination (including alpha) unmodified

al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_ZERO);

Multiplying source and destination components

al_set_blender(ALLEGRO_ADD, ALLEGRO_DEST_COLOR, ALLEGRO_ZERO)

Tinting the source (like al_draw_tinted_bitmap)

al_set_blender(ALLEGRO_ADD, ALLEGRO_CONST_COLOR, ALLEGRO_ONE);
al_set_blend_color(al_map_rgb(0, 96, 255)); /* nice Chrysler blue */

Averaging source and destination pixels

al_set_blender(ALLEGRO_ADD, ALLEGRO_CONST_COLOR, ALLEGRO_CONST_COLOR);
al_set_blend_color(al_map_rgba_f(0.5, 0.5, 0.5, 0.5));

As formula:

r = d.r * 0 + s.r * d.r
g = d.g * 0 + s.g * d.g
b = d.b * 0 + s.b * d.b
a = d.a * 0 + s.a * d.a

See also: al_set_separate_blender, al_set_blend_color, al_get_blender

al_set_separate_blender

void al_set_separate_blender(int op, int src, int dst,
   int alpha_op, int alpha_src, int alpha_dst)

Source Code

Like al_set_blender, but allows specifying a separate blending operation for the alpha channel. This is useful if your target bitmap also has an alpha channel and the two alpha channels need to be combined in a different way than the color components.

See also: al_set_blender, al_get_blender, al_get_separate_blender

al_set_blend_color

void al_set_blend_color(ALLEGRO_COLOR color)

Source Code

Sets the color to use for blending when using the ALLEGRO_CONST_COLOR or ALLEGRO_INVERSE_CONST_COLOR blend functions. See al_set_blender for more information.

See also: al_set_blender, al_get_blend_color

Since: 5.1.12

Clipping

al_get_clipping_rectangle

void al_get_clipping_rectangle(int *x, int *y, int *w, int *h)

Source Code

Gets the clipping rectangle of the target bitmap.

See also: al_set_clipping_rectangle

al_set_clipping_rectangle

void al_set_clipping_rectangle(int x, int y, int width, int height)

Source Code

Set the region of the target bitmap or display that pixels get clipped to. The default is to clip pixels to the entire bitmap.

See also: al_get_clipping_rectangle, al_reset_clipping_rectangle

al_reset_clipping_rectangle

void al_reset_clipping_rectangle(void)

Source Code

Equivalent to calling `al_set_clipping_rectangle(0, 0, w, h)' where w and h are the width and height of the target bitmap respectively.

Does nothing if there is no target bitmap.

See also: al_set_clipping_rectangle

Since: 5.0.6, 5.1.0

Graphics utility functions

al_convert_mask_to_alpha

void al_convert_mask_to_alpha(ALLEGRO_BITMAP *bitmap, ALLEGRO_COLOR mask_color)

Source Code

Convert the given mask color to an alpha channel in the bitmap. Can be used to convert older 4.2-style bitmaps with magic pink to alpha-ready bitmaps.

See also: ALLEGRO_COLOR

Deferred drawing

al_hold_bitmap_drawing

void al_hold_bitmap_drawing(bool hold)

Source Code

Enables or disables deferred bitmap drawing. This allows for efficient drawing of many bitmaps that share a parent bitmap, such as sub-bitmaps from a tilesheet or simply identical bitmaps. Drawing bitmaps that do not share a parent is less efficient, so it is advisable to stagger bitmap drawing calls such that the parent bitmap is the same for large number of those calls. While deferred bitmap drawing is enabled, the only functions that can be used are the bitmap drawing functions and font drawing functions. Changing the state such as the blending modes will result in undefined behaviour. One exception to this rule are the non-projection transformations. It is possible to set a new transformation while the drawing is held.

No drawing is guaranteed to take place until you disable the hold. Thus, the idiom of this function's usage is to enable the deferred bitmap drawing, draw as many bitmaps as possible, taking care to stagger bitmaps that share parent bitmaps, and then disable deferred drawing. As mentioned above, this function also works with bitmap and truetype fonts, so if multiple lines of text need to be drawn, this function can speed things up.

See also: al_is_bitmap_drawing_held

al_is_bitmap_drawing_held

bool al_is_bitmap_drawing_held(void)

Source Code

Returns whether the deferred bitmap drawing mode is turned on or off.

See also: al_hold_bitmap_drawing

Image I/O

al_register_bitmap_loader

bool al_register_bitmap_loader(const char *extension,
   ALLEGRO_BITMAP *(*loader)(const char *filename, int flags))

Source Code

Register a handler for al_load_bitmap. The given function will be used to handle the loading of bitmaps files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The loader argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_bitmap_saver, al_register_bitmap_loader_f

al_register_bitmap_saver

bool al_register_bitmap_saver(const char *extension,
   bool (*saver)(const char *filename, ALLEGRO_BITMAP *bmp))

Source Code

Register a handler for al_save_bitmap. The given function will be used to handle the saving of bitmaps files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The saver argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_bitmap_loader, al_register_bitmap_saver_f

al_register_bitmap_loader_f

bool al_register_bitmap_loader_f(const char *extension,
   ALLEGRO_BITMAP *(*fs_loader)(ALLEGRO_FILE *fp, int flags))

Source Code

Register a handler for al_load_bitmap_f. The given function will be used to handle the loading of bitmaps files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The fs_loader argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_bitmap_loader

al_register_bitmap_saver_f

bool al_register_bitmap_saver_f(const char *extension,
   bool (*fs_saver)(ALLEGRO_FILE *fp, ALLEGRO_BITMAP *bmp))

Source Code

Register a handler for al_save_bitmap_f. The given function will be used to handle the saving of bitmaps files with the given extension.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The saver_f argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

See also: al_register_bitmap_saver

al_load_bitmap

ALLEGRO_BITMAP *al_load_bitmap(const char *filename)

Source Code

Loads an image file into a new ALLEGRO_BITMAP. The file type is determined by the extension, except if the file has no extension in which case al_identify_bitmap is used instead.

Returns NULL on error.

This is the same as calling al_load_bitmap_flags with a flags parameter of 0.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

See also: al_load_bitmap_flags, al_load_bitmap_f, al_register_bitmap_loader, al_set_new_bitmap_format, al_set_new_bitmap_flags, al_init_image_addon

al_load_bitmap_flags

ALLEGRO_BITMAP *al_load_bitmap_flags(const char *filename, int flags)

Source Code

Loads an image file into a new ALLEGRO_BITMAP. The file type is determined by the extension, except if the file has no extension in which case al_identify_bitmap is used instead.

Returns NULL on error.

The flags parameter may be a combination of the following constants:

ALLEGRO_NO_PREMULTIPLIED_ALPHA

By default, Allegro pre-multiplies the alpha channel of an image with the images color data when it loads it. Typically that would look something like this:

r = get_float_byte();
g = get_float_byte();
b = get_float_byte();
a = get_float_byte();

r = r * a;
g = g * a;
b = b * a;

set_image_pixel(x, y, r, g, b, a);

The reason for this can be seen in the Allegro example ex_premulalpha, ie, using pre-multiplied alpha gives more accurate color results in some cases. To use alpha blending with images loaded with pre-multiplied alpha, you would use the default blending mode, which is set with al_set_blender(ALLEGRO_ADD, ALLEGRO_ONE, ALLEGRO_INVERSE_ALPHA).

The ALLEGRO_NO_PREMULTIPLIED_ALPHA flag being set will ensure that images are not loaded with alpha pre-multiplied, but are loaded with color values direct from the image. That looks like this:

r = get_float_byte();
g = get_float_byte();
b = get_float_byte();
a = get_float_byte();

set_image_pixel(x, y, r, g, b, a);

To draw such an image using regular alpha blending, you would use al_set_blender(ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) to set the correct blender. This has some caveats. First, as mentioned above, drawing such an image can result in less accurate color blending (when drawing an image with linear filtering on, the edges will be darker than they should be). Second, the behaviour is somewhat confusing, which is explained in the example below.

// Load and create bitmaps with an alpha channel
al_set_new_bitmap_format(ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA);
// Load some bitmap with alpha in it
bmp = al_load_bitmap("some_alpha_bitmap.png");
// We will draw to this buffer and then draw this buffer to the screen
tmp_buffer = al_create_bitmap(SCREEN_W, SCREEN_H);
// Set the buffer as the target and clear it
al_set_target_bitmap(tmp_buffer);
al_clear_to_color(al_map_rgba_f(0, 0, 0, 1));
// Draw the bitmap to the temporary buffer
al_draw_bitmap(bmp, 0, 0, 0);
// Finally, draw the buffer to the screen
// The output will look incorrect (may take close inspection
// depending on the bitmap -- it may also be very obvious)
al_set_target_bitmap(al_get_backbuffer(display));
al_draw_bitmap(tmp_buffer, 0, 0, 0);

To explain further, if you have a pixel with 0.5 alpha, and you're using (ALLEGRO_ADD, ALLEGRO_ALPHA, ALLEGRO_INVERSE_ALPHA) for blending, the formula is:

a = da * dst + sa * src

Expands to:

result_a = dst_a * (1-0.5) + 0.5 * 0.5

So if you draw the image to the temporary buffer, it is blended once resulting in 0.75 alpha, then drawn again to the screen, blended in the same way, resulting in a pixel has 0.1875 as an alpha value.

ALLEGRO_KEEP_INDEX
Load the palette indices of 8-bit .bmp and .pcx files instead of the rgb colors. Since 5.1.0.
ALLEGRO_KEEP_BITMAP_FORMAT

Force the resulting ALLEGRO_BITMAP to use the same format as the file.

This is not yet honoured.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

Since: 5.1.0

See also: al_load_bitmap

al_load_bitmap_f

ALLEGRO_BITMAP *al_load_bitmap_f(ALLEGRO_FILE *fp, const char *ident)

Source Code

Loads an image from an ALLEGRO_FILE stream into a new ALLEGRO_BITMAP. The file type is determined by the passed 'ident' parameter, which is a file name extension including the leading dot. If (and only if) 'ident' is NULL, the file type is determined with al_identify_bitmap_f instead.

This is the same as calling al_load_bitmap_flags_f with 0 for the flags parameter.

Returns NULL on error. The file remains open afterwards.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

See also: al_load_bitmap_flags_f, al_load_bitmap, al_register_bitmap_loader_f, al_init_image_addon

al_load_bitmap_flags_f

ALLEGRO_BITMAP *al_load_bitmap_flags_f(ALLEGRO_FILE *fp,
   const char *ident, int flags)

Source Code

Loads an image from an ALLEGRO_FILE stream into a new ALLEGRO_BITMAP. The file type is determined by the passed 'ident' parameter, which is a file name extension including the leading dot. If (and only if) 'ident' is NULL, the file type is determined with al_identify_bitmap_f instead.

The flags parameter is the same as for al_load_bitmap_flags.

Returns NULL on error. The file remains open afterwards.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

Since: 5.1.0

See also: al_load_bitmap_f, al_load_bitmap_flags

al_save_bitmap

bool al_save_bitmap(const char *filename, ALLEGRO_BITMAP *bitmap)

Source Code

Saves an ALLEGRO_BITMAP to an image file. The file type is determined by the extension.

Returns true on success, false on error.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

See also: al_save_bitmap_f, al_register_bitmap_saver, al_init_image_addon

al_save_bitmap_f

bool al_save_bitmap_f(ALLEGRO_FILE *fp, const char *ident,
   ALLEGRO_BITMAP *bitmap)

Source Code

Saves an ALLEGRO_BITMAP to an ALLEGRO_FILE stream. The file type is determined by the passed 'ident' parameter, which is a file name extension including the leading dot.

Returns true on success, false on error. The file remains open afterwards.

Note: the core Allegro library does not support any image file formats by default. You must use the allegro_image addon, or register your own format handler.

See also: al_save_bitmap, al_register_bitmap_saver_f, al_init_image_addon

al_register_bitmap_identifier

bool al_register_bitmap_identifier(const char *extension,
   bool (*identifier)(ALLEGRO_FILE *f))

Source Code

Register an identify handler for al_identify_bitmap. The given function will be used to detect files for the given extension. It will be called with a single argument of type ALLEGRO_FILE which is a file handle opened for reading and located at the first byte of the file. The handler should try to read as few bytes as possible to safely determine if the given file contents correspond to the type with the extension and return true in that case, false otherwise. The file handle must not be closed but there is no need to reset it to the beginning.

The extension should include the leading dot ('.') character. It will be matched case-insensitively.

The identifier argument may be NULL to unregister an entry.

Returns true on success, false on error. Returns false if unregistering an entry that doesn't exist.

Since: 5.1.12

See also: al_identify_bitmap

al_identify_bitmap

char const *al_identify_bitmap(char const *filename)

Source Code

This works exactly as al_identify_bitmap_f but you specify the filename of the file for which to detect the type and not a file handle. The extension, if any, of the passed filename is not taken into account - only the file contents.

Since: 5.1.12

See also: al_init_image_addon, al_identify_bitmap_f, al_register_bitmap_identifier

al_identify_bitmap_f

char const *al_identify_bitmap_f(ALLEGRO_FILE *fp)

Source Code

Tries to guess the bitmap file type of the open ALLEGRO_FILE by reading the first few bytes. By default Allegro cannot recognize any file types, but calling al_init_image_addon will add detection of (some of) the types it can read. You can also use al_register_bitmap_identifier to add identification for custom file types.

Returns a pointer to a static string with a file extension for the type, including the leading dot. For example ".png" or ".jpg". Returns NULL if the bitmap type cannot be determined.

Since: 5.1.12

See also: al_init_image_addon, al_identify_bitmap, al_register_bitmap_identifier

Render State

ALLEGRO_RENDER_STATE

typedef enum ALLEGRO_RENDER_STATE {

Source Code

Possible render states which can be set with al_set_render_state:

ALLEGRO_ALPHA_TEST
If this is set to 1, the values of ALLEGRO_ALPHA_FUNCTION and ALLEGRO_ALPHA_TEST_VALUE define a comparison function which is performed for each pixel. Only if it evaluates to true the pixel is written. Otherwise no subsequent processing (like depth test or blending) is performed.
ALLEGRO_ALPHA_FUNCTION
One of ALLEGRO_RENDER_FUNCTION, only used when ALLEGRO_ALPHA_TEST is 1.
ALLEGRO_ALPHA_TEST_VALUE
Only used when ALLEGRO_ALPHA_TEST is 1.
ALLEGRO_WRITE_MASK
This determines how the framebuffer and depthbuffer are updated whenever a pixel is written (in case alpha and/or depth testing is enabled: after all such enabled tests succeed). Depth values are only written if ALLEGRO_DEPTH_TEST is 1, in addition to the write mask flag being set.
ALLEGRO_DEPTH_TEST
If this is set to 1, compare the depth value of any newly written pixels with the depth value already in the buffer, according to ALLEGRO_DEPTH_FUNCTION. Allegro primitives with no explicit z coordinate will write a value of 0 into the depth buffer.
ALLEGRO_DEPTH_FUNCTION
One of ALLEGRO_RENDER_FUNCTION, only used when ALLEGRO_DEPTH_TEST is 1.

Since: 5.1.2

See also: al_set_render_state, ALLEGRO_RENDER_FUNCTION, ALLEGRO_WRITE_MASK_FLAGS

ALLEGRO_RENDER_FUNCTION

typedef enum ALLEGRO_RENDER_FUNCTION {

Source Code

Possible functions are:

  • ALLEGRO_RENDER_NEVER
  • ALLEGRO_RENDER_ALWAYS
  • ALLEGRO_RENDER_LESS
  • ALLEGRO_RENDER_EQUAL
  • ALLEGRO_RENDER_LESS_EQUAL
  • ALLEGRO_RENDER_GREATER
  • ALLEGRO_RENDER_NOT_EQUAL
  • ALLEGRO_RENDER_GREATER_EQUAL

Since: 5.1.2

See also: al_set_render_state

ALLEGRO_WRITE_MASK_FLAGS

typedef enum ALLEGRO_WRITE_MASK_FLAGS {

Source Code

Each enabled bit means the corresponding value is written, a disabled bit means it is not.

  • ALLEGRO_MASK_RED
  • ALLEGRO_MASK_GREEN
  • ALLEGRO_MASK_BLUE
  • ALLEGRO_MASK_ALPHA
  • ALLEGRO_MASK_DEPTH
  • ALLEGRO_MASK_RGB - Same as RED | GREEN | BLUE.
  • ALLEGRO_MASK_RGBA - Same as RGB | ALPHA.

Since: 5.1.2

See also: al_set_render_state

al_set_render_state

void al_set_render_state(ALLEGRO_RENDER_STATE state, int value)

Source Code

Set one of several render attributes; see ALLEGRO_RENDER_STATE for details.

This function does nothing if the target bitmap is a memory bitmap.

Since: 5.1.2

See also: ALLEGRO_RENDER_STATE, ALLEGRO_RENDER_FUNCTION, ALLEGRO_WRITE_MASK_FLAGS

al_backup_dirty_bitmap

void al_backup_dirty_bitmap(ALLEGRO_BITMAP *bitmap)

Source Code

On some platforms, notably Windows Direct3D and Android, textures may be lost at any time for events such as display resize or switching out of the app. On those platforms, bitmaps created without the ALLEGRO_NO_PRESERVE_TEXTURE flag automatically get backed up to system memory every time al_flip_display is called.

This function gives you more control over when your bitmaps get backed up. By calling this function after modifying a bitmap, you can make sure the bitmap is backed up right away instead of during the next flip.

Since: 5.2.1

Unstable API: This API is new and subject to refinement.

See also: al_backup_dirty_bitmaps, al_create_bitmap

al_backup_dirty_bitmaps

void al_backup_dirty_bitmaps(ALLEGRO_DISPLAY *display)

Source Code

Backs up all of a display's bitmaps to system memory.

Since: 5.2.1

Unstable API: This API is new and subject to refinement.

See also: al_backup_dirty_bitmap

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:41 UTC


Haptic routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Haptic routines

  • ALLEGRO_HAPTIC
  • ALLEGRO_HAPTIC_CONSTANTS
  • ALLEGRO_HAPTIC_EFFECT
  • ALLEGRO_HAPTIC_EFFECT_ID
  • al_install_haptic
  • al_uninstall_haptic
  • al_is_haptic_installed
  • al_is_mouse_haptic
  • al_is_keyboard_haptic
  • al_is_display_haptic
  • al_is_joystick_haptic
  • al_is_touch_input_haptic
  • al_get_haptic_from_mouse
  • al_get_haptic_from_keyboard
  • al_get_haptic_from_display
  • al_get_haptic_from_joystick
  • al_get_haptic_from_touch_input
  • al_release_haptic
  • al_is_haptic_active
  • al_get_haptic_capabilities
  • al_is_haptic_capable
  • al_set_haptic_gain
  • al_get_haptic_gain
  • al_set_haptic_autocenter
  • al_get_haptic_autocenter
  • al_get_max_haptic_effects
  • al_is_haptic_effect_ok
  • al_upload_haptic_effect
  • al_play_haptic_effect
  • al_upload_and_play_haptic_effect
  • al_stop_haptic_effect
  • al_is_haptic_effect_playing
  • al_get_haptic_effect_duration
  • al_release_haptic_effect
  • al_rumble_haptic

Haptic functions support force feedback and vibration on input devices. These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

Currently force feedback is fully supported on Linux and on Windows for DirectInput compatible devices. There is also minimal support for Android. It is not yet supported on OSX, iOS, or on Windows for XInput compatible devices.

ALLEGRO_HAPTIC

typedef struct ALLEGRO_HAPTIC ALLEGRO_HAPTIC;

Source Code

This is an abstract data type representing a haptic device that supports force feedback or vibration.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

See also: al_get_haptic_from_joystick

ALLEGRO_HAPTIC_CONSTANTS

enum ALLEGRO_HAPTIC_CONSTANTS

Source Code

This enum contains flags that are used to define haptic effects and capabilities. If the flag is set in the return value of al_get_haptic_capabilities, it means the device supports the given effect. The value of these flags should be set into a ALLEGRO_HAPTIC_EFFECT struct to determine what kind of haptic effect should be played.

  • ALLEGRO_HAPTIC_RUMBLE - simple vibration effects
  • ALLEGRO_HAPTIC_PERIODIC - periodic, wave-form effects
  • ALLEGRO_HAPTIC_CONSTANT - constant effects
  • ALLEGRO_HAPTIC_SPRING - spring effects
  • ALLEGRO_HAPTIC_FRICTION - friction effects
  • ALLEGRO_HAPTIC_DAMPER - damper effects
  • ALLEGRO_HAPTIC_INERTIA - inertia effects
  • ALLEGRO_HAPTIC_RAMP - ramp effects
  • ALLEGRO_HAPTIC_SQUARE - square wave periodic effect
  • ALLEGRO_HAPTIC_TRIANGLE - triangle wave periodic effect
  • ALLEGRO_HAPTIC_SINE - sine wave periodic effect
  • ALLEGRO_HAPTIC_SAW_UP - upwards saw wave periodic effect
  • ALLEGRO_HAPTIC_SAW_DOWN - downwards saw wave periodic effect
  • ALLEGRO_HAPTIC_CUSTOM - custom wave periodic effect
  • ALLEGRO_HAPTIC_GAIN - the haptic device supports gain setting
  • ALLEGRO_HAPTIC_ANGLE - the haptic device supports angle coordinates
  • ALLEGRO_HAPTIC_RADIUS - the haptic device supports radius coordinates
  • ALLEGRO_HAPTIC_AZIMUTH - the haptic device supports azimuth coordinates
  • ALLEGRO_HAPTIC_AUTOCENTER

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

See also: al_get_haptic_capabilities, ALLEGRO_HAPTIC_EFFECT

ALLEGRO_HAPTIC_EFFECT

struct ALLEGRO_HAPTIC_EFFECT

Source Code

This struct models a particular haptic or vibration effect. It needs to be filled in correctly and uploaded to a haptic device before the device can play it back.

Fields:

type

The type of the haptic effect. May be one of the ALLEGRO_HAPTIC_CONSTANTS constants between or equal to ALLEGRO_HAPTIC_RUMBLE and ALLEGRO_HAPTIC_RAMP.

  • If type is set to ALLEGRO_HAPTIC_RUMBLE, then the effect is a simple "rumble" or vibration effect that shakes the device. In some cases, such as on a mobile platform, the whole device may shake.

  • If type is set to ALLEGRO_HAPTIC_PERIODIC, the effect is a shake or vibration of which the intensity is a periodic wave form.

  • If type is set to ALLEGRO_HAPTIC_CONSTANT, the effect is a constant pressure, motion or push-back in a certain direction of the axes of the device.

  • If type is set to ALLEGRO_HAPTIC_SPRING, the effect is a springy kind of resistance against motion of the axes of the haptic device.

  • If type is set to ALLEGRO_HAPTIC_FRICTION, the effect is a friction kind of resistance against motion of the axes of the haptic device.

  • If type is set to ALLEGRO_HAPTIC_DAMPER, the effect is a damper kind of resistance against motion of the axes of the haptic device.

  • If type is set to ALLEGRO_HAPTIC_INERTIA, the effect causes inertia or slowness of motions on the axes of the haptic device.

  • If type is set to ALLEGRO_HAPTIC_RAMP, the effect causes a pressure or push-back that ramps up or down depending on the position of the axis.

direction

The direction of location in 3D space where the effect should be played. Allegro haptic devices model directions in 3D space using spherical coordinates. However, the haptic device may not support localized effects, or may not support all coordinate components.

In Allegro's coordinate system, the value in direction.angle determines the planar angle between the effect and the direction of the user who holds the device, expressed in radians. This angle increases clockwise away from the user. So, an effect with an angle 0.0 takes place in the direction of the user of the haptic device, an angle of π/2 is to the left of the user, an angle of π means the direction away from the user, and an angle of 3π/2 means to the right of the user.

If al_get_haptic_capabilities has the flag ALLEGRO_HAPTIC_ANGLE set, then setting direction.angle is supported. Otherwise, it is unsupported, and you should set it to 0.

The value in direction.radius is a relative value between 0.0 and 1.0 that determines the relative distance from the center of the haptic device at which the effect will play back. A value of 0 means that the effect should play back at the center of the device. A value of 1.0 means that the effect should play back away from the center as far as is possible.

If al_get_haptic_capabilities has the flag ALLEGRO_HAPTIC_RADIUS set, then setting direction.radius is supported. Otherwise, it is unsupported, and you should set it to 0.

The value in direction.azimuth determines the elevation angle between the effect and the plane in which the user is holding the device, expressed in radians. An effect with an azimuth 0.0 plays back in the plane in which the user is holding the device, an azimuth +π/2 means the effect plays back vertically above the user plane, and an azimuth -π/2 means the effect plays back vertically below the user plane.

If al_get_haptic_capabilities has the flag ALLEGRO_HAPTIC_AZIMUTH set, then setting direction.azimuth is supported. Otherwise, it is unsupported, and you should set it to 0.

replay
Determines how the effect should be played back. replay.length is the duration in seconds of the effect, and replay.delay is the time in seconds that the effect playback should be delayed when playback is started with al_play_haptic_effect.
data

Determines in detail the parameters of the haptic effect to play back.

If type is set to ALLEGRO_HAPTIC_RUMBLE, then data.rumble.strong_magnitude must be set to a relative magnitude between 0.0 and 1.0 to determine how intensely the "large" rumble motor of the haptic device will vibrate, and data.rumble.weak_magnitude must be set to relative magnitude between 0.0 and 1.0 to determine how intensely the "weak" ruble motor of the haptic device will vibrate. Not all devices have a "weak" motor, in which case the value set in data.rumble.weak_magnitude will be ignored.

If type is set to ALLEGRO_HAPTIC_PERIODIC, then data.periodic.waveform must be set to one of ALLEGRO_HAPTIC_SQUARE, ALLEGRO_HAPTIC_TRIANGLE, ALLEGRO_HAPTIC_SINE, ALLEGRO_HAPTIC_SAW_UP, ALLEGRO_HAPTIC_SAW_DOWN, ALLEGRO_HAPTIC_CUSTOM. This will then determine the wave form of the vibration effect that will be played on the haptic device.

In these cases, data.periodic.period must be set to the period in seconds of the wave form. The field data.periodic.magnitude must be set to the relative magnitude of intensity between -1.0 and 1.0 at which the wave form of the vibration will be played back. The field data.periodic.offset must be filled in with the offset from origin in seconds of the wave form of vibration, and the field data.periodic.phase is the phase of the wave form of vibration in seconds.

If data.periodic.waveform is set to ALLEGRO_HAPTIC_CUSTOM, then data.periodic.custom_data must point to an array of data.periodic.custom_len doubles, each with values between -1.0 and 1.0. This value array will determine the shape of the wave form of the haptic effect. ALLEGRO_HAPTIC_CUSTOM is not supported on some platforms, so use al_get_haptic_capabilities to check if it's available. If it isn't, you may want to play back a non-custom wave effect as a substitute instead.

If type is set to ALLEGRO_HAPTIC_CONSTANT, then data.constant.level must be set to a relative intensity value between 0.0 and 1.0 to determine the intensity of the effect.

If type is set to any of ALLEGRO_HAPTIC_SPRING, ALLEGRO_HAPTIC_FRICTION, ALLEGRO_HAPTIC_DAMPER, ALLEGRO_HAPTIC_INERTIA, ALLEGRO_HAPTIC_RAMP, then the data.condition struct should be filled in. To explain this better, it's best to keep in mind that these kinds of effects are most useful for steering-wheel kind of devices, where resistance or inertia should be applied when turning the device's wheel a certain distance to the left or right.

The field data.condition.right_saturation must be filled in with a relative magnitude between -1.0 and 1.0 to determine the intensity of resistance or inertia on the "right" side of the axis. Likewise, data.condition.left_saturation must be filled in with a relative magnitude between -1.0 and 1.0 to determine the intensity of resistance or inertia on the "left" side of the axis.

The field data.condition.deadband must be filled in with a relative value between 0.0 and 1.0 to determine the relative width of the "dead band" of the haptic effect. As long as the axis of the haptic device remains in the "dead band" area, the effect will not be applied. A value of 0.0 means there is no dead band, and a value of 1.0 means it applied over the whole range of the axis in question.

The field data.condition.center must be filled in with a relative value between -1.0 and 1.0 to determine the relative position of the "center" of the effect around which the dead band is centered. It should be set to 0.0 in case the center should not be shifted.

The field data.condition.right_coef and data.condition.right_left_coef must be filled in with a relative coefficient, that will determine how quickly the effect ramps up on the right and left side. If set to 1.0, then the effect will be immediately at full intensity when outside of the dead band. If set to 0.0 the effect will not be felt at all.

If type is set to ALLEGRO_HAPTIC_RAMP, then data.ramp.start_level should be set to a relative magnitude value between -1.0 and 1.0 to determine the initial intensity of the haptic effect. The field data.ramp.end_level should be set to a relative magnitude value between -1.0 and 1.0 to determine the final intensity of the haptic effect at the end of playback.

If type is set to any of ALLEGRO_HAPTIC_PERIODIC, ALLEGRO_HAPTIC_CONSTANT, ALLEGRO_HAPTIC_RAMP, then data.envelope determines the "envelope" of the effect. That is, it determines the duration and intensity for the ramp-up attack or "fade in" and the ramp-down or "fade out" of the effect.

In these cases the field data.envelope.attack_level must be set to a relative value between 0.0 and 1.0 that determines the intensity the effect should have when it starts playing (after replay.delay seconds have passed since the playback was started). The field data.envelope.attack_length must be set to the time in seconds that the effect should ramp up to the maximum intensity as set by the other parameters. If data.envelope.attack_length is 0, then the effect will play immediately at full intensity.

The field data.envelope.fade_level must be set to a relative value between 0.0 and 1.0 that determines the intensity the effect should have when it stops playing after replay.length + replay.delay seconds have passed since the playback of the effect started. The field data.envelope.fade_length must be set to the time in seconds that the effect should fade out before it finishes playing. If data.envelope.fade_length is 0, then the effect will not fade out.

If you don't want to use an envelope, then set all four fields of data.envelope to 0.0. The effect will then play back at full intensity throughout its playback.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

ALLEGRO_HAPTIC_EFFECT_ID

typedef struct ALLEGRO_HAPTIC_EFFECT_ID ALLEGRO_HAPTIC_EFFECT_ID;

Source Code

This struct is used as a handle to control playback of a haptic effect and should be considered opaque. Its implementation is visible merely to allow allocation by the users of the Allegro library.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_install_haptic

bool al_install_haptic(void)

Source Code

Installs the haptic (force feedback) device subsystem. This must be called before using any other haptic-related functions. Returns true if the haptics subsystem could be initialized correctly, false in case of error.

For portability you should first open a display before calling al_install_haptic. On some platforms, such as DirectInput under Windows, al_install_haptic will only work if at least one active display is available. This display must stay available until al_uninstall_haptic is called.

If you need to close and reopen your active display for example, then you should call al_uninstall_haptic before closing the display, and al_install_haptic after opening it again.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_uninstall_haptic

void al_uninstall_haptic(void)

Source Code

Uninstalls the haptic device subsystem. This is useful since on some platforms haptic effects are bound to the active display.

If you need to close and reopen your active display for example, then you should call al_uninstall_haptic before closing the display, and al_install_haptic after opening it again.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_haptic_installed

bool al_is_haptic_installed(void)

Source Code

Returns true if the haptic device subsystem is installed, false if not.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_mouse_haptic

bool al_is_mouse_haptic(ALLEGRO_MOUSE *dev)

Source Code

Returns true if the mouse has haptic capabilities, false if not.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_keyboard_haptic

bool al_is_keyboard_haptic(ALLEGRO_KEYBOARD *dev)

Source Code

Returns true if the keyboard has haptic capabilities, false if not.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_display_haptic

bool al_is_display_haptic(ALLEGRO_DISPLAY *dev)

Source Code

Returns true if the display has haptic capabilities, false if not. This mainly concerns force feedback that shakes a hand held device, such as a phone or a tablet.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_joystick_haptic

bool al_is_joystick_haptic(ALLEGRO_JOYSTICK *dev)

Source Code

Returns true if the joystick has haptic capabilities, false if not.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_touch_input_haptic

bool al_is_touch_input_haptic(ALLEGRO_TOUCH_INPUT *dev)

Source Code

Returns true if the touch input device has haptic capabilities, false if not.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_from_mouse

ALLEGRO_HAPTIC *al_get_haptic_from_mouse(ALLEGRO_MOUSE *dev)

Source Code

If the mouse has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_from_keyboard

ALLEGRO_HAPTIC *al_get_haptic_from_keyboard(ALLEGRO_KEYBOARD *dev)

Source Code

If the keyboard has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_from_display

ALLEGRO_HAPTIC *al_get_haptic_from_display(ALLEGRO_DISPLAY *dev)

Source Code

If the display has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_from_joystick

ALLEGRO_HAPTIC *al_get_haptic_from_joystick(ALLEGRO_JOYSTICK *dev)

Source Code

If the joystick has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL. It's necessary to call this again every time the joystick configuration changes, such as through hot plugging. In that case, the old haptic device must be released using al_release_haptic.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_from_touch_input

ALLEGRO_HAPTIC *al_get_haptic_from_touch_input(ALLEGRO_TOUCH_INPUT *dev)

Source Code

If the touch input device has haptic capabilities, returns the associated haptic device handle. Otherwise returns NULL.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_release_haptic

bool al_release_haptic(ALLEGRO_HAPTIC *haptic)

Source Code

Releases the haptic device and its resources when it's not needed anymore. Should also be used in case the joystick configuration changed, such as when a joystick is hot plugged. This function also automatically releases all haptic effects that are still uploaded to the device and that have not been released manually using al_release_haptic_effect.

Returns true on success or false if the haptic device couldn't be released for any reason, such as NULL being passed, the device not being active or failure in the driver.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_haptic_active

bool al_is_haptic_active(ALLEGRO_HAPTIC *hap)

Source Code

Returns true if the haptic device can currently be used, false if not.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_capabilities

int al_get_haptic_capabilities(ALLEGRO_HAPTIC *hap)

Source Code

Returns an integer with or'ed values from ALLEGRO_HAPTIC_CONSTANTS, which, if set, indicate that the haptic device supports the given feature.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_haptic_capable

bool al_is_haptic_capable(ALLEGRO_HAPTIC * hap, int query) {

Source Code

Returns true if the haptic device supports the feature indicated by the query parameter, false if the feature is not supported. The query parameter must be one of the values of ALLEGRO_HAPTIC_CONSTANTS.

Since: 5.1.9

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

See also: al_get_haptic_capabilities

al_set_haptic_gain

bool al_set_haptic_gain(ALLEGRO_HAPTIC *hap, double gain)

Source Code

Sets the gain of the haptic device if supported. Gain is much like volume for sound, it is as if every effect's intensity is multiplied by it. Gain is a value between 0.0 and 1.0. Returns true if set successfully, false if not. Only works if al_get_haptic_capabilities returns a value that has ALLEGRO_HAPTIC_GAIN set. If not, this function returns false, and all effects will be played without any gain influence.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_gain

double al_get_haptic_gain(ALLEGRO_HAPTIC *hap)

Source Code

Returns the current gain of the device. Gain is much like volume for sound, it is as if every effect's intensity is multiplied by it. Gain is a value between 0.0 and 1.0. Only works correctly if al_get_haptic_capabilities returns a value that has ALLEGRO_HAPTIC_GAIN set. If this is not set, this function will simply return 1.0 and all effects will be played without any gain influence.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_set_haptic_autocenter

bool al_set_haptic_autocenter(ALLEGRO_HAPTIC *hap, double intensity)

Source Code

Turns on or off the automatic centering feature of the haptic device if supported. Depending on the device automatic centering may ensure that the axes of the device are centered again automatically after playing a haptic effect. The intensity parameter should be passed with a value between 0.0 and 1.0. The value 0.0 means automatic centering is disabled, and 1.0 means full strength automatic centering. Any value in between those two extremes will result in partial automatic centering. Some platforms do not support partial automatic centering. If that is the case, a value of less than 0.5 will turn it off, while a value equal to or higher to 0.5 will turn it on. Returns true if set successfully, false if not. Can only work if al_get_haptic_capabilities returns a value that has ALLEGRO_HAPTIC_AUTOCENTER set. If not, this function returns false.

Since: 5.1.9

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_autocenter

double al_get_haptic_autocenter(ALLEGRO_HAPTIC *hap)

Source Code

Returns the current automatic centering intensity of the device. Depending on the device automatic centering may ensure that the axes of the device are centered again automatically after playing a haptic effect. The return value can be between 0.0 and 1.0. The value 0.0 means automatic centering is disabled, and 1.0 means automatic centering is enabled at full strength. Any value in between those two extremes means partial automatic centering is enabled. Some platforms do not support partial automatic centering. If that is the case, a value of less than 0.5 means it is turned off, while a value equal to or higher to 0.5 means it is turned on. Can only work if al_get_haptic_capabilities returns a value that has ALLEGRO_HAPTIC_AUTOCENTER set. If not, this function returns 0.0.

Since: 5.1.9

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_max_haptic_effects

int al_get_max_haptic_effects(ALLEGRO_HAPTIC *hap)

Source Code

Returns the maximum amount of haptic effects that can be uploaded to the device. This depends on the operating system, driver, platform and the device itself. This may return a value as low as 1.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_haptic_effect_ok

bool al_is_haptic_effect_ok(ALLEGRO_HAPTIC *hap, ALLEGRO_HAPTIC_EFFECT *effect)

Source Code

Returns true if the haptic device can play the haptic effect as given, false if not. The haptic effect must have been filled in completely and correctly.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_upload_haptic_effect

bool al_upload_haptic_effect(ALLEGRO_HAPTIC *hap,
   ALLEGRO_HAPTIC_EFFECT *effect, ALLEGRO_HAPTIC_EFFECT_ID *id)

Source Code

Uploads the haptic effect to the device. The haptic effect must have been filled in completely and correctly. You must also pass in a pointer to a user allocated ALLEGRO_HAPTIC_EFFECT_ID. This id can be used to control playback of the effect. Returns true if the effect was successfully uploaded, false if not.

The function al_get_max_haptic_effects returns how many effects can be uploaded to the device at the same time.

The same haptic effect can be uploaded several times, as long as care is taken to pass in a different ALLEGRO_HAPTIC_EFFECT_ID.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_play_haptic_effect

bool al_play_haptic_effect(ALLEGRO_HAPTIC_EFFECT_ID *id, int loop)

Source Code

Plays back a previously uploaded haptic effect. The play_id must be a valid ALLEGRO_HAPTIC_EFFECT_ID obtained from al_upload_haptic_effect, al_upload_and_play_haptic_effect or al_rumble_haptic.

The haptic effect will be played back loop times in sequence. If loop is less than or equal to 1, then the effect will be played once only.

This function returns immediately and doesn't wait for the playback to finish. It returns true if the playback was started successfully or false if not.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_upload_and_play_haptic_effect

bool al_upload_and_play_haptic_effect(ALLEGRO_HAPTIC *hap,
   ALLEGRO_HAPTIC_EFFECT *effect, ALLEGRO_HAPTIC_EFFECT_ID *id, int loop)

Source Code

Uploads the haptic effect to the device and starts playback immediately. Returns true if the upload and playback were successful, false if either failed.

In case false is returned, the haptic effect will be automatically released as if al_release_haptic_effect had been called, so there is no need to call it again manually in this case. However, if true is returned, it is necessary to call al_release_haptic_effect when the effect isn't needed anymore, to prevent the amount of available effects on the haptic devicefrom running out.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

See also: al_upload_haptic_effect, al_play_haptic_effect

al_stop_haptic_effect

bool al_stop_haptic_effect(ALLEGRO_HAPTIC_EFFECT_ID *id)

Source Code

Stops playing a previously uploaded haptic effect. The play_id must be a valid ALLEGRO_HAPTIC_EFFECT_ID obtained from al_upload_haptic_effect, al_upload_and_play_haptic_effect or al_rumble_haptic.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_is_haptic_effect_playing

bool al_is_haptic_effect_playing(ALLEGRO_HAPTIC_EFFECT_ID *id)

Source Code

Returns true if the haptic effect is currently playing. Returns false if the effect has been stopped or if it has already finished playing, or if it has not been played yet. The play_id must be a valid ALLEGRO_HAPTIC_EFFECT_ID obtained from al_upload_haptic_effect, al_upload_and_play_haptic_effect or al_rumble_haptic.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_get_haptic_effect_duration

double al_get_haptic_effect_duration(ALLEGRO_HAPTIC_EFFECT * effect)

Source Code

Returns the estimated duration in seconds of a single loop of the given haptic effect. The effect's effect.replay must have been filled in correctly before using this function.

Since: 5.1.9

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_release_haptic_effect

bool al_release_haptic_effect(ALLEGRO_HAPTIC_EFFECT_ID *id)

Source Code

Releases a previously uploaded haptic effect from the device it has been uploaded to, allowing for other effects to be uploaded. The play_id must be a valid ALLEGRO_HAPTIC_EFFECT_ID obtained from al_upload_haptic_effect, al_upload_and_play_haptic_effect or al_rumble_haptic.

This function is called automatically when you call al_release_haptic on a ALLEGRO_HAPTIC for all effects that are still uploaded to the device. Therefore this function is most useful if you want to upload and release haptic effects dynamically, for example as a way to circumvent the limit imposed by al_get_max_haptic_effects.

Returns true on success, false if the effect couldn't be released for any reason such as when NULL is passed, the effect is not active or failure to release the effect by the driver.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

al_rumble_haptic

bool al_rumble_haptic(ALLEGRO_HAPTIC *hap,
   double intensity, double duration, ALLEGRO_HAPTIC_EFFECT_ID *id)

Source Code

Uploads a simple rumble effect to the haptic device and starts playback immediately. The parameter intensity is a relative magnitude between 0.0 and 1.0 that determines the intensity of the rumble effect. The duration determines the duration of the effect in seconds.

You must also pass in a pointer to a user allocated ALLEGRO_HAPTIC_EFFECT_ID. It it is stored a reference to be used to control playback of the effect. Returns true if the rumble effect was successfully uploaded and started, false if not.

In case false is returned, the rumble effect will be automatically released as if al_release_haptic_effect had been called, so there is no need to call it again manually in this case. However, if true is returned, it is necessary to call al_release_haptic_effect when the effect isn't needed anymore, to prevent the amount of available effects on the haptic device from running out.

Since: 5.1.8

Unstable API: Perhaps could be simplified due to limited support for all the exposed features across all of the platforms. Awaiting feedback from users.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:15 UTC


Image I/O addon

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Image I/O addon

  • al_init_image_addon
  • al_shutdown_image_addon
  • al_get_allegro_image_version

These functions are declared in the following header file. Link with allegro_image.

 #include <allegro5/allegro_image.h>

Some of the format handlers define configuration options for specifying things like compression level or gamma handling. Refer to al_get_system_config for their documentation.

al_init_image_addon

bool al_init_image_addon(void)

Source Code

Initializes the image addon. This registers bitmap format handlers for al_load_bitmap, al_load_bitmap_f, al_save_bitmap, al_save_bitmap_f.

The following types are built into the Allegro image addon and guaranteed to be available: BMP, DDS, PCX, TGA. Every platform also supports JPEG and PNG via external dependencies.

Other formats may be available depending on the operating system and installed libraries, but are not guaranteed and should not be assumed to be universally available.

The DDS format is only supported to load from, and only if the DDS file contains textures compressed in the DXT1, DXT3 and DXT5 formats. Note that when loading a DDS file, the created bitmap will always be a video bitmap and will have the pixel format matching the format in the file.

al_shutdown_image_addon

void al_shutdown_image_addon(void)

Source Code

Shut down the image addon. This is done automatically at program exit, but can be called any time the user wishes as well.

al_get_allegro_image_version

uint32_t al_get_allegro_image_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:19 UTC


Allegro 5 reference manual

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Allegro 5 reference manual

  • Core API
  • Addons
  • Getting started guide

Core API

  • Configuration files
  • Displays
  • Events
  • File I/O
  • Filesystem
  • Fixed point math
  • Fullscreen modes
  • Graphics routines
  • Haptic routines
  • Joystick routines
  • Keyboard routines
  • Memory management
  • Monitors
  • Mouse routines
  • Path structures
  • Shader
  • State
  • System routines
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8 string routines
  • Miscellaneous
  • Platform-specific
  • Direct3D integration
  • OpenGL integration

Addons

  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:20 UTC


Index

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Index

  • ALLEGRO_AUDIO_DEPTH
  • ALLEGRO_AUDIO_EVENT_TYPE
  • ALLEGRO_AUDIO_PAN_NONE
  • ALLEGRO_AUDIO_RECORDER
  • ALLEGRO_AUDIO_RECORDER_EVENT
  • ALLEGRO_AUDIO_STREAM
  • ALLEGRO_BITMAP
  • ALLEGRO_BPM_TO_SECS
  • ALLEGRO_BPS_TO_SECS
  • ALLEGRO_CHANNEL_CONF
  • ALLEGRO_COLOR
  • ALLEGRO_COND
  • ALLEGRO_CONFIG
  • ALLEGRO_CONFIG_ENTRY
  • ALLEGRO_CONFIG_SECTION
  • ALLEGRO_DISPLAY
  • ALLEGRO_DISPLAY_MODE
  • ALLEGRO_EVENT
  • ALLEGRO_EVENT_AUDIO_RECORDER_FRAGMENT
  • ALLEGRO_EVENT_AUDIO_STREAM_FINISHED
  • ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT
  • ALLEGRO_EVENT_DISPLAY_CLOSE
  • ALLEGRO_EVENT_DISPLAY_CONNECTED
  • ALLEGRO_EVENT_DISPLAY_DISCONNECTED
  • ALLEGRO_EVENT_DISPLAY_EXPOSE
  • ALLEGRO_EVENT_DISPLAY_FOUND
  • ALLEGRO_EVENT_DISPLAY_HALT_DRAWING
  • ALLEGRO_EVENT_DISPLAY_LOST
  • ALLEGRO_EVENT_DISPLAY_ORIENTATION
  • ALLEGRO_EVENT_DISPLAY_RESIZE
  • ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING
  • ALLEGRO_EVENT_DISPLAY_SWITCH_IN
  • ALLEGRO_EVENT_DISPLAY_SWITCH_OUT
  • ALLEGRO_EVENT_JOYSTICK_AXIS
  • ALLEGRO_EVENT_JOYSTICK_BUTTON_DOWN
  • ALLEGRO_EVENT_JOYSTICK_BUTTON_UP
  • ALLEGRO_EVENT_JOYSTICK_CONFIGURATION
  • ALLEGRO_EVENT_KEY_CHAR
  • ALLEGRO_EVENT_KEY_DOWN
  • ALLEGRO_EVENT_KEY_UP
  • ALLEGRO_EVENT_MOUSE_AXES
  • ALLEGRO_EVENT_MOUSE_BUTTON_DOWN
  • ALLEGRO_EVENT_MOUSE_BUTTON_UP
  • ALLEGRO_EVENT_MOUSE_ENTER_DISPLAY
  • ALLEGRO_EVENT_MOUSE_LEAVE_DISPLAY
  • ALLEGRO_EVENT_MOUSE_WARPED
  • ALLEGRO_EVENT_QUEUE
  • ALLEGRO_EVENT_SOURCE
  • ALLEGRO_EVENT_TIMER
  • ALLEGRO_EVENT_TOUCH_BEGIN
  • ALLEGRO_EVENT_TOUCH_CANCEL
  • ALLEGRO_EVENT_TOUCH_END
  • ALLEGRO_EVENT_TOUCH_MOVE
  • ALLEGRO_EVENT_TYPE
  • ALLEGRO_EVENT_TYPE_IS_USER
  • ALLEGRO_EVENT_VIDEO_FINISHED
  • ALLEGRO_EVENT_VIDEO_FRAME_SHOW
  • ALLEGRO_FILE
  • ALLEGRO_FILECHOOSER
  • ALLEGRO_FILE_INTERFACE
  • ALLEGRO_FILE_MODE
  • ALLEGRO_FONT
  • ALLEGRO_FOR_EACH_FS_ENTRY_RESULT
  • ALLEGRO_FS_ENTRY
  • ALLEGRO_FS_INTERFACE
  • ALLEGRO_GET_EVENT_TYPE
  • ALLEGRO_GLYPH
  • ALLEGRO_HAPTIC
  • ALLEGRO_HAPTIC_CONSTANTS
  • ALLEGRO_HAPTIC_EFFECT
  • ALLEGRO_HAPTIC_EFFECT_ID
  • ALLEGRO_INDEX_BUFFER
  • ALLEGRO_JOYFLAGS
  • ALLEGRO_JOYSTICK
  • ALLEGRO_JOYSTICK_STATE
  • ALLEGRO_KEYBOARD_STATE
  • ALLEGRO_LINE_CAP
  • ALLEGRO_LINE_JOIN
  • ALLEGRO_LOCKED_REGION
  • ALLEGRO_MEMORY_INTERFACE
  • ALLEGRO_MENU
  • ALLEGRO_MENU_INFO
  • ALLEGRO_MIXER
  • ALLEGRO_MIXER_QUALITY
  • ALLEGRO_MONITOR_INFO
  • ALLEGRO_MOUSE_EMULATION_MODE
  • ALLEGRO_MOUSE_STATE
  • ALLEGRO_MSECS_TO_SECS
  • ALLEGRO_MUTEX
  • ALLEGRO_NEW_WINDOW_TITLE_MAX_SIZE
  • ALLEGRO_PI
  • ALLEGRO_PIXEL_FORMAT
  • ALLEGRO_PLAYMODE
  • ALLEGRO_PRIM_ATTR
  • ALLEGRO_PRIM_BUFFER_FLAGS
  • ALLEGRO_PRIM_QUALITY
  • ALLEGRO_PRIM_STORAGE
  • ALLEGRO_PRIM_TYPE
  • ALLEGRO_RENDER_FUNCTION
  • ALLEGRO_RENDER_STATE
  • ALLEGRO_SAMPLE
  • ALLEGRO_SAMPLE_ID
  • ALLEGRO_SAMPLE_INSTANCE
  • ALLEGRO_SEEK
  • ALLEGRO_SHADER
  • ALLEGRO_SHADER_PLATFORM
  • ALLEGRO_SHADER_TYPE
  • ALLEGRO_STATE
  • ALLEGRO_STATE_FLAGS
  • ALLEGRO_TEXTLOG
  • ALLEGRO_THREAD
  • ALLEGRO_TIMEOUT
  • ALLEGRO_TIMER
  • ALLEGRO_TOUCH_INPUT
  • ALLEGRO_TOUCH_INPUT_MAX_TOUCH_COUNT
  • ALLEGRO_TOUCH_INPUT_STATE
  • ALLEGRO_TOUCH_STATE
  • ALLEGRO_TRANSFORM
  • ALLEGRO_USECS_TO_SECS
  • ALLEGRO_USER_EVENT
  • ALLEGRO_USTR
  • ALLEGRO_USTR_INFO
  • ALLEGRO_VERTEX
  • ALLEGRO_VERTEX_BUFFER
  • ALLEGRO_VERTEX_CACHE_SIZE
  • ALLEGRO_VERTEX_DECL
  • ALLEGRO_VERTEX_ELEMENT
  • ALLEGRO_VIDEO_EVENT_TYPE
  • ALLEGRO_VIDEO_POSITION_TYPE
  • ALLEGRO_VOICE
  • ALLEGRO_WRITE_MASK_FLAGS
  • About UTF-8 string routines
  • Alternative file streams
  • Alternative filesystem functions
  • Android
  • Appending to strings
  • Assigning one string to another
  • Audio addon
  • Audio codecs addon
  • Audio file I/O
  • Audio recording
  • Audio types
  • Bitmap creation
  • Bitmap fonts
  • Bitmap properties
  • Blending
  • Blending modes
  • Changing the drawing target
  • Clipboard
  • Clipping
  • Color addon
  • Colors
  • Comparing
  • Configuration files
  • Creating and destroying strings
  • Creating strings by referencing other data
  • Custom vertex declaration routines
  • Deferred drawing
  • Direct3D integration
  • Directory functions
  • Display an image
  • Display creation
  • Display operations
  • Display settings
  • Display size and position
  • Displaying some text
  • Displays
  • Drawing halts
  • Drawing operations
  • Drawing primitives
  • Event queues and input
  • Event system and events
  • File I/O
  • File system routines
  • Fixed point math routines
  • Fixed point trig
  • Font addons
  • Fullscreen modes
  • General
  • General font routines
  • Getting code points
  • Getting started guide
  • Graphics routines
  • Graphics utility functions
  • Haptic routines
  • High level drawing routines
  • Image I/O
  • Image I/O addon
  • Index buffer routines
  • Initialisation
  • Inserting into strings
  • Introduction
  • Joystick routines
  • Key codes
  • Keyboard modifier flags
  • Keyboard routines
  • Locking and pixel formats
  • Low level drawing routines
  • Low-level UTF-16 routines
  • Low-level UTF-8 routines
  • Mac OS X
  • Main addon
  • Memfile interface
  • Memory management routines
  • Menus
  • Misc audio functions
  • Miscellaneous routines
  • Mixer functions
  • Monitors
  • Monster description
  • Mouse cursors
  • Mouse routines
  • Multiline text drawing
  • Native dialogs support
  • Not the end
  • OpenGL configuration
  • OpenGL integration
  • Opening a window
  • Path structures
  • Per glyph text handling
  • PhysicsFS integration
  • Pixel-precise output
  • Platform-specific functions
  • Polygon routines
  • Predefined strings
  • Primitives addon
  • Removing parts of strings
  • Render State
  • Replacing parts of string
  • Sample functions
  • Sample instance functions
  • Screensaver
  • Searching
  • Setting up audio
  • Shader routines
  • Sizes and offsets
  • Sound
  • Standard I/O specific routines
  • State
  • Stream functions
  • Structure of the library and its addons
  • Structures and types
  • System routines
  • TTF fonts
  • Target bitmap
  • The main function
  • Threads
  • Time routines
  • Timer routines
  • Touch input
  • Transformations
  • UTF-16 conversion
  • UTF-8 string routines
  • UTF-8 string types
  • Unstable API
  • Vertex buffer routines
  • Video streaming addon
  • Voice functions
  • Windows
  • X11
  • al_acknowledge_drawing_halt
  • al_acknowledge_drawing_resume
  • al_acknowledge_resize
  • al_add_config_comment
  • al_add_config_section
  • al_add_new_bitmap_flag
  • al_add_timer_count
  • al_android_get_activity
  • al_android_get_jni_env
  • al_android_get_os_version
  • al_android_set_apk_file_interface
  • al_android_set_apk_fs_interface
  • al_append_menu_item
  • al_append_native_text_log
  • al_append_path_component
  • al_apply_window_constraints
  • al_attach_audio_stream_to_mixer
  • al_attach_audio_stream_to_voice
  • al_attach_mixer_to_mixer
  • al_attach_mixer_to_voice
  • al_attach_sample_instance_to_mixer
  • al_attach_sample_instance_to_voice
  • al_attach_shader_source
  • al_attach_shader_source_file
  • al_backup_dirty_bitmap
  • al_backup_dirty_bitmaps
  • al_broadcast_cond
  • al_build_camera_transform
  • al_build_menu
  • al_build_shader
  • al_build_transform
  • al_calculate_arc
  • al_calculate_ribbon
  • al_calculate_spline
  • al_calloc
  • al_calloc_with_context
  • al_change_directory
  • al_check_inverse
  • al_clear_depth_buffer
  • al_clear_keyboard_state
  • al_clear_to_color
  • al_clipboard_has_text
  • al_clone_bitmap
  • al_clone_menu
  • al_clone_menu_for_popup
  • al_clone_path
  • al_close_directory
  • al_close_native_text_log
  • al_close_video
  • al_color_cmyk
  • al_color_cmyk_to_rgb
  • al_color_distance_ciede2000_lab
  • al_color_hsl
  • al_color_hsl_to_rgb
  • al_color_hsv
  • al_color_hsv_to_rgb
  • al_color_html
  • al_color_html_to_rgb
  • al_color_lab
  • al_color_lab_to_rgb
  • al_color_lch
  • al_color_lch_to_rgb
  • al_color_name
  • al_color_name_to_rgb
  • al_color_rgb_to_cmyk
  • al_color_rgb_to_hsl
  • al_color_rgb_to_hsv
  • al_color_rgb_to_html
  • al_color_rgb_to_lab
  • al_color_rgb_to_lch
  • al_color_rgb_to_name
  • al_color_rgb_to_xyy
  • al_color_rgb_to_xyz
  • al_color_rgb_to_yuv
  • al_color_xyy
  • al_color_xyy_to_rgb
  • al_color_xyz
  • al_color_xyz_to_rgb
  • al_color_yuv
  • al_color_yuv_to_rgb
  • al_compose_transform
  • al_convert_bitmap
  • al_convert_mask_to_alpha
  • al_convert_memory_bitmaps
  • al_copy_transform
  • al_create_audio_recorder
  • al_create_audio_stream
  • al_create_bitmap
  • al_create_builtin_font
  • al_create_cond
  • al_create_config
  • al_create_display
  • al_create_event_queue
  • al_create_file_handle
  • al_create_fs_entry
  • al_create_index_buffer
  • al_create_menu
  • al_create_mixer
  • al_create_mouse_cursor
  • al_create_mutex
  • al_create_mutex_recursive
  • al_create_native_file_dialog
  • al_create_path
  • al_create_path_for_directory
  • al_create_popup_menu
  • al_create_sample
  • al_create_sample_instance
  • al_create_shader
  • al_create_sub_bitmap
  • al_create_thread
  • al_create_timer
  • al_create_vertex_buffer
  • al_create_vertex_decl
  • al_create_voice
  • al_cstr
  • al_cstr_dup
  • al_destroy_audio_recorder
  • al_destroy_audio_stream
  • al_destroy_bitmap
  • al_destroy_cond
  • al_destroy_config
  • al_destroy_display
  • al_destroy_event_queue
  • al_destroy_font
  • al_destroy_fs_entry
  • al_destroy_index_buffer
  • al_destroy_menu
  • al_destroy_mixer
  • al_destroy_mouse_cursor
  • al_destroy_mutex
  • al_destroy_native_file_dialog
  • al_destroy_path
  • al_destroy_sample
  • al_destroy_sample_instance
  • al_destroy_shader
  • al_destroy_thread
  • al_destroy_timer
  • al_destroy_user_event_source
  • al_destroy_vertex_buffer
  • al_destroy_vertex_decl
  • al_destroy_voice
  • al_detach_audio_stream
  • al_detach_mixer
  • al_detach_sample_instance
  • al_detach_voice
  • al_disable_menu_event_source
  • al_do_multiline_text
  • al_do_multiline_ustr
  • al_drain_audio_stream
  • al_draw_arc
  • al_draw_bitmap
  • al_draw_bitmap_region
  • al_draw_circle
  • al_draw_ellipse
  • al_draw_elliptical_arc
  • al_draw_filled_circle
  • al_draw_filled_ellipse
  • al_draw_filled_pieslice
  • al_draw_filled_polygon
  • al_draw_filled_polygon_with_holes
  • al_draw_filled_rectangle
  • al_draw_filled_rounded_rectangle
  • al_draw_filled_triangle
  • al_draw_glyph
  • al_draw_indexed_buffer
  • al_draw_indexed_prim
  • al_draw_justified_text
  • al_draw_justified_textf
  • al_draw_justified_ustr
  • al_draw_line
  • al_draw_multiline_text
  • al_draw_multiline_textf
  • al_draw_multiline_ustr
  • al_draw_pieslice
  • al_draw_pixel
  • al_draw_polygon
  • al_draw_polyline
  • al_draw_prim
  • al_draw_rectangle
  • al_draw_ribbon
  • al_draw_rotated_bitmap
  • al_draw_rounded_rectangle
  • al_draw_scaled_bitmap
  • al_draw_scaled_rotated_bitmap
  • al_draw_soft_line
  • al_draw_soft_triangle
  • al_draw_spline
  • al_draw_text
  • al_draw_textf
  • al_draw_tinted_bitmap
  • al_draw_tinted_bitmap_region
  • al_draw_tinted_rotated_bitmap
  • al_draw_tinted_scaled_bitmap
  • al_draw_tinted_scaled_rotated_bitmap
  • al_draw_tinted_scaled_rotated_bitmap_region
  • al_draw_triangle
  • al_draw_ustr
  • al_draw_vertex_buffer
  • al_drop_next_event
  • al_drop_path_tail
  • al_emit_user_event
  • al_enable_menu_event_source
  • al_fclearerr
  • al_fclose
  • al_feof
  • al_ferrmsg
  • al_ferror
  • al_fflush
  • al_fget_ustr
  • al_fgetc
  • al_fgets
  • al_filename_exists
  • al_fill_silence
  • al_find_menu
  • al_find_menu_item
  • al_fixacos
  • al_fixadd
  • al_fixasin
  • al_fixatan
  • al_fixatan2
  • al_fixceil
  • al_fixcos
  • al_fixdiv
  • al_fixed
  • al_fixfloor
  • al_fixhypot
  • al_fixmul
  • al_fixsin
  • al_fixsqrt
  • al_fixsub
  • al_fixtan
  • al_fixtof
  • al_fixtoi
  • al_fixtorad_r
  • al_flip_display
  • al_flush_event_queue
  • al_fopen
  • al_fopen_fd
  • al_fopen_interface
  • al_fopen_slice
  • al_for_each_fs_entry
  • al_fprintf
  • al_fputc
  • al_fputs
  • al_fread
  • al_fread16be
  • al_fread16le
  • al_fread32be
  • al_fread32le
  • al_free
  • al_free_with_context
  • al_fs_entry_exists
  • al_fseek
  • al_fsize
  • al_ftell
  • al_ftofix
  • al_fungetc
  • al_fwrite
  • al_fwrite16be
  • al_fwrite16le
  • al_fwrite32be
  • al_fwrite32le
  • al_get_allegro_acodec_version
  • al_get_allegro_audio_version
  • al_get_allegro_color_version
  • al_get_allegro_font_version
  • al_get_allegro_image_version
  • al_get_allegro_memfile_version
  • al_get_allegro_native_dialog_version
  • al_get_allegro_physfs_version
  • al_get_allegro_primitives_version
  • al_get_allegro_ttf_version
  • al_get_allegro_version
  • al_get_allegro_video_version
  • al_get_app_name
  • al_get_audio_depth_size
  • al_get_audio_recorder_event
  • al_get_audio_recorder_event_source
  • al_get_audio_stream_attached
  • al_get_audio_stream_channels
  • al_get_audio_stream_depth
  • al_get_audio_stream_event_source
  • al_get_audio_stream_fragment
  • al_get_audio_stream_fragments
  • al_get_audio_stream_frequency
  • al_get_audio_stream_gain
  • al_get_audio_stream_length
  • al_get_audio_stream_length_secs
  • al_get_audio_stream_pan
  • al_get_audio_stream_played_samples
  • al_get_audio_stream_playing
  • al_get_audio_stream_playmode
  • al_get_audio_stream_position_secs
  • al_get_audio_stream_speed
  • al_get_available_audio_stream_fragments
  • al_get_backbuffer
  • al_get_bitmap_depth
  • al_get_bitmap_flags
  • al_get_bitmap_format
  • al_get_bitmap_height
  • al_get_bitmap_samples
  • al_get_bitmap_width
  • al_get_bitmap_x
  • al_get_bitmap_y
  • al_get_blend_color
  • al_get_blender
  • al_get_channel_count
  • al_get_clipboard_text
  • al_get_clipping_rectangle
  • al_get_config_value
  • al_get_cpu_count
  • al_get_current_directory
  • al_get_current_display
  • al_get_current_inverse_transform
  • al_get_current_projection_transform
  • al_get_current_transform
  • al_get_d3d_device
  • al_get_d3d_system_texture
  • al_get_d3d_texture_position
  • al_get_d3d_texture_size
  • al_get_d3d_video_texture
  • al_get_default_menu_event_source
  • al_get_default_mixer
  • al_get_default_shader_source
  • al_get_default_voice
  • al_get_display_event_source
  • al_get_display_flags
  • al_get_display_format
  • al_get_display_height
  • al_get_display_menu
  • al_get_display_mode
  • al_get_display_option
  • al_get_display_orientation
  • al_get_display_refresh_rate
  • al_get_display_width
  • al_get_errno
  • al_get_event_source_data
  • al_get_fallback_font
  • al_get_file_userdata
  • al_get_first_config_entry
  • al_get_first_config_section
  • al_get_font_ascent
  • al_get_font_descent
  • al_get_font_line_height
  • al_get_font_ranges
  • al_get_fs_entry_atime
  • al_get_fs_entry_ctime
  • al_get_fs_entry_mode
  • al_get_fs_entry_mtime
  • al_get_fs_entry_name
  • al_get_fs_entry_size
  • al_get_fs_interface
  • al_get_glyph
  • al_get_glyph_advance
  • al_get_glyph_dimensions
  • al_get_glyph_width
  • al_get_haptic_autocenter
  • al_get_haptic_capabilities
  • al_get_haptic_effect_duration
  • al_get_haptic_from_display
  • al_get_haptic_from_joystick
  • al_get_haptic_from_keyboard
  • al_get_haptic_from_mouse
  • al_get_haptic_from_touch_input
  • al_get_haptic_gain
  • al_get_index_buffer_size
  • al_get_joystick
  • al_get_joystick_active
  • al_get_joystick_axis_name
  • al_get_joystick_button_name
  • al_get_joystick_event_source
  • al_get_joystick_name
  • al_get_joystick_num_axes
  • al_get_joystick_num_buttons
  • al_get_joystick_num_sticks
  • al_get_joystick_state
  • al_get_joystick_stick_flags
  • al_get_joystick_stick_name
  • al_get_keyboard_event_source
  • al_get_keyboard_state
  • al_get_max_haptic_effects
  • al_get_menu_item_caption
  • al_get_menu_item_flags
  • al_get_menu_item_icon
  • al_get_mixer_attached
  • al_get_mixer_channels
  • al_get_mixer_depth
  • al_get_mixer_frequency
  • al_get_mixer_gain
  • al_get_mixer_playing
  • al_get_mixer_quality
  • al_get_monitor_info
  • al_get_mouse_cursor_position
  • al_get_mouse_emulation_mode
  • al_get_mouse_event_source
  • al_get_mouse_num_axes
  • al_get_mouse_num_buttons
  • al_get_mouse_state
  • al_get_mouse_state_axis
  • al_get_mouse_wheel_precision
  • al_get_native_file_dialog_count
  • al_get_native_file_dialog_path
  • al_get_native_text_log_event_source
  • al_get_new_bitmap_depth
  • al_get_new_bitmap_flags
  • al_get_new_bitmap_format
  • al_get_new_bitmap_samples
  • al_get_new_display_adapter
  • al_get_new_display_flags
  • al_get_new_display_option
  • al_get_new_display_refresh_rate
  • al_get_new_file_interface
  • al_get_new_window_position
  • al_get_new_window_title
  • al_get_next_config_entry
  • al_get_next_config_section
  • al_get_next_event
  • al_get_num_display_modes
  • al_get_num_joysticks
  • al_get_num_video_adapters
  • al_get_opengl_extension_list
  • al_get_opengl_fbo
  • al_get_opengl_proc_address
  • al_get_opengl_program_object
  • al_get_opengl_texture
  • al_get_opengl_texture_position
  • al_get_opengl_texture_size
  • al_get_opengl_variant
  • al_get_opengl_version
  • al_get_org_name
  • al_get_parent_bitmap
  • al_get_path_basename
  • al_get_path_component
  • al_get_path_drive
  • al_get_path_extension
  • al_get_path_filename
  • al_get_path_num_components
  • al_get_path_tail
  • al_get_pixel
  • al_get_pixel_block_height
  • al_get_pixel_block_size
  • al_get_pixel_block_width
  • al_get_pixel_format_bits
  • al_get_pixel_size
  • al_get_ram_size
  • al_get_sample
  • al_get_sample_channels
  • al_get_sample_data
  • al_get_sample_depth
  • al_get_sample_frequency
  • al_get_sample_instance_attached
  • al_get_sample_instance_channels
  • al_get_sample_instance_depth
  • al_get_sample_instance_frequency
  • al_get_sample_instance_gain
  • al_get_sample_instance_length
  • al_get_sample_instance_pan
  • al_get_sample_instance_playing
  • al_get_sample_instance_playmode
  • al_get_sample_instance_position
  • al_get_sample_instance_speed
  • al_get_sample_instance_time
  • al_get_sample_length
  • al_get_separate_blender
  • al_get_shader_log
  • al_get_shader_platform
  • al_get_standard_path
  • al_get_system_config
  • al_get_target_bitmap
  • al_get_text_dimensions
  • al_get_text_width
  • al_get_thread_should_stop
  • al_get_time
  • al_get_timer_count
  • al_get_timer_event_source
  • al_get_timer_speed
  • al_get_timer_started
  • al_get_touch_input_event_source
  • al_get_touch_input_mouse_emulation_event_source
  • al_get_touch_input_state
  • al_get_ustr_dimensions
  • al_get_ustr_width
  • al_get_vertex_buffer_size
  • al_get_video_audio_rate
  • al_get_video_event_source
  • al_get_video_fps
  • al_get_video_frame
  • al_get_video_position
  • al_get_video_scaled_height
  • al_get_video_scaled_width
  • al_get_voice_channels
  • al_get_voice_depth
  • al_get_voice_frequency
  • al_get_voice_playing
  • al_get_voice_position
  • al_get_win_window_handle
  • al_get_window_constraints
  • al_get_window_position
  • al_get_x_window_id
  • al_grab_font_from_bitmap
  • al_grab_mouse
  • al_have_d3d_non_pow2_texture_support
  • al_have_d3d_non_square_texture_support
  • al_have_opengl_extension
  • al_hide_mouse_cursor
  • al_hold_bitmap_drawing
  • al_horizontal_shear_transform
  • al_identify_bitmap
  • al_identify_bitmap_f
  • al_identity_transform
  • al_inhibit_screensaver
  • al_init
  • al_init_acodec_addon
  • al_init_font_addon
  • al_init_image_addon
  • al_init_native_dialog_addon
  • al_init_primitives_addon
  • al_init_timeout
  • al_init_ttf_addon
  • al_init_user_event_source
  • al_init_video_addon
  • al_insert_menu_item
  • al_insert_path_component
  • al_install_audio
  • al_install_haptic
  • al_install_joystick
  • al_install_keyboard
  • al_install_mouse
  • al_install_system
  • al_install_touch_input
  • al_invert_transform
  • al_iphone_get_view
  • al_iphone_get_window
  • al_iphone_set_statusbar_orientation
  • al_is_audio_installed
  • al_is_audio_recorder_recording
  • al_is_bitmap_drawing_held
  • al_is_bitmap_locked
  • al_is_color_valid
  • al_is_compatible_bitmap
  • al_is_d3d_device_lost
  • al_is_display_haptic
  • al_is_event_queue_empty
  • al_is_event_queue_paused
  • al_is_event_source_registered
  • al_is_haptic_active
  • al_is_haptic_capable
  • al_is_haptic_effect_ok
  • al_is_haptic_effect_playing
  • al_is_haptic_installed
  • al_is_joystick_haptic
  • al_is_joystick_installed
  • al_is_keyboard_haptic
  • al_is_keyboard_installed
  • al_is_mouse_haptic
  • al_is_mouse_installed
  • al_is_sub_bitmap
  • al_is_system_installed
  • al_is_touch_input_haptic
  • al_is_touch_input_installed
  • al_is_video_playing
  • al_itofix
  • al_join_paths
  • al_join_thread
  • al_key_down
  • al_keycode_to_name
  • al_load_audio_stream
  • al_load_audio_stream_f
  • al_load_bitmap
  • al_load_bitmap_f
  • al_load_bitmap_flags
  • al_load_bitmap_flags_f
  • al_load_bitmap_font
  • al_load_bitmap_font_flags
  • al_load_config_file
  • al_load_config_file_f
  • al_load_font
  • al_load_sample
  • al_load_sample_f
  • al_load_ttf_font
  • al_load_ttf_font_f
  • al_load_ttf_font_stretch
  • al_load_ttf_font_stretch_f
  • al_lock_bitmap
  • al_lock_bitmap_blocked
  • al_lock_bitmap_region
  • al_lock_bitmap_region_blocked
  • al_lock_index_buffer
  • al_lock_mutex
  • al_lock_sample_id
  • al_lock_vertex_buffer
  • al_make_directory
  • al_make_path_canonical
  • al_make_temp_file
  • al_malloc
  • al_malloc_with_context
  • al_map_rgb
  • al_map_rgb_f
  • al_map_rgba
  • al_map_rgba_f
  • al_merge_config
  • al_merge_config_into
  • al_mouse_button_down
  • al_open_directory
  • al_open_fs_entry
  • al_open_memfile
  • al_open_native_text_log
  • al_open_video
  • al_orthographic_transform
  • al_osx_get_window
  • al_path_cstr
  • al_path_ustr
  • al_pause_event_queue
  • al_peek_next_event
  • al_perspective_transform
  • al_play_haptic_effect
  • al_play_sample
  • al_play_sample_instance
  • al_popup_menu
  • al_premul_rgba
  • al_premul_rgba_f
  • al_put_blended_pixel
  • al_put_pixel
  • al_radtofix_r
  • al_read_directory
  • al_realloc
  • al_realloc_with_context
  • al_rebase_path
  • al_reconfigure_joysticks
  • al_ref_buffer
  • al_ref_cstr
  • al_ref_ustr
  • al_register_assert_handler
  • al_register_audio_stream_loader
  • al_register_audio_stream_loader_f
  • al_register_bitmap_identifier
  • al_register_bitmap_loader
  • al_register_bitmap_loader_f
  • al_register_bitmap_saver
  • al_register_bitmap_saver_f
  • al_register_event_source
  • al_register_font_loader
  • al_register_sample_loader
  • al_register_sample_loader_f
  • al_register_sample_saver
  • al_register_sample_saver_f
  • al_register_trace_handler
  • al_release_haptic
  • al_release_haptic_effect
  • al_release_joystick
  • al_remove_config_key
  • al_remove_config_section
  • al_remove_display_menu
  • al_remove_filename
  • al_remove_fs_entry
  • al_remove_menu_item
  • al_remove_opengl_fbo
  • al_remove_path_component
  • al_reparent_bitmap
  • al_replace_path_component
  • al_reserve_samples
  • al_reset_clipping_rectangle
  • al_reset_new_display_options
  • al_resize_display
  • al_rest
  • al_restore_default_mixer
  • al_restore_state
  • al_resume_timer
  • al_rewind_audio_stream
  • al_rotate_transform
  • al_rotate_transform_3d
  • al_rumble_haptic
  • al_run_detached_thread
  • al_run_main
  • al_save_bitmap
  • al_save_bitmap_f
  • al_save_config_file
  • al_save_config_file_f
  • al_save_sample
  • al_save_sample_f
  • al_scale_transform
  • al_scale_transform_3d
  • al_seek_audio_stream_secs
  • al_seek_video
  • al_set_app_name
  • al_set_audio_stream_channel_matrix
  • al_set_audio_stream_fragment
  • al_set_audio_stream_gain
  • al_set_audio_stream_loop_secs
  • al_set_audio_stream_pan
  • al_set_audio_stream_playing
  • al_set_audio_stream_playmode
  • al_set_audio_stream_speed
  • al_set_blend_color
  • al_set_blender
  • al_set_clipboard_text
  • al_set_clipping_rectangle
  • al_set_config_value
  • al_set_current_opengl_context
  • al_set_d3d_device_release_callback
  • al_set_d3d_device_restore_callback
  • al_set_default_mixer
  • al_set_default_voice
  • al_set_display_flag
  • al_set_display_icon
  • al_set_display_icons
  • al_set_display_menu
  • al_set_display_option
  • al_set_errno
  • al_set_event_source_data
  • al_set_exe_name
  • al_set_fallback_font
  • al_set_fs_interface
  • al_set_haptic_autocenter
  • al_set_haptic_gain
  • al_set_keyboard_leds
  • al_set_memory_interface
  • al_set_menu_item_caption
  • al_set_menu_item_flags
  • al_set_menu_item_icon
  • al_set_mixer_frequency
  • al_set_mixer_gain
  • al_set_mixer_playing
  • al_set_mixer_postprocess_callback
  • al_set_mixer_quality
  • al_set_mouse_axis
  • al_set_mouse_cursor
  • al_set_mouse_emulation_mode
  • al_set_mouse_w
  • al_set_mouse_wheel_precision
  • al_set_mouse_xy
  • al_set_mouse_z
  • al_set_new_bitmap_depth
  • al_set_new_bitmap_flags
  • al_set_new_bitmap_format
  • al_set_new_bitmap_samples
  • al_set_new_display_adapter
  • al_set_new_display_flags
  • al_set_new_display_option
  • al_set_new_display_refresh_rate
  • al_set_new_file_interface
  • al_set_new_window_position
  • al_set_new_window_title
  • al_set_org_name
  • al_set_path_drive
  • al_set_path_extension
  • al_set_path_filename
  • al_set_physfs_file_interface
  • al_set_render_state
  • al_set_sample
  • al_set_sample_instance_channel_matrix
  • al_set_sample_instance_gain
  • al_set_sample_instance_length
  • al_set_sample_instance_pan
  • al_set_sample_instance_playing
  • al_set_sample_instance_playmode
  • al_set_sample_instance_position
  • al_set_sample_instance_speed
  • al_set_separate_blender
  • al_set_shader_bool
  • al_set_shader_float
  • al_set_shader_float_vector
  • al_set_shader_int
  • al_set_shader_int_vector
  • al_set_shader_matrix
  • al_set_shader_sampler
  • al_set_standard_file_interface
  • al_set_standard_fs_interface
  • al_set_system_mouse_cursor
  • al_set_target_backbuffer
  • al_set_target_bitmap
  • al_set_thread_should_stop
  • al_set_timer_count
  • al_set_timer_speed
  • al_set_video_playing
  • al_set_voice_playing
  • al_set_voice_position
  • al_set_window_constraints
  • al_set_window_position
  • al_set_window_title
  • al_show_mouse_cursor
  • al_show_native_file_dialog
  • al_show_native_message_box
  • al_shutdown_font_addon
  • al_shutdown_image_addon
  • al_shutdown_native_dialog_addon
  • al_shutdown_primitives_addon
  • al_shutdown_ttf_addon
  • al_shutdown_video_addon
  • al_signal_cond
  • al_start_audio_recorder
  • al_start_thread
  • al_start_timer
  • al_start_video
  • al_start_video_with_voice
  • al_stop_audio_recorder
  • al_stop_haptic_effect
  • al_stop_sample
  • al_stop_sample_instance
  • al_stop_samples
  • al_stop_timer
  • al_store_state
  • al_toggle_menu_item_flags
  • al_transform_coordinates
  • al_transform_coordinates_3d
  • al_translate_transform
  • al_translate_transform_3d
  • al_triangulate_polygon
  • al_ungrab_mouse
  • al_uninstall_audio
  • al_uninstall_haptic
  • al_uninstall_joystick
  • al_uninstall_keyboard
  • al_uninstall_mouse
  • al_uninstall_system
  • al_uninstall_touch_input
  • al_unlock_bitmap
  • al_unlock_index_buffer
  • al_unlock_mutex
  • al_unlock_sample_id
  • al_unlock_vertex_buffer
  • al_unmap_rgb
  • al_unmap_rgb_f
  • al_unmap_rgba
  • al_unmap_rgba_f
  • al_unref_user_event
  • al_unregister_event_source
  • al_update_display_region
  • al_update_fs_entry
  • al_upload_and_play_haptic_effect
  • al_upload_haptic_effect
  • al_use_projection_transform
  • al_use_shader
  • al_use_transform
  • al_ustr_append
  • al_ustr_append_chr
  • al_ustr_append_cstr
  • al_ustr_appendf
  • al_ustr_assign
  • al_ustr_assign_cstr
  • al_ustr_assign_substr
  • al_ustr_compare
  • al_ustr_dup
  • al_ustr_dup_substr
  • al_ustr_empty_string
  • al_ustr_encode_utf16
  • al_ustr_equal
  • al_ustr_find_chr
  • al_ustr_find_cset
  • al_ustr_find_cset_cstr
  • al_ustr_find_cstr
  • al_ustr_find_replace
  • al_ustr_find_replace_cstr
  • al_ustr_find_set
  • al_ustr_find_set_cstr
  • al_ustr_find_str
  • al_ustr_free
  • al_ustr_get
  • al_ustr_get_next
  • al_ustr_has_prefix
  • al_ustr_has_prefix_cstr
  • al_ustr_has_suffix
  • al_ustr_has_suffix_cstr
  • al_ustr_insert
  • al_ustr_insert_chr
  • al_ustr_insert_cstr
  • al_ustr_length
  • al_ustr_ltrim_ws
  • al_ustr_ncompare
  • al_ustr_new
  • al_ustr_new_from_buffer
  • al_ustr_new_from_utf16
  • al_ustr_newf
  • al_ustr_next
  • al_ustr_offset
  • al_ustr_prev
  • al_ustr_prev_get
  • al_ustr_remove_chr
  • al_ustr_remove_range
  • al_ustr_replace_range
  • al_ustr_rfind_chr
  • al_ustr_rfind_cstr
  • al_ustr_rfind_str
  • al_ustr_rtrim_ws
  • al_ustr_set_chr
  • al_ustr_size
  • al_ustr_size_utf16
  • al_ustr_to_buffer
  • al_ustr_trim_ws
  • al_ustr_truncate
  • al_ustr_vappendf
  • al_utf16_encode
  • al_utf16_width
  • al_utf8_encode
  • al_utf8_width
  • al_vertical_shear_transform
  • al_vfprintf
  • al_wait_cond
  • al_wait_cond_until
  • al_wait_for_event
  • al_wait_for_event_timed
  • al_wait_for_event_until
  • al_wait_for_vsync
  • al_win_add_window_callback
  • al_win_remove_window_callback
  • al_x_set_initial_icon
  • iPhone

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:20 UTC


Joystick routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Joystick routines

  • ALLEGRO_JOYSTICK
  • ALLEGRO_JOYSTICK_STATE
  • ALLEGRO_JOYFLAGS
  • al_install_joystick
  • al_uninstall_joystick
  • al_is_joystick_installed
  • al_reconfigure_joysticks
  • al_get_num_joysticks
  • al_get_joystick
  • al_release_joystick
  • al_get_joystick_active
  • al_get_joystick_name
  • al_get_joystick_stick_name
  • al_get_joystick_axis_name
  • al_get_joystick_button_name
  • al_get_joystick_stick_flags
  • al_get_joystick_num_sticks
  • al_get_joystick_num_axes
  • al_get_joystick_num_buttons
  • al_get_joystick_state
  • al_get_joystick_event_source

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

On Windows there are two joystick drivers, a DirectInput one and an Xinput one. If support for XInput was compiled in, then it can be enabled by calling al_set_config_value(al_get_system_config(), "joystick", "driver", "xinput") before calling al_install_joystick, or by setting the same option in the allegro5.cfg configuration file. The Xinput and DirectInput drivers are mutually exclusive. The haptics subsystem will use the same driver as the joystick system does.

ALLEGRO_JOYSTICK

typedef struct ALLEGRO_JOYSTICK ALLEGRO_JOYSTICK;

Source Code

This is an abstract data type representing a physical joystick.

See also: al_get_joystick

ALLEGRO_JOYSTICK_STATE

typedef struct ALLEGRO_JOYSTICK_STATE ALLEGRO_JOYSTICK_STATE;

Source Code

This is a structure that is used to hold a "snapshot" of a joystick's axes and buttons at a particular instant. All fields public and read-only.

struct {
   float axis[num_axes];             // -1.0 to 1.0
} stick[num_sticks];
int button[num_buttons];             // 0 to 32767

See also: al_get_joystick_state

ALLEGRO_JOYFLAGS

enum ALLEGRO_JOYFLAGS

Source Code

  • ALLEGRO_JOYFLAG_DIGITAL - the stick provides digital input
  • ALLEGRO_JOYFLAG_ANALOGUE - the stick provides analogue input

(this enum is a holdover from the old API and may be removed)

See also: al_get_joystick_stick_flags

al_install_joystick

bool al_install_joystick(void)

Source Code

Install a joystick driver, returning true if successful. If a joystick driver was already installed, returns true immediately.

See also: al_uninstall_joystick

al_uninstall_joystick

void al_uninstall_joystick(void)

Source Code

Uninstalls the active joystick driver. All outstanding ALLEGRO_JOYSTICK structures are invalidated. If no joystick driver was active, this function does nothing.

This function is automatically called when Allegro is shut down.

See also: al_install_joystick

al_is_joystick_installed

bool al_is_joystick_installed(void)

Source Code

Returns true if al_install_joystick was called successfully.

al_reconfigure_joysticks

bool al_reconfigure_joysticks(void)

Source Code

Allegro is able to cope with users connecting and disconnected joystick devices on-the-fly. On existing platforms, the joystick event source will generate an event of type ALLEGRO_EVENT_JOYSTICK_CONFIGURATION when a device is plugged in or unplugged. In response, you should call al_reconfigure_joysticks.

Afterwards, the number returned by al_get_num_joysticks may be different, and the handles returned by al_get_joystick may be different or be ordered differently.

All ALLEGRO_JOYSTICK handles remain valid, but handles for disconnected devices become inactive: their states will no longer update, and al_get_joystick will not return the handle. Handles for devices which remain connected will continue to represent the same devices. Previously inactive handles may become active again, being reused to represent newly connected devices.

Returns true if the joystick configuration changed, otherwise returns false.

It is possible that on some systems, Allegro won't be able to generate ALLEGRO_EVENT_JOYSTICK_CONFIGURATION events. If your game has an input configuration screen or similar, you may wish to call al_reconfigure_joysticks when entering that screen.

See also: al_get_joystick_event_source, ALLEGRO_EVENT

al_get_num_joysticks

int al_get_num_joysticks(void)

Source Code

Return the number of joysticks currently on the system (or potentially on the system). This number can change after al_reconfigure_joysticks is called, in order to support hotplugging.

Returns 0 if there is no joystick driver installed.

See also: al_get_joystick, al_get_joystick_active

al_get_joystick

ALLEGRO_JOYSTICK * al_get_joystick(int num)

Source Code

Get a handle for a joystick on the system. The number may be from 0 to al_get_num_joysticks-1. If successful a pointer to a joystick object is returned, which represents a physical device. Otherwise NULL is returned.

The handle and the index are only incidentally linked. After al_reconfigure_joysticks is called, al_get_joystick may return handles in a different order, and handles which represent disconnected devices will not be returned.

See also: al_get_num_joysticks, al_reconfigure_joysticks, al_get_joystick_active

al_release_joystick

void al_release_joystick(ALLEGRO_JOYSTICK *joy)

Source Code

This function currently does nothing.

See also: al_get_joystick

al_get_joystick_active

bool al_get_joystick_active(ALLEGRO_JOYSTICK *joy)

Source Code

Return if the joystick handle is "active", i.e. in the current configuration, the handle represents some physical device plugged into the system. al_get_joystick returns active handles. After reconfiguration, active handles may become inactive, and vice versa.

See also: al_reconfigure_joysticks

al_get_joystick_name

const char *al_get_joystick_name(ALLEGRO_JOYSTICK *joy)

Source Code

Return the name of the given joystick.

See also: al_get_joystick_stick_name, al_get_joystick_axis_name, al_get_joystick_button_name

al_get_joystick_stick_name

const char *al_get_joystick_stick_name(ALLEGRO_JOYSTICK *joy, int stick)

Source Code

Return the name of the given "stick". If the stick doesn't exist, NULL is returned.

See also: al_get_joystick_axis_name, al_get_joystick_num_sticks

al_get_joystick_axis_name

const char *al_get_joystick_axis_name(ALLEGRO_JOYSTICK *joy, int stick, int axis)

Source Code

Return the name of the given axis. If the axis doesn't exist, NULL is returned. Indices begin from 0.

See also: al_get_joystick_stick_name, al_get_joystick_num_axes

al_get_joystick_button_name

const char *al_get_joystick_button_name(ALLEGRO_JOYSTICK *joy, int button)

Source Code

Return the name of the given button. If the button doesn't exist, NULL is returned. Indices begin from 0.

See also: al_get_joystick_stick_name, al_get_joystick_axis_name, al_get_joystick_num_buttons

al_get_joystick_stick_flags

int al_get_joystick_stick_flags(ALLEGRO_JOYSTICK *joy, int stick)

Source Code

Return the flags of the given "stick". If the stick doesn't exist, NULL is returned. Indices begin from 0.

See also: ALLEGRO_JOYFLAGS

al_get_joystick_num_sticks

int al_get_joystick_num_sticks(ALLEGRO_JOYSTICK *joy)

Source Code

Return the number of "sticks" on the given joystick. A stick has one or more axes.

See also: al_get_joystick_num_axes, al_get_joystick_num_buttons

al_get_joystick_num_axes

int al_get_joystick_num_axes(ALLEGRO_JOYSTICK *joy, int stick)

Source Code

Return the number of axes on the given "stick". If the stick doesn't exist, 0 is returned.

See also: al_get_joystick_num_sticks

al_get_joystick_num_buttons

int al_get_joystick_num_buttons(ALLEGRO_JOYSTICK *joy)

Source Code

Return the number of buttons on the joystick.

See also: al_get_joystick_num_sticks

al_get_joystick_state

void al_get_joystick_state(ALLEGRO_JOYSTICK *joy, ALLEGRO_JOYSTICK_STATE *ret_state)

Source Code

Get the current joystick state.

See also: ALLEGRO_JOYSTICK_STATE, al_get_joystick_num_buttons, al_get_joystick_num_axes

al_get_joystick_event_source

ALLEGRO_EVENT_SOURCE *al_get_joystick_event_source(void)

Source Code

Returns the global joystick event source. All joystick events are generated by this event source.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:06:41 UTC


  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:15 UTC


Main addon

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Main addon

The main addon has no public API, but contains functionality to enable programs using Allegro to build and run without platform-specific changes.

On platforms that require this functionality (e.g. OSX) this addon contains a C main function that invokes al_run_main with the user's own main function, where the user's main function has had its name mangled to something else. The file that defines the user main function must include the header file allegro5/allegro.h; that header performs the name mangling using some macros.

If the user main function is defined in C++, then it must have the following signature for this addon to work:

int main(int argc, char **argv)

This addon does nothing on platforms that don't require its functionality, but you should keep it in mind in case you need to port to platforms that do require it.

Link with allegro_main.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:19 UTC


Memfile interface

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Memfile interface

  • al_open_memfile
  • al_get_allegro_memfile_version

The memfile interface allows you to treat a fixed block of contiguous memory as a file that can be used with Allegro's I/O functions.

These functions are declared in the following header file. Link with allegro_memfile.

 #include <allegro5/allegro_memfile.h>

al_open_memfile

ALLEGRO_FILE *al_open_memfile(void *mem, int64_t size, const char *mode)

Source Code

Returns a file handle to the block of memory. All read and write operations act upon the memory directly, so it must not be freed while the file remains open.

The mode can be any combination of "r" (readable) and "w" (writable). Regardless of the mode, the file always opens at position 0. The file size is fixed and cannot be expanded. The file is always read from/written to in binary mode, which means that no newline translation is performed.

It should be closed with al_fclose. After the file is closed, you are responsible for freeing the memory (if needed).

al_get_allegro_memfile_version

uint32_t al_get_allegro_memfile_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:19 UTC


Memory management routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Memory management routines

  • al_malloc
  • al_free
  • al_realloc
  • al_calloc
  • al_malloc_with_context
  • al_free_with_context
  • al_realloc_with_context
  • al_calloc_with_context
  • ALLEGRO_MEMORY_INTERFACE
  • al_set_memory_interface

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

al_malloc

#define al_malloc(n) \
   (al_malloc_with_context((n), __LINE__, __FILE__, __func__))

Source Code

Like malloc() in the C standard library, but the implementation may be overridden.

This is a macro.

See also: al_free, al_realloc, al_calloc, al_malloc_with_context, al_set_memory_interface

al_free

#define al_free(p) \
   (al_free_with_context((p), __LINE__, __FILE__, __func__))

Source Code

Like free() in the C standard library, but the implementation may be overridden.

Additionally, on Windows, a memory block allocated by one DLL must be freed from the same DLL. In the few places where an Allegro function returns a pointer that must be freed, you must use al_free for portability to Windows.

This is a macro.

See also: al_malloc, al_free_with_context

al_realloc

#define al_realloc(p, n) \
   (al_realloc_with_context((p), (n), __LINE__, __FILE__, __func__))

Source Code

Like realloc() in the C standard library, but the implementation may be overridden.

This is a macro.

See also: al_malloc, al_realloc_with_context

al_calloc

#define al_calloc(c, n) \
   (al_calloc_with_context((c), (n), __LINE__, __FILE__, __func__))

Source Code

Like calloc() in the C standard library, but the implementation may be overridden.

This is a macro.

See also: al_malloc, al_calloc_with_context

al_malloc_with_context

void *al_malloc_with_context(size_t n,
   int line, const char *file, const char *func)

Source Code

This calls malloc() from the Allegro library (this matters on Windows), unless overridden with al_set_memory_interface,

Generally you should use the al_malloc macro.

al_free_with_context

void al_free_with_context(void *ptr,
   int line, const char *file, const char *func)

Source Code

This calls free() from the Allegro library (this matters on Windows), unless overridden with al_set_memory_interface.

Generally you should use the al_free macro.

al_realloc_with_context

void *al_realloc_with_context(void *ptr, size_t n,
   int line, const char *file, const char *func)

Source Code

This calls realloc() from the Allegro library (this matters on Windows), unless overridden with al_set_memory_interface,

Generally you should use the al_realloc macro.

al_calloc_with_context

void *al_calloc_with_context(size_t count, size_t n,
   int line, const char *file, const char *func)

Source Code

This calls calloc() from the Allegro library (this matters on Windows), unless overridden with al_set_memory_interface,

Generally you should use the al_calloc macro.

ALLEGRO_MEMORY_INTERFACE

typedef struct ALLEGRO_MEMORY_INTERFACE ALLEGRO_MEMORY_INTERFACE;

Source Code

This structure has the following fields.

void *(*mi_malloc)(size_t n, int line, const char *file, const char *func);
void (*mi_free)(void *ptr, int line, const char *file, const char *func);
void *(*mi_realloc)(void *ptr, size_t n, int line, const char *file,
                    const char *func);
void *(*mi_calloc)(size_t count, size_t n, int line, const char *file,
                   const char *func);

See also: al_set_memory_interface

al_set_memory_interface

void al_set_memory_interface(ALLEGRO_MEMORY_INTERFACE *memory_interface)

Source Code

Override the memory management functions with implementations of al_malloc_with_context, al_free_with_context, al_realloc_with_context and al_calloc_with_context. The context arguments may be used for debugging. The new functions should be thread safe.

If the pointer is NULL, the default behaviour will be restored.

See also: ALLEGRO_MEMORY_INTERFACE

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:15 UTC


Miscellaneous routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Miscellaneous routines

  • ALLEGRO_PI
  • al_run_main

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_PI

#define ALLEGRO_PI        3.14159265358979323846

Source Code

C99 compilers have no predefined value like M_PI for the constant π, but you can use this one instead.

al_run_main

int al_run_main(int argc, char **argv, int (*user_main)(int, char **))

Source Code

This function is useful in cases where you don't have a main() function but want to run Allegro (mostly useful in a wrapper library). Under Windows and Linux this is no problem because you simply can call al_install_system. But some other system (like OSX) don't allow calling al_install_system in the main thread. al_run_main will know what to do in that case.

The passed argc and argv will simply be passed on to user_main and the return value of user_main will be returned.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:15 UTC


Monitors

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Monitors

  • ALLEGRO_MONITOR_INFO
  • al_get_new_display_adapter
  • al_set_new_display_adapter
  • al_get_monitor_info
  • al_get_num_video_adapters

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_MONITOR_INFO

typedef struct ALLEGRO_MONITOR_INFO

Source Code

Describes a monitor's size and position relative to other monitors. x1, y1 will be 0, 0 on the primary display. Other monitors can have negative values if they are to the left or above the primary display. x2, y2 are the coordinates one beyond the bottom right pixel, so that x2-x1 gives the width and y2-y1 gives the height of the display.

typedef struct ALLEGRO_MONITOR_INFO
{
   int x1;
   int y1;
   int x2;
   int y2;
} ALLEGRO_MONITOR_INFO;

See also: al_get_monitor_info

al_get_new_display_adapter

int al_get_new_display_adapter(void)

Source Code

Gets the video adapter index where new displays will be created by the calling thread, if previously set with al_set_new_display_adapter. Otherwise returns ALLEGRO_DEFAULT_DISPLAY_ADAPTER.

See also: al_set_new_display_adapter

al_set_new_display_adapter

void al_set_new_display_adapter(int adapter)

Source Code

Sets the adapter to use for new displays created by the calling thread. The adapter has a monitor attached to it. Information about the monitor can be gotten using al_get_num_video_adapters and al_get_monitor_info.

To return to the default behaviour, pass ALLEGRO_DEFAULT_DISPLAY_ADAPTER.

See also: al_get_num_video_adapters, al_get_monitor_info

al_get_monitor_info

bool al_get_monitor_info(int adapter, ALLEGRO_MONITOR_INFO *info)

Source Code

Get information about a monitor's position on the desktop. adapter is a number from 0 to al_get_num_video_adapters()-1.

On Windows, use al_set_new_display_flags to switch between Direct3D and OpenGL backends, which will often have different adapters available.

Returns true on success, false on failure.

See also: ALLEGRO_MONITOR_INFO, al_get_num_video_adapters

al_get_num_video_adapters

int al_get_num_video_adapters(void)

Source Code

Get the number of video "adapters" attached to the computer. Each video card attached to the computer counts as one or more adapters. An adapter is thus really a video port that can have a monitor connected to it.

On Windows, use al_set_new_display_flags to switch between Direct3D and OpenGL backends, which will often have different adapters available.

See also: al_get_monitor_info

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:16 UTC


Mouse routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Mouse routines

  • ALLEGRO_MOUSE_STATE
  • al_install_mouse
  • al_is_mouse_installed
  • al_uninstall_mouse
  • al_get_mouse_num_axes
  • al_get_mouse_num_buttons
  • al_get_mouse_state
  • al_get_mouse_state_axis
  • al_mouse_button_down
  • al_set_mouse_xy
  • al_set_mouse_z
  • al_set_mouse_w
  • al_set_mouse_axis
  • al_get_mouse_event_source
  • al_set_mouse_wheel_precision
  • al_get_mouse_wheel_precision
  • Mouse cursors
    • al_create_mouse_cursor
    • al_destroy_mouse_cursor
    • al_set_mouse_cursor
    • al_set_system_mouse_cursor
    • al_get_mouse_cursor_position
    • al_hide_mouse_cursor
    • al_show_mouse_cursor
    • al_grab_mouse
    • al_ungrab_mouse

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_MOUSE_STATE

typedef struct ALLEGRO_MOUSE_STATE ALLEGRO_MOUSE_STATE;

Source Code

Public fields (read only):

  • x - mouse x position
  • y - mouse y position
  • w, z - mouse wheel position (2D 'ball')

  • buttons - mouse buttons bitfield

    The zeroth bit is set if the primary mouse button is held down, the first bit is set if the secondary mouse button is held down, and so on.

  • pressure - pressure, ranging from 0.0 to 1.0

See also: al_get_mouse_state, al_get_mouse_state_axis, al_mouse_button_down

al_install_mouse

bool al_install_mouse(void)

Source Code

Install a mouse driver.

Returns true if successful. If a driver was already installed, nothing happens and true is returned.

al_is_mouse_installed

bool al_is_mouse_installed(void)

Source Code

Returns true if al_install_mouse was called successfully.

al_uninstall_mouse

void al_uninstall_mouse(void)

Source Code

Uninstalls the active mouse driver, if any. This will automatically unregister the mouse event source with any event queues.

This function is automatically called when Allegro is shut down.

al_get_mouse_num_axes

unsigned int al_get_mouse_num_axes(void)

Source Code

Return the number of axes on the mouse. The first axis is 0.

See also: al_get_mouse_num_buttons

al_get_mouse_num_buttons

unsigned int al_get_mouse_num_buttons(void)

Source Code

Return the number of buttons on the mouse. The first button is 1.

See also: al_get_mouse_num_axes

al_get_mouse_state

void al_get_mouse_state(ALLEGRO_MOUSE_STATE *ret_state)

Source Code

Save the state of the mouse specified at the time the function is called into the given structure.

Example:

ALLEGRO_MOUSE_STATE state;

al_get_mouse_state(&state);
if (state.buttons & 1) {
    /* Primary (e.g. left) mouse button is held. */
    printf("Mouse position: (%d, %d)\n", state.x, state.y);
}
if (state.buttons & 2) {
    /* Secondary (e.g. right) mouse button is held. */
}
if (state.buttons & 4) {
    /* Tertiary (e.g. middle) mouse button is held. */
}

See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state_axis, al_mouse_button_down

al_get_mouse_state_axis

int al_get_mouse_state_axis(const ALLEGRO_MOUSE_STATE *state, int axis)

Source Code

Extract the mouse axis value from the saved state. The axes are numbered from 0, in this order: x-axis, y-axis, z-axis, w-axis.

See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state, al_mouse_button_down

al_mouse_button_down

bool al_mouse_button_down(const ALLEGRO_MOUSE_STATE *state, int button)

Source Code

Return true if the mouse button specified was held down in the state specified. Unlike most things, the first mouse button is numbered 1.

See also: ALLEGRO_MOUSE_STATE, al_get_mouse_state, al_get_mouse_state_axis

al_set_mouse_xy

bool al_set_mouse_xy(ALLEGRO_DISPLAY *display, int x, int y)

Source Code

Try to position the mouse at the given coordinates on the given display. The mouse movement resulting from a successful move will generate an ALLEGRO_EVENT_MOUSE_WARPED event.

Returns true on success, false on failure.

See also: al_set_mouse_z, al_set_mouse_w

al_set_mouse_z

bool al_set_mouse_z(int z)

Source Code

Set the mouse wheel position to the given value.

Returns true on success, false on failure.

See also: al_set_mouse_w

al_set_mouse_w

bool al_set_mouse_w(int w)

Source Code

Set the second mouse wheel position to the given value.

Returns true on success, false on failure.

See also: al_set_mouse_z

al_set_mouse_axis

bool al_set_mouse_axis(int which, int value)

Source Code

Set the given mouse axis to the given value.

The axis number must not be 0 or 1, which are the X and Y axes. Use al_set_mouse_xy for that.

Returns true on success, false on failure.

See also: al_set_mouse_xy, al_set_mouse_z, al_set_mouse_w

al_get_mouse_event_source

ALLEGRO_EVENT_SOURCE *al_get_mouse_event_source(void)

Source Code

Retrieve the mouse event source. All mouse events are generated by this event source.

Returns NULL if the mouse subsystem was not installed.

al_set_mouse_wheel_precision

void al_set_mouse_wheel_precision(int precision)

Source Code

Sets the precision of the mouse wheel (the z and w coordinates). This precision manifests itself as a multiplier on the dz and dw fields in mouse events. It also affects the z and w fields of events and ALLEGRO_MOUSE_STATE, but not in a simple way if you alter the precision often, so it is suggested to reset those axes to 0 when you change precision. Setting this to a high value allows you to detect small changes in those two axes for some high precision mice. A flexible way of using this precision is to set it to a high value (120 is likely sufficient for most, if not all, mice) and use a floating point dz and dw like so:

al_set_mouse_wheel_precision(120);

ALLEGRO_EVENT event;
al_wait_for_event(event_queue, &event);
if (event.type == ALLEGRO_EVENT_MOUSE_AXES) {
  double dz = (double)event.mouse.dz / al_get_mouse_wheel_precision();
  /* Use dz in some way... */
}

Precision is set to 1 by default. It is impossible to set it to a lower precision than that.

Since: 5.1.10

See also: al_get_mouse_wheel_precision

al_get_mouse_wheel_precision

int al_get_mouse_wheel_precision(void)

Source Code

Gets the precision of the mouse wheel (the z and w coordinates).

Since: 5.1.10

See also: al_set_mouse_wheel_precision

Mouse cursors

al_create_mouse_cursor

ALLEGRO_MOUSE_CURSOR *al_create_mouse_cursor(ALLEGRO_BITMAP *bmp,
   int x_focus, int y_focus)

Source Code

Create a mouse cursor from the bitmap provided. x_focus and y_focus describe the bit of the cursor that will represent the actual mouse position.

Returns a pointer to the cursor on success, or NULL on failure.

See also: al_set_mouse_cursor, al_destroy_mouse_cursor

al_destroy_mouse_cursor

void al_destroy_mouse_cursor(ALLEGRO_MOUSE_CURSOR *cursor)

Source Code

Free the memory used by the given cursor.

Has no effect if cursor is NULL.

See also: al_create_mouse_cursor

al_set_mouse_cursor

bool al_set_mouse_cursor(ALLEGRO_DISPLAY *display, ALLEGRO_MOUSE_CURSOR *cursor)

Source Code

Set the given mouse cursor to be the current mouse cursor for the given display.

If the cursor is currently 'shown' (as opposed to 'hidden') the change is immediately visible.

Returns true on success, false on failure.

See also: al_set_system_mouse_cursor, al_show_mouse_cursor, al_hide_mouse_cursor

al_set_system_mouse_cursor

bool al_set_system_mouse_cursor(ALLEGRO_DISPLAY *display,
   ALLEGRO_SYSTEM_MOUSE_CURSOR cursor_id)

Source Code

Set the given system mouse cursor to be the current mouse cursor for the given display. If the cursor is currently 'shown' (as opposed to 'hidden') the change is immediately visible.

If the cursor doesn't exist on the current platform another cursor will be silently be substituted.

The cursors are:

  • ALLEGRO_SYSTEM_MOUSE_CURSOR_DEFAULT
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_ARROW
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_BUSY
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_QUESTION
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_EDIT
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_MOVE
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_N
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_W
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_S
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_E
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_NW
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_SW
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_SE
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_RESIZE_NE
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_PROGRESS
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_PRECISION
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_LINK
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_ALT_SELECT
  • ALLEGRO_SYSTEM_MOUSE_CURSOR_UNAVAILABLE

Returns true on success, false on failure.

See also: al_set_mouse_cursor, al_show_mouse_cursor, al_hide_mouse_cursor

al_get_mouse_cursor_position

bool al_get_mouse_cursor_position(int *ret_x, int *ret_y)

Source Code

On platforms where this information is available, this function returns the global location of the mouse cursor, relative to the desktop. You should not normally use this function, as the information is not useful except for special scenarios as moving a window.

Returns true on success, false on failure.

al_hide_mouse_cursor

bool al_hide_mouse_cursor(ALLEGRO_DISPLAY *display)

Source Code

Hide the mouse cursor in the given display. This has no effect on what the current mouse cursor looks like; it just makes it disappear.

Returns true on success (or if the cursor already was hidden), false otherwise.

See also: al_show_mouse_cursor

al_show_mouse_cursor

bool al_show_mouse_cursor(ALLEGRO_DISPLAY *display)

Source Code

Make a mouse cursor visible in the given display.

Returns true if a mouse cursor is shown as a result of the call (or one already was visible), false otherwise.

See also: al_hide_mouse_cursor

al_grab_mouse

bool al_grab_mouse(ALLEGRO_DISPLAY *display)

Source Code

Confine the mouse cursor to the given display. The mouse cursor can only be confined to one display at a time.

Returns true if successful, otherwise returns false. Do not assume that the cursor will remain confined until you call al_ungrab_mouse. It may lose the confined status at any time for other reasons.

Note: not yet implemented on Mac OS X.

See also: al_ungrab_mouse

al_ungrab_mouse

bool al_ungrab_mouse(void)

Source Code

Stop confining the mouse cursor to any display belonging to the program.

Note: not yet implemented on Mac OS X.

See also: al_grab_mouse

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:16 UTC


Native dialogs support

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Native dialogs support

  • ALLEGRO_FILECHOOSER
  • ALLEGRO_TEXTLOG
  • al_init_native_dialog_addon
  • al_shutdown_native_dialog_addon
  • al_create_native_file_dialog
  • al_show_native_file_dialog
  • al_get_native_file_dialog_count
  • al_get_native_file_dialog_path
  • al_destroy_native_file_dialog
  • al_show_native_message_box
  • al_open_native_text_log
  • al_close_native_text_log
  • al_append_native_text_log
  • al_get_native_text_log_event_source
  • al_get_allegro_native_dialog_version
  • Menus
    • ALLEGRO_MENU
    • ALLEGRO_MENU_INFO
    • al_create_menu
    • al_create_popup_menu
    • al_build_menu
    • al_append_menu_item
    • al_insert_menu_item
    • al_remove_menu_item
    • al_clone_menu
    • al_clone_menu_for_popup
    • al_destroy_menu
    • al_get_menu_item_caption
    • al_set_menu_item_caption
    • al_get_menu_item_flags
    • al_set_menu_item_flags
    • al_toggle_menu_item_flags
    • al_get_menu_item_icon
    • al_set_menu_item_icon
    • al_find_menu
    • al_find_menu_item
    • al_get_default_menu_event_source
    • al_enable_menu_event_source
    • al_disable_menu_event_source
    • al_get_display_menu
    • al_set_display_menu
    • al_popup_menu
    • al_remove_display_menu

These functions are declared in the following header file. Link with allegro_dialog.

 #include <allegro5/allegro_native_dialog.h>

ALLEGRO_FILECHOOSER

typedef struct ALLEGRO_FILECHOOSER ALLEGRO_FILECHOOSER;

Source Code

Opaque handle to a native file dialog.

ALLEGRO_TEXTLOG

typedef struct ALLEGRO_TEXTLOG ALLEGRO_TEXTLOG;

Source Code

Opaque handle to a text log window.

al_init_native_dialog_addon

bool al_init_native_dialog_addon(void)

Source Code

Initialise the native dialog addon.

Returns true on success, false on error.

Since: 5.0.9, 5.1.0

Note: Prior to Allegro 5.1.0 native dialog functions could be called without explicit initialisation, but that is now deprecated. Future functionality may require explicit initialisation. An exception is al_show_native_message_box, which may be useful to show an error message if Allegro fails to initialise.

See also: al_shutdown_native_dialog_addon

al_shutdown_native_dialog_addon

void al_shutdown_native_dialog_addon(void)

Source Code

Shut down the native dialog addon.

Since: 5.0.9, 5.1.5

See also: al_init_native_dialog_addon

al_create_native_file_dialog

ALLEGRO_FILECHOOSER *al_create_native_file_dialog(
   char const *initial_path,
   char const *title,
   char const *patterns,
   int mode)

Source Code

Creates a new native file dialog. You should only have one such dialog opened at a time.

Parameters:

  • initial_path: The initial search path and filename. Can be NULL. To start with a blank file name the string should end with a directory separator (this should be the common case).

  • title: Title of the dialog.

  • patterns: A list of semi-colon separated patterns to match. This should not contain any whitespace characters. If a pattern contains the '/' character, then it is treated as a MIME type (e.g. 'image/png'). Not all platforms support file patterns. If the native dialog does not provide support, this parameter is ignored.

  • mode: 0, or a combination of the following flags:

ALLEGRO_FILECHOOSER_FILE_MUST_EXIST
If supported by the native dialog, it will not allow entering new names, but just allow existing files to be selected. Else it is ignored.
ALLEGRO_FILECHOOSER_SAVE
If the native dialog system has a different dialog for saving (for example one which allows creating new directories), it is used. Else it is ignored.
ALLEGRO_FILECHOOSER_FOLDER
If there is support for a separate dialog to select a folder instead of a file, it will be used.
ALLEGRO_FILECHOOSER_PICTURES
If a different dialog is available for selecting pictures, it is used. Else it is ignored.
ALLEGRO_FILECHOOSER_SHOW_HIDDEN
If the platform supports it, also hidden files will be shown.
ALLEGRO_FILECHOOSER_MULTIPLE
If supported, allow selecting multiple files.

Returns:

A handle to the dialog which you can pass to al_show_native_file_dialog to display it, and from which you then can query the results using al_get_native_file_dialog_count and al_get_native_file_dialog_path. When you are done, call al_destroy_native_file_dialog on it.

If a dialog window could not be created then this function returns NULL.

al_show_native_file_dialog

bool al_show_native_file_dialog(ALLEGRO_DISPLAY *display,
   ALLEGRO_FILECHOOSER *dialog)

Source Code

Show the dialog window. The display may be NULL, otherwise the given display is treated as the parent if possible.

This function blocks the calling thread until it returns, so you may want to spawn a thread with al_create_thread and call it from inside that thread.

Returns true on success, false on failure.

al_get_native_file_dialog_count

int al_get_native_file_dialog_count(const ALLEGRO_FILECHOOSER *dialog)

Source Code

Returns the number of files selected, or 0 if the dialog was cancelled.

al_get_native_file_dialog_path

const char *al_get_native_file_dialog_path(
   const ALLEGRO_FILECHOOSER *dialog, size_t i)

Source Code

Returns one of the selected paths with index i. The index should range from 0 to the return value of al_get_native_file_dialog_count -1.

al_destroy_native_file_dialog

void al_destroy_native_file_dialog(ALLEGRO_FILECHOOSER *dialog)

Source Code

Frees up all resources used by the file dialog.

al_show_native_message_box

int al_show_native_message_box(ALLEGRO_DISPLAY *display,
   char const *title, char const *heading, char const *text,
   char const *buttons, int flags)

Source Code

Show a native GUI message box. This can be used for example to display an error message if creation of an initial display fails. The display may be NULL, otherwise the given display is treated as the parent if possible.

The message box will have a single "OK" button and use the style informative dialog boxes usually have on the native system. If the buttons parameter is not NULL, you can instead specify the button text in a string, with buttons separated by a vertical bar (|).

Note: buttons parameter is currently unimplemented on Windows.

The flags available are:

ALLEGRO_MESSAGEBOX_WARN
The message is a warning. This may cause a different icon (or other effects).
ALLEGRO_MESSAGEBOX_ERROR
The message is an error.
ALLEGRO_MESSAGEBOX_QUESTION
The message is a question.
ALLEGRO_MESSAGEBOX_OK_CANCEL
Display a cancel button alongside the "OK" button. Ignored if buttons is not NULL.
ALLEGRO_MESSAGEBOX_YES_NO
Display Yes/No buttons instead of the "OK" button. Ignored if buttons is not NULL.

al_show_native_message_box may be called without Allegro being installed. This is useful to report an error during initialisation of Allegro itself.

Returns:

  • 0 if the dialog window was closed without activating a button.
  • 1 if the OK or Yes button was pressed.
  • 2 if the Cancel or No button was pressed.

If buttons is not NULL, the number of the pressed button is returned, starting with 1.

All of the remaining parameters must not be NULL.

If a message box could not be created then this returns 0, as if the window was dismissed without activating a button.

Example:

int button = al_show_native_message_box(
  display,
  "Warning",
  "Are you sure?",
  "If you click yes then you are confirming that \"Yes\" "
  "is your response to the query which you have "
  "generated by the action you took to open this "
  "message box.",
  NULL,
  ALLEGRO_MESSAGEBOX_YES_NO
);

al_open_native_text_log

ALLEGRO_TEXTLOG *al_open_native_text_log(char const *title, int flags)

Source Code

Opens a window to which you can append log messages with al_append_native_text_log. This can be useful for debugging if you don't want to depend on a console being available.

Use al_close_native_text_log to close the window again.

The flags available are:

ALLEGRO_TEXTLOG_NO_CLOSE
Prevent the window from having a close button. Otherwise, if the close button is pressed, an event is generated; see al_get_native_text_log_event_source.
ALLEGRO_TEXTLOG_MONOSPACE
Use a monospace font to display the text.

Returns NULL if there was an error opening the window, or if text log windows are not implemented on the platform.

See also: al_append_native_text_log, al_close_native_text_log

al_close_native_text_log

void al_close_native_text_log(ALLEGRO_TEXTLOG *textlog)

Source Code

Closes a message log window opened with al_open_native_text_log earlier.

Does nothing if passed NULL.

See also: al_open_native_text_log

al_append_native_text_log

void al_append_native_text_log(ALLEGRO_TEXTLOG *textlog,
   char const *format, ...)

Source Code

Appends a line of text to the message log window and scrolls to the bottom (if the line would not be visible otherwise). This works like printf. A line is continued until you add a newline character.

If the window is NULL then this function will fall back to calling printf. This makes it convenient to support logging to a window or a terminal.

al_get_native_text_log_event_source

ALLEGRO_EVENT_SOURCE *al_get_native_text_log_event_source(
   ALLEGRO_TEXTLOG *textlog)

Source Code

Get an event source for a text log window. The possible events are:

ALLEGRO_EVENT_NATIVE_DIALOG_CLOSE
The window was requested to be closed, either by pressing the close button or pressing Escape on the keyboard. The user.data1 field will hold a pointer to the ALLEGRO_TEXTLOG which generated the event. The user.data2 field will be 1 if the event was generated as a result of a key press; otherwise it will be zero.

al_get_allegro_native_dialog_version

uint32_t al_get_allegro_native_dialog_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

Menus

Menus are implemented on Windows, X and OS X. Menus on X are implemented with GTK, and have a special requirement: you must set the ALLEGRO_GTK_TOPLEVEL display flag prior to creating the display which will have menus attached.

A menu can be attached to a single display window or popped up as a context menu. If you wish to use the same menu on multiple displays or use a sub-menu as a context menu, you must make a copy via al_clone_menu or al_clone_menu_for_popup.

Top level items in a non-popup menu must have at least one sub-item, or the behavior is undefined.

Each menu item can be given an ID of any 16-bit integer greater than zero. When a user clicks on a menu item, an event will be generated only if it has an ID. This ID should be unique per menu; if you duplicate IDs, then there will be no way for you to determine exactly which item generated the event.

There are many functions that take pos as a parameter used for locating a particular menu item. In those cases, it represents one of two things: an ID or a zero-based index. Any value greater than zero will always be treated as an ID. Anything else (including zero) will be considered an index based on the absolute value. In other words, 0 is the first menu item, -1 is the second menu item, -2 is the third menu item, and so on.

The event type is ALLEGRO_EVENT_MENU_CLICK. It contains three fields:

event.user.data1 = id;
event.user.data2 = (intptr_t) display;
event.user.data3 = (intptr_t) menu;

The display and menu may be NULL if it was not possible to tell exactly which item generated the event.

A basic example:

 #define FILE_EXIT_ID 1

ALLEGRO_MENU *menu = al_create_menu();
ALLEGRO_MENU *file_menu = al_create_menu();
al_append_menu_item(file_menu, "Exit", FILE_EXIT_ID, 0, NULL, NULL);
al_append_menu_item(menu, "File", 0, 0, NULL, file_menu);
al_set_display_menu(display, menu);

al_register_event_source(queue, al_get_default_menu_event_source());
al_wait_for_event(queue, &event);

if (event.type == ALLEGRO_EVENT_MENU_CLICK) {
   if (event.user.data1 == FILE_EXIT_ID) {
      exit_program();
   }
}

Because there is no "DISPLAY_DESTROYED" event, you must call al_set_display_menu(display, NULL) before destroying any display with a menu attached, to avoid leaking resources.

ALLEGRO_MENU

typedef struct ALLEGRO_MENU ALLEGRO_MENU;

Source Code

An opaque data type that represents a menu that contains menu items. Each of the menu items may optionally include a sub-menu.

ALLEGRO_MENU_INFO

typedef struct ALLEGRO_MENU_INFO {

Source Code

A structure that defines how to create a complete menu system. For standard menu items, the following format is used:

   { caption, id, flags, icon }

For special items, these macros are helpful:

ALLEGRO_START_OF_MENU(caption, id)
ALLEGRO_MENU_SEPARATOR
ALLEGRO_END_OF_MENU

A well-defined menu will begin with ALLEGRO_START_OF_MENU, contain one or more menu items, and end with ALLEGRO_END_OF_MENU. A menu may contain sub-menus. An example:

ALLEGRO_MENU_INFO menu_info[] = {
   ALLEGRO_START_OF_MENU("&File", 1),
      { "&Open", 2, 0, NULL },
      ALLEGRO_START_OF_MENU("Open &Recent...", 3),
         { "Recent 1", 4, 0, NULL },
         { "Recent 2", 5, 0, NULL },
         ALLEGRO_END_OF_MENU,
      ALLEGRO_MENU_SEPARATOR,
      { "E&xit", 6, 0, NULL },
      ALLEGRO_END_OF_MENU,
   ALLEGRO_START_OF_MENU("&Help", 7),
      {"&About", 8, 0, NULL },
      ALLEGRO_END_OF_MENU,
   ALLEGRO_END_OF_MENU
};

ALLEGRO_MENU *menu = al_build_menu(menu_info);

If you prefer, you can build the menu without the structure by using al_create_menu and al_insert_menu_item.

See also: al_build_menu

al_create_menu

ALLEGRO_MENU *al_create_menu(void)

Source Code

Creates a menu container that can hold menu items.

Returns NULL on failure.

Since: 5.1.0

See also: al_create_popup_menu, al_build_menu

al_create_popup_menu

ALLEGRO_MENU *al_create_popup_menu(void)

Source Code

Creates a menu container for popup menus. Only the root (outermost) menu should be created with this function. Sub menus of popups should be created with al_create_menu.

Returns NULL on failure.

Since: 5.1.0

See also: al_create_menu, al_build_menu

al_build_menu

ALLEGRO_MENU *al_build_menu(ALLEGRO_MENU_INFO *info)

Source Code

Builds a menu based on the specifications of a sequence of ALLEGRO_MENU_INFO elements.

Returns a pointer to the root ALLEGRO_MENU, or NULL on failure. To gain access to the other menus and items, you will need to search for them using al_find_menu_item.

Since: 5.1.0

See also: ALLEGRO_MENU_INFO, al_create_menu, al_create_popup_menu

al_append_menu_item

int al_append_menu_item(ALLEGRO_MENU *parent, char const *title, uint16_t id,
   int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu)

Source Code

Appends a menu item to the end of the menu. See al_insert_menu_item for more information.

Since: 5.1.0

See also: al_insert_menu_item, al_remove_menu_item

al_insert_menu_item

int al_insert_menu_item(ALLEGRO_MENU *parent, int pos, char const *title,
   uint16_t id, int flags, ALLEGRO_BITMAP *icon, ALLEGRO_MENU *submenu)

Source Code

Inserts a menu item at the spot specified. See the introductory text for a detailed explanation of how the pos parameter is interpreted.

The parent menu can be a popup menu or a regular menu. To underline one character in the title, prefix it with an ampersand.

The flags can be any combination of:

ALLEGRO_MENU_ITEM_DISABLED
The item is "grayed out" and cannot be selected.
ALLEGRO_MENU_ITEM_CHECKBOX
The item is a check box. This flag can only be set at the time the menu is created. If a check box is clicked, it will automatically be toggled.
ALLEGRO_MENU_ITEM_CHECKED
The item is checked. If set, ALLEGRO_MENU_ITEM_CHECKBOX will automatically be set as well.

The icon is not yet supported.

The submenu parameter indicates that this item contains a child menu. The child menu must have previously been created with al_create_menu, and not be associated with any other menu.

Returns true on success.

Since: 5.1.0

See also: al_append_menu_item, al_remove_menu_item

al_remove_menu_item

bool al_remove_menu_item(ALLEGRO_MENU *menu, int pos)

Source Code

Removes the specified item from the menu and destroys it. If the item contains a sub-menu, it too is destroyed. Any references to it are invalidated. If you want to preserve that sub-menu, you should first make a copy with al_clone_menu.

This is safe to call on a menu that is currently being displayed.

Returns true if an item was removed.

Since: 5.1.0

See also: al_append_menu_item, al_insert_menu_item, al_destroy_menu

al_clone_menu

ALLEGRO_MENU *al_clone_menu(ALLEGRO_MENU *menu)

Source Code

Makes a copy of a menu so that it can be reused on another display. The menu being cloned can be anything: a regular menu, a popup menu, or a sub-menu.

Returns the cloned menu.

Since: 5.1.0

See also: al_clone_menu_for_popup

al_clone_menu_for_popup

ALLEGRO_MENU *al_clone_menu_for_popup(ALLEGRO_MENU *menu)

Source Code

Exactly like al_clone_menu, except that the copy is for a popup menu.

Since: 5.1.0

See also: al_clone_menu

al_destroy_menu

void al_destroy_menu(ALLEGRO_MENU *menu)

Source Code

Destroys an entire menu, including its sub-menus. Any references to it or a sub-menu are no longer valid. It is safe to call this on a menu that is currently being displayed.

Since: 5.1.0

See also: al_remove_menu_item

al_get_menu_item_caption

const char *al_get_menu_item_caption(ALLEGRO_MENU *menu, int pos)

Source Code

Returns the caption associated with the menu item. It is valid as long as the caption is not modified.

Returns NULL if the item was not found.

Since: 5.1.0

See also: al_set_menu_item_caption

al_set_menu_item_caption

void al_set_menu_item_caption(ALLEGRO_MENU *menu, int pos, const char *caption)

Source Code

Updates the menu item caption with the new caption. This will invalidate any previous calls to al_get_menu_item_caption.

Since: 5.1.0

See also: al_get_menu_item_caption

al_get_menu_item_flags

int al_get_menu_item_flags(ALLEGRO_MENU *menu, int pos)

Source Code

Returns the currently set flags. See al_insert_menu_item for a description of the available flags.

Returns -1 if the item was not found.

Since: 5.1.0

See also: al_set_menu_item_flags, al_toggle_menu_item_flags

al_set_menu_item_flags

void al_set_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)

Source Code

Updates the menu item's flags. See al_insert_menu_item for a description of the available flags.

Since: 5.1.0

See also: al_get_menu_item_flags, al_toggle_menu_item_flags

al_toggle_menu_item_flags

int al_toggle_menu_item_flags(ALLEGRO_MENU *menu, int pos, int flags)

Source Code

Toggles the specified menu item's flags. See al_insert_menu_item for a description of the available flags.

Returns a bitfield of only the specified flags that are set after the toggle. A flag that was not toggled will not be returned, even if it is set. Returns -1 if the id is invalid.

Since: 5.1.0

Unstable API: Redundant with al_get/set_menu_item_flags.

See also: al_get_menu_item_flags, al_set_menu_item_flags

al_get_menu_item_icon

ALLEGRO_BITMAP *al_get_menu_item_icon(ALLEGRO_MENU *menu, int pos)

Source Code

Returns the icon associated with the menu. It is safe to draw to the returned bitmap, but you must call al_set_menu_item_icon in order for the changes to be applied.

Returns NULL if the item was not found or if it has no icon.

Since: 5.1.0

See also: al_set_menu_item_icon

al_set_menu_item_icon

void al_set_menu_item_icon(ALLEGRO_MENU *menu, int pos, ALLEGRO_BITMAP *icon)

Source Code

Sets the icon for the specified menu item. The menu assumes ownership of the ALLEGRO_BITMAP and may invalidate the pointer, so you must clone it if you wish to continue using it.

If a video bitmap is passed, it will automatically be converted to a memory bitmap, so it is preferable to pass a memory bitmap.

Since: 5.1.0

See also: al_get_menu_item_icon, al_clone_bitmap

al_find_menu

ALLEGRO_MENU *al_find_menu(ALLEGRO_MENU *haystack, uint16_t id)

Source Code

Searches in the haystack menu for any submenu with the given id. (Note that this only represents a literal ID, and cannot be used as an index.)

Returns the menu, if found. Otherwise returns NULL.

Since: 5.1.0

See also: al_find_menu_item

al_find_menu_item

bool al_find_menu_item(ALLEGRO_MENU *haystack, uint16_t id, ALLEGRO_MENU **menu,
   int *index)

Source Code

Searches in the haystack menu for an item with the given id. (Note that this only represents a literal ID, and cannot be used as an index.)

If menu and index are not NULL, they will be set as the parent menu containing the item and the zero-based (positive) index of the item. (If the menu item was not found, then their values are undefined.)

Returns true if the menu item was found.

Since: 5.1.0

See also: al_find_menu

al_get_default_menu_event_source

ALLEGRO_EVENT_SOURCE *al_get_default_menu_event_source(void)

Source Code

Returns the default event source used for menu clicks. If a menu was not given its own event source via al_enable_menu_event_source, then it will use this default source.

Since: 5.1.0

See also: al_register_event_source, al_enable_menu_event_source, al_disable_menu_event_source

al_enable_menu_event_source

ALLEGRO_EVENT_SOURCE *al_enable_menu_event_source(ALLEGRO_MENU *menu)

Source Code

Enables a unique event source for this menu. It and all of its sub-menus will use this event source. (It is safe to call this multiple times on the same menu.)

Returns the event source.

Since: 5.1.0

See also: al_register_event_source, al_get_default_menu_event_source, al_disable_menu_event_source

al_disable_menu_event_source

void al_disable_menu_event_source(ALLEGRO_MENU *menu)

Source Code

Disables a unique event source for the menu, causing it to use the default event source.

Since: 5.1.0

See also: al_get_default_menu_event_source, al_enable_menu_event_source

al_get_display_menu

ALLEGRO_MENU *al_get_display_menu(ALLEGRO_DISPLAY *display)

Source Code

Returns the menu associated with the display, or NULL if it does not have a menu.

Since: 5.1.0

See also: al_set_display_menu

al_set_display_menu

bool al_set_display_menu(ALLEGRO_DISPLAY *display, ALLEGRO_MENU *menu)

Source Code

Associates the menu with the display and shows it. If there was a previous menu associated with the display, it will be destroyed. If you don't want that to happen, you should first remove the menu with al_remove_display_menu.

If the menu is already attached to a display, it will not be attached to the new display. If menu is NULL, the current menu will still be destroyed.

Note: Attaching a menu may cause the window as available to your application to be resized! You should listen for a resize event, check how much space was lost, and resize the window accordingly if you want to maintain your window's prior size.

Returns true if successful.

Since: 5.1.0

See also: al_create_menu, al_remove_display_menu

al_popup_menu

bool al_popup_menu(ALLEGRO_MENU *popup, ALLEGRO_DISPLAY *display)

Source Code

Displays a context menu next to the mouse cursor. The menu must have been created with al_create_popup_menu. It generates events just like a regular display menu does. It is possible that the menu will be canceled without any selection being made.

The display parameter indicates which window the menu is associated with (when you process the menu click event), but does not actually affect where the menu is located on the screen.

Returns true if the context menu was displayed.

Since: 5.1.0

See also: al_create_popup_menu

al_remove_display_menu

ALLEGRO_MENU *al_remove_display_menu(ALLEGRO_DISPLAY *display)

Source Code

Detaches the menu associated with the display and returns it. The menu can then be used on a different display.

If you simply want to destroy the active menu, you can call al_set_display_menu with a NULL menu.

Since: 5.1.0

See also: al_set_display_menu

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:19 UTC


OpenGL integration

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

OpenGL integration

  • al_get_opengl_extension_list
  • al_get_opengl_proc_address
  • al_get_opengl_texture
  • al_get_opengl_texture_size
  • al_get_opengl_texture_position
  • al_get_opengl_program_object
  • al_get_opengl_fbo
  • al_remove_opengl_fbo
  • al_have_opengl_extension
  • al_get_opengl_version
  • al_get_opengl_variant
  • al_set_current_opengl_context
  • OpenGL configuration

These functions are declared in the following header file:

 #include <allegro5/allegro_opengl.h>

al_get_opengl_extension_list

ALLEGRO_OGL_EXT_LIST *al_get_opengl_extension_list(void)

Source Code

Returns the list of OpenGL extensions supported by Allegro, for the given display.

Allegro will keep information about all extensions it knows about in a structure returned by al_get_opengl_extension_list.

For example:

if (al_get_opengl_extension_list()->ALLEGRO_GL_ARB_multitexture) {
   //use it
}

The extension will be set to true if available for the given display and false otherwise. This means to use the definitions and functions from an OpenGL extension, all you need to do is to check for it as above at run time, after acquiring the OpenGL display from Allegro.

Under Windows, this will also work with WGL extensions, and under Unix with GLX extensions.

In case you want to manually check for extensions and load function pointers yourself (say, in case the Allegro developers did not include it yet), you can use the al_have_opengl_extension and al_get_opengl_proc_address functions instead.

Note: the exact extensions exposed depend on how Allegro was compiled. It is recommended to use al_have_opengl_extension and al_get_opengl_proc_address for the most stable experience.

al_get_opengl_proc_address

void *al_get_opengl_proc_address(const char *name)

Source Code

Helper to get the address of an OpenGL symbol

Example:

How to get the function glMultiTexCoord3fARB that comes with ARB's Multitexture extension:

// define the type of the function
ALLEGRO_DEFINE_PROC_TYPE(void, MULTI_TEX_FUNC,
                         (GLenum, GLfloat, GLfloat, GLfloat));
// declare the function pointer
MULTI_TEX_FUNC glMultiTexCoord3fARB;
// get the address of the function
glMultiTexCoord3fARB = (MULTI_TEX_FUNC) al_get_opengl_proc_address(
                                                        "glMultiTexCoord3fARB");

If glMultiTexCoord3fARB is not NULL then it can be used as if it has been defined in the OpenGL core library.

Note: Under Windows, OpenGL functions may need a special calling convention, so it's best to always use the ALLEGRO_DEFINE_PROC_TYPE macro when declaring function pointer types for OpenGL functions.

Parameters:

name - The name of the symbol you want to link to.

Return value:

A pointer to the symbol if available or NULL otherwise.

al_get_opengl_texture

GLuint al_get_opengl_texture(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the OpenGL texture id internally used by the given bitmap if it uses one, else 0.

Example:

bitmap = al_load_bitmap("my_texture.png");
texture = al_get_opengl_texture(bitmap);
if (texture != 0)
    glBindTexture(GL_TEXTURE_2D, texture);

al_get_opengl_texture_size

bool al_get_opengl_texture_size(ALLEGRO_BITMAP *bitmap, int *w, int *h)

Source Code

Retrieves the size of the texture used for the bitmap. This can be different from the bitmap size if OpenGL only supports power-of-two sizes or if it is a sub-bitmap.

Returns true on success, false on failure. Zero width and height are returned if the bitmap is not an OpenGL bitmap.

See also: al_get_opengl_texture_position

al_get_opengl_texture_position

void al_get_opengl_texture_position(ALLEGRO_BITMAP *bitmap, int *u, int *v)

Source Code

Returns the u/v coordinates for the top/left corner of the bitmap within the used texture, in pixels.

See also: al_get_opengl_texture_size

al_get_opengl_program_object

GLuint al_get_opengl_program_object(ALLEGRO_SHADER *shader)

Source Code

Returns the OpenGL program object associated with this shader, if the platform is ALLEGRO_SHADER_GLSL. Otherwise, returns 0.

al_get_opengl_fbo

GLuint al_get_opengl_fbo(ALLEGRO_BITMAP *bitmap)

Source Code

Returns the OpenGL FBO id internally used by the given bitmap if it uses one, otherwise returns zero. No attempt will be made to create an FBO if the bitmap is not owned by the current display.

The FBO returned by this function will only be freed when the bitmap is destroyed, or if you call al_remove_opengl_fbo on the bitmap.

Note: In Allegro 5.0.0 this function only returned an FBO which had previously been created by calling al_set_target_bitmap. It would not attempt to create an FBO itself. This has since been changed.

See also: al_remove_opengl_fbo, al_set_target_bitmap

al_remove_opengl_fbo

void al_remove_opengl_fbo(ALLEGRO_BITMAP *bitmap)

Source Code

Explicitly free an OpenGL FBO created for a bitmap, if it has one. Usually you do not need to worry about freeing FBOs, unless you use al_get_opengl_fbo.

See also: al_get_opengl_fbo, al_set_target_bitmap

al_have_opengl_extension

bool al_have_opengl_extension(const char *extension)

Source Code

This function is a helper to determine whether an OpenGL extension is available on the given display or not.

Example:

bool packedpixels = al_have_opengl_extension("GL_EXT_packed_pixels");

If packedpixels is true then you can safely use the constants related to the packed pixels extension.

Returns true if the extension is available; false otherwise.

al_get_opengl_version

uint32_t al_get_opengl_version(void)

Source Code

Returns the OpenGL or OpenGL ES version number of the client (the computer the program is running on), for the current display. "1.0" is returned as 0x01000000, "1.2.1" is returned as 0x01020100, and "1.2.2" as 0x01020200, etc.

A valid OpenGL context must exist for this function to work, which means you may not call it before al_create_display.

See also: al_get_opengl_variant

al_get_opengl_variant

int al_get_opengl_variant(void)

Source Code

Returns the variant or type of OpenGL used on the running platform. This function can be called before creating a display or setting properties for new displays. Possible values are:

ALLEGRO_DESKTOP_OPENGL
Regular OpenGL as seen on desktop/laptop computers.
ALLEGRO_OPENGL_ES
Trimmed down version of OpenGL used on many small consumer electronic devices such as handheld (and sometimes full size) consoles.

See also: al_get_opengl_version

al_set_current_opengl_context

void al_set_current_opengl_context(ALLEGRO_DISPLAY *display)

Source Code

Make the OpenGL context associated with the given display current for the calling thread. If there is a current target bitmap which belongs to a different OpenGL context, the target bitmap will be changed to NULL.

Normally you do not need to use this function, as the context will be made current when you call al_set_target_bitmap or al_set_target_backbuffer. You might need it if you created an OpenGL "forward compatible" context. Then al_get_backbuffer only returns NULL, so it would not work to pass that to al_set_target_bitmap.

OpenGL configuration

You can disable the detection of any OpenGL extension by Allegro with a section like this in allegro5.cfg:

[opengl_disabled_extensions]
GL_ARB_texture_non_power_of_two=0
GL_EXT_framebuffer_object=0

Any extension which appears in the section is treated as not available (it does not matter if you set it to 0 or any other value).

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:18 UTC


Path structures

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Path structures

  • al_create_path
  • al_create_path_for_directory
  • al_destroy_path
  • al_clone_path
  • al_join_paths
  • al_rebase_path
  • al_get_path_drive
  • al_get_path_num_components
  • al_get_path_component
  • al_get_path_tail
  • al_get_path_filename
  • al_get_path_basename
  • al_get_path_extension
  • al_set_path_drive
  • al_append_path_component
  • al_insert_path_component
  • al_replace_path_component
  • al_remove_path_component
  • al_drop_path_tail
  • al_set_path_filename
  • al_set_path_extension
  • al_path_cstr
  • al_path_ustr
  • al_make_path_canonical

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

We define a path as an optional drive, followed by zero or more directory components, followed by an optional filename. The filename may be broken up into a basename and an extension, where the basename includes the start of the filename up to, but not including, the last dot (.) character. If no dot character exists the basename is the whole filename. The extension is everything from the last dot character to the end of the filename.

al_create_path

ALLEGRO_PATH *al_create_path(const char *str)

Source Code

Create a path structure from a string. The last component, if it is followed by a directory separator and is neither "." nor "..", is treated as the last directory name in the path. Otherwise the last component is treated as the filename. The string may be NULL for an empty path.

See also: al_create_path_for_directory, al_destroy_path

al_create_path_for_directory

ALLEGRO_PATH *al_create_path_for_directory(const char *str)

Source Code

This is the same as al_create_path, but interprets the passed string as a directory path. The filename component of the returned path will always be empty.

See also: al_create_path, al_destroy_path

al_destroy_path

void al_destroy_path(ALLEGRO_PATH *path)

Source Code

Free a path structure. Does nothing if passed NULL.

See also: al_create_path, al_create_path_for_directory

al_clone_path

ALLEGRO_PATH *al_clone_path(const ALLEGRO_PATH *path)

Source Code

Clones an ALLEGRO_PATH structure. Returns NULL on failure.

See also: al_destroy_path

al_join_paths

bool al_join_paths(ALLEGRO_PATH *path, const ALLEGRO_PATH *tail)

Source Code

Concatenate two path structures. The first path structure is modified. If 'tail' is an absolute path, this function does nothing.

If 'tail' is a relative path, all of its directory components will be appended to 'path'. tail's filename will also overwrite path's filename, even if it is just the empty string.

Tail's drive is ignored.

Returns true if 'tail' was a relative path and so concatenated to 'path', otherwise returns false.

See also: al_rebase_path

al_rebase_path

bool al_rebase_path(const ALLEGRO_PATH *head, ALLEGRO_PATH *tail)

Source Code

Concatenate two path structures, modifying the second path structure. If tail is an absolute path, this function does nothing. Otherwise, the drive and path components in head are inserted at the start of tail.

For example, if head is "/anchor/" and tail is "data/file.ext", then after the call tail becomes "/anchor/data/file.ext".

See also: al_join_paths

al_get_path_drive

const char *al_get_path_drive(const ALLEGRO_PATH *path)

Source Code

Return the drive letter on a path, or the empty string if there is none.

The "drive letter" is only used on Windows, and is usually a string like "c:", but may be something like "\\Computer Name" in the case of UNC (Uniform Naming Convention) syntax.

al_get_path_num_components

int al_get_path_num_components(const ALLEGRO_PATH *path)

Source Code

Return the number of directory components in a path.

The directory components do not include the final part of a path (the filename).

See also: al_get_path_component

al_get_path_component

const char *al_get_path_component(const ALLEGRO_PATH *path, int i)

Source Code

Return the i'th directory component of a path, counting from zero. If the index is negative then count from the right, i.e. -1 refers to the last path component. It is an error to pass an index which is out of bounds.

See also: al_get_path_num_components, al_get_path_tail

al_get_path_tail

const char *al_get_path_tail(const ALLEGRO_PATH *path)

Source Code

Returns the last directory component, or NULL if there are no directory components.

al_get_path_filename

const char *al_get_path_filename(const ALLEGRO_PATH *path)

Source Code

Return the filename part of the path, or the empty string if there is none.

The returned pointer is valid only until the filename part of the path is modified in any way, or until the path is destroyed.

See also: al_get_path_basename, al_get_path_extension, al_get_path_component

al_get_path_basename

const char *al_get_path_basename(const ALLEGRO_PATH *path)

Source Code

Return the basename, i.e. filename with the extension removed. If the filename doesn't have an extension, the whole filename is the basename. If there is no filename part then the empty string is returned.

The returned pointer is valid only until the filename part of the path is modified in any way, or until the path is destroyed.

See also: al_get_path_filename, al_get_path_extension

al_get_path_extension

const char *al_get_path_extension(const ALLEGRO_PATH *path)

Source Code

Return a pointer to the start of the extension of the filename, i.e. everything from the final dot ('.') character onwards. If no dot exists, returns an empty string.

The returned pointer is valid only until the filename part of the path is modified in any way, or until the path is destroyed.

See also: al_get_path_filename, al_get_path_basename

al_set_path_drive

void al_set_path_drive(ALLEGRO_PATH *path, const char *drive)

Source Code

Set the drive string on a path. The drive may be NULL, which is equivalent to setting the drive string to the empty string.

See also: al_get_path_drive

al_append_path_component

void al_append_path_component(ALLEGRO_PATH *path, const char *s)

Source Code

Append a directory component.

See also: al_insert_path_component

al_insert_path_component

void al_insert_path_component(ALLEGRO_PATH *path, int i, const char *s)

Source Code

Insert a directory component at index i. If the index is negative then count from the right, i.e. -1 refers to the last path component.

It is an error to pass an index i which is not within these bounds: 0 <= i <= al_get_path_num_components(path).

See also: al_append_path_component, al_replace_path_component, al_remove_path_component

al_replace_path_component

void al_replace_path_component(ALLEGRO_PATH *path, int i, const char *s)

Source Code

Replace the i'th directory component by another string. If the index is negative then count from the right, i.e. -1 refers to the last path component. It is an error to pass an index which is out of bounds.

See also: al_insert_path_component, al_remove_path_component

al_remove_path_component

void al_remove_path_component(ALLEGRO_PATH *path, int i)

Source Code

Delete the i'th directory component. If the index is negative then count from the right, i.e. -1 refers to the last path component. It is an error to pass an index which is out of bounds.

See also: al_insert_path_component, al_replace_path_component, al_drop_path_tail

al_drop_path_tail

void al_drop_path_tail(ALLEGRO_PATH *path)

Source Code

Remove the last directory component, if any.

See also: al_remove_path_component

al_set_path_filename

void al_set_path_filename(ALLEGRO_PATH *path, const char *filename)

Source Code

Set the optional filename part of the path. The filename may be NULL, which is equivalent to setting the filename to the empty string.

See also: al_set_path_extension, al_get_path_filename

al_set_path_extension

bool al_set_path_extension(ALLEGRO_PATH *path, char const *extension)

Source Code

Replaces the extension of the path with the given one, i.e. replaces everything from the final dot ('.') character onwards, including the dot. If the filename of the path has no extension, the given one is appended. Usually the new extension you supply should include a leading dot.

Returns false if the path contains no filename part, i.e. the filename part is the empty string.

See also: al_set_path_filename, al_get_path_extension

al_path_cstr

const char *al_path_cstr(const ALLEGRO_PATH *path, char delim)

Source Code

Convert a path to its string representation, i.e. optional drive, followed by directory components separated by 'delim', followed by an optional filename.

To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP for 'delim'.

The returned pointer is valid only until the path is modified in any way, or until the path is destroyed. This returns a null-terminated string. If you need an ALLEGRO_USTR instead, use al_path_ustr.

See also: al_path_ustr

al_path_ustr

const ALLEGRO_USTR *al_path_ustr(const ALLEGRO_PATH *path, char delim)

Source Code

Convert a path to its string representation, i.e. optional drive, followed by directory components separated by 'delim', followed by an optional filename.

To use the current native path separator, use ALLEGRO_NATIVE_PATH_SEP for 'delim'.

The returned pointer is valid only until the path is modified in any way, or until the path is destroyed. This returns an ALLEGRO_USTR. If you need a null-terminated string instead, use al_path_cstr.

Since: 5.2.3

See also: al_path_cstr

al_make_path_canonical

bool al_make_path_canonical(ALLEGRO_PATH *path)

Source Code

Removes any leading '..' directory components in absolute paths. Removes all '.' directory components.

Note that this does not collapse "x/../y" sections into "y". This is by design. If "/foo" on your system is a symlink to "/bar/baz", then "/foo/../quux" is actually "/bar/quux", not "/quux" as a naive removal of ".." components would give you.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:16 UTC


PhysicsFS integration

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

PhysicsFS integration

  • al_set_physfs_file_interface
  • al_get_allegro_physfs_version

PhysicsFS is a library to provide abstract access to various archives. See http://icculus.org/physfs/ for more information.

This addon makes it possible to read and write files (on disk or inside archives) using PhysicsFS, through Allegro's file I/O API. For example, that means you can use the Image I/O addon to load images from .zip files.

You must set up PhysicsFS through its own API. When you want to open an ALLEGRO_FILE using PhysicsFS, first call al_set_physfs_file_interface, then al_fopen or another function that calls al_fopen.

These functions are declared in the following header file. Link with allegro_physfs.

 #include <allegro5/allegro_physfs.h>

al_set_physfs_file_interface

void al_set_physfs_file_interface(void)

Source Code

This function sets both the ALLEGRO_FILE_INTERFACE and ALLEGRO_FS_INTERFACE for the calling thread.

Subsequent calls to al_fopen on the calling thread will be handled by PHYSFS_open(). Operations on the files returned by al_fopen will then be performed through PhysicsFS. Calls to the Allegro filesystem functions, such as al_read_directory or al_create_fs_entry, on the calling thread will be diverted to PhysicsFS.

To remember and restore another file I/O backend, you can use al_store_state/al_restore_state.

Note: due to an oversight, this function differs from al_set_new_file_interface and al_set_standard_file_interface which only alter the current ALLEGRO_FILE_INTERFACE.

Note: PhysFS does not support the text-mode reading and writing, which means that Windows-style newlines will not be preserved.

See also: al_set_new_file_interface.

al_get_allegro_physfs_version

uint32_t al_get_allegro_physfs_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:19 UTC


Platform-specific functions

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Platform-specific functions

  • Windows
    • al_get_win_window_handle
    • al_win_add_window_callback
    • al_win_remove_window_callback
  • Mac OS X
    • al_osx_get_window
  • iPhone
    • al_iphone_set_statusbar_orientation
    • al_iphone_get_view
    • al_iphone_get_window
  • Android
    • al_android_set_apk_file_interface
    • al_android_set_apk_fs_interface
    • al_android_get_os_version
    • al_android_get_jni_env
    • al_android_get_activity
  • X11
    • al_get_x_window_id
    • al_x_set_initial_icon

Windows

These functions are declared in the following header file:

 #include <allegro5/allegro_windows.h>

al_get_win_window_handle

HWND al_get_win_window_handle(ALLEGRO_DISPLAY *display)

Source Code

Returns the handle to the window that the passed display is using.

al_win_add_window_callback

bool al_win_add_window_callback(ALLEGRO_DISPLAY *display,
   bool (*callback)(ALLEGRO_DISPLAY *display, UINT message, WPARAM wparam,
   LPARAM lparam, LRESULT *result, void *userdata), void *userdata)

Source Code

The specified callback function will intercept the window's message before Allegro processes it. If the callback function consumes the event, then it should return true. In that case, Allegro will not do anything with the event.

Optionally, you may use result to customize what Allegro will return return in response to this event. By default, Allegro returns TRUE.

The userdata pointer can be used to supply additional context to the callback function.

The callbacks are executed in the same order they were added.

Returns true if the callback was added.

Since: 5.1.2

al_win_remove_window_callback

bool al_win_remove_window_callback(ALLEGRO_DISPLAY *display,
   bool (*callback)(ALLEGRO_DISPLAY *display, UINT message, WPARAM wparam,
   LPARAM lparam, LRESULT *result, void *userdata), void *userdata)

Source Code

Removes the callback that was previously registered with al_win_add_window_callback. The userdata pointer must be the same as what was used during the registration of the callback.

Returns true if the callback was removed.

Since: 5.1.2

Mac OS X

These functions are declared in the following header file:

 #include <allegro5/allegro_osx.h>

al_osx_get_window

NSWindow* al_osx_get_window(ALLEGRO_DISPLAY *display)

Source Code

Retrieves the NSWindow handle associated with the Allegro display.

Since: 5.0.8, 5.1.3

iPhone

These functions are declared in the following header file:

 #include <allegro5/allegro_iphone.h>

al_iphone_set_statusbar_orientation

void al_iphone_set_statusbar_orientation(int o)

Source Code

Sets the orientation of the status bar, which can be one of the following:

  • ALLEGRO_IPHONE_STATUSBAR_ORIENTATION_PORTRAIT
  • ALLEGRO_IPHONE_STATUSBAR_ORIENTATION_PORTRAIT_UPSIDE_DOWN
  • ALLEGRO_IPHONE_STATUSBAR_ORIENTATION_LANDSCAPE_RIGHT
  • ALLEGRO_IPHONE_STATUSBAR_ORIENTATION_LANDSCAPE_LEFT

Since: 5.1.0

al_iphone_get_view

UIView *al_iphone_get_view(ALLEGRO_DISPLAY *display)

Source Code

Retrieves the UIView* (EAGLView*) associated with the Allegro display.

Since: 5.1.0

al_iphone_get_window

UIWindow *al_iphone_get_window(ALLEGRO_DISPLAY *display)

Source Code

Retrieves the UIWindow* associated with the Allegro display.

Since: 5.1.0

Android

These functions are declared in the following header file:

 #include <allegro5/allegro_android.h>

al_android_set_apk_file_interface

void al_android_set_apk_file_interface(void)

Source Code

This function will set up a custom ALLEGRO_FILE_INTERFACE that makes all future calls of al_fopen read from the applicatons's APK file.

Note: Currently, access to the APK file after calling this function is read only.

Since: 5.1.2

al_android_set_apk_fs_interface

void al_android_set_apk_fs_interface(void)

Source Code

This function will set up a custom ALLEGRO_FS_INTERFACE which allows working within the APK filesystem. The filesystem root is your assets directory and there is read-only access to all files within.

Note: Some things like querying file size or attributes are not supported by this. You can always use the PhysFS addon to open the APK file (it is just a regular .zip file) and get more complete information.

Since: 5.1.13

al_android_get_os_version

const char *al_android_get_os_version(void)

Source Code

Returns a pointer to a static buffer that contains the version string of the Android platform that the calling Allegro program is running on.

Since: 5.1.2

al_android_get_jni_env

JNIEnv *al_android_get_jni_env(void)

Source Code

Returns the Android JNI environment used by Allegro to call into Java. As a convenience this function provides it to the user so there is no need to obtain it yourself.

For example if you have a Java method "void send(String message)" in your activity class, you could call it like this from C code:

JNIEnv * env = al_android_get_jni_env();
jclass class_id = (* env)->GetObjectClass(env, al_android_get_activity());
jmethodID method_id = (* env)->GetMethodID(env, class_id, "send",
    "(Ljava/lang/String;)V");
jstring jdata = (* env)->NewStringUTF(env, "Hello Java!");
(* env)->CallVoidMethod(env, al_android_get_activity(), method_id, jdata);
(* env)->DeleteLocalRef(env, jdata);

Since: 5.2.2

Unstable API: This API is new and subject to refinement.

al_android_get_activity

jobject al_android_get_activity(void)

Source Code

Returns the Java Android activity used by Allegro. This is the same object created by Android from the class you specify in your manifest and either an instance of AllegroActivity or a derived class.

Since: 5.2.2

Unstable API: This API is new and subject to refinement.

X11

These functions are declared in the following header file:

 #include <allegro5/allegro_x.h>

al_get_x_window_id

XID al_get_x_window_id(ALLEGRO_DISPLAY *display)

Source Code

Retrieves the XID associated with the Allegro display.

Since: 5.1.12

al_x_set_initial_icon

bool al_x_set_initial_icon(ALLEGRO_BITMAP *bitmap)

Source Code

On some window managers (notably Ubuntu's Unity) al_set_display_icon doesn't work and you need to use a .desktop file. But with this function you can set an icon before calling al_create_display. This works by setting the icon before XMapWindow.

Since: 5.2.3

Unstable API: New API.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:17 UTC


Primitives addon

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Primitives addon

  • General
    • al_get_allegro_primitives_version
    • al_init_primitives_addon
    • al_shutdown_primitives_addon
  • High level drawing routines
    • Pixel-precise output
    • al_draw_line
    • al_draw_triangle
    • al_draw_filled_triangle
    • al_draw_rectangle
    • al_draw_filled_rectangle
    • al_draw_rounded_rectangle
    • al_draw_filled_rounded_rectangle
    • al_calculate_arc
    • al_draw_pieslice
    • al_draw_filled_pieslice
    • al_draw_ellipse
    • al_draw_filled_ellipse
    • al_draw_circle
    • al_draw_filled_circle
    • al_draw_arc
    • al_draw_elliptical_arc
    • al_calculate_spline
    • al_draw_spline
    • al_calculate_ribbon
    • al_draw_ribbon
  • Low level drawing routines
    • al_draw_prim
    • al_draw_indexed_prim
    • al_draw_vertex_buffer
    • al_draw_indexed_buffer
    • al_draw_soft_triangle
    • al_draw_soft_line
  • Custom vertex declaration routines
    • al_create_vertex_decl
    • al_destroy_vertex_decl
  • Vertex buffer routines
    • al_create_vertex_buffer
    • al_destroy_vertex_buffer
    • al_lock_vertex_buffer
    • al_unlock_vertex_buffer
    • al_get_vertex_buffer_size
  • Index buffer routines
    • al_create_index_buffer
    • al_destroy_index_buffer
    • al_lock_index_buffer
    • al_unlock_index_buffer
    • al_get_index_buffer_size
  • Polygon routines
    • al_draw_polyline
    • al_draw_polygon
    • al_draw_filled_polygon
    • al_draw_filled_polygon_with_holes
    • al_triangulate_polygon
  • Structures and types
    • ALLEGRO_VERTEX
    • ALLEGRO_VERTEX_DECL
    • ALLEGRO_VERTEX_ELEMENT
    • ALLEGRO_PRIM_TYPE
    • ALLEGRO_PRIM_ATTR
    • ALLEGRO_PRIM_STORAGE
    • ALLEGRO_VERTEX_CACHE_SIZE
    • ALLEGRO_PRIM_QUALITY
    • ALLEGRO_LINE_JOIN
    • ALLEGRO_LINE_CAP
    • ALLEGRO_VERTEX_BUFFER
    • ALLEGRO_INDEX_BUFFER
    • ALLEGRO_PRIM_BUFFER_FLAGS

These functions are declared in the following header file. Link with allegro_primitives.

 #include <allegro5/allegro_primitives.h>

General

al_get_allegro_primitives_version

uint32_t al_get_allegro_primitives_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

al_init_primitives_addon

bool al_init_primitives_addon(void)

Source Code

Initializes the primitives addon.

Returns: True on success, false on failure.

See also: al_shutdown_primitives_addon

al_shutdown_primitives_addon

void al_shutdown_primitives_addon(void)

Source Code

Shut down the primitives addon. This is done automatically at program exit, but can be called any time the user wishes as well.

See also: al_init_primitives_addon

High level drawing routines

High level drawing routines encompass the most common usage of this addon: to draw geometric primitives, both smooth (variations on the circle theme) and piecewise linear. Outlined primitives support the concept of thickness with two distinct modes of output: hairline lines and thick lines. Hairline lines are specifically designed to be exactly a pixel wide, and are commonly used for drawing outlined figures that need to be a pixel wide. Hairline thickness is designated as thickness less than or equal to 0. Unfortunately, the exact rasterization rules for drawing these hairline lines vary from one video card to another, and sometimes leave gaps where the lines meet. If that matters to you, then you should use thick lines. In many cases, having a thickness of 1 will produce 1 pixel wide lines that look better than hairline lines. Obviously, hairline lines cannot replicate thicknesses greater than 1. Thick lines grow symmetrically around the generating shape as thickness is increased.

Pixel-precise output

While normally you should not be too concerned with which pixels are displayed when the high level primitives are drawn, it is nevertheless possible to control that precisely by carefully picking the coordinates at which you draw those primitives.

To be able to do that, however, it is critical to understand how GPU cards convert shapes to pixels. Pixels are not the smallest unit that can be addressed by the GPU. Because the GPU deals with floating point coordinates, it can in fact assign different coordinates to different parts of a single pixel. To a GPU, thus, a screen is composed of a grid of squares that have width and length of 1. The top left corner of the top left pixel is located at (0, 0). Therefore, the center of that pixel is at (0.5, 0.5). The basic rule that determines which pixels are associated with which shape is then as follows: a pixel is treated to belong to a shape if the pixel's center is located in that shape. The figure below illustrates the above concepts:

Diagram showing a how pixel output is calculated by the GPU given the mathematical description of several shapes.

Diagram showing a how pixel output is calculated by the GPU given the mathematical description of several shapes.

This figure depicts three shapes drawn at the top left of the screen: an orange and green rectangles and a purple circle. On the left are the mathematical descriptions of pixels on the screen and the shapes to be drawn. On the right is the screen output. Only a single pixel has its center inside the circle, and therefore only a single pixel is drawn on the screen. Similarly, two pixels are drawn for the orange rectangle. Since there are no pixels that have their centers inside the green rectangle, the output image has no green pixels.

Here is a more practical example. The image below shows the output of this code:

/* blue vertical line */
al_draw_line(0.5, 0, 0.5, 6, color_blue, 1);
/* red horizontal line */
al_draw_line(2, 1, 6, 1, color_red, 2);
/* green filled rectangle */
al_draw_filled_rectangle(3, 4, 5, 5, color_green);
/* purple outlined rectangle */
al_draw_rectangle(2.5, 3.5, 5.5, 5.5, color_purple, 1);
Diagram showing a practical example of pixel output resulting from the invocation of several primitives addon functions.

Diagram showing a practical example of pixel output resulting from the invocation of several primitives addon functions.

It can be seen that lines are generated by making a rectangle based on the dashed line between the two endpoints. The thickness causes the rectangle to grow symmetrically about that generating line, as can be seen by comparing the red and blue lines. Note that to get proper pixel coverage, the coordinates passed to the al_draw_line had to be offset by 0.5 in the appropriate dimensions.

Filled rectangles are generated by making a rectangle between the endpoints passed to the al_draw_filled_rectangle.

Outlined rectangles are generated by symmetrically expanding an outline of a rectangle. With a thickness of 1, as depicted in the diagram, this means that an offset of 0.5 is needed for both sets of endpoint coordinates to exactly line up with the pixels of the display raster.

The above rules only apply when multisampling is turned off. When multisampling is turned on, the area of a pixel that is covered by a shape is taken into account when choosing what color to draw there. This also means that shapes no longer have to contain the pixel's center to affect its color. For example, the green rectangle in the first diagram may in fact be drawn as two (or one) semi-transparent pixels. The advantages of multisampling is that slanted shapes will look smoother because they will not have jagged edges. A disadvantage of multisampling is that it may make vertical and horizontal edges blurry. While the exact rules for multisampling are unspecified, and may vary from GPU to GPU, it is usually safe to assume that as long as a pixel is either completely covered by a shape or completely not covered, then the shape edges will be sharp. The offsets used in the second diagram were chosen so that this is the case: if you use those offsets, your shapes (if they are oriented the same way as they are on the diagram) should look the same whether multisampling is turned on or off.

al_draw_line

void al_draw_line(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color, float thickness)

Source Code

Draws a line segment between two points.

Parameters:

  • x1, y1, x2, y2 - Start and end points of the line
  • color - Color of the line
  • thickness - Thickness of the line, pass <= 0 to draw hairline lines

See also: al_draw_soft_line

al_draw_triangle

void al_draw_triangle(float x1, float y1, float x2, float y2,
   float x3, float y3, ALLEGRO_COLOR color, float thickness)

Source Code

Draws an outlined triangle.

Parameters:

  • x1, y1, x2, y2, x3, y3 - Three points of the triangle
  • color - Color of the triangle
  • thickness - Thickness of the lines, pass <= 0 to draw hairline lines

See also: al_draw_filled_triangle, al_draw_soft_triangle

al_draw_filled_triangle

void al_draw_filled_triangle(float x1, float y1, float x2, float y2,
   float x3, float y3, ALLEGRO_COLOR color)

Source Code

Draws a filled triangle.

Parameters:

  • x1, y1, x2, y2, x3, y3 - Three points of the triangle
  • color - Color of the triangle

See also: al_draw_triangle

al_draw_rectangle

void al_draw_rectangle(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color, float thickness)

Source Code

Draws an outlined rectangle.

Parameters:

  • x1, y1, x2, y2 - Upper left and lower right points of the rectangle
  • color - Color of the rectangle
  • thickness - Thickness of the lines, pass <= 0 to draw hairline lines

See also: al_draw_filled_rectangle, al_draw_rounded_rectangle

al_draw_filled_rectangle

void al_draw_filled_rectangle(float x1, float y1, float x2, float y2,
   ALLEGRO_COLOR color)

Source Code

Draws a filled rectangle.

Parameters:

  • x1, y1, x2, y2 - Upper left and lower right points of the rectangle
  • color - Color of the rectangle

See also: al_draw_rectangle, al_draw_filled_rounded_rectangle

al_draw_rounded_rectangle

void al_draw_rounded_rectangle(float x1, float y1, float x2, float y2,
   float rx, float ry, ALLEGRO_COLOR color, float thickness)

Source Code

Draws an outlined rounded rectangle.

Parameters:

  • x1, y1, x2, y2 - Upper left and lower right points of the rectangle
  • color - Color of the rectangle
  • rx, ry - The radii of the round
  • thickness - Thickness of the lines, pass <= 0 to draw hairline lines

See also: al_draw_filled_rounded_rectangle, al_draw_rectangle

al_draw_filled_rounded_rectangle

void al_draw_filled_rounded_rectangle(float x1, float y1, float x2, float y2,
   float rx, float ry, ALLEGRO_COLOR color)

Source Code

Draws an filled rounded rectangle.

Parameters:

  • x1, y1, x2, y2 - Upper left and lower right points of the rectangle
  • color - Color of the rectangle
  • rx, ry - The radii of the round

See also: al_draw_rounded_rectangle, al_draw_filled_rectangle

al_calculate_arc

void al_calculate_arc(float* dest, int stride, float cx, float cy,
   float rx, float ry, float start_theta, float delta_theta, float thickness,
   int num_points)

Source Code

When thickness <= 0 this function computes positions of num_points regularly spaced points on an elliptical arc. When thickness > 0 this function computes two sets of points, obtained as follows: the first set is obtained by taking the points computed in the thickness <= 0 case and shifting them by thickness / 2 outward, in a direction perpendicular to the arc curve. The second set is the same, but shifted thickness / 2 inward relative to the arc. The two sets of points are interleaved in the destination buffer (i.e. the first pair of points will be collinear with the arc center, the first point of the pair will be farther from the center than the second point; the next pair will also be collinear, but at a different angle and so on).

The destination buffer dest is interpreted as a set of regularly spaced pairs of floats, each pair holding the coordinates of the corresponding point on the arc. The two floats in the pair are adjacent, and the distance (in bytes) between the addresses of the first float in two successive pairs is stride. For example, if you have a tightly packed array of floats with no spaces between pairs, then stride will be exactly 2 * sizeof(float).

Example with thickness <= 0:

const int num_points = 4;
float points[num_points][2];
al_calculate_arc(&points[0][0], 2 * sizeof(float), 0, 0, 10, 10, 0, ALLEGRO_PI / 2, 0, num_points);

assert((int)points[0][0] == 10);
assert((int)points[0][1] == 0);

assert((int)points[num_points - 1][0] == 0);
assert((int)points[num_points - 1][1] == 10);

Example with thickness > 0:

const int num_points = 4;
float points[num_points * 2][2];
al_calculate_arc(&points[0][0], 2 * sizeof(float), 0, 0, 10, 10, 0, ALLEGRO_PI / 2, 2, num_points);

assert((int)points[0][0] == 11);
assert((int)points[0][1] == 0);
assert((int)points[1][0] == 9);
assert((int)points[1][1] == 0);

assert((int)points[(num_points - 1) * 2][0] == 0);
assert((int)points[(num_points - 1) * 2][1] == 11);
assert((int)points[(num_points - 1) * 2 + 1][0] == 0);
assert((int)points[(num_points - 1) * 2 + 1][1] == 9);

Parameters:

  • dest - The destination buffer
  • stride - Distance (in bytes) between starts of successive pairs of points
  • cx, cy - Center of the arc
  • rx, ry - Radii of the arc
  • start_theta - The initial angle from which the arc is calculated in radians
  • delta_theta - Angular span of the arc in radians (pass a negative number to switch direction)
  • thickness - Thickness of the arc
  • num_points - The number of points to calculate

See also: al_draw_arc, al_calculate_spline, al_calculate_ribbon

al_draw_pieslice

void al_draw_pieslice(float cx, float cy, float r, float start_theta,
   float delta_theta, ALLEGRO_COLOR color, float thickness)

Source Code

Draws a pieslice (outlined circular sector).

Parameters:

  • cx, cy - Center of the pieslice
  • r - Radius of the pieslice
  • color - Color of the pieslice
  • start_theta - The initial angle from which the pieslice is drawn in radians
  • delta_theta - Angular span of the pieslice in radians (pass a negative number to switch direction)
  • thickness - Thickness of the circle, pass <= 0 to draw hairline pieslice

Since: 5.0.6, 5.1.0

See also: al_draw_filled_pieslice

al_draw_filled_pieslice

void al_draw_filled_pieslice(float cx, float cy, float r, float start_theta,
   float delta_theta, ALLEGRO_COLOR color)

Source Code

Draws a filled pieslice (filled circular sector).

Parameters:

  • cx, cy - Center of the pieslice
  • r - Radius of the pieslice
  • color - Color of the pieslice
  • start_theta - The initial angle from which the pieslice is drawn in radians
  • delta_theta - Angular span of the pieslice in radians (pass a negative number to switch direction)

Since: 5.0.6, 5.1.0

See also: al_draw_pieslice

al_draw_ellipse

void al_draw_ellipse(float cx, float cy, float rx, float ry,
   ALLEGRO_COLOR color, float thickness)

Source Code

Draws an outlined ellipse.

Parameters:

  • cx, cy - Center of the ellipse
  • rx, ry - Radii of the ellipse
  • color - Color of the ellipse
  • thickness - Thickness of the ellipse, pass <= 0 to draw a hairline ellipse

See also: al_draw_filled_ellipse, al_draw_circle

al_draw_filled_ellipse

void al_draw_filled_ellipse(float cx, float cy, float rx, float ry,
   ALLEGRO_COLOR color)

Source Code

Draws a filled ellipse.

Parameters:

  • cx, cy - Center of the ellipse
  • rx, ry - Radii of the ellipse
  • color - Color of the ellipse

See also: al_draw_ellipse, al_draw_filled_circle

al_draw_circle

void al_draw_circle(float cx, float cy, float r, ALLEGRO_COLOR color,
   float thickness)

Source Code

Draws an outlined circle.

Parameters:

  • cx, cy - Center of the circle
  • r - Radius of the circle
  • color - Color of the circle
  • thickness - Thickness of the circle, pass <= 0 to draw a hairline circle

See also: al_draw_filled_circle, al_draw_ellipse

al_draw_filled_circle

void al_draw_filled_circle(float cx, float cy, float r, ALLEGRO_COLOR color)

Source Code

Draws a filled circle.

Parameters:

  • cx, cy - Center of the circle
  • r - Radius of the circle
  • color - Color of the circle

See also: al_draw_circle, al_draw_filled_ellipse

al_draw_arc

void al_draw_arc(float cx, float cy, float r, float start_theta,
   float delta_theta, ALLEGRO_COLOR color, float thickness)

Source Code

Draws an arc.

Parameters:

  • cx, cy - Center of the arc
  • r - Radius of the arc
  • color - Color of the arc
  • start_theta - The initial angle from which the arc is calculated in radians
  • delta_theta - Angular span of the arc in radians (pass a negative number to switch direction)
  • thickness - Thickness of the arc, pass <= 0 to draw hairline arc

See also: al_calculate_arc, al_draw_elliptical_arc

al_draw_elliptical_arc

void al_draw_elliptical_arc(float cx, float cy, float rx, float ry, float start_theta,
   float delta_theta, ALLEGRO_COLOR color, float thickness)

Source Code

Draws an elliptical arc.

Parameters:

  • cx, cy - Center of the arc
  • rx, ry - Radii of the arc
  • color - Color of the arc
  • start_theta - The initial angle from which the arc is calculated in radians
  • delta_theta - Angular span of the arc in radians (pass a negative number to switch direction)
  • thickness - Thickness of the arc, pass <= 0 to draw hairline arc

Since: 5.0.6, 5.1.0

See also: al_calculate_arc, al_draw_arc

al_calculate_spline

void al_calculate_spline(float* dest, int stride, float points[8],
   float thickness, int num_segments)

Source Code

Calculates a Bézier spline given 4 control points. If thickness <= 0, then num_segments of points are required in the destination, otherwise twice as many are needed. The destination buffer should consist of regularly spaced (by distance of stride bytes) doublets of floats, corresponding to x and y coordinates of the vertices.

Parameters:

  • dest - The destination buffer
  • stride - Distance (in bytes) between starts of successive pairs of coordinates
  • points - An array of 4 pairs of coordinates of the 4 control points
  • thickness - Thickness of the spline ribbon
  • num_segments - The number of points to calculate

See also: al_draw_spline, al_calculate_arc, al_calculate_ribbon

al_draw_spline

void al_draw_spline(float points[8], ALLEGRO_COLOR color, float thickness)

Source Code

Draws a Bézier spline given 4 control points.

Parameters:

  • points - An array of 4 pairs of coordinates of the 4 control points
  • color - Color of the spline
  • thickness - Thickness of the spline, pass <= 0 to draw a hairline spline

See also: al_calculate_spline

al_calculate_ribbon

void al_calculate_ribbon(float* dest, int dest_stride, const float *points,
   int points_stride, float thickness, int num_segments)

Source Code

Calculates a ribbon given an array of points. The ribbon will go through all of the passed points. If thickness <= 0, then num_segments of points are required in the destination buffer, otherwise twice as many are needed. The destination and the points buffer should consist of regularly spaced doublets of floats, corresponding to x and y coordinates of the vertices.

Parameters:

  • dest - Pointer to the destination buffer
  • dest_stride - Distance (in bytes) between starts of successive pairs of coordinates in the destination buffer
  • points - An array of pairs of coordinates for each point
  • points_stride - Distance (in bytes) between starts of successive pairs of coordinates in the points buffer
  • thickness - Thickness of the spline ribbon
  • num_segments - The number of points to calculate

See also: al_draw_ribbon, al_calculate_arc, al_calculate_spline

al_draw_ribbon

void al_draw_ribbon(const float *points, int points_stride, ALLEGRO_COLOR color,
   float thickness, int num_segments)

Source Code

Draws a ribbon given an array of points. The ribbon will go through all of the passed points. The points buffer should consist of regularly spaced doublets of floats, corresponding to x and y coordinates of the vertices.

Parameters:

  • points - An array of coordinate pairs (x and y) for each point
  • points_stride - Distance (in bytes) between starts of successive pairs of coordinates in the points buffer
  • color - Color of the spline
  • thickness - Thickness of the spline, pass <= 0 to draw hairline spline
  • num_segments - The number of segments

See also: al_calculate_ribbon

Low level drawing routines

Low level drawing routines allow for more advanced usage of the addon, allowing you to pass arbitrary sequences of vertices to draw to the screen. These routines also support using textures on the primitives with the following restrictions:

For maximum portability, you should only use textures that have dimensions that are a power of two, as not every videocard supports textures of different sizes completely. This warning is relaxed, however, if the texture coordinates never exit the boundaries of a single bitmap (i.e. you are not having the texture repeat/tile). As long as that is the case, any texture can be used safely. Sub-bitmaps work as textures, but cannot be tiled.

Some platforms also dictate a minimum texture size, which means that textures smaller than that size will not tile properly. The minimum size that will work on all platforms is 32 by 32.

A note about pixel coordinates. In OpenGL the texture coordinate (0, 0) refers to the top left corner of the pixel. This confuses some drivers, because due to rounding errors the actual pixel sampled might be the pixel to the top and/or left of the (0, 0) pixel. To make this error less likely it is advisable to offset the texture coordinates you pass to the al_draw_prim by (0.5, 0.5) if you need precise pixel control. E.g. to refer to pixel (5, 10) you'd set the u and v to 5.5 and 10.5 respectively.

See also: Pixel-precise output

al_draw_prim

int al_draw_prim(const void* vtxs, const ALLEGRO_VERTEX_DECL* decl,
   ALLEGRO_BITMAP* texture, int start, int end, int type)

Source Code

Draws a subset of the passed vertex array.

Parameters:

  • texture - Texture to use, pass NULL to use only color shaded primitves
  • vtxs - Pointer to an array of vertices
  • decl - Pointer to a vertex declaration. If set to NULL, the vertices are assumed to be of the ALLEGRO_VERTEX type
  • start - Start index of the subset of the vertex array to draw
  • end - One past the last index of the subset of the vertex array to draw
  • type - A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw

Returns: Number of primitives drawn

For example to draw a textured triangle you could use:

ALLEGRO_COLOR white = al_map_rgb_f(1, 1, 1);
ALLEGRO_VERTEX v[] = {
   {.x = 128, .y = 0, .z = 0, .color = white, .u = 128, .v = 0},
   {.x = 0, .y = 256, .z = 0, .color = white, .u = 0, .v = 256},
   {.x = 256, .y = 256, .z = 0, .color = white, .u = 256, .v = 256}};
al_draw_prim(v, NULL, texture, 0, 3, ALLEGRO_PRIM_TRIANGLE_LIST);

See also: ALLEGRO_VERTEX, ALLEGRO_PRIM_TYPE, ALLEGRO_VERTEX_DECL, al_draw_indexed_prim

al_draw_indexed_prim

int al_draw_indexed_prim(const void* vtxs, const ALLEGRO_VERTEX_DECL* decl,
   ALLEGRO_BITMAP* texture, const int* indices, int num_vtx, int type)

Source Code

Draws a subset of the passed vertex array. This function uses an index array to specify which vertices to use.

Parameters:

  • texture - Texture to use, pass NULL to use only color shaded primitves
  • vtxs - Pointer to an array of vertices
  • decl - Pointer to a vertex declaration. If set to NULL, the vtxs are assumed to be of the ALLEGRO_VERTEX type
  • indices - An array of indices into the vertex array
  • num_vtx - Number of indices from the indices array you want to draw
  • type - A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw

Returns: Number of primitives drawn

See also: ALLEGRO_VERTEX, ALLEGRO_PRIM_TYPE, ALLEGRO_VERTEX_DECL, al_draw_prim

al_draw_vertex_buffer

int al_draw_vertex_buffer(ALLEGRO_VERTEX_BUFFER* vertex_buffer,
   ALLEGRO_BITMAP* texture, int start, int end, int type)

Source Code

Draws a subset of the passed vertex buffer. The vertex buffer must not be locked. Additionally, to draw onto memory bitmaps or with memory bitmap textures the vertex buffer must support reading (i.e. it must be created with the ALLEGRO_PRIM_BUFFER_READWRITE).

Parameters:

  • vertex_buffer - Vertex buffer to draw
  • texture - Texture to use, pass NULL to use only color shaded primitves
  • start - Start index of the subset of the vertex buffer to draw
  • end - One past the last index of the subset of the vertex buffer to draw
  • type - A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw

Returns: Number of primitives drawn

Since: 5.1.3

See also: ALLEGRO_VERTEX_BUFFER, ALLEGRO_PRIM_TYPE

al_draw_indexed_buffer

int al_draw_indexed_buffer(ALLEGRO_VERTEX_BUFFER* vertex_buffer,
   ALLEGRO_BITMAP* texture, ALLEGRO_INDEX_BUFFER* index_buffer,
   int start, int end, int type)

Source Code

Draws a subset of the passed vertex buffer. This function uses an index buffer to specify which vertices to use. Both buffers must not be locked. Additionally, to draw onto memory bitmaps or with memory bitmap textures both buffers must support reading (i.e. they must be created with the ALLEGRO_PRIM_BUFFER_READWRITE).

Parameters:

  • vertex_buffer - Vertex buffer to draw
  • texture - Texture to use, pass NULL to use only color shaded primitves
  • index_buffer - Index buffer to use
  • start - Start index of the subset of the vertex buffer to draw
  • end - One past the last index of the subset of the vertex buffer to draw
  • type - A member of the ALLEGRO_PRIM_TYPE enumeration, specifying what kind of primitive to draw. Note that ALLEGRO_PRIM_LINE_LOOP and ALLEGRO_PRIM_POINT_LIST are not supported.

Returns: Number of primitives drawn

Since: 5.1.8

See also: ALLEGRO_VERTEX_BUFFER, ALLEGRO_INDEX_BUFFER, ALLEGRO_PRIM_TYPE

al_draw_soft_triangle

void al_draw_soft_triangle(
   ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, ALLEGRO_VERTEX* v3, uintptr_t state,
   void (*init)(uintptr_t, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),
   void (*first)(uintptr_t, int, int, int, int),
   void (*step)(uintptr_t, int),
   void (*draw)(uintptr_t, int, int, int))

Source Code

Draws a triangle using the software rasterizer and user supplied pixel functions. For help in understanding what these functions do, see the implementation of the various shading routines in addons/primitives/tri_soft.c. The triangle is drawn in two segments, from top to bottom. The segments are deliniated by the vertically middle vertex of the triangle. One of the two segments may be absent if two vertices are horizontally collinear.

Parameters:

  • v1, v2, v3 - The three vertices of the triangle
  • state - A pointer to a user supplied struct, this struct will be passed to all the pixel functions
  • init - Called once per call before any drawing is done. The three points passed to it may be altered by clipping.
  • first - Called twice per call, once per triangle segment. It is passed 4 parameters, the first two are the coordinates of the initial pixel drawn in the segment. The second two are the left minor and the left major steps, respectively. They represent the sizes of two steps taken by the rasterizer as it walks on the left side of the triangle. From then on, each step will either be classified as a minor or a major step, corresponding to the above values.
  • step - Called once per scanline. The last parameter is set to 1 if the step is a minor step, and 0 if it is a major step.
  • draw - Called once per scanline. The function is expected to draw the scanline starting with a point specified by the first two parameters (corresponding to x and y values) going to the right until it reaches the value of the third parameter (the x value of the end point). All coordinates are inclusive.

See also: al_draw_triangle

al_draw_soft_line

void al_draw_soft_line(ALLEGRO_VERTEX* v1, ALLEGRO_VERTEX* v2, uintptr_t state,
   void (*first)(uintptr_t, int, int, ALLEGRO_VERTEX*, ALLEGRO_VERTEX*),
   void (*step)(uintptr_t, int),
   void (*draw)(uintptr_t, int, int))

Source Code

Draws a line using the software rasterizer and user supplied pixel functions. For help in understanding what these functions do, see the implementation of the various shading routines in addons/primitives/line_soft.c. The line is drawn top to bottom.

Parameters:

  • v1, v2 - The two vertices of the line
  • state - A pointer to a user supplied struct, this struct will be passed to all the pixel functions
  • first - Called before drawing the first pixel of the line. It is passed the coordinates of this pixel, as well as the two vertices above. The passed vertices may have been altered by clipping.
  • step - Called once per pixel. The second parameter is set to 1 if the step is a minor step, and 0 if this step is a major step. Minor steps are taken only either in x or y directions. Major steps are taken in both directions diagonally. In all cases, the absolute value of the change in coordinate is at most 1 in either direction.
  • draw - Called once per pixel. The function is expected to draw the pixel at the coordinates passed to it.

See also: al_draw_line

Custom vertex declaration routines

al_create_vertex_decl

ALLEGRO_VERTEX_DECL* al_create_vertex_decl(const ALLEGRO_VERTEX_ELEMENT* elements, int stride)

Source Code

Creates a vertex declaration, which describes a custom vertex format.

Parameters:

  • elements - An array of ALLEGRO_VERTEX_ELEMENT structures.
  • stride - Size of the custom vertex structure

Returns: Newly created vertex declaration.

See also: ALLEGRO_VERTEX_ELEMENT, ALLEGRO_VERTEX_DECL, al_destroy_vertex_decl

al_destroy_vertex_decl

void al_destroy_vertex_decl(ALLEGRO_VERTEX_DECL* decl)

Source Code

Destroys a vertex declaration.

Parameters:

  • decl - Vertex declaration to destroy

See also: ALLEGRO_VERTEX_ELEMENT, ALLEGRO_VERTEX_DECL, al_create_vertex_decl

Vertex buffer routines

al_create_vertex_buffer

ALLEGRO_VERTEX_BUFFER* al_create_vertex_buffer(ALLEGRO_VERTEX_DECL* decl,
   const void* initial_data, int num_vertices, int flags)

Source Code

Creates a vertex buffer. Can return NULL if the buffer could not be created (e.g. the system only supports write-only buffers).

Note:

This is an advanced feature, often unsupported on lower-end video cards. Be extra mindful of this function failing and make arrangements for fallback drawing functionality or a nice error message for users with such lower-end cards.

Parameters:

  • decl - Vertex type that this buffer will hold. NULL implies that this buffer will hold ALLEGRO_VERTEX vertices
  • initial_data - Memory buffer to copy from to initialize the vertex buffer. Can be NULL, in which case the buffer is uninitialized.
  • num_vertices - Number of vertices the buffer will hold
  • flags - A combination of the ALLEGRO_PRIM_BUFFER_FLAGS flags specifying how this buffer will be created. Passing 0 is the same as passing ALLEGRO_PRIM_BUFFER_STATIC.

Since: 5.1.3

See also: ALLEGRO_VERTEX_BUFFER, al_destroy_vertex_buffer

al_destroy_vertex_buffer

void al_destroy_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)

Source Code

Destroys a vertex buffer. Does nothing if passed NULL.

Since: 5.1.3

See also: ALLEGRO_VERTEX_BUFFER, al_create_vertex_buffer

al_lock_vertex_buffer

void* al_lock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer, int offset,
   int length, int flags)

Source Code

Locks a vertex buffer so you can access its data. Will return NULL if the parameters are invalid, if reading is requested from a write only buffer, or if the buffer is already locked.

Parameters:

  • buffer - Vertex buffer to lock
  • offset - Vertex index of the start of the locked range
  • length - How many vertices to lock
  • flags - ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or ALLEGRO_LOCK_READWRITE

Since: 5.1.3

See also: ALLEGRO_VERTEX_BUFFER, al_unlock_vertex_buffer

al_unlock_vertex_buffer

void al_unlock_vertex_buffer(ALLEGRO_VERTEX_BUFFER* buffer)

Source Code

Unlocks a previously locked vertex buffer.

Since: 5.1.3

See also: ALLEGRO_VERTEX_BUFFER, al_lock_vertex_buffer

al_get_vertex_buffer_size

int al_get_vertex_buffer_size(ALLEGRO_VERTEX_BUFFER* buffer)

Source Code

Returns the size of the vertex buffer

Since: 5.1.8

See also: ALLEGRO_VERTEX_BUFFER

Index buffer routines

al_create_index_buffer

ALLEGRO_INDEX_BUFFER* al_create_index_buffer(int index_size,
    const void* initial_data, int num_indices, int flags)

Source Code

Creates a index buffer. Can return NULL if the buffer could not be created (e.g. the system only supports write-only buffers).

Note:

This is an advanced feature, often unsupported on lower-end video cards. Be extra mindful of this function failing and make arrangements for fallback drawing functionality or a nice error message for users with such lower-end cards.

Parameters:

  • index_size - Size of the index in bytes. Supported sizes are 2 for short integers and 4 for integers
  • initial_data - Memory buffer to copy from to initialize the index buffer. Can be NULL, in which case the buffer is uninitialized.
  • num_indices - Number of indices the buffer will hold
  • flags - A combination of the ALLEGRO_PRIM_BUFFER_FLAGS flags specifying how this buffer will be created. Passing 0 is the same as passing ALLEGRO_PRIM_BUFFER_STATIC.

Since: 5.1.8

See also: ALLEGRO_INDEX_BUFFER, al_destroy_index_buffer

al_destroy_index_buffer

void al_destroy_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)

Source Code

Destroys a index buffer. Does nothing if passed NULL.

Since: 5.1.8

See also: ALLEGRO_INDEX_BUFFER, al_create_index_buffer

al_lock_index_buffer

void* al_lock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer, int offset,
    int length, int flags)

Source Code

Locks a index buffer so you can access its data. Will return NULL if the parameters are invalid, if reading is requested from a write only buffer and if the buffer is already locked.

Parameters:

  • buffer - Index buffer to lock
  • offset - Element index of the start of the locked range
  • length - How many indices to lock
  • flags - ALLEGRO_LOCK_READONLY, ALLEGRO_LOCK_WRITEONLY or ALLEGRO_LOCK_READWRITE

Since: 5.1.8

See also: ALLEGRO_INDEX_BUFFER, al_unlock_index_buffer

al_unlock_index_buffer

void al_unlock_index_buffer(ALLEGRO_INDEX_BUFFER* buffer)

Source Code

Unlocks a previously locked index buffer.

Since: 5.1.8

See also: ALLEGRO_INDEX_BUFFER, al_lock_index_buffer

al_get_index_buffer_size

int al_get_index_buffer_size(ALLEGRO_INDEX_BUFFER* buffer)

Source Code

Returns the size of the index buffer

Since: 5.1.8

See also: ALLEGRO_INDEX_BUFFER

Polygon routines

al_draw_polyline

void al_draw_polyline(const float* vertices, int vertex_stride,
   int vertex_count, int join_style, int cap_style,
   ALLEGRO_COLOR color, float thickness, float miter_limit)

Source Code

Draw a series of line segments.

  • vertices - Interleaved array of (x, y) vertex coordinates
  • vertex_stride - the number of bytes between pairs of vertices (the stride)
  • vertex_count - Number of vertices in the array
  • join_style - Member of ALLEGRO_LINE_JOIN specifying how to render the joins between line segments
  • cap_style - Member of ALLEGRO_LINE_CAP specifying how to render the end caps
  • color - Color of the line
  • thickness - Thickness of the line, pass <= 0 to draw hairline lines
  • miter_limit - Parameter for miter join style

The stride is normally 2 * sizeof(float) but may be more if the vertex coordinates are in an array of some structure type, e.g.

struct VertexInfo {
   float x;
   float y;
   int id;
};

void my_draw(struct VertexInfo verts[], int vertex_count, ALLEGRO_COLOR c)
{
   al_draw_polyline((float *)verts, sizeof(VertexInfo), vertex_count,
      ALLEGRO_LINE_JOIN_NONE, ALLEGRO_LINE_CAP_NONE, c, 1.0, 1.0);
}

The stride may also be negative if the vertices are stored in reverse order.

Since: 5.1.0

See also: al_draw_polygon, ALLEGRO_LINE_JOIN, ALLEGRO_LINE_CAP

al_draw_polygon

void al_draw_polygon(const float *vertices, int vertex_count,
   int join_style, ALLEGRO_COLOR color, float thickness, float miter_limit)

Source Code

Draw an unfilled polygon. This is the same as passing ALLEGRO_LINE_CAP_CLOSED to al_draw_polyline.

  • vertex - Interleaved array of (x, y) vertex coordinates
  • vertex_count - Number of vertices in the array
  • join_style - Member of ALLEGRO_LINE_JOIN specifying how to render the joins between line segments
  • color - Color of the line
  • thickness - Thickness of the line, pass <= 0 to draw hairline lines
  • miter_limit - Parameter for miter join style

Since: 5.1.0

See also: al_draw_filled_polygon, al_draw_polyline, ALLEGRO_LINE_JOIN

al_draw_filled_polygon

void al_draw_filled_polygon(const float *vertices, int vertex_count,
   ALLEGRO_COLOR color)

Source Code

Draw a filled, simple polygon. Simple means it does not have to be convex but must not be self-overlapping.

  • vertices - Interleaved array of (x, y) vertex coordinates
  • vertex_count - Number of vertices in the array
  • color - Color of the filled polygon

When the y-axis is facing downwards (the usual), the coordinates must be ordered anti-clockwise.

Since: 5.1.0

See also: al_draw_polygon, al_draw_filled_polygon_with_holes

al_draw_filled_polygon_with_holes

void al_draw_filled_polygon_with_holes(const float *vertices,
   const int *vertex_counts, ALLEGRO_COLOR color)

Source Code

Draws a filled simple polygon with zero or more other simple polygons subtracted from it - the holes. The holes cannot touch or intersect with the outline of the filled polygon.

  • vertices - Interleaved array of (x, y) vertex coordinates for each of the polygons, including holes.
  • vertex_counts - Number of vertices for each polygon. The number of vertices in the filled polygon is given by vertex_counts[0] and must be at least three. Subsequent elements indicate the number of vertices in each hole. The array must be terminated with an element with value zero.
  • color - Color of the filled polygon

All hole vertices must use the opposite order (clockwise with y down) of the polygon vertices. All hole vertices must be inside the main polygon and no hole may overlap the main polygon.

For example:

float vertices[] = {
      0,   0, // filled polygon, upper left corner
      0, 100, // filled polygon, lower left corner
    100, 100, // filled polygon, lower right corner
    100,   0, // filled polygon, upper right corner
     10,  10, // hole, upper left
     90,  10, // hole, upper right
     90,  90  // hole, lower right
};
int vertex_counts[] = {
   4, // number of vertices for filled polygon
   3, // number of vertices for hole
   0  // terminator
};

There are 7 vertices: four for an outer square from (0, 0) to (100, 100) in anti-clockwise order, and three more for an inner triangle in clockwise order. The outer main polygon uses vertices 0 to 3 (inclusive) and the hole uses vertices 4 to 6 (inclusive).

Since: 5.1.0

See also: al_draw_filled_polygon, al_draw_filled_polygon_with_holes, al_triangulate_polygon

al_triangulate_polygon

bool al_triangulate_polygon(
   const float* vertices, size_t vertex_stride, const int* vertex_counts,
   void (*emit_triangle)(int, int, int, void*), void* userdata)

Source Code

Divides a simple polygon into triangles, with zero or more other simple polygons subtracted from it - the holes. The holes cannot touch or intersect with the outline of the main polygon. Simple means the polygon does not have to be convex but must not be self-overlapping.

Parameters:

  • vertices - Interleaved array of (x, y) vertex coordinates for each of the polygons, including holes.
  • vertex_stride - distance (in bytes) between successive pairs of vertices in the array.
  • vertex_counts - Number of vertices for each polygon. The number of vertices in the main polygon is given by vertex_counts[0] and must be at least three. Subsequent elements indicate the number of vertices in each hole. The array must be terminated with an element with value zero.
  • emit_triangle - a function to be called for every set of three points that form a triangle. The function is passed the indices of the points in vertices and userdata.
  • userdata - arbitrary data to be passed to emit_triangle.

Since: 5.1.0

See also: al_draw_filled_polygon_with_holes

Structures and types

ALLEGRO_VERTEX

typedef struct ALLEGRO_VERTEX ALLEGRO_VERTEX;

Source Code

Defines the generic vertex type, with a 3D position, color and texture coordinates for a single texture. Note that at this time, the software driver for this addon cannot render 3D primitives. If you want a 2D only primitive, set z to 0. Note that you must initialize all members of this struct when you're using it. One exception to this rule are the u and v variables which can be left uninitialized when you are not using textures.

Fields:

  • x, y, z - Position of the vertex (float)
  • u, v - Texture coordinates measured in pixels (float)
  • color - ALLEGRO_COLOR structure, storing the color of the vertex

See also: ALLEGRO_PRIM_ATTR

ALLEGRO_VERTEX_DECL

typedef struct ALLEGRO_VERTEX_DECL ALLEGRO_VERTEX_DECL;

Source Code

A vertex declaration. This opaque structure is responsible for describing the format and layout of a user defined custom vertex. It is created and destroyed by specialized functions.

See also: al_create_vertex_decl, al_destroy_vertex_decl, ALLEGRO_VERTEX_ELEMENT

ALLEGRO_VERTEX_ELEMENT

typedef struct ALLEGRO_VERTEX_ELEMENT ALLEGRO_VERTEX_ELEMENT;

Source Code

A small structure describing a certain element of a vertex. E.g. the position of the vertex, or its color. These structures are used by the al_create_vertex_decl function to create the vertex declaration. For that they generally occur in an array. The last element of such an array should have the attribute field equal to 0, to signify that it is the end of the array. Here is an example code that would create a declaration describing the ALLEGRO_VERTEX structure (passing this as vertex declaration to al_draw_prim would be identical to passing NULL):

/* On compilers without the offsetof keyword you need to obtain the
 * offset with sizeof and make sure to account for packing.
 */
ALLEGRO_VERTEX_ELEMENT elems[] = {
   {ALLEGRO_PRIM_POSITION, ALLEGRO_PRIM_FLOAT_3, offsetof(ALLEGRO_VERTEX, x)},
   {ALLEGRO_PRIM_TEX_COORD_PIXEL, ALLEGRO_PRIM_FLOAT_2, offsetof(ALLEGRO_VERTEX, u)},
   {ALLEGRO_PRIM_COLOR_ATTR, 0, offsetof(ALLEGRO_VERTEX, color)},
   {0, 0, 0}
};
ALLEGRO_VERTEX_DECL* decl = al_create_vertex_decl(elems, sizeof(ALLEGRO_VERTEX));

Fields:

  • attribute - A member of the ALLEGRO_PRIM_ATTR enumeration, specifying what this attribute signifies
  • storage - A member of the ALLEGRO_PRIM_STORAGE enumeration, specifying how this attribute is stored
  • offset - Offset in bytes from the beginning of the custom vertex structure. The C function offsetof is very useful here.

See also: al_create_vertex_decl, ALLEGRO_VERTEX_DECL, ALLEGRO_PRIM_ATTR, ALLEGRO_PRIM_STORAGE

ALLEGRO_PRIM_TYPE

typedef enum ALLEGRO_PRIM_TYPE

Source Code

Enumerates the types of primitives this addon can draw.

  • ALLEGRO_PRIM_POINT_LIST - A list of points, each vertex defines a point

  • ALLEGRO_PRIM_LINE_LIST - A list of lines, sequential pairs of vertices define disjointed lines

  • ALLEGRO_PRIM_LINE_STRIP - A strip of lines, sequential vertices define a strip of lines

  • ALLEGRO_PRIM_LINE_LOOP - Like a line strip, except at the end the first and the last vertices are also connected by a line

  • ALLEGRO_PRIM_TRIANGLE_LIST - A list of triangles, sequential triplets of vertices define disjointed triangles

  • ALLEGRO_PRIM_TRIANGLE_STRIP - A strip of triangles, sequential vertices define a strip of triangles

  • ALLEGRO_PRIM_TRIANGLE_FAN - A fan of triangles, all triangles share the first vertex

ALLEGRO_PRIM_ATTR

typedef enum ALLEGRO_PRIM_ATTR

Source Code

Enumerates the types of vertex attributes that a custom vertex may have.

  • ALLEGRO_PRIM_POSITION - Position information, can be stored only in ALLEGRO_PRIM_SHORT_2, ALLEGRO_PRIM_FLOAT_2 and ALLEGRO_PRIM_FLOAT_3.

  • ALLEGRO_PRIM_COLOR_ATTR - Color information, stored in an ALLEGRO_COLOR. The storage field of ALLEGRO_VERTEX_ELEMENT is ignored

  • ALLEGRO_PRIM_TEX_COORD - Texture coordinate information, can be stored only in ALLEGRO_PRIM_FLOAT_2 and ALLEGRO_PRIM_SHORT_2. These coordinates are normalized by the width and height of the texture, meaning that the bottom-right corner has texture coordinates of (1, 1).

  • ALLEGRO_PRIM_TEX_COORD_PIXEL - Texture coordinate information, can be stored only in ALLEGRO_PRIM_FLOAT_2 and ALLEGRO_PRIM_SHORT_2. These coordinates are measured in pixels.

  • ALLEGRO_PRIM_USER_ATTR - A user specified attribute. You can use any storage for this attribute. You may have at most ALLEGRO_PRIM_MAX_USER_ATTR (currently 10) of these that you can specify by adding an index to the value of ALLEGRO_PRIM_USER_ATTR, e.g. the first user attribute is ALLEGRO_PRIM_USER_ATTR + 0, the second is ALLEGRO_PRIM_USER_ATTR + 1 and so on.

    To access these custom attributes from GLSL shaders you need to declare attributes that follow this nomenclature: user_attr_# where # is the index of the attribute.

    To access these custom attributes from HLSL you need to declare a parameter with the following semantics: TEXCOORD{# + 2} where # is the index of the attribute. E.g. the first attribute can be accessed via TEXCOORD2, second via TEXCOORD3 and so on.

    Since: 5.1.6

See also: ALLEGRO_VERTEX_DECL, ALLEGRO_PRIM_STORAGE

ALLEGRO_PRIM_STORAGE

typedef enum ALLEGRO_PRIM_STORAGE

Source Code

Enumerates the types of storage an attribute of a custom vertex may be stored in. Many of these can only be used for ALLEGRO_PRIM_USER_ATTR attributes and can only be accessed via shaders. Usually no matter what the storage is specified the attribute gets converted to single precision floating point when the shader is run. Despite that, it may be advantageous to use more dense storage formats (e.g. ALLEGRO_PRIM_NORMALIZED_UBYTE_4 instead of ALLEGRO_PRIM_FLOAT_4) when bandwidth (amount of memory sent to the GPU) is an issue but precision is not.

  • ALLEGRO_PRIM_FLOAT_1 - A single float

    Since: 5.1.6

  • ALLEGRO_PRIM_FLOAT_2 - A doublet of floats

  • ALLEGRO_PRIM_FLOAT_3 - A triplet of floats

  • ALLEGRO_PRIM_FLOAT_4 - A quad of floats

    Since: 5.1.6

  • ALLEGRO_PRIM_SHORT_2 - A doublet of shorts

  • ALLEGRO_PRIM_SHORT_4 - A quad of shorts

    Since: 5.1.6

  • ALLEGRO_PRIM_UBYTE_4 - A quad of unsigned bytes

    Since: 5.1.6

  • ALLEGRO_PRIM_NORMALIZED_SHORT_2 - A doublet of shorts. Before being sent to the shader, each component is divided by 32767. Each component of the resultant float doublet ranges between -1.0 and 1.0

    Since: 5.1.6

  • ALLEGRO_PRIM_NORMALIZED_SHORT_4 - A quad of shorts. Before being sent to the shader, each component is divided by 32767. Each component of the resultant float quad ranges between -1.0 and 1.0

    Since: 5.1.6

  • ALLEGRO_PRIM_NORMALIZED_UBYTE_4 - A quad of unsigned bytes. Before being sent to the shader, each component is divided by 255. Each component of the resultant float quad ranges between 0.0 and 1.0

    Since: 5.1.6

  • ALLEGRO_PRIM_NORMALIZED_USHORT_2 - A doublet of unsigned shorts. Before being sent to the shader, each component is divided by 65535. Each component of the resultant float doublet ranges between 0.0 and 1.0

    Since: 5.1.6

  • ALLEGRO_PRIM_NORMALIZED_USHORT_4 - A quad of unsigned shorts. Before being sent to the shader, each component is divided by 65535. Each component of the resultant float quad ranges between 0.0 and 1.0

    Since: 5.1.6

  • ALLEGRO_PRIM_HALF_FLOAT_2 - A doublet of half-precision floats. Note that this storage format is not supported on all platforms. al_create_vertex_decl will return NULL if you use it on those platforms

    Since: 5.1.6

  • ALLEGRO_PRIM_HALF_FLOAT_4 - A quad of half-precision floats. Note that this storage format is not supported on all platforms. al_create_vertex_decl will return NULL if you use it on those platforms.

    Since: 5.1.6

See also: ALLEGRO_PRIM_ATTR

ALLEGRO_VERTEX_CACHE_SIZE

#define ALLEGRO_VERTEX_CACHE_SIZE 256

Source Code

Defines the size of the transformation vertex cache for the software renderer. If you pass less than this many vertices to the primitive rendering functions you will get a speed boost. This also defines the size of the cache vertex buffer, used for the high-level primitives. This corresponds to the maximum number of line segments that will be used to form them.

ALLEGRO_PRIM_QUALITY

#define ALLEGRO_PRIM_QUALITY 10

Source Code

Controls the quality of the approximation of curved primitives (e.g. circles). Curved primitives are drawn by approximating them with a sequence of line segments. By default, this roughly corresponds to error of less than half of a pixel.

ALLEGRO_LINE_JOIN

typedef enum ALLEGRO_LINE_JOIN

Source Code

  • ALLEGRO_LINE_JOIN_NONE
  • ALLEGRO_LINE_JOIN_BEVEL
  • ALLEGRO_LINE_JOIN_ROUND
  • ALLEGRO_LINE_JOIN_MITER

ALLEGRO_LINE_JOIN styles

See the picture for the difference.

The maximum miter length (relative to the line width) can be specified as parameter to the polygon functions.

Since: 5.1.0

See also: al_draw_polygon

ALLEGRO_LINE_CAP

typedef enum ALLEGRO_LINE_CAP

Source Code

  • ALLEGRO_LINE_CAP_NONE
  • ALLEGRO_LINE_CAP_SQUARE
  • ALLEGRO_LINE_CAP_ROUND
  • ALLEGRO_LINE_CAP_TRIANGLE
  • ALLEGRO_LINE_CAP_CLOSED

ALLEGRO_LINE_CAP styles

See the picture for the difference.

ALLEGRO_LINE_CAP_CLOSED is different from the others - it causes the polygon to have no caps. (And the ALLEGRO_LINE_JOIN style will determine how the vertex looks.)

Since: 5.1.0

See also: al_draw_polygon

ALLEGRO_VERTEX_BUFFER

typedef struct ALLEGRO_VERTEX_BUFFER ALLEGRO_VERTEX_BUFFER;

Source Code

A GPU vertex buffer that you can use to store vertices on the GPU instead of uploading them afresh during every drawing operation.

Since: 5.1.3

See also: al_create_vertex_buffer, al_destroy_vertex_buffer

ALLEGRO_INDEX_BUFFER

typedef struct ALLEGRO_INDEX_BUFFER ALLEGRO_INDEX_BUFFER;

Source Code

A GPU index buffer that you can use to store indices of vertices in a vertex buffer on the GPU instead of uploading them afresh during every drawing operation.

Since: 5.1.8

See also: al_create_index_buffer, al_destroy_index_buffer

ALLEGRO_PRIM_BUFFER_FLAGS

typedef enum ALLEGRO_PRIM_BUFFER_FLAGS

Source Code

Flags to specify how to create a vertex or an index buffer.

  • ALLEGRO_PRIM_BUFFER_STREAM - Hints to the driver that the buffer is written to often, but used only a few times per frame

  • ALLEGRO_PRIM_BUFFER_STATIC - Hints to the driver that the buffer is written to once and is used often

  • ALLEGRO_PRIM_BUFFER_DYNAMIC - Hints to the driver that the buffer is written to often and is used often

  • ALLEGRO_PRIM_BUFFER_READWRITE - Specifies that you want to be able read from this buffer. By default this is disabled for performance. Some platforms (like OpenGL ES) do not support reading from vertex buffers, so if you pass this flag to al_create_vertex_buffer or al_create_index_buffer the call will fail.

Since: 5.1.3

See also: al_create_vertex_buffer, al_create_index_buffer

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:19 UTC


Shader routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Shader routines

  • ALLEGRO_SHADER
  • ALLEGRO_SHADER_TYPE
  • ALLEGRO_SHADER_PLATFORM
  • al_create_shader
  • al_attach_shader_source
  • al_attach_shader_source_file
  • al_build_shader
  • al_get_shader_log
  • al_get_shader_platform
  • al_use_shader
  • al_destroy_shader
  • al_set_shader_sampler
  • al_set_shader_matrix
  • al_set_shader_int
  • al_set_shader_float
  • al_set_shader_bool
  • al_set_shader_int_vector
  • al_set_shader_float_vector
  • al_get_default_shader_source

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_SHADER

typedef struct ALLEGRO_SHADER ALLEGRO_SHADER;

Source Code

An ALLEGRO_SHADER is a program that runs on the GPU. It combines both a vertex and a pixel shader. (In OpenGL terms, an ALLEGRO_SHADER is actually a program which has one or more shaders attached. This can be confusing.)

The source code for the underlying vertex or pixel shader can be provided either as GLSL or HLSL, depending on the value of ALLEGRO_SHADER_PLATFORM used when creating it.

Since: 5.1.0

ALLEGRO_SHADER_TYPE

typedef enum ALLEGRO_SHADER_TYPE ALLEGRO_SHADER_TYPE;

Source Code

Used with al_attach_shader_source and al_attach_shader_source_file to specify how to interpret the attached source.

ALLEGRO_VERTEX_SHADER

A vertex shader is executed for each vertex it is used with. The program will output exactly one vertex at a time.

When Allegro's graphics are being used then in addition to all vertices of primitives from the primitives addon, each drawn bitmap also consists of four vertices.

ALLEGRO_PIXEL_SHADER

A pixel shader is executed for each pixel it is used with. The program will output exactly one pixel at a time - either in the backbuffer or in the current target bitmap.

With Allegro's builtin graphics this means the shader is for example called for each destination pixel of the output of an al_draw_bitmap call.

A more accurate term for pixel shader would be fragment shader since one final pixel in the target bitmap is not necessarily composed of only a single output but of multiple fragments (for example when multi-sampling is being used).

Since: 5.1.0

ALLEGRO_SHADER_PLATFORM

typedef enum ALLEGRO_SHADER_PLATFORM ALLEGRO_SHADER_PLATFORM;

Source Code

The underlying platform which the ALLEGRO_SHADER is built on top of, which dictates the language used to program the shader.

  • ALLEGRO_SHADER_AUTO
  • ALLEGRO_SHADER_GLSL - OpenGL Shading Language
  • ALLEGRO_SHADER_HLSL - High Level Shader Language (for Direct3D)

Since: 5.1.0

al_create_shader

ALLEGRO_SHADER *al_create_shader(ALLEGRO_SHADER_PLATFORM platform)

Source Code

Create a shader object.

The platform argument is one of the ALLEGRO_SHADER_PLATFORM values, and specifies the type of shader object to create, and which language is used to program the shader.

The shader platform must be compatible with the type of display that you will use the shader with. For example, you cannot create and use a HLSL shader on an OpenGL display, nor a GLSL shader on a Direct3D display.

The ALLEGRO_SHADER_AUTO value automatically chooses the appropriate platform for the display currently targeted by the calling thread; there must be such a display. It will create a GLSL shader for an OpenGL display, and a HLSL shader for a Direct3D display.

Returns the shader object on success. Otherwise, returns NULL.

Since: 5.1.0

See also: al_attach_shader_source, al_attach_shader_source_file, al_build_shader, al_use_shader, al_destroy_shader, al_get_shader_platform

al_attach_shader_source

bool al_attach_shader_source(ALLEGRO_SHADER *shader, ALLEGRO_SHADER_TYPE type,
    const char *source)

Source Code

Attaches the shader's source code to the shader object and compiles it. Passing NULL deletes the underlying (OpenGL or DirectX) shader. See also al_attach_shader_source_file if you prefer to obtain your shader source from an external file.

If you do not use ALLEGRO_PROGRAMMABLE_PIPELINE Allegro's graphics functions will not use any shader specific functions themselves. In case of a system with no fixed function pipeline (like OpenGL ES 2 or OpenGL 3 or 4) this means Allegro's drawing functions cannot be used.

TODO: Is ALLEGRO_PROGRAMMABLE_PIPELINE set automatically in this case?

When ALLEGRO_PROGRAMMABLE_PIPELINE is used the following shader uniforms are provided by Allegro and can be accessed in your shaders:

al_projview_matrix
matrix for Allegro's orthographic projection multiplied by the al_use_transform matrix. The type is mat4 in GLSL, and float4x4 in HLSL.
al_use_tex
whether or not to use the bound texture. The type is bool in both GLSL and HLSL.
al_tex
the texture if one is bound. The type is sampler2D in GLSL and texture in HLSL.
al_use_tex_matrix
whether or not to use a texture matrix (used by the primitives addon). The type is bool in both GLSL and HLSL.
al_tex_matrix
the texture matrix (used by the primitives addon). Your shader should multiply the texture coordinates by this matrix. The type is mat4 in GLSL, and float4x4 in HLSL.

For GLSL shaders the vertex attributes are passed using the following variables:

al_pos
vertex position attribute. Type is vec4.
al_texcoord
vertex texture coordinate attribute. Type is vec2.
al_color
vertex color attribute. Type is vec4.

For HLSL shaders the vertex attributes are passed using the following semantics:

POSITION0
vertex position attribute. Type is float4.
TEXCOORD0
vertex texture coordinate attribute. Type is float2.
TEXCOORD1
vertex color attribute. Type is float4.

Also, each shader variable has a corresponding macro name that can be used when defining the shaders using string literals. Don't use these macros with the other shader functions as that will lead to undefined behavior.

  • ALLEGRO_SHADER_VAR_PROJVIEW_MATRIX for "al_projview_matrix"
  • ALLEGRO_SHADER_VAR_POS for "al_pos"
  • ALLEGRO_SHADER_VAR_COLOR for "al_color"
  • ALLEGRO_SHADER_VAR_TEXCOORD for "al_texcoord"
  • ALLEGRO_SHADER_VAR_USE_TEX for "al_use_tex"
  • ALLEGRO_SHADER_VAR_TEX for "al_tex"
  • ALLEGRO_SHADER_VAR_USE_TEX_MATRIX for "al_use_tex_matrix"
  • ALLEGRO_SHADER_VAR_TEX_MATRIX for "al_tex_matrix"

Examine the output of al_get_default_shader_source for an example of how to use the above uniforms and attributes.

Returns true on success and false on error, in which case the error log is updated. The error log can be retrieved with al_get_shader_log.

Since: 5.1.0

See also: al_attach_shader_source_file, al_build_shader, al_get_default_shader_source, al_get_shader_log

al_attach_shader_source_file

bool al_attach_shader_source_file(ALLEGRO_SHADER *shader,
   ALLEGRO_SHADER_TYPE type, const char *filename)

Source Code

Like al_attach_shader_source but reads the source code for the shader from the named file.

Returns true on success and false on error, in which case the error log is updated. The error log can be retrieved with al_get_shader_log.

Since: 5.1.0

See also: al_attach_shader_source, al_build_shader, al_get_shader_log

al_build_shader

bool al_build_shader(ALLEGRO_SHADER *shader)

Source Code

This is required before the shader can be used with al_use_shader. It should be called after successfully attaching the pixel and/or vertex shaders with al_attach_shader_source or al_attach_shader_source_file.

Returns true on success and false on error, in which case the error log is updated. The error log can be retrieved with al_get_shader_log.

Note: If you are using the ALLEGRO_PROGRAMMABLE_PIPELINE flag, then you must specify both a pixel and a vertex shader sources for anything to be rendered.

Since: 5.1.6

See also: al_use_shader, al_get_shader_log

al_get_shader_log

const char *al_get_shader_log(ALLEGRO_SHADER *shader)

Source Code

Return a read-only string containing the information log for a shader program. The log is updated by certain functions, such as al_attach_shader_source or al_build_shader when there is an error.

This function never returns NULL.

Since: 5.1.0

See also: al_attach_shader_source, al_attach_shader_source_file, al_build_shader

al_get_shader_platform

ALLEGRO_SHADER_PLATFORM al_get_shader_platform(ALLEGRO_SHADER *shader)

Source Code

Returns the platform the shader was created with (either ALLEGRO_SHADER_HLSL or ALLEGRO_SHADER_GLSL).

Since: 5.1.6

See also: al_create_shader

al_use_shader

bool al_use_shader(ALLEGRO_SHADER *shader)

Source Code

Uses the shader for subsequent drawing operations on the current target bitmap. Pass NULL to stop using any shader on the current target bitmap.

Returns true on success. Otherwise returns false, e.g. because the shader is incompatible with the target bitmap.

Since: 5.1.6

See also: al_destroy_shader, al_set_shader_sampler, al_set_shader_matrix, al_set_shader_int, al_set_shader_float, al_set_shader_bool, al_set_shader_int_vector, al_set_shader_float_vector

al_destroy_shader

void al_destroy_shader(ALLEGRO_SHADER *shader)

Source Code

Destroy a shader. Any bitmaps which currently use the shader will implicitly stop using the shader. In multi-threaded programs, be careful that no such bitmaps are being accessed by other threads at the time.

As a convenience, if the target bitmap of the calling thread is using the shader then the shader is implicitly unused before being destroyed.

This function does nothing if the shader argument is NULL.

Since: 5.1.0

See also: al_create_shader

al_set_shader_sampler

bool al_set_shader_sampler(const char *name,
   ALLEGRO_BITMAP *bitmap, int unit)

Source Code

Sets a texture sampler uniform and texture unit of the current target bitmap's shader. The given bitmap must be a video bitmap.

Different samplers should use different units. The bitmap passed to Allegro's drawing functions uses the 0th unit, so if you're planning on using the al_tex variable in your pixel shader as well as another sampler, set the other sampler to use a unit different from 0. With the primitives addon, it is possible to free up the 0th unit by passing NULL as the texture argument to the relevant drawing functions. In this case, you may set a sampler to use the 0th unit and thus not use al_tex (the al_use_tex variable will be set to false).

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_use_shader

al_set_shader_matrix

bool al_set_shader_matrix(const char *name,
   const ALLEGRO_TRANSFORM *matrix)

Source Code

Sets a matrix uniform of the current target bitmap's shader.

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_use_shader

al_set_shader_int

bool al_set_shader_int(const char *name, int i)

Source Code

Sets an integer uniform of the current target bitmap's shader.

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_use_shader

al_set_shader_float

bool al_set_shader_float(const char *name, float f)

Source Code

Sets a float uniform of the target bitmap's shader.

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_use_shader

al_set_shader_bool

bool al_set_shader_bool(const char *name, bool b)

Source Code

Sets a boolean uniform of the target bitmap's shader.

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.6

See also: al_use_shader

al_set_shader_int_vector

bool al_set_shader_int_vector(const char *name,
   int num_components, const int *i, int num_elems)

Source Code

Sets an integer vector array uniform of the current target bitmap's shader. The 'num_components' parameter can take one of the values 1, 2, 3 or 4. If it is 1 then an array of 'num_elems' integer elements is added. Otherwise each added array element is assumed to be a vector with 2, 3 or 4 components in it.

For example, if you have a GLSL uniform declared as uniform ivec3 flowers[4] or an HLSL uniform declared as uniform int3 flowers[4], then you'd use this function from your code like so:

int flowers[4][3] =
{
   {1, 2, 3},
   {4, 5, 6},
   {7, 8, 9},
   {2, 5, 7}
};

al_set_shader_int_vector("flowers", 3, (int*)flowers, 4);

Returns true on success. Otherwise returns false, e.g. if the uniform by that name does not exist in the shader.

Since: 5.1.0

See also: al_set_shader_float_vector, al_use_shader

al_set_shader_float_vector

bool al_set_shader_float_vector(const char *name,
   int num_components, const float *f, int num_elems)

Source Code

Same as al_set_shader_int_vector except all values are float instead of int.

Since: 5.1.0

See also: al_set_shader_int_vector, al_use_shader

al_get_default_shader_source

char const *al_get_default_shader_source(ALLEGRO_SHADER_PLATFORM platform,
   ALLEGRO_SHADER_TYPE type)

Source Code

Returns a string containing the source code to Allegro's default vertex or pixel shader appropriate for the passed platform. The ALLEGRO_SHADER_AUTO value means GLSL is used if OpenGL is being used otherwise HLSL. ALLEGRO_SHADER_AUTO requires that there is a current display set on the calling thread. This function can return NULL if Allegro was built without support for shaders of the selected platform.

Since: 5.1.6

See also: al_attach_shader_source

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:19 UTC


State

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

State

  • ALLEGRO_STATE
  • ALLEGRO_STATE_FLAGS
  • al_restore_state
  • al_store_state
  • al_get_errno
  • al_set_errno

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_STATE

typedef struct ALLEGRO_STATE ALLEGRO_STATE;

Source Code

Opaque type which is passed to al_store_state/al_restore_state.

The various state kept internally by Allegro can be displayed like this:

  global
      active system driver
          current config
  per thread
      new bitmap params
      new display params
      active file interface
      errno
      current blending mode
      current display
          deferred drawing
      current target bitmap
          current transformation
          current projection transformation
          current clipping rectangle
          bitmap locking
          current shader

In general, the only real global state is the active system driver. All other global state is per-thread, so if your application has multiple separate threads they never will interfere with each other. (Except if there are objects accessed by multiple threads of course. Usually you want to minimize that though and for the remaining cases use synchronization primitives described in the threads section or events described in the events section to control inter-thread communication.)

ALLEGRO_STATE_FLAGS

typedef enum ALLEGRO_STATE_FLAGS

Source Code

Flags which can be passed to al_store_state/al_restore_state as bit combinations. See al_store_state for the list of flags.

al_restore_state

void al_restore_state(ALLEGRO_STATE const *state)

Source Code

Restores part of the state of the current thread from the given ALLEGRO_STATE object.

See also: al_store_state, ALLEGRO_STATE_FLAGS

al_store_state

void al_store_state(ALLEGRO_STATE *state, int flags)

Source Code

Stores part of the state of the current thread in the given ALLEGRO_STATE object. The flags parameter can take any bit-combination of these flags:

  • ALLEGRO_STATE_NEW_DISPLAY_PARAMETERS - new_display_format, new_display_refresh_rate, new_display_flags
  • ALLEGRO_STATE_NEW_BITMAP_PARAMETERS - new_bitmap_format, new_bitmap_flags
  • ALLEGRO_STATE_DISPLAY - current_display
  • ALLEGRO_STATE_TARGET_BITMAP - target_bitmap
  • ALLEGRO_STATE_BLENDER - blender
  • ALLEGRO_STATE_TRANSFORM - current_transformation
  • ALLEGRO_STATE_PROJECTION_TRANSFORM - current_projection_transformation
  • ALLEGRO_STATE_NEW_FILE_INTERFACE - new_file_interface
  • ALLEGRO_STATE_BITMAP - same as ALLEGRO_STATE_NEW_BITMAP_PARAMETERS and ALLEGRO_STATE_TARGET_BITMAP
  • ALLEGRO_STATE_ALL - all of the above

See also: al_restore_state, ALLEGRO_STATE

al_get_errno

int al_get_errno(void)
GETTER(allegro_errno, 0)

Source Code

Some Allegro functions will set an error number as well as returning an error code. Call this function to retrieve the last error number set for the calling thread.

al_set_errno

void al_set_errno(int errnum)
SETTER(allegro_errno, errnum)

Source Code

Set the error number for the calling thread.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:16 UTC


System routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

System routines

  • al_install_system
  • al_init
  • al_uninstall_system
  • al_is_system_installed
  • al_get_allegro_version
  • al_get_standard_path
  • al_set_exe_name
  • al_set_app_name
  • al_set_org_name
  • al_get_app_name
  • al_get_org_name
  • al_get_system_config
  • al_register_assert_handler
  • al_register_trace_handler
  • al_get_cpu_count
  • al_get_ram_size

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.

See also: al_init

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.

See also: al_install_system

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().

al_is_system_installed

bool al_is_system_installed(void)

Source Code

Returns true if Allegro is initialized, otherwise returns false.

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 (/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.

See also: al_set_app_name, al_set_org_name, al_destroy_path, al_set_exe_name

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

See also: al_get_standard_path

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.

See also: al_get_app_name, al_set_org_name

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.

See also: al_get_org_name, al_set_app_name

al_get_app_name

const char *al_get_app_name(void)

Source Code

Returns the global application name string.

See also: al_set_app_name

al_get_org_name

const char *al_get_org_name(void)

Source Code

Returns the global organization name string.

See also: al_set_org_name

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

[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 buffer size (in samples)

buffer_size=32

[pulseaudio]

# Set the buffer size (in samples)

buffer_size=1024

[directsound]

# Set the DirectSound buffer size (in samples)

buffer_size = 8192

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

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

[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

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

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

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:16 UTC


Threads

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Threads

  • ALLEGRO_THREAD
  • ALLEGRO_MUTEX
  • ALLEGRO_COND
  • al_create_thread
  • al_start_thread
  • al_join_thread
  • al_set_thread_should_stop
  • al_get_thread_should_stop
  • al_destroy_thread
  • al_run_detached_thread
  • al_create_mutex
  • al_create_mutex_recursive
  • al_lock_mutex
  • al_unlock_mutex
  • al_destroy_mutex
  • al_create_cond
  • al_destroy_cond
  • al_wait_cond
  • al_wait_cond_until
  • al_broadcast_cond
  • al_signal_cond

Allegro includes a simple cross-platform threading interface. It is a thin layer on top of two threading APIs: Windows threads and POSIX Threads (pthreads). Enforcing a consistent semantics on all platforms would be difficult at best, hence the behaviour of the following functions will differ subtly on different platforms (more so than usual). Your best bet is to be aware of this and code to the intersection of the semantics and avoid edge cases.

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_THREAD

typedef struct ALLEGRO_THREAD ALLEGRO_THREAD;

Source Code

An opaque structure representing a thread.

ALLEGRO_MUTEX

typedef struct ALLEGRO_MUTEX ALLEGRO_MUTEX;

Source Code

An opaque structure representing a mutex.

ALLEGRO_COND

typedef struct ALLEGRO_COND ALLEGRO_COND;

Source Code

An opaque structure representing a condition variable.

al_create_thread

ALLEGRO_THREAD *al_create_thread(
   void *(*proc)(ALLEGRO_THREAD *thread, void *arg), void *arg)

Source Code

Spawn a new thread which begins executing proc. The new thread is passed its own thread handle and the value arg.

Returns a pointer to the thread on success. Otherwise, returns NULL if there was an error.

See also: al_start_thread, al_join_thread.

al_start_thread

void al_start_thread(ALLEGRO_THREAD *thread)

Source Code

When a thread is created, it is initially in a suspended state. Calling al_start_thread will start its actual execution.

Starting a thread which has already been started does nothing.

See also: al_create_thread.

al_join_thread

void al_join_thread(ALLEGRO_THREAD *thread, void **ret_value)

Source Code

Wait for the thread to finish executing. This implicitly calls al_set_thread_should_stop first.

If ret_value is non-NULL, the value returned by the thread function will be stored at the location pointed to by ret_value.

See also: al_set_thread_should_stop, al_get_thread_should_stop, al_destroy_thread.

al_set_thread_should_stop

void al_set_thread_should_stop(ALLEGRO_THREAD *thread)

Source Code

Set the flag to indicate thread should stop. Returns immediately.

See also: al_join_thread, al_get_thread_should_stop.

al_get_thread_should_stop

bool al_get_thread_should_stop(ALLEGRO_THREAD *thread)

Source Code

Check if another thread is waiting for thread to stop. Threads which run in a loop should check this periodically and act on it when convenient.

Returns true if another thread has called al_join_thread or al_set_thread_should_stop on this thread.

See also: al_join_thread, al_set_thread_should_stop.

Note: We don't support forceful killing of threads.

al_destroy_thread

void al_destroy_thread(ALLEGRO_THREAD *thread)

Source Code

Free the resources used by a thread. Implicitly performs al_join_thread on the thread if it hasn't been done already.

Does nothing if thread is NULL.

See also: al_join_thread.

al_run_detached_thread

void al_run_detached_thread(void *(*proc)(void *arg), void *arg)

Source Code

Runs the passed function in its own thread, with arg passed to it as only parameter. This is similar to calling al_create_thread, al_start_thread and (after the thread has finished) al_destroy_thread - but you don't have the possibility of ever calling al_join_thread on the thread.

al_create_mutex

ALLEGRO_MUTEX *al_create_mutex(void)

Source Code

Create the mutex object (a mutual exclusion device). The mutex may or may not support "recursive" locking.

Returns the mutex on success or NULL on error.

See also: al_create_mutex_recursive.

al_create_mutex_recursive

ALLEGRO_MUTEX *al_create_mutex_recursive(void)

Source Code

Create the mutex object (a mutual exclusion device), with support for "recursive" locking. That is, the mutex will count the number of times it has been locked by the same thread. If the caller tries to acquire a lock on the mutex when it already holds the lock then the count is incremented. The mutex is only unlocked when the thread releases the lock on the mutex an equal number of times, i.e. the count drops down to zero.

See also: al_create_mutex.

al_lock_mutex

void al_lock_mutex(ALLEGRO_MUTEX *mutex)

Source Code

Acquire the lock on mutex. If the mutex is already locked by another thread, the call will block until the mutex becomes available and locked.

If the mutex is already locked by the calling thread, then the behaviour depends on whether the mutex was created with al_create_mutex or al_create_mutex_recursive. In the former case, the behaviour is undefined; the most likely behaviour is deadlock. In the latter case, the count in the mutex will be incremented and the call will return immediately.

See also: al_unlock_mutex.

We don't yet have al_mutex_trylock.

al_unlock_mutex

void al_unlock_mutex(ALLEGRO_MUTEX *mutex)

Source Code

Release the lock on mutex if the calling thread holds the lock on it.

If the calling thread doesn't hold the lock, or if the mutex is not locked, undefined behaviour results.

See also: al_lock_mutex.

al_destroy_mutex

void al_destroy_mutex(ALLEGRO_MUTEX *mutex)

Source Code

Free the resources used by the mutex. The mutex should be unlocked. Destroying a locked mutex results in undefined behaviour.

Does nothing if mutex is NULL.

al_create_cond

ALLEGRO_COND *al_create_cond(void)

Source Code

Create a condition variable.

Returns the condition value on success or NULL on error.

al_destroy_cond

void al_destroy_cond(ALLEGRO_COND *cond)

Source Code

Destroy a condition variable.

Destroying a condition variable which has threads block on it results in undefined behaviour.

Does nothing if cond is NULL.

al_wait_cond

void al_wait_cond(ALLEGRO_COND *cond, ALLEGRO_MUTEX *mutex)

Source Code

On entering this function, mutex must be locked by the calling thread. The function will atomically release mutex and block on cond. The function will return when cond is "signalled", acquiring the lock on the mutex in the process.

Example of proper use:

al_lock_mutex(mutex);
while (something_not_true) {
   al_wait_cond(cond, mutex);
}
do_something();
al_unlock_mutex(mutex);

The mutex should be locked before checking the condition, and should be rechecked al_wait_cond returns. al_wait_cond can return for other reasons than the condition becoming true (e.g. the process was signalled). If multiple threads are blocked on the condition variable, the condition may no longer be true by the time the second and later threads are unblocked. Remember not to unlock the mutex prematurely.

See also: al_wait_cond_until, al_broadcast_cond, al_signal_cond.

al_wait_cond_until

int al_wait_cond_until(ALLEGRO_COND *cond, ALLEGRO_MUTEX *mutex,
   const ALLEGRO_TIMEOUT *timeout)

Source Code

Like al_wait_cond but the call can return if the absolute time passes timeout before the condition is signalled.

Returns zero on success, non-zero if the call timed out.

See also: al_wait_cond

al_broadcast_cond

void al_broadcast_cond(ALLEGRO_COND *cond)

Source Code

Unblock all threads currently waiting on a condition variable. That is, broadcast that some condition which those threads were waiting for has become true.

See also: al_signal_cond.

Note: The pthreads spec says to lock the mutex associated with cond before signalling for predictable scheduling behaviour.

al_signal_cond

void al_signal_cond(ALLEGRO_COND *cond)

Source Code

Unblock at least one thread waiting on a condition variable.

Generally you should use al_broadcast_cond but al_signal_cond may be more efficient when it's applicable.

See also: al_broadcast_cond.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:16 UTC


Time routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Time routines

  • ALLEGRO_TIMEOUT
  • al_get_time
  • al_init_timeout
  • al_rest

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_TIMEOUT

typedef struct ALLEGRO_TIMEOUT ALLEGRO_TIMEOUT;

Source Code

Represent a timeout value. The size of the structure is known so it can be statically allocated. The contents are private.

See also: al_init_timeout

al_get_time

double al_get_time(void)

Source Code

Return the number of seconds since the Allegro library was initialised. The return value is undefined if Allegro is uninitialised. The resolution depends on the used driver, but typically can be in the order of microseconds.

al_init_timeout

void al_init_timeout(ALLEGRO_TIMEOUT *timeout, double seconds)

Source Code

Set timeout value of some number of seconds after the function call.

For compatibility with all platforms, seconds must be 2,147,483.647 seconds or less.

See also: ALLEGRO_TIMEOUT, al_wait_for_event_until

al_rest

void al_rest(double seconds)

Source Code

Waits for the specified number of seconds. This tells the system to pause the current thread for the given amount of time. With some operating systems, the accuracy can be in the order of 10ms. That is, even

al_rest(0.000001)

might pause for something like 10ms. Also see the section on Timer routines for easier ways to time your program without using up all CPU.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:17 UTC


Timer routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Timer routines

  • ALLEGRO_TIMER
  • ALLEGRO_USECS_TO_SECS
  • ALLEGRO_MSECS_TO_SECS
  • ALLEGRO_BPS_TO_SECS
  • ALLEGRO_BPM_TO_SECS
  • al_create_timer
  • al_start_timer
  • al_resume_timer
  • al_stop_timer
  • al_get_timer_started
  • al_destroy_timer
  • al_get_timer_count
  • al_set_timer_count
  • al_add_timer_count
  • al_get_timer_speed
  • al_set_timer_speed
  • al_get_timer_event_source

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_TIMER

typedef struct ALLEGRO_TIMER ALLEGRO_TIMER;

Source Code

This is an abstract data type representing a timer object.

ALLEGRO_USECS_TO_SECS

#define ALLEGRO_USECS_TO_SECS(x)      ((x) / 1000000.0)

Source Code

Convert microseconds to seconds.

ALLEGRO_MSECS_TO_SECS

#define ALLEGRO_MSECS_TO_SECS(x)      ((x) / 1000.0)

Source Code

Convert milliseconds to seconds.

ALLEGRO_BPS_TO_SECS

#define ALLEGRO_BPS_TO_SECS(x)        (1.0 / (x))

Source Code

Convert beats per second to seconds.

ALLEGRO_BPM_TO_SECS

#define ALLEGRO_BPM_TO_SECS(x)        (60.0 / (x))

Source Code

Convert beats per minute to seconds.

al_create_timer

ALLEGRO_TIMER *al_create_timer(double speed_secs)

Source Code

Allocates and initializes a timer. If successful, a pointer to a new timer object is returned, otherwise NULL is returned. speed_secs is in seconds per "tick", and must be positive. The new timer is initially stopped.

Usage note: typical granularity is on the order of microseconds, but with some drivers might only be milliseconds.

See also: al_start_timer, al_destroy_timer

al_start_timer

void al_start_timer(ALLEGRO_TIMER *timer)

Source Code

Start the timer specified. From then, the timer's counter will increment at a constant rate, and it will begin generating events. Starting a timer that is already started does nothing. Starting a timer that was stopped will reset the timer's counter, effectively restarting the timer from the beginning.

See also: al_stop_timer, al_get_timer_started, al_resume_timer

al_resume_timer

void al_resume_timer(ALLEGRO_TIMER *timer)

Source Code

Resume the timer specified. From then, the timer's counter will increment at a constant rate, and it will begin generating events. Resuming a timer that is already started does nothing. Resuming a stopped timer will not reset the timer's counter (unlike al_start_timer).

See also: al_start_timer, al_stop_timer, al_get_timer_started

al_stop_timer

void al_stop_timer(ALLEGRO_TIMER *timer)

Source Code

Stop the timer specified. The timer's counter will stop incrementing and it will stop generating events. Stopping a timer that is already stopped does nothing.

See also: al_start_timer, al_get_timer_started, al_resume_timer

al_get_timer_started

bool al_get_timer_started(const ALLEGRO_TIMER *timer)

Source Code

Return true if the timer specified is currently started.

al_destroy_timer

void al_destroy_timer(ALLEGRO_TIMER *timer)

Source Code

Uninstall the timer specified. If the timer is started, it will automatically be stopped before uninstallation. It will also automatically unregister the timer with any event queues.

Does nothing if passed the NULL pointer.

See also: al_create_timer

al_get_timer_count

int64_t al_get_timer_count(const ALLEGRO_TIMER *timer)

Source Code

Return the timer's counter value. The timer can be started or stopped.

See also: al_set_timer_count

al_set_timer_count

void al_set_timer_count(ALLEGRO_TIMER *timer, int64_t new_count)

Source Code

Set the timer's counter value. The timer can be started or stopped. The count value may be positive or negative, but will always be incremented by +1 at each tick.

See also: al_get_timer_count, al_add_timer_count

al_add_timer_count

void al_add_timer_count(ALLEGRO_TIMER *timer, int64_t diff)

Source Code

Add diff to the timer's counter value. This is similar to writing:

al_set_timer_count(timer, al_get_timer_count(timer) + diff);

except that the addition is performed atomically, so no ticks will be lost.

See also: al_set_timer_count

al_get_timer_speed

double al_get_timer_speed(const ALLEGRO_TIMER *timer)

Source Code

Return the timer's speed, in seconds. (The same value passed to al_create_timer or al_set_timer_speed.)

See also: al_set_timer_speed

al_set_timer_speed

void al_set_timer_speed(ALLEGRO_TIMER *timer, double new_speed_secs)

Source Code

Set the timer's speed, i.e. the rate at which its counter will be incremented when it is started. This can be done when the timer is started or stopped. If the timer is currently running, it is made to look as though the speed change occurred precisely at the last tick.

speed_secs has exactly the same meaning as with al_create_timer.

See also: al_get_timer_speed

al_get_timer_event_source

ALLEGRO_EVENT_SOURCE *al_get_timer_event_source(ALLEGRO_TIMER *timer)

Source Code

Retrieve the associated event source. Timers will generate events of type ALLEGRO_EVENT_TIMER.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:17 UTC


Touch input

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Touch input

  • ALLEGRO_TOUCH_INPUT
  • ALLEGRO_TOUCH_INPUT_MAX_TOUCH_COUNT
  • ALLEGRO_TOUCH_STATE
  • ALLEGRO_TOUCH_INPUT_STATE
  • ALLEGRO_MOUSE_EMULATION_MODE
  • al_install_touch_input
  • al_uninstall_touch_input
  • al_is_touch_input_installed
  • al_get_touch_input_state
  • al_set_mouse_emulation_mode
  • al_get_mouse_emulation_mode
  • al_get_touch_input_event_source
  • al_get_touch_input_mouse_emulation_event_source

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

ALLEGRO_TOUCH_INPUT

typedef struct ALLEGRO_TOUCH_INPUT ALLEGRO_TOUCH_INPUT;

Source Code

An abstract data type representing a physical touch screen or touch pad.

Since: 5.1.0

ALLEGRO_TOUCH_INPUT_MAX_TOUCH_COUNT

#define ALLEGRO_TOUCH_INPUT_MAX_TOUCH_COUNT        16

Source Code

The maximum amount of simultaneous touches that can be detected.

Since: 5.1.0

ALLEGRO_TOUCH_STATE

typedef struct ALLEGRO_TOUCH_STATE ALLEGRO_TOUCH_STATE;

Source Code

This is a structure that is used to hold a "snapshot" of a touch at a particular instant.

Public fields (read only):

  • id - identifier of the touch. If the touch is valid, this is positive.
  • x - touch x position
  • y - touch y position
  • dx - touch relative x position
  • dy - touch relative y position
  • primary - TRUE if this touch is the primary one (usually the first one).
  • display - The ALLEGRO_DISPLAY that was touched.

Since: 5.1.0

ALLEGRO_TOUCH_INPUT_STATE

typedef struct ALLEGRO_TOUCH_INPUT_STATE ALLEGRO_TOUCH_INPUT_STATE;

Source Code

This is a structure that holds a snapshot of all simultaneous touches at a particular instant.

Public fields (read only):

  • touches - an array of ALLEGRO_TOUCH_STATE

Since: 5.1.0

ALLEGRO_MOUSE_EMULATION_MODE

typedef enum ALLEGRO_MOUSE_EMULATION_MODE

Source Code

Type of mouse emulation to apply.

ALLEGRO_MOUSE_EMULATION_NONE
Disables mouse emulation.
ALLEGRO_MOUSE_EMULATION_TRANSPARENT
Enables transparent mouse emulation.
ALLEGRO_MOUSE_EMULATION_INCLUSIVE
Enable inclusive mouse emulation.
ALLEGRO_MOUSE_EMULATION_EXCLUSIVE
Enables exclusive mouse emulation.
ALLEGRO_MOUSE_EMULATION_5_0_x
Enables mouse emulation that is backwards compatible with Allegro 5.0.x.

Since: 5.1.0

Unstable API: Seems of limited value, as touch input tends to have different semantics compared to mouse input.

al_install_touch_input

bool al_install_touch_input(void)

Source Code

Install a touch input driver, returning true if successful. If a touch input driver was already installed, returns true immediately.

Since: 5.1.0

See also: al_uninstall_touch_input

al_uninstall_touch_input

void al_uninstall_touch_input(void)

Source Code

Uninstalls the active touch input driver. If no touch input driver was active, this function does nothing.

This function is automatically called when Allegro is shut down.

Since: 5.1.0

See also: al_install_touch_input

al_is_touch_input_installed

bool al_is_touch_input_installed(void)

Source Code

Returns true if al_install_touch_input was called successfully.

Since: 5.1.0

al_get_touch_input_state

void al_get_touch_input_state(ALLEGRO_TOUCH_INPUT_STATE *ret_state)

Source Code

Gets the current touch input state. The touch information is copied into the ALLEGRO_TOUCH_INPUT_STATE you provide to this function.

Since: 5.1.0

al_set_mouse_emulation_mode

void al_set_mouse_emulation_mode(int mode)

Source Code

Sets the kind of mouse emulation for the touch input subsystem to perform.

Since: 5.1.0

Unstable API: Seems of limited value, as touch input tends to have different semantics compared to mouse input.

See also: ALLEGRO_MOUSE_EMULATION_MODE, al_get_mouse_emulation_mode.

al_get_mouse_emulation_mode

int al_get_mouse_emulation_mode(void)

Source Code

Returns the kind of mouse emulation which the touch input subsystem is set to perform.

Since: 5.1.0

Unstable API: Seems of limited value, as touch input tends to have different semantics compared to mouse input.

See also: ALLEGRO_MOUSE_EMULATION_MODE, al_set_mouse_emulation_mode.

al_get_touch_input_event_source

ALLEGRO_EVENT_SOURCE *al_get_touch_input_event_source(void)

Source Code

Returns the global touch input event source. This event source generates touch input events.

Since: 5.1.0

See also: ALLEGRO_EVENT_SOURCE, al_register_event_source

al_get_touch_input_mouse_emulation_event_source

ALLEGRO_EVENT_SOURCE *al_get_touch_input_mouse_emulation_event_source(void)

Source Code

Returns the global touch input event source for emulated mouse events. This event source generates emulated mouse events that are based on touch events.

See also: ALLEGRO_EVENT_SOURCE, al_register_event_source

Since: 5.1.0

Unstable API: Seems of limited value, as touch input tends to have different semantics compared to mouse input.

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:17 UTC


Transformations

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Transformations

  • ALLEGRO_TRANSFORM
  • al_copy_transform
  • al_use_transform
  • al_get_current_transform
  • al_use_projection_transform
  • al_get_current_projection_transform
  • al_get_current_inverse_transform
  • al_invert_transform
  • al_check_inverse
  • al_identity_transform
  • al_build_transform
  • al_build_camera_transform
  • al_translate_transform
  • al_rotate_transform
  • al_scale_transform
  • al_transform_coordinates
  • al_transform_coordinates_3d
  • al_compose_transform
  • al_orthographic_transform
  • al_perspective_transform
  • al_translate_transform_3d
  • al_scale_transform_3d
  • al_rotate_transform_3d
  • al_horizontal_shear_transform
  • al_vertical_shear_transform

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

Transformations allow you to transform the coordinates you use for drawing operations without additional overhead. Scaling, rotating, translating, and combinations of these are possible as well as using custom transformations. There are two types of transformations that you can set, 'regular' transformations and projection transformations. The projection transform is rarely used in 2D games, but is common in 3D games to set up the projection from the 3D world to the 2D screen. Typically, you would use the regular transform for non-projective types of transformations (that is, translations, rotations, scales, skews... i.e. transformations that are linear), while the projection transform will be used for setting up perspective and possibly more advanced effects. It is possible to do everything with just using the projection transformation (that is, you'd compose the projection transformation with the non-projection transformations that, e.g., move the camera in the world), but it is more convenient to use both for two reasons:

  • Regular transformations can be changed while the bitmap drawing is held (see al_hold_bitmap_drawing).

  • Regular transformations work with memory bitmaps.

As a result, if you're making a 2D game, it's best to leave the projection transformations at their default values.

Both types of transformations are set per target-bitmap, i.e. a change of the target bitmap will also change the active transformation.

Allegro provides convenience functions to construct transformations in 2D and 3D variants (the latter with a _3d suffix), so you don't have to deal with the underlying matrix algebra yourself.

The transformations are combined in the order of the function invocations. Thus to create a transformation that first rotates a point and then translates it, you would (starting with an identity transformation) call al_rotate_transform and then al_translate_transform. This approach is opposite of what OpenGL uses but similar to what Direct3D uses.

For those who know the matrix algebra going behind the scenes, what the transformation functions in Allegro do is "pre-multiply" the successive transformations. So, for example, if you have code that does:

al_identity_transform(&T);

al_compose_transform(&T, &T1);
al_compose_transform(&T, &T2);
al_compose_transform(&T, &T3);
al_compose_transform(&T, &T4);

The resultant matrix multiplication expression will look like this:

T4 * T3 * T2 * T1

Since the point coordinate vector term will go on the right of that sequence of factors, the transformation that is called first, will also be applied first.

This means if you have code like this:

al_identity_transform(&T1);
al_scale_transform(&T1, 2, 2);
al_identity_transform(&T2);
al_translate_transform(&T2, 100, 0);

al_identity_transform(&T);

al_compose_transform(&T, &T1);
al_compose_transform(&T, &T2);

al_use_transform(&T);

it does exactly the same as:

al_identity_transform(&T);
al_scale_transform(&T, 2, 2);
al_translate_transform(&T, 100, 0);
al_use_transform(&T);

ALLEGRO_TRANSFORM

typedef struct ALLEGRO_TRANSFORM ALLEGRO_TRANSFORM;

Source Code

Defines the generic transformation type, a 4x4 matrix. 2D transforms use only a small subsection of this matrix, namely the top left 2x2 matrix, and the right most 2x1 matrix, for a total of 6 values.

Fields:

  • m - A 4x4 float matrix

al_copy_transform

void al_copy_transform(ALLEGRO_TRANSFORM *dest, const ALLEGRO_TRANSFORM *src)

Source Code

Makes a copy of a transformation.

Parameters:

  • dest - Source transformation
  • src - Destination transformation

al_use_transform

void al_use_transform(const ALLEGRO_TRANSFORM *trans)

Source Code

Sets the transformation to be used for the the drawing operations on the target bitmap (each bitmap maintains its own transformation). Every drawing operation after this call will be transformed using this transformation. Call this function with an identity transformation to return to the default behaviour.

This function does nothing if there is no target bitmap.

The parameter is passed by reference as an optimization to avoid the overhead of stack copying. The reference will not be stored in the Allegro library so it is safe to pass references to local variables.

void setup_my_transformation(void)
{
   ALLEGRO_TRANSFORM transform;
   al_translate_transform(&transform, 5, 10);
   al_use_transform(&transform);
}

Parameters:

  • trans - Transformation to use

See also: al_get_current_transform, al_transform_coordinates

al_get_current_transform

const ALLEGRO_TRANSFORM *al_get_current_transform(void)

Source Code

Returns the transformation of the current target bitmap, as set by al_use_transform. If there is no target bitmap, this function returns NULL.

Returns: A pointer to the current transformation.

See also: al_get_current_projection_transform

al_use_projection_transform

void al_use_projection_transform(const ALLEGRO_TRANSFORM *trans)

Source Code

Sets the projection transformation to be used for the the drawing operations on the target bitmap (each bitmap maintains its own projection transformation). Every drawing operation after this call will be transformed using this transformation. To return default behavior, call this function with an orthographic transform like so:

ALLEGRO_TRANSFORM trans;
al_identity_transform(&trans);
al_orthographic_transform(&trans, 0, 0, -1.0, al_get_bitmap_width(bitmap),
                          al_get_bitmap_height(bitmap), 1.0);

al_set_target_bitmap(bitmap);
al_use_projection_transform(&trans);

The orthographic transformation above is the default projection transform.

This function does nothing if there is no target bitmap. This function also does nothing if the bitmap is a memory bitmap (i.e. memory bitmaps always use an orthographic transform like the snippet above). Note that the projection transform will be reset to default if a video bitmap is converted to a memory bitmap. Additionally, if the bitmap in question is the backbuffer, it's projection transformation will be reset to default if it is resized. Lastly, when you draw a memory bitmap to a video bitmap with a custom projection transform, this transformation will be ignored (i.e. it'll be as if the projection transform of the target bitmap was temporarily reset to default).

The parameter is passed by reference as an optimization to avoid the overhead of stack copying. The reference will not be stored in the Allegro library so it is safe to pass references to local variables.

Since: 5.1.9

See also: al_get_current_projection_transform

al_get_current_projection_transform

const ALLEGRO_TRANSFORM *al_get_current_projection_transform(void)

Source Code

If there is no target bitmap, this function returns NULL.

Returns: A pointer to the current transformation.

Since: 5.1.9

See also: al_use_projection_transform

al_get_current_inverse_transform

const ALLEGRO_TRANSFORM *al_get_current_inverse_transform(void)

Source Code

Returns the inverse of the current transformation of the target bitmap. If there is no target bitmap, this function returns NULL.

This is similar to calling al_invert_transform(al_get_current_transform()) but the result of this function is cached.

Since: 5.1.0

al_invert_transform

void al_invert_transform(ALLEGRO_TRANSFORM *trans)

Source Code

Inverts the passed transformation. If the transformation is nearly singular (close to not having an inverse) then the returned transformation may be invalid. Use al_check_inverse to ascertain if the transformation has an inverse before inverting it if you are in doubt.

Parameters:

  • trans - Transformation to invert

See also: al_check_inverse

al_check_inverse

int al_check_inverse(const ALLEGRO_TRANSFORM *trans, float tol)

Source Code

Checks if the transformation has an inverse using the supplied tolerance. Tolerance should be a small value between 0 and 1, with 1e-7 being sufficient for most applications.

In this function tolerance specifies how close the determinant can be to 0 (if the determinant is 0, the transformation has no inverse). Thus the smaller the tolerance you specify, the "worse" transformations will pass this test. Using a tolerance of 1e-7 will catch errors greater than 1/1000's of a pixel, but let smaller errors pass. That means that if you transformed a point by a transformation and then transformed it again by the inverse transformation that passed this check, the resultant point should less than 1/1000's of a pixel away from the original point.

Note that this check is superfluous most of the time if you never touched the transformation matrix values yourself. The only thing that would cause the transformation to not have an inverse is if you applied a 0 (or very small) scale to the transformation or you have a really large translation. As long as the scale is comfortably above 0, the transformation will be invertible.

Parameters:

  • trans - Transformation to check
  • tol - Tolerance

Returns: 1 if the transformation is invertible, 0 otherwise

See also: al_invert_transform

al_identity_transform

void al_identity_transform(ALLEGRO_TRANSFORM *trans)

Source Code

Sets the transformation to be the identity transformation. This is the default transformation. Use al_use_transform on an identity transformation to return to the default.

ALLEGRO_TRANSFORM t;
al_identity_transform(&t);
al_use_transform(&t);

Parameters:

  • trans - Transformation to alter

See also: al_translate_transform, al_rotate_transform, al_scale_transform

al_build_transform

void al_build_transform(ALLEGRO_TRANSFORM *trans, float x, float y,
   float sx, float sy, float theta)

Source Code

Builds a transformation given some parameters. This call is equivalent to calling the transformations in this order: make identity, rotate, scale, translate. This method is faster, however, than actually calling those functions.

Parameters:

  • trans - Transformation to alter
  • x, y - Translation
  • sx, sy - Scale
  • theta - Rotation angle in radians

Note: this function was previously documented to be equivalent to a different (and more useful) order of operations: identity, scale, rotate, translate.

See also: al_translate_transform, al_rotate_transform, al_scale_transform, al_compose_transform

al_build_camera_transform

void al_build_camera_transform(ALLEGRO_TRANSFORM *trans,
   float position_x, float position_y, float position_z,
   float look_x, float look_y, float look_z,
   float up_x, float up_y, float up_z)

Source Code

Builds a transformation which can be used to transform 3D coordinates in world space to camera space. This involves translation and a rotation. The function expects three coordinate triplets: The camera's position, the position the camera is looking at and an up vector. The up vector does not need to be of unit length and also does not need to be perpendicular to the view direction - it can usually just be the world up direction (most commonly 0/1/0).

For example:

al_build_camera_transform(&t,
    1, 1, 1,
    5, 5, 5,
    0, 1, 0);

This create a transformation for a camera standing at 1/1/1 and looking towards 5/5/5.

Note: If the position and look parameters are identical, or if the up direction is parallel to the view direction, an identity matrix is created.

Another example which will simply re-create the identity matrix:

al_build_camera_transform(&t,
    0, 0, 0,
    0, 0, -1,
    0, 1, 0);

An example where the up vector will cause the camera to lean (roll) by 45 degrees:

al_build_camera_transform(&t,
    1, 1, 1,
    5, 5, 5,
    1, 1, 0);

Since 5.1.9

See also: al_translate_transform_3d, al_rotate_transform_3d, al_scale_transform_3d, al_compose_transform, al_use_transform

al_translate_transform

void al_translate_transform(ALLEGRO_TRANSFORM *trans, float x, float y)

Source Code

Apply a translation to a transformation.

Parameters:

  • trans - Transformation to alter
  • x, y - Translation

See also: al_rotate_transform, al_scale_transform, al_build_transform

al_rotate_transform

void al_rotate_transform(ALLEGRO_TRANSFORM *trans, float theta)

Source Code

Apply a rotation to a transformation.

Parameters:

  • trans - Transformation to alter
  • theta - Rotation angle in radians

See also: al_translate_transform, al_scale_transform, al_build_transform

al_scale_transform

void al_scale_transform(ALLEGRO_TRANSFORM *trans, float sx, float sy)

Source Code

Apply a scale to a transformation.

Parameters:

  • trans - Transformation to alter
  • sx, sy - Scale

See also: al_translate_transform, al_rotate_transform, al_build_transform

al_transform_coordinates

void al_transform_coordinates(const ALLEGRO_TRANSFORM *trans, float *x, float *y)

Source Code

Transform a pair of coordinates.

Parameters:

  • trans - Transformation to use
  • x, y - Pointers to the coordinates

See also: al_use_transform, al_transform_coordinates_3d

al_transform_coordinates_3d

void al_transform_coordinates_3d(const ALLEGRO_TRANSFORM *trans,
   float *x, float *y, float *z)

Source Code

Transform x, y, z coordinates.

Parameters:

  • trans - Transformation to use
  • x, y, z - Pointers to the coordinates

Since 5.1.9

See also: al_use_transform, al_transform_coordinates

al_compose_transform

void al_compose_transform(ALLEGRO_TRANSFORM *trans, const ALLEGRO_TRANSFORM *other)

Source Code

Compose (combine) two transformations by a matrix multiplication.

trans := trans other

Note that the order of matrix multiplications is important. The effect of applying the combined transform will be as if first applying trans and then applying other and not the other way around.

Parameters:

  • trans - Transformation to alter
  • other - Transformation used to transform trans

See also: al_translate_transform, al_rotate_transform, al_scale_transform

al_orthographic_transform

void al_orthographic_transform(ALLEGRO_TRANSFORM *trans,
   float left, float top, float n,
   float right, float bottom, float f)

Source Code

Combines the given transformation with an orthographic transformation which maps the screen rectangle to the given left/top and right/bottom coordinates. near/far is the z-buffer range, if there is no z-buffer you can set it to -1/1.

Since: 5.1.3

See also: al_use_projection_transform, al_perspective_transform

al_perspective_transform

void al_perspective_transform(ALLEGRO_TRANSFORM *trans,
   float left, float top, float n,
   float right, float bottom, float f)

Source Code

Like al_orthographic_transform but honors perspective. If everything is at a z-position of -near it will look the same as with an orthographic transformation.

To use a specific horizontal field of view you can use the relation:

tan(hfov / 2) = (right - left) / 2 / near

Since: 5.1.3

See also: al_use_projection_transform, al_orthographic_transform

al_translate_transform_3d

void al_translate_transform_3d(ALLEGRO_TRANSFORM *trans, float x, float y,
    float z)

Source Code

Combines the given transformation with a transformation which translates coordinates by the given vector.

Since: 5.1.3

See also: al_use_projection_transform

al_scale_transform_3d

void al_scale_transform_3d(ALLEGRO_TRANSFORM *trans, float sx, float sy,
    float sz)

Source Code

Combines the given transformation with a transformation which scales coordinates by the given vector.

Since: 5.1.3

See also: al_use_projection_transform

al_rotate_transform_3d

void al_rotate_transform_3d(ALLEGRO_TRANSFORM *trans,
   float x, float y, float z, float angle)

Source Code

Combines the given transformation with a transformation which rotates coordinates around the given vector by the given angle in radians.

Since: 5.1.3

al_horizontal_shear_transform

void al_horizontal_shear_transform(ALLEGRO_TRANSFORM* trans, float theta)

Source Code

Apply a horizontal shear to the transform

Parameters:

  • trans - Transformation to alter
  • theta - Rotation angle in radians

Since: 5.1.7

See also: al_vertical_shear_transform

al_vertical_shear_transform

void al_vertical_shear_transform(ALLEGRO_TRANSFORM* trans, float theta)

Source Code

Apply a vertical shear to the transform

Parameters:

  • trans - Transformation to alter
  • theta - Rotation angle in radians

Since: 5.1.7

See also: al_horizontal_shear_transform

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:17 UTC


UTF-8 string routines

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

UTF-8 string routines

  • About UTF-8 string routines
  • UTF-8 string types
    • ALLEGRO_USTR
    • ALLEGRO_USTR_INFO
  • Creating and destroying strings
    • al_ustr_new
    • al_ustr_new_from_buffer
    • al_ustr_newf
    • al_ustr_free
    • al_cstr
    • al_ustr_to_buffer
    • al_cstr_dup
    • al_ustr_dup
    • al_ustr_dup_substr
  • Predefined strings
    • al_ustr_empty_string
  • Creating strings by referencing other data
    • al_ref_cstr
    • al_ref_buffer
    • al_ref_ustr
  • Sizes and offsets
    • al_ustr_size
    • al_ustr_length
    • al_ustr_offset
    • al_ustr_next
    • al_ustr_prev
  • Getting code points
    • al_ustr_get
    • al_ustr_get_next
    • al_ustr_prev_get
  • Inserting into strings
    • al_ustr_insert
    • al_ustr_insert_cstr
    • al_ustr_insert_chr
  • Appending to strings
    • al_ustr_append
    • al_ustr_append_cstr
    • al_ustr_append_chr
    • al_ustr_appendf
    • al_ustr_vappendf
  • Removing parts of strings
    • al_ustr_remove_chr
    • al_ustr_remove_range
    • al_ustr_truncate
    • al_ustr_ltrim_ws
    • al_ustr_rtrim_ws
    • al_ustr_trim_ws
  • Assigning one string to another
    • al_ustr_assign
    • al_ustr_assign_substr
    • al_ustr_assign_cstr
  • Replacing parts of string
    • al_ustr_set_chr
    • al_ustr_replace_range
  • Searching
    • al_ustr_find_chr
    • al_ustr_rfind_chr
    • al_ustr_find_set
    • al_ustr_find_set_cstr
    • al_ustr_find_cset
    • al_ustr_find_cset_cstr
    • al_ustr_find_str
    • al_ustr_find_cstr
    • al_ustr_rfind_str
    • al_ustr_rfind_cstr
    • al_ustr_find_replace
    • al_ustr_find_replace_cstr
  • Comparing
    • al_ustr_equal
    • al_ustr_compare
    • al_ustr_ncompare
    • al_ustr_has_prefix
    • al_ustr_has_prefix_cstr
    • al_ustr_has_suffix
    • al_ustr_has_suffix_cstr
  • UTF-16 conversion
    • al_ustr_new_from_utf16
    • al_ustr_size_utf16
    • al_ustr_encode_utf16
  • Low-level UTF-8 routines
    • al_utf8_width
    • al_utf8_encode
  • Low-level UTF-16 routines
    • al_utf16_width
    • al_utf16_encode

These functions are declared in the main Allegro header file:

 #include <allegro5/allegro.h>

About UTF-8 string routines

Some parts of the Allegro API, such as the font rountines, expect Unicode strings encoded in UTF-8. The following basic routines are provided to help you work with UTF-8 strings, however it does not mean you need to use them. You should consider another library (e.g. ICU) if you require more functionality.

Briefly, Unicode is a standard consisting of a large character set of over 100,000 characters, and rules, such as how to sort strings. A code point is the integer value of a character, but not all code points are characters, as some code points have other uses. Unlike legacy character sets, the set of code points is open ended and more are assigned with time.

Clearly it is impossible to represent each code point with a 8-bit byte (limited to 256 code points) or even a 16-bit integer (limited to 65536 code points). It is possible to store code points in a 32-bit integers but it is space inefficient, and not actually that useful (at least, when handling the full complexity of Unicode; Allegro only does the very basics). There exist different Unicode Transformation Formats for encoding code points into smaller code units. The most important transformation formats are UTF-8 and UTF-16.

UTF-8 is a variable-length encoding which encodes each code point to between one and four 8-bit bytes each. UTF-8 has many nice properties, but the main advantages are that it is backwards compatible with C strings, and ASCII characters (code points in the range 0-127) are encoded in UTF-8 exactly as they would be in ASCII.

UTF-16 is another variable-length encoding, but encodes each code point to one or two 16-bit words each. It is, of course, not compatible with traditional C strings. Allegro does not generally use UTF-16 strings.

Here is a diagram of the representation of the word "ål", with a NUL terminator, in both UTF-8 and UTF-16.

                   ---------------- ---------------- --------------
           String         å                l              NUL
                   ---------------- ---------------- --------------
      Code points    U+00E5 (229)     U+006C (108)     U+0000 (0)
                   ---------------- ---------------- --------------
      UTF-8 bytes     0xC3, 0xA5          0x6C            0x00
                   ---------------- ---------------- --------------
   UTF-16LE bytes     0xE5, 0x00       0x6C, 0x00      0x00, 0x00
                   ---------------- ---------------- --------------

You can see the aforementioned properties of UTF-8. The first code point U+00E5 ("å") is outside of the ASCII range (0-127) so is encoded to multiple code units -- it requires two bytes. U+006C ("l") and U+0000 (NUL) both exist in the ASCII range so take exactly one byte each, as in a pure ASCII string. A zero byte never appears except to represent the NUL character, so many functions which expect C-style strings will work with UTF-8 strings without modification.

On the other hand, UTF-16 represents each code point by either one or two 16-bit code units (two or four bytes). The representation of each 16-bit code unit depends on the byte order; here we have demonstrated little endian.

Both UTF-8 and UTF-16 are self-synchronising. Starting from any offset within a string, it is efficient to find the beginning of the previous or next code point.

Not all sequences of bytes or 16-bit words are valid UTF-8 and UTF-16 strings respectively. UTF-8 also has an additional problem of overlong forms, where a code point value is encoded using more bytes than is strictly necessary. This is invalid and needs to be guarded against.

In the following "ustr" functions, be careful whether a function takes code unit (byte) or code point indices. In general, all position parameters are in code unit offsets. This may be surprising, but if you think about it, it is required for good performance. (It also means some functions will work even if they do not contain UTF-8, since they only care about storing bytes, so you may actually store arbitrary data in the ALLEGRO_USTRs.)

For actual text processing, where you want to specify positions with code point indices, you should use al_ustr_offset to find the code unit offset position. However, most of the time you would probably just work with byte offsets.

UTF-8 string types

ALLEGRO_USTR

typedef struct _al_tagbstring ALLEGRO_USTR;

Source Code

An opaque type representing a string. ALLEGRO_USTRs normally contain UTF-8 encoded strings, but they may be used to hold any byte sequences, including NULs.

ALLEGRO_USTR_INFO

typedef struct _al_tagbstring ALLEGRO_USTR_INFO;

Source Code

A type that holds additional information for an ALLEGRO_USTR that references an external memory buffer.

See also: al_ref_cstr, al_ref_buffer and al_ref_ustr.

Creating and destroying strings

al_ustr_new

ALLEGRO_USTR *al_ustr_new(const char *s)

Source Code

Create a new string containing a copy of the C-style string s. The string must eventually be freed with al_ustr_free.

See also: al_ustr_new_from_buffer, al_ustr_newf, al_ustr_dup, al_ustr_new_from_utf16

al_ustr_new_from_buffer

ALLEGRO_USTR *al_ustr_new_from_buffer(const char *s, size_t size)

Source Code

Create a new string containing a copy of the buffer pointed to by s of the given size in bytes. The string must eventually be freed with al_ustr_free.

See also: al_ustr_new

al_ustr_newf

ALLEGRO_USTR *al_ustr_newf(const char *fmt, ...)

Source Code

Create a new string using a printf-style format string.

Notes:

The "%s" specifier takes C string arguments, not ALLEGRO_USTRs. Therefore to pass an ALLEGRO_USTR as a parameter you must use al_cstr, and it must be NUL terminated. If the string contains an embedded NUL byte everything from that byte onwards will be ignored.

The "%c" specifier outputs a single byte, not the UTF-8 encoding of a code point. Therefore it is only usable for ASCII characters (value <= 127) or if you really mean to output byte values from 128--255. To insert the UTF-8 encoding of a code point, encode it into a memory buffer using al_utf8_encode then use the "%s" specifier. Remember to NUL terminate the buffer.

See also: al_ustr_new, al_ustr_appendf

al_ustr_free

void al_ustr_free(ALLEGRO_USTR *us)

Source Code

Free a previously allocated string. Does nothing if the argument is NULL.

See also: al_ustr_new, al_ustr_new_from_buffer, al_ustr_newf

al_cstr

const char *al_cstr(const ALLEGRO_USTR *us)

Source Code

Get a char * pointer to the data in a string. This pointer will only be valid while the ALLEGRO_USTR object is not modified and not destroyed. The pointer may be passed to functions expecting C-style strings, with the following caveats:

  • ALLEGRO_USTRs are allowed to contain embedded NUL ('\0') bytes. That means al_ustr_size(u) and strlen(al_cstr(u)) may not agree.

  • An ALLEGRO_USTR may be created in such a way that it is not NUL terminated. A string which is dynamically allocated will always be NUL terminated, but a string which references the middle of another string or region of memory will not be NUL terminated.

  • If the ALLEGRO_USTR references another string, the returned C string will point into the referenced string. Again, no NUL terminator will be added to the referenced string.

See also: al_ustr_to_buffer, al_cstr_dup

al_ustr_to_buffer

void al_ustr_to_buffer(const ALLEGRO_USTR *us, char *buffer, int size)

Source Code

Write the contents of the string into a pre-allocated buffer of the given size in bytes. The result will always be NUL terminated, so a maximum of size - 1 bytes will be copied.

See also: al_cstr, al_cstr_dup

al_cstr_dup

char *al_cstr_dup(const ALLEGRO_USTR *us)

Source Code

Create a NUL ('\0') terminated copy of the string. Any embedded NUL bytes will still be presented in the returned string. The new string must eventually be freed with al_free.

If an error occurs NULL is returned.

See also: al_cstr, al_ustr_to_buffer, al_free

al_ustr_dup

ALLEGRO_USTR *al_ustr_dup(const ALLEGRO_USTR *us)

Source Code

Return a duplicate copy of a string. The new string will need to be freed with al_ustr_free.

See also: al_ustr_dup_substr, al_ustr_free

al_ustr_dup_substr

ALLEGRO_USTR *al_ustr_dup_substr(const ALLEGRO_USTR *us, int start_pos,
   int end_pos)

Source Code

Return a new copy of a string, containing its contents in the byte interval [start_pos, end_pos). The new string will be NUL terminated and will need to be freed with al_ustr_free.

If necessary, use al_ustr_offset to find the byte offsets for a given code point that you are interested in.

See also: al_ustr_dup, al_ustr_free

Predefined strings

al_ustr_empty_string

const ALLEGRO_USTR *al_ustr_empty_string(void)

Source Code

Return a pointer to a static empty string. The string is read only and must not be freed.

Creating strings by referencing other data

al_ref_cstr

const ALLEGRO_USTR *al_ref_cstr(ALLEGRO_USTR_INFO *info, const char *s)

Source Code

Create a string that references the storage of a C-style string. The information about the string (e.g. its size) is stored in the structure pointed to by the info parameter. The string will not have any other storage allocated of its own, so if you allocate the info structure on the stack then no explicit "free" operation is required.

The string is valid until the underlying C string disappears.

Example:

ALLEGRO_USTR_INFO info;
ALLEGRO_USTR *us = al_ref_cstr(&info, "my string");

See also: al_ref_buffer, al_ref_ustr

al_ref_buffer

const ALLEGRO_USTR *al_ref_buffer(ALLEGRO_USTR_INFO *info, const char *s, size_t size)

Source Code

Create a string that references the storage of an underlying buffer. The size of the buffer is given in bytes. You can use it to reference only part of a string or an arbitrary region of memory.

The string is valid while the underlying memory buffer is valid.

See also: al_ref_cstr, al_ref_ustr

al_ref_ustr

const ALLEGRO_USTR *al_ref_ustr(ALLEGRO_USTR_INFO *info, const ALLEGRO_USTR *us,
   int start_pos, int end_pos)

Source Code

Create a read-only string that references the storage of another ALLEGRO_USTR string. The information about the string (e.g. its size) is stored in the structure pointed to by the info parameter. The new string will not have any other storage allocated of its own, so if you allocate the info structure on the stack then no explicit "free" operation is required.

The referenced interval is [start_pos, end_pos). Both are byte offsets.

The string is valid until the underlying string is modified or destroyed.

If you need a range of code-points instead of bytes, use al_ustr_offset to find the byte offsets.

See also: al_ref_cstr, al_ref_buffer

Sizes and offsets

al_ustr_size

size_t al_ustr_size(const ALLEGRO_USTR *us)

Source Code

Return the size of the string in bytes. This is equal to the number of code points in the string if the string is empty or contains only 7-bit ASCII characters.

See also: al_ustr_length

al_ustr_length

size_t al_ustr_length(const ALLEGRO_USTR *us)

Source Code

Return the number of code points in the string.

See also: al_ustr_size, al_ustr_offset

al_ustr_offset

int al_ustr_offset(const ALLEGRO_USTR *us, int index)

Source Code

Return the byte offset (from the start of the string) of the code point at the specified index in the string. A zero index parameter will return the first character of the string. If index is negative, it counts backward from the end of the string, so an index of -1 will return an offset to the last code point.

If the index is past the end of the string, returns the offset of the end of the string.

See also: al_ustr_length

al_ustr_next

bool al_ustr_next(const ALLEGRO_USTR *us, int *pos)

Source Code

Find the byte offset of the next code point in string, beginning at *pos. *pos does not have to be at the beginning of a code point.

Returns true on success, and the value pointed to by pos will be updated to the found offset. Otherwise returns false if *pos was already at the end of the string, and *pos is unmodified.

This function just looks for an appropriate byte; it doesn't check if found offset is the beginning of a valid code point. If you are working with possibly invalid UTF-8 strings then it could skip over some invalid bytes.

See also: al_ustr_prev

al_ustr_prev

bool al_ustr_prev(const ALLEGRO_USTR *us, int *pos)

Source Code

Find the byte offset of the previous code point in string, before *pos. *pos does not have to be at the beginning of a code point. Returns true on success, and the value pointed to by pos will be updated to the found offset. Otherwise returns false if *pos was already at the end of the string, and *pos is unmodified.

This function just looks for an appropriate byte; it doesn't check if found offset is the beginning of a valid code point. If you are working with possibly invalid UTF-8 strings then it could skip over some invalid bytes.

See also: al_ustr_next

Getting code points

al_ustr_get

int32_t al_ustr_get(const ALLEGRO_USTR *ub, int pos)

Source Code

Return the code point in ub beginning at byte offset pos.

On success returns the code point value. If pos was out of bounds (e.g. past the end of the string), return -1. On an error, such as an invalid byte sequence, return -2.

See also: al_ustr_get_next, al_ustr_prev_get

al_ustr_get_next

int32_t al_ustr_get_next(const ALLEGRO_USTR *us, int *pos)

Source Code

Find the code point in us beginning at byte offset *pos, then advance to the next code point.

On success return the code point value. If pos was out of bounds (e.g. past the end of the string), return -1. On an error, such as an invalid byte sequence, return -2. As with al_ustr_next, invalid byte sequences may be skipped while advancing.

See also: al_ustr_get, al_ustr_prev_get

al_ustr_prev_get

int32_t al_ustr_prev_get(const ALLEGRO_USTR *us, int *pos)

Source Code

Find the beginning of a code point before byte offset *pos, then return it. Note this performs a pre-increment.

On success returns the code point value. If pos was out of bounds (e.g. past the end of the string), return -1. On an error, such as an invalid byte sequence, return -2. As with al_ustr_prev, invalid byte sequences may be skipped while advancing.

See also: al_ustr_get_next

Inserting into strings

al_ustr_insert

bool al_ustr_insert(ALLEGRO_USTR *us1, int pos, const ALLEGRO_USTR *us2)

Source Code

Insert us2 into us1 beginning at byte offset pos. pos cannot be less than 0. If pos is past the end of us1 then the space between the end of the string and pos will be padded with NUL ('\0') bytes.

If required, use al_ustr_offset to find the byte offset for a given code point index.

Returns true on success, false on error.

See also: al_ustr_insert_cstr, al_ustr_insert_chr, al_ustr_append, al_ustr_offset

al_ustr_insert_cstr

bool al_ustr_insert_cstr(ALLEGRO_USTR *us, int pos, const char *s)

Source Code

Like al_ustr_insert but inserts a C-style string at byte offset pos.

See also: al_ustr_insert, al_ustr_insert_chr

al_ustr_insert_chr

size_t al_ustr_insert_chr(ALLEGRO_USTR *us, int pos, int32_t c)

Source Code

Insert a code point into us beginning at byte offset pos. pos cannot be less than 0. If pos is past the end of us then the space between the end of the string and pos will be padded with NUL ('\0') bytes.

Returns the number of bytes inserted, or 0 on error.

See also: al_ustr_insert, al_ustr_insert_cstr

Appending to strings

al_ustr_append

bool al_ustr_append(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

Source Code

Append us2 to the end of us1.

Returns true on success, false on error.

This function can be used to append an arbitrary buffer:

  ALLEGRO_USTR_INFO info;
  al_ustr_append(us, al_ref_buffer(&info, buf, size));

See also: al_ustr_append_cstr, al_ustr_append_chr, al_ustr_appendf, al_ustr_vappendf

al_ustr_append_cstr

bool al_ustr_append_cstr(ALLEGRO_USTR *us, const char *s)

Source Code

Append C-style string s to the end of us.

Returns true on success, false on error.

See also: al_ustr_append

al_ustr_append_chr

size_t al_ustr_append_chr(ALLEGRO_USTR *us, int32_t c)

Source Code

Append a code point to the end of us.

Returns the number of bytes added, or 0 on error.

See also: al_ustr_append

al_ustr_appendf

bool al_ustr_appendf(ALLEGRO_USTR *us, const char *fmt, ...)

Source Code

This function appends formatted output to the string us. fmt is a printf-style format string. See al_ustr_newf about the "%s" and "%c" specifiers.

Returns true on success, false on error.

See also: al_ustr_vappendf, al_ustr_append

al_ustr_vappendf

bool al_ustr_vappendf(ALLEGRO_USTR *us, const char *fmt, va_list ap)

Source Code

Like al_ustr_appendf but you pass the variable argument list directly, instead of the arguments themselves. See al_ustr_newf about the "%s" and "%c" specifiers.

Returns true on success, false on error.

See also: al_ustr_appendf, al_ustr_append

Removing parts of strings

al_ustr_remove_chr

bool al_ustr_remove_chr(ALLEGRO_USTR *us, int pos)

Source Code

Remove the code point beginning at byte offset pos. Returns true on success. If pos is out of range or pos is not the beginning of a valid code point, returns false leaving the string unmodified.

Use al_ustr_offset to find the byte offset for a code-points offset.

See also: al_ustr_remove_range

al_ustr_remove_range

bool al_ustr_remove_range(ALLEGRO_USTR *us, int start_pos, int end_pos)

Source Code

Remove the interval [start_pos, end_pos) from a string. start_pos and end_pos are byte offsets. Both may be past the end of the string but cannot be less than 0 (the start of the string).

Returns true on success, false on error.

See also: al_ustr_remove_chr, al_ustr_truncate

al_ustr_truncate

bool al_ustr_truncate(ALLEGRO_USTR *us, int start_pos)

Source Code

Truncate a portion of a string from byte offset start_pos onwards. start_pos can be past the end of the string (has no effect) but cannot be less than 0.

Returns true on success, false on error.

See also: al_ustr_remove_range, al_ustr_ltrim_ws, al_ustr_rtrim_ws, al_ustr_trim_ws

al_ustr_ltrim_ws

bool al_ustr_ltrim_ws(ALLEGRO_USTR *us)

Source Code

Remove leading whitespace characters from a string, as defined by the C function isspace().

Returns true on success, or false on error.

See also: al_ustr_rtrim_ws, al_ustr_trim_ws

al_ustr_rtrim_ws

bool al_ustr_rtrim_ws(ALLEGRO_USTR *us)

Source Code

Remove trailing ("right") whitespace characters from a string, as defined by the C function isspace().

Returns true on success, or false on error.

See also: al_ustr_ltrim_ws, al_ustr_trim_ws

al_ustr_trim_ws

bool al_ustr_trim_ws(ALLEGRO_USTR *us)

Source Code

Remove both leading and trailing whitespace characters from a string.

Returns true on success, or false on error.

See also: al_ustr_ltrim_ws, al_ustr_rtrim_ws

Assigning one string to another

al_ustr_assign

bool al_ustr_assign(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

Source Code

Overwrite the string us1 with another string us2. Returns true on success, false on error.

See also: al_ustr_assign_substr, al_ustr_assign_cstr

al_ustr_assign_substr

bool al_ustr_assign_substr(ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2,
   int start_pos, int end_pos)

Source Code

Overwrite the string us1 with the contents of us2 in the byte interval [start_pos, end_pos). The end points will be clamped to the bounds of us2.

Usually you will first have to use al_ustr_offset to find the byte offsets.

Returns true on success, false on error.

See also: al_ustr_assign, al_ustr_assign_cstr

al_ustr_assign_cstr

bool al_ustr_assign_cstr(ALLEGRO_USTR *us1, const char *s)

Source Code

Overwrite the string us1 with the contents of the C-style string s. Returns true on success, false on error.

See also: al_ustr_assign_substr, al_ustr_assign_cstr

Replacing parts of string

al_ustr_set_chr

size_t al_ustr_set_chr(ALLEGRO_USTR *us, int start_pos, int32_t c)

Source Code

Replace the code point beginning at byte offset start_pos with c. start_pos cannot be less than 0. If start_pos is past the end of us then the space between the end of the string and start_pos will be padded with NUL ('\0') bytes. If start_pos is not the start of a valid code point, that is an error and the string will be unmodified.

On success, returns the number of bytes written, i.e. the offset to the following code point. On error, returns 0.

See also: al_ustr_replace_range

al_ustr_replace_range

bool al_ustr_replace_range(ALLEGRO_USTR *us1, int start_pos1, int end_pos1,
   const ALLEGRO_USTR *us2)

Source Code

Replace the part of us1 in the byte interval [start_pos1, end_pos1) with the contents of us2. start_pos1 cannot be less than 0. If start_pos1 is past the end of us1 then the space between the end of the string and start_pos1 will be padded with NUL ('\0') bytes.

Use al_ustr_offset to find the byte offsets.

Returns true on success, false on error.

See also: al_ustr_set_chr

Searching

al_ustr_find_chr

int al_ustr_find_chr(const ALLEGRO_USTR *us, int start_pos, int32_t c)

Source Code

Search for the encoding of code point c in us from byte offset start_pos (inclusive).

Returns the position where it is found or -1 if it is not found.

See also: al_ustr_rfind_chr

al_ustr_rfind_chr

int al_ustr_rfind_chr(const ALLEGRO_USTR *us, int end_pos, int32_t c)

Source Code

Search for the encoding of code point c in us backwards from byte offset end_pos (exclusive). Returns the position where it is found or -1 if it is not found.

See also: al_ustr_find_chr

al_ustr_find_set

int al_ustr_find_set(const ALLEGRO_USTR *us, int start_pos,
   const ALLEGRO_USTR *accept)

Source Code

This function finds the first code point in us, beginning from byte offset start_pos, that matches any code point in accept. Returns the position if a code point was found. Otherwise returns -1.

See also: al_ustr_find_set_cstr, al_ustr_find_cset

al_ustr_find_set_cstr

int al_ustr_find_set_cstr(const ALLEGRO_USTR *us, int start_pos,
   const char *accept)

Source Code

Like al_ustr_find_set but takes a C-style string for accept.

See also: al_ustr_find_set, al_ustr_find_cset_cstr

al_ustr_find_cset

int al_ustr_find_cset(const ALLEGRO_USTR *us, int start_pos,
   const ALLEGRO_USTR *reject)

Source Code

This function finds the first code point in us, beginning from byte offset start_pos, that does not match any code point in reject. In other words it finds a code point in the complementary set of reject. Returns the byte position of that code point, if any. Otherwise returns -1.

See also: al_ustr_find_cset_cstr, al_ustr_find_set

al_ustr_find_cset_cstr

int al_ustr_find_cset_cstr(const ALLEGRO_USTR *us, int start_pos,
   const char *reject)

Source Code

Like al_ustr_find_cset but takes a C-style string for reject.

See also: al_ustr_find_cset, al_ustr_find_set_cstr

al_ustr_find_str

int al_ustr_find_str(const ALLEGRO_USTR *haystack, int start_pos,
   const ALLEGRO_USTR *needle)

Source Code

Find the first occurrence of string needle in haystack, beginning from byte offset start_pos (inclusive). Return the byte offset of the occurrence if it is found, otherwise return -1.

See also: al_ustr_find_cstr, al_ustr_rfind_str, al_ustr_find_replace

al_ustr_find_cstr

int al_ustr_find_cstr(const ALLEGRO_USTR *haystack, int start_pos,
   const char *needle)

Source Code

Like al_ustr_find_str but takes a C-style string for needle.

See also: al_ustr_find_str, al_ustr_rfind_cstr

al_ustr_rfind_str

int al_ustr_rfind_str(const ALLEGRO_USTR *haystack, int end_pos,
   const ALLEGRO_USTR *needle)

Source Code

Find the last occurrence of string needle in haystack before byte offset end_pos (exclusive). Return the byte offset of the occurrence if it is found, otherwise return -1.

See also: al_ustr_rfind_cstr, al_ustr_find_str

al_ustr_rfind_cstr

int al_ustr_rfind_cstr(const ALLEGRO_USTR *haystack, int end_pos,
   const char *needle)

Source Code

Like al_ustr_rfind_str but takes a C-style string for needle.

See also: al_ustr_rfind_str, al_ustr_find_cstr

al_ustr_find_replace

bool al_ustr_find_replace(ALLEGRO_USTR *us, int start_pos,
   const ALLEGRO_USTR *find, const ALLEGRO_USTR *replace)

Source Code

Replace all occurrences of find in us with replace, beginning at byte offset start_pos. The find string must be non-empty. Returns true on success, false on error.

See also: al_ustr_find_replace_cstr

al_ustr_find_replace_cstr

bool al_ustr_find_replace_cstr(ALLEGRO_USTR *us, int start_pos,
   const char *find, const char *replace)

Source Code

Like al_ustr_find_replace but takes C-style strings for find and replace.

Comparing

al_ustr_equal

bool al_ustr_equal(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

Source Code

Return true iff the two strings are equal. This function is more efficient than al_ustr_compare so is preferable if ordering is not important.

See also: al_ustr_compare

al_ustr_compare

int al_ustr_compare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

Source Code

This function compares us1 and us2 by code point values. Returns zero if the strings are equal, a positive number if us1 comes after us2, else a negative number.

This does not take into account locale-specific sorting rules. For that you will need to use another library.

See also: al_ustr_ncompare, al_ustr_equal

al_ustr_ncompare

int al_ustr_ncompare(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2, int n)

Source Code

Like al_ustr_compare but only compares up to the first n code points of both strings.

Returns zero if the strings are equal, a positive number if us1 comes after us2, else a negative number.

See also: al_ustr_compare, al_ustr_equal

al_ustr_has_prefix

bool al_ustr_has_prefix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

Source Code

Returns true iff us1 begins with us2.

See also: al_ustr_has_prefix_cstr, al_ustr_has_suffix

al_ustr_has_prefix_cstr

bool al_ustr_has_prefix_cstr(const ALLEGRO_USTR *us1, const char *s2)

Source Code

Returns true iff us1 begins with s2.

See also: al_ustr_has_prefix, al_ustr_has_suffix_cstr

al_ustr_has_suffix

bool al_ustr_has_suffix(const ALLEGRO_USTR *us1, const ALLEGRO_USTR *us2)

Source Code

Returns true iff us1 ends with us2.

See also: al_ustr_has_suffix_cstr, al_ustr_has_prefix

al_ustr_has_suffix_cstr

bool al_ustr_has_suffix_cstr(const ALLEGRO_USTR *us1, const char *s2)

Source Code

Returns true iff us1 ends with s2.

See also: al_ustr_has_suffix, al_ustr_has_prefix_cstr

UTF-16 conversion

al_ustr_new_from_utf16

ALLEGRO_USTR *al_ustr_new_from_utf16(uint16_t const *s)

Source Code

Create a new string containing a copy of the 0-terminated string s which must be encoded as UTF-16. The string must eventually be freed with al_ustr_free.

See also: al_ustr_new

al_ustr_size_utf16

size_t al_ustr_size_utf16(const ALLEGRO_USTR *us)

Source Code

Returns the number of bytes required to encode the string in UTF-16 (including the terminating 0). Usually called before al_ustr_encode_utf16 to determine the size of the buffer to allocate.

See also: al_ustr_size

al_ustr_encode_utf16

size_t al_ustr_encode_utf16(const ALLEGRO_USTR *us, uint16_t *s,
   size_t n)

Source Code

Encode the string into the given buffer, in UTF-16. Returns the number of bytes written. There are never more than n bytes written. The minimum size to encode the complete string can be queried with al_ustr_size_utf16. If the n parameter is smaller than that, the string will be truncated but still always 0 terminated.

See also: al_ustr_size_utf16, al_utf16_encode

Low-level UTF-8 routines

al_utf8_width

size_t al_utf8_width(int c)

Source Code

Returns the number of bytes that would be occupied by the specified code point when encoded in UTF-8. This is between 1 and 4 bytes for legal code point values. Otherwise returns 0.

See also: al_utf8_encode, al_utf16_width

al_utf8_encode

size_t al_utf8_encode(char s[], int32_t c)

Source Code

Encode the specified code point to UTF-8 into the buffer s. The buffer must have enough space to hold the encoding, which takes between 1 and 4 bytes. This routine will refuse to encode code points above 0x10FFFF.

Returns the number of bytes written, which is the same as that returned by al_utf8_width.

See also: al_utf16_encode

Low-level UTF-16 routines

al_utf16_width

size_t al_utf16_width(int c)

Source Code

Returns the number of bytes that would be occupied by the specified code point when encoded in UTF-16. This is either 2 or 4 bytes for legal code point values. Otherwise returns 0.

See also: al_utf16_encode, al_utf8_width

al_utf16_encode

size_t al_utf16_encode(uint16_t s[], int32_t c)

Source Code

Encode the specified code point to UTF-16 into the buffer s. The buffer must have enough space to hold the encoding, which takes either 2 or 4 bytes. This routine will refuse to encode code points above 0x10FFFF.

Returns the number of bytes written, which is the same as that returned by al_utf16_width.

See also: al_utf8_encode, al_ustr_encode_utf16

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:17 UTC


Video streaming addon

  • System
  • Threads
  • Time
  • Timer
  • Touch input
  • Transformations
  • UTF-8
  • Miscellaneous
  • Platform-specific
  • Direct3D
  • OpenGL
  • Addons
  • Audio addon
  • Audio codecs
  • Color addon
  • Font addons
  • Image I/O addon
  • Main addon
  • Memfile addon
  • Native dialogs addon
  • PhysicsFS addon
  • Primitives addon
  • Video streaming addon
  • Index

Video streaming addon

  • ALLEGRO_VIDEO_EVENT_TYPE
    • ALLEGRO_EVENT_VIDEO_FRAME_SHOW
    • ALLEGRO_EVENT_VIDEO_FINISHED
  • ALLEGRO_VIDEO_POSITION_TYPE
  • al_init_video_addon
  • al_shutdown_video_addon
  • al_get_allegro_video_version
  • al_open_video
  • al_close_video
  • al_start_video
  • al_start_video_with_voice
  • al_get_video_event_source
  • al_set_video_playing
  • al_is_video_playing
  • al_get_video_audio_rate
  • al_get_video_fps
  • al_get_video_scaled_width
  • al_get_video_scaled_height
  • al_get_video_frame
  • al_get_video_position
  • al_seek_video

These functions are declared in the following header file. Link with allegro_video.

 #include <allegro5/allegro_video.h>

Currently we have an Ogg backend (Theora + Vorbis). See http://xiph.org/ for installation instructions, licensing information and supported video formats.

ALLEGRO_VIDEO_EVENT_TYPE

enum ALLEGRO_VIDEO_EVENT_TYPE

Source Code

Events sent by al_get_video_event_source.

ALLEGRO_EVENT_VIDEO_FRAME_SHOW

This event is sent when it is time to show a new frame. Once you receive this event, you can draw the current frame (as returned by al_get_video_frame). al_get_video_frame will continue returning the same frame until the next ALLEGRO_EVENT_VIDEO_FRAME_SHOW is sent.

user.data1 (ALLEGRO_VIDEO *)
The video which generated the event.

Since: 5.1.0

ALLEGRO_EVENT_VIDEO_FINISHED

This event is sent when the video is finished. Depending on the backend, it may be possible to seek to an earlier part of the video and set the video to play to resume playback.

user.data1 (ALLEGRO_VIDEO *)
The video which generated the event.

Since: 5.1.0

ALLEGRO_VIDEO_POSITION_TYPE

typedef enum ALLEGRO_VIDEO_POSITION_TYPE ALLEGRO_VIDEO_POSITION_TYPE;

Source Code

Used with al_get_video_position to specify which position to retrieve. If these get out of sync, audio and video may be out of sync in the display of the video.

  • ALLEGRO_VIDEO_POSITION_ACTUAL - The amount of time the video has been playing. If the video has audio then this value can be ahead of ALLEGRO_VIDEO_POSITION_VIDEO_DECODE when video decoding lags.

  • ALLEGRO_VIDEO_POSITION_VIDEO_DECODE - The amount of video that has been decoded. This may lag behind the "actual" and audio positions if decoding is slower than realtime.

  • ALLEGRO_VIDEO_POSITION_AUDIO_DECODE - The amount of audio that has been decoded. This may be the same as ALLEGRO_VIDEO_POSITION_ACTUAL if audio decode is driving the position, which is common to keep audio and video in sync.

Since: 5.1.11

al_init_video_addon

bool al_init_video_addon(void)

Source Code

Initializes the video addon.

Since: 5.1.12

al_shutdown_video_addon

void al_shutdown_video_addon(void)

Source Code

Shut down the video addon. This is done automatically at program exit, but can be called any time the user wishes as well.

Since: 5.1.12

al_get_allegro_video_version

uint32_t al_get_allegro_video_version(void)

Source Code

Returns the (compiled) version of the addon, in the same format as al_get_allegro_version.

Since: 5.1.12

al_open_video

ALLEGRO_VIDEO *al_open_video(char const *filename)

Source Code

Reads a video file. This does not start streaming yet but reads the meta info so you can query e.g. the size or audio rate.

Since: 5.1.0

al_close_video

void al_close_video(ALLEGRO_VIDEO *video)

Source Code

Closes the video and frees all allocated resources. The video pointer is invalid after the function returns.

Since: 5.1.0

al_start_video

void al_start_video(ALLEGRO_VIDEO *video, ALLEGRO_MIXER *mixer)

Source Code

Starts streaming the video from the beginning.

Since: 5.1.0

al_start_video_with_voice

void al_start_video_with_voice(ALLEGRO_VIDEO *video, ALLEGRO_VOICE *voice)

Source Code

Like al_start_video but audio is routed to the provided voice.

Since: 5.1.0

al_get_video_event_source

ALLEGRO_EVENT_SOURCE *al_get_video_event_source(ALLEGRO_VIDEO *video)

Source Code

Get an event source for the video. The possible events are described under ALLEGRO_VIDEO_EVENT_TYPE.

Since: 5.1.0

al_set_video_playing

void al_set_video_playing(ALLEGRO_VIDEO *video, bool play)

Source Code

Paused or resumes playback.

Since: 5.1.12

al_is_video_playing

bool al_is_video_playing(ALLEGRO_VIDEO *video)

Source Code

Returns true if the video is currently playing.

Since: 5.1.12

al_get_video_audio_rate

double al_get_video_audio_rate(ALLEGRO_VIDEO *video)

Source Code

Returns the audio rate of the video, in Hz.

Since: 5.1.0

al_get_video_fps

double al_get_video_fps(ALLEGRO_VIDEO *video)

Source Code

Returns the speed of the video in frames per second. Often this will not be an integer value.

Since: 5.1.0

al_get_video_scaled_width

float al_get_video_scaled_width(ALLEGRO_VIDEO *video)

Source Code

Returns the width with which the video frame should be drawn. Videos often do not use square pixels, so this will may return a value larger than the width of the frame bitmap.

Since: 5.1.12

See also: al_get_video_frame

al_get_video_scaled_height

float al_get_video_scaled_height(ALLEGRO_VIDEO *video)

Source Code

Returns the height with which the video frame should be drawn. Videos often do not use square pixels, so this will may return a value larger than the height of the frame bitmap.

See also: al_get_video_frame

Since: 5.1.12

al_get_video_frame

ALLEGRO_BITMAP *al_get_video_frame(ALLEGRO_VIDEO *video)

Source Code

Returns the current video frame. The bitmap is owned by the video so do not attempt to free it. The bitmap will stay valid until the next call to al_get_video_frame.

Videos often do not use square pixels so the recommended way to draw a video frame would be using code like this:

float scale = 1.0; /* Adjust this to fit your target bitmap dimensions. */
ALLEGRO_BITMAP* frame = al_get_video_frame(video);
float sw = al_get_bitmap_width(frame);
float sh = al_get_bitmap_height(frame);
float dw = scale * al_get_video_scaled_width(video);
float dh = scale * al_get_video_scaled_height(video);
al_draw_scaled_bitmap(frame, 0, 0, sw, sh, 0, 0, dw, dh, 0);

Since: 5.1.0

See also: al_get_video_scaled_width, al_get_video_scaled_height

al_get_video_position

double al_get_video_position(ALLEGRO_VIDEO *video, ALLEGRO_VIDEO_POSITION_TYPE which)

Source Code

Returns the current position of the video stream in seconds since the beginning. The parameter is one of the ALLEGRO_VIDEO_POSITION_TYPE constants.

Since: 5.1.0

al_seek_video

bool al_seek_video(ALLEGRO_VIDEO *video, double pos_in_seconds)

Source Code

Seek to a different position in the video. Currently only seeking to the beginning of the video is supported.

Since: 5.1.0

Allegro version 5.2.4 (GIT) - Last updated: 2017-10-30 17:08:20 UTC