Programmer_28 [12:02 PM]
hello

Apiza [12:03 PM]
Hello!

Programmer_28 [12:03 PM]
How are you?

Apiza [12:04 PM]
I'm good, how about you?

Programmer_28 [12:04 PM]
very well!

Programmer_28 [12:24 PM]
How do you handle keyboard input in Allegro?

Apiza [12:26 PM]
To get started, you'll probably want to use al_install_keyboard:

bool al_install_keyboard(void)

Install a keyboard driver. Returns true if successful. If a driver was already installed, nothing happens and true is returned.

Programmer_28 [12:30 PM]
what's next?

Apiza [12:30 PM]
You'll probably want to look at one of the following events:

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.

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.

Programmer_28 [12:35 PM]
how do you handle keyboard events?

Apiza [12:36 PM]
You'll probably want to use al_get_keyboard_event_source:

ALLEGRO_EVENT_SOURCE *al_get_keyboard_event_source(void)

Retrieve the keyboard event source. All keyboard events are generated by this event source.

Returns NULL if the keyboard subsystem was not installed.

Programmer_28 [12:37 PM]
how do you check key pressed state

Apiza [12:38 PM]
You can check that with al_key_down:

bool al_key_down(const ALLEGRO_KEYBOARD_STATE *state, int keycode)

Return true if the key specified was held down in the state specified.

Programmer_28 [12:39 PM]
how do you use ALLEGRO_KEYBOARD_STATE ?

Apiza [12:40 PM]
What would you like to do with it? Here's some basic information:

ALLEGRO_KEYBOARD_STATE

typedef struct ALLEGRO_KEYBOARD_STATE ALLEGRO_KEYBOARD_STATE;

This is a structure that is used to hold a "snapshot" of a keyboard's state at a particular instant. It contains the following publically readable fields:

display - points to the display that had keyboard focus at the time the state was saved. If no display was focused, this points to NULL.
You cannot read the state of keys directly. Use the function al_key_down.

Programmer_28 [12:42 PM]
how do you retrieve the current ALLEGRO_KEYBOARD_STATE for the keyboard?

Apiza [12:42 PM]
You can retrieve the keyboard state with al_get_keyboard_state:

void al_get_keyboard_state(ALLEGRO_KEYBOARD_STATE *ret_state)

Save the state of the keyboard specified at the time the function is called into the structure pointed to by ret_state.

Programmer_28 [12:51 PM]
great, it works

Apiza [12:51 PM]
Great!

Programmer_28 [12:52 PM]
how do you play sounds in Allegro

Apiza [12:53 PM]
You'll probably want to start with al_install_audio:

bool al_install_audio(void)

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.

Programmer_28 [12:54 PM]
describe al_reserve_samples

Apiza [12:55 PM]
Here's some information on al_reserve_samples:

bool al_reserve_samples(int reserve_samples)

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.

Programmer_28 [12:56 PM]
how do you play a single wav file in Allegro?

Apiza [12:58 PM]
You'll probably want to use al_load_sample followed by al_play_sample:

ALLEGRO_SAMPLE *al_load_sample(const char *filename)

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.

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

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.

Programmer_28 [1:03 PM]
how do you get the error message when al_load_sample fails?
how do you use allegro_acodec to handle .wav audio files?

Apiza [1:05 PM]
Have you called al_init_acodec_addon?

bool al_init_acodec_addon(void)

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.

Programmer_28 [1:15 PM]
ok, it works

Apiza [1:15 PM]
Great!

Programmer_28 [1:16 PM]
how do you draw text with Allegro?

Apiza [1:17 PM]
You'll probably want to start with al_init_font_addon:

bool al_init_font_addon(void)

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.

Programmer_28 [1:20 PM]
what's next?

Apiza [1:21 PM]
You'll probably want to use al_load_font to load a font:

ALLEGRO_FONT *al_load_font(char const *filename, int size, int flags)

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.

Programmer_28 [1:22 PM]
how do you use al_load_ttf_font?

Apiza [1:23 PM]
Here's some information on al_load_ttf_font:

ALLEGRO_FONT *al_load_ttf_font(char const *filename, int size, int flags)

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

Programmer_28 [1:26 PM]
what's next, to draw text once I have loaded the font?

Apiza [1:27 PM]
To draw text you'll probably want to use al_draw_text:

void al_draw_text(const ALLEGRO_FONT *font,
  ALLEGRO_COLOR color, float x, float y, int flags,
  char const *text)

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.

Programmer_28 [1:28 PM]
how do you use ALLEGRO_COLOR?

Apiza [1:30 PM]
al_map_rgb should allow you to create an ALLEGRO_COLOR:

ALLEGRO_COLOR al_map_rgb(
  unsigned char r, unsigned char g, unsigned char b)

Convert r, g, b (ranging from 0-255) into an ALLEGRO_COLOR, using 255 for alpha.

Programmer_28 [1:38 PM]
why would al_draw_text() produce the warning "VERR_BUFFER_OVERFLOW

Apiza [1:40 PM]
It seems like that's most likely a problem with your virtual machine. What size display are you using?

Programmer_28 [1:41 PM]
ok, nevermind

Programmer_28 [1:46 PM]
What to do if al_draw_text produces no result?
nevermind
ok, it works

Apiza [1:51 PM]
Great!

Programmer_28 [1:53 PM]
how do you load a .png into a bitmap