Allegro 4 examples

This article is a stub. Please help Allegro by expanding it.

This page exists to provide a set of indepth guides to Allegro 4's Examples.

Allegro Examples

exhello

  This is a very simple program showing how to get into graphics
  mode and draw text onto the screen.

exmem

  This program demonstrates the use of memory bitmaps. It creates
  a small temporary bitmap in memory, draws some circles onto it,
  and then blits lots of copies of it onto the screen.

expal

  This program demonstrates how to manipulate the palette. It draws
  a set of concentric circles onto the screen and animates them by
  cycling the palette.

expat

  This program demonstrates the use of patterned drawing and sub-bitmaps.

exflame

  This program demonstrates how to write directly to video memory.
  It implements a simple fire effect, first by calling getpixel() and
  putpixel(), then by accessing video memory directly a byte at a
  time, and finally using block memory copy operations.

exdbuf

  This program demonstrates the use of double buffering.
  It moves a circle across the screen, first just erasing and
  redrawing directly to the screen, then with a double buffer.

exflip

  This program moves a circle across the screen, first with a
  double buffer and then using page flips.

exfixed

  This program demonstrates how to use fixed point numbers, which
  are signed 32-bit integers storing the integer part in the
  upper 16 bits and the decimal part in the 16 lower bits. This
  example also uses the unusual approach of communicating with
  the user exclusively via the allegro_message() function.

exfont

  This is a very simple program showing how to load and manipulate fonts.

exmouse

  This program demonstrates how to get mouse input. The
  first part of the test retrieves the raw mouse input data
  and displays it on the screen without using any mouse
  cursor. When you press a key the standard arrow-like mouse
  cursor appears.  You are not restricted to this shape,
  and a second keypress modifies the cursor to be several
  concentric colored circles. They are not joined together,
  so you can still see bits of what's behind when you move the
  cursor over the printed text message.

extimer

  This program demonstrates how to use the timer routines.
  These can be a bit of a pain, because you have to be sure
  you lock all the memory that is used inside your interrupt
  handlers.  The first part of the example shows a basic use of
  timing using the blocking function rest(). The second part
  shows how to use three timers with different frequencies in
  a non blocking way.

exkeys

  This program demonstrates how to access the keyboard. The
  first part shows the basic use of readkey(). The second part
  shows how to extract the ASCII value. Next come the scancodes.
  The fourth test detects modifier keys like alt or shift. The
  fifth test requires some focus to be passed. The final step
  shows how to use the global key array to read simultaneous
  keypresses.
  The last method to detect key presses are keyboard callbacks.
  This is demonstrated by by installing a keyboard callback,
  which marks all pressed keys by drawing to a grid.

exjoy

  This program uses the Allegro library to detect and read the value
  of a joystick. The output of the program is a small target sight
  on the screen which you can move. At the same time the program will
  tell you what you are doing with the joystick (moving or firing).

exsample

  This program demonstrates how to play samples. You have to
  use this example from the commandline to specify as first
  parameter a WAV or VOC sound file to play. If the file is
  loaded successfully, the sound will be played in an infinite
  loop. While it is being played, you can use the left and right
  arrow keys to modify the panning of the sound. You can also
  use the up and down arrow keys to modify the pitch.

exmidi

  This program demonstrates how to play MIDI files.

exgui

  This program demonstrates how to use the GUI routines. From
  the simple dialog controls that display a text or a bitmap to
  more complex multiple choice selection lists, Allegro provides
  a framework which can be customised to suit your needs.

excustom

  A follow up of the exgui.c example showing how to customise the
  default Allegro framework. In this case a dialog procedure
  animates a graphical clock without disrupting other GUI
  dialogs.  A more simple option shows how to dynamically change
  the font used by all GUI elements.

exunicod

  This program demonstrates the use of the 16-bit Unicode text
  encoding format with Allegro. The example displays a message
  translated to different languages scrolling on the screen
  using an external font containing the required characters to
  display those messages.

  Note how the Allegro unicode string functions resemble the
  functions you can find in the standard C library, only these
  handle Unicode on all platforms.

exbitmap

  This program demonstrates how to load and display a bitmap
  file.  You have to use this example from the commandline to
  specify as first parameter a graphic file in one of Allegro's
  supported formats.  If the file is loaded successfully,
  it will be displayed until you press a key.

exscale

  This example demonstrates how to use pcx files, palettes and stretch
  blits. It loads a pcx file, sets its palette and does some random
  stretch_blits. Don't worry - it's VERY slowed down using vsync().

exconfig

  This is a very simple program showing how to use the allegro
  config (ini file) routines. A first look at the example
  shows nothing more than a static graphic and the wait for
  a keypress. However, the way this graphic is displayed is
  configured through a custom exconfig.ini file which is loaded
  manually. From this file the example obtains parameters like
  fullscreen/windowed mode, a specific graphic resolution to set
  up, which graphic to show, how to blit it on the screen, etc.

exdata

  This program demonstrates how to access the contents of an
  Allegro datafile (created by the grabber utility). The example
  loads the file `example.dat', then blits a bitmap and shows
  a font, both from this datafile.

exsprite

  This example demonstrates how to use datafiles, various sprite
  drawing routines and flicker-free animation.

  Why is the animate() routine coded in that way?  As you
  probably know, VIDEO RAM is much slower than "normal"
  RAM, so it's advisable to reduce VRAM blits to a minimum.
  Drawing sprite on the screen (meaning in VRAM) and then
  clearing a background for it is not very fast. This example
  uses a different method which is much faster, but require a
  bit more memory.

  First the buffer is cleared (it's a normal BITMAP), then the
  sprite is drawn on it, and when the drawing is finished this
  buffer is copied directly to the screen. So the end result is
  that there is a single VRAM blit instead of blitting/clearing
  the background and drawing a sprite on it.  It's a good method
  even when you have to restore the background. And of course,
  it completely removes any flickering effect.

  When one uses a big (ie. 800x600 background) and draws
  something on it, it's wise to use a copy of background
  somewhere in memory and restore background using this
  "virtual background". When blitting from VRAM in SVGA modes,
  it's probably, that drawing routines have to switch banks on
  video card. I think, I don't have to remind how slow is it.

  Note that on modern systems, the above isn't true anymore, and
  you usually get the best performance by caching all your
  animations in video ram and doing only VRAM->VRAM blits, so
  there is no more RAM->VRAM transfer at all anymore. And usually,
  such transfers can run in parallel on the graphics card's
  processor as well, costing virtually no main cpu time at all.
  See the exaccel example for an example of this.

exexedat

  This program demonstrates how to access the contents of an Allegro
  datafile (created by the grabber utility) linked to the exe by the
  exedat tool. It is basically the exdata example with minor
  modifications.

  You may ask: how do you compile, append and exec your program?

  Answer: like this...

1. ) Compile your program like normal. Use the magic filenames with '#'

  to load your data where needed.

1. ) Once you compressed your program, run "exedat foo.exe data.dat"

1. ) Finally run your program.

  Note that appending data to the end of binaries may not be portable
  accross all platforms supported by Allegro.

extrans

  This program demonstrates how to use the lighting and
  translucency functions. The first part of the example will
  show a dark screen iluminated by a spotlight you can move
  with your mouse. After a keypress the example shows the full
  bitmap and the spotlight changes to be a reduced version of
  the background with 50% of translucency.

  The translucency effect is easy to do in all color depths.
  However, the lighting effect has to be performed in a different
  way depending on whether the screen is in 8bit mode or another
  color depth. This is because additive drawing mode uses a
  different set of routines for truecolor modes.

extruec

  This program shows how to specify colors in the various different
  truecolor pixel formats. The example shows the same screen (a few
  text lines and three coloured gradients) in all the color depth
  modes supported by your video card. The more color depth you have,
  the less banding you will see in the gradients.

excolmap

  This program demonstrates how to create custom graphic effects
  with the create_color_table function. Allegro drawing routines
  are affected by any color table you might have set up. In
  the first part of this example, a greyscale color table is
  set. The result is that a simple rectfill call, instead of
  drawing a rectangle with color zero, uses the already drawn
  pixels to determine the pixel to be drawn (read the comment
  of return_grey_color() for a precise description of the
  algorithm). In the second part of the test, the color table
  is changed to be an inverse table, meaning that any pixel
  drawn will be shown as its color values had been inverted.

exrgbhsv

  This program shows how to convert colors between the different
  color-space representations. The central area of the screen
  will display the current color. On the top left corner of the
  screen, three sliders allow you to modify the red, green and
  blue value of the color. On the bottom right corner of the
  screen, three sliders allow you to modify the hue, saturation
  and value of the color. The color bars beneath the sliders
  show what the resulting color will look like when the slider
  is dragged to that position.

  Additionally this example also shows how to "inherit" the
  behaviour of a GUI object and extend it, here used to create
  the sliders.

exshade

  This program demonstrates how to draw gouraud shaded (lit)
  sprites.  In an apparently black screen, a planet like sprite
  is drawn close to the middle of the screen. In a similar
  way to how the first test of extrans works, you move the
  cursor on the screen with the mouse. Attached to this mouse
  you can imagine a virtual spotlight illuminating the scene
  around. Depending on where the mouse is, the goraud shaded
  sprite will show the direction of the light.

exblend

  This program demonstrates how to use the translucency functions
  in truecolor video modes. Two image files are loaded from
  disk and displayed moving slowly around the screen. One of
  the images will be tinted to different colors. The other
  image will be faded out with a varying alpha strength, and
  drawn on top of the other image.

exxfade

  This program demonstrates how to load and display bitmap files
  in truecolor video modes, and how to crossfade between them.
  You have to use this example from the commandline to specify
  as parameters a number of graphic files. Use at least two
  files to see the graphical effect. The example will crossfade
  from one image to another with each keypress until you press
  the ESC key.

exalpha

  This program demonstrates how to use the 32 bit RGBA
  translucency functions to store an alpha channel along with
  a bitmap graphic.  Two images are loaded from disk. One will
  be used for the background and the other as a sprite. The
  example generates an alpha channel for the sprite image,
  composing the 32 bit RGBA bitmap during runtime, and draws
  it at the position of the mouse cursor.

exlights

  This program shows one way to implement colored lighting effects
  in a hicolor video mode. Warning: it is not for the faint of heart!
  This is by no means the simplest or easiest to understand method,
  I just thought it was a cool concept that would be worth
  demonstrating.

  The basic approach is to select a 15 or 16 bit screen mode, but
  then draw onto 24 bit memory bitmaps. Since we only need the bottom

1. bits of each 8 bit color in order to store 15 bit data within a
2. bit location, we can fit a light level into the top 3 bits.

  The tricky bit is that these aren't actually 24 bit images at all:
  they are implemented as 8 bit memory bitmaps, and we just store the
  red level in one pixel, green in the next, and blue in the next,
  making the total image be three times wider than we really wanted.
  This allows us to use all the normal 256 color graphics routines
  for drawing onto our memory surfaces, most importantly the lookup
  table translucency, which can be used to combine the low 5 bits
  of color and the top 3 bits of light in a single drawing operation.
  Some trickery is needed to load 24 bit data into this fake 8 bit
  format, and of course it needs a custom routine to convert the
  resulting image while copying it across to the hardware screen.

  This program chugs slightly on my p133, but not significantly
  worse than any double buffering in what amounts to a 1920x640,

1. color resolution. The light blending doesn't seem to slow

  it down too badly, so I think this technique would be quite usable
  on faster machines and in lower resolution hicolor modes. The
  biggest problem is that although you keep the full 15 bit color
  resolution, you only get 3 bits of light, ie. 8 light levels.
  You can do some nice colored light patches, but smooth gradients
  aren't going to work too well :-)

ex3d

  This program demonstrates how to use the 3d matrix functions.
  It isn't a very elegant or efficient piece of code, but it
  does show the stuff in action. It is left to the reader as
  an exercise to design a proper model structure and rendering
  pipeline: after all, the best way to do that sort of stuff
  varies hugely from one game to another.

  The example first shows a screen resolution selection dialog.
  Then, a number of bouncing 3d cubes are animated. Pressing
  a key modifies the rendering of the cubes, which can be
  wireframe, the more complex transparent perspective correct
  texture mapped version, and many other.

excamera

  This program demonstrates how to use the get_camera_matrix()
  function to view a 3d world from any position and angle. The
  example draws a checkered floor through a viewport region
  on the screen. You can use the keyboard to move around the
  camera or modify the size of the viewport. The keys that can
  be used with this example are displayed between brackets at
  the top of the screen.

exquat

  Euler angles are convenient for storing and creating 3D orientations.
  However, this program demonstrates that they are not good when
  interpolating between two different orientations. The problem is
  solved by using Allegro's quaternion operations.

  In this program, two cubes are rotated between random orientations.
  Notice that although they have the same beginning and ending
  orientations, they do not follow the same path between orientations.

  One cube is being rotated by directly incrementing or decrementing
  the Euler angles from the starting point to the ending point.
  This is an intuitive notion, but it is incorrect because it does not
  cause the object to turn around a single unchanging axis of rotation.
  The axis of rotation wobbles resulting in the object spinning in
  strange ways. The object will eventually end up in the orientation
  that the user intended, but it gets there in a way that is unattractive.
  Imagine if this method was used to update the position of a camera in a
  game! Sometimes it would swing wildly and disorient the player.

  The other cube is animated using quaternions. This results in a much
  more pleasing animation because the cube turns around a single axis
  of rotation.

exstars

  This program draws a 3D starfield (depth-cued) and a polygon
  starship (controllable with the keyboard cursor keys), using
  the Allegro math functions.

exscn3d

  This program demonstrates how to use scanline sorting algo
  in Allegro (create_scene, clear_scene, ... functions). It
  also provides an example of how to use the 3D clipping
  function. The example consists of a flyby through a lot of
  rotating 3d cubes.

exzbuf

  This program demonstrates how to use Z-buffered polygons and
  floating point 3D math routines. It also provides a simple
  way to compute fps (frames per second) using a timer. After
  selecting a screen resolution through the standard GUI dialog,
  the example shows two 3D cubes rotating and intersecting each
  other. Rather than having full polygons incorrectly overlap
  other polgons due to per-polygon sorting, each pixel is drawn
  at the correct depth.

exscroll

  This program demonstrates how to use hardware scrolling.
  The scrolling should work on anything that supports virtual
  screens larger than the physical screen.

ex3buf

  This program demonstrates the use of triple buffering. Several
  triangles are displayed rotating and bouncing on the screen
  until you press a key. Note that on some platforms you
  can't get real hardware triple buffering.  The Allegro code
  remains the same, but most likely the graphic driver will
  emulate it. Unfortunately, in these cases you can't expect
  the animation to be completely smooth and flicker free.

ex12bit

  This program sets up a 12-bit mode on any 8-bit card, by
  setting up a 256-colour palette that will fool the eye into
  grouping two 8-bit pixels into one 12-bit pixel. In order
  to do this, you make your 256-colour palette with all the
  combinations of blue and green, assuming green ranges from 0-15
  and blue from 0-14. This takes up 16x15=240 colours. This
  leaves 16 colours to use as red (red ranges from 0-15).
  Then you put your green/blue in one pixel, and your red in
  the pixel next to it. The eye gets fooled into thinking it's
  all one pixel.

  The example starts setting a normal 256 color mode, and
  construct a special palette for it. But then comes the trick:
  you need to write to a set of two adjacent pixels to form a
  single 12 bit dot. Two eight bit pixels is the same as one 16
  bit pixel, so after setting the video mode you need to hack
  the screen bitmap about, halving the width and changing it
  to use the 16 bit drawing code. Then, once you have packed a
  color into the correct format (using the makecol12() function
  below), any of the normal Allegro drawing functions can be
  used with this 12 bit display!

  Things to note:

• The horizontal width is halved, so you get resolutions

  like 320x480, 400x600, and 512x768.

• Because each dot is spread over two actual pixels, the

  display will be darker than in a normal video mode.

• Any bitmap data will obviously need converting to the

  correct 12 bit format: regular 15 or 16 bit images won't
  display correctly...

• Although this works like a truecolor mode, it is

  actually using a 256 color palette, so palette fades are
  still possible!

• This code only works in linear screen modes (don't try

  Mode-X).

exaccel

  This program demonstrates how to use an offscreen part of
  the video memory to store source graphics for a hardware
  accelerated graphics driver. The example loads the `mysha.pcx'
  file and then blits it several times on the screen. Depending
  on whether you have enough video memory and Allegro supports
  the hardware acceleration features of your card, your success
  running this example may be none at all, sluggish performance
  due to software emulation, or flicker free smooth hardware
  accelerated animation.

exspline

  This program demonstrates the use of spline curves to create smooth
  paths connecting a number of node points. This can be useful for
  constructing realistic motion and animations.

  The technique is to connect the series of guide points p1..p(n) with
  spline curves from p1-p2, p2-p3, etc. Each spline must pass though
  both of its guide points, so they must be used as the first and fourth
  of the spline control points. The fun bit is coming up with sensible
  values for the second and third spline control points, such that the
  spline segments will have equal gradients where they meet. I came
  up with the following solution:

  For each guide point p(n), calculate the desired tangent to the curve
  at that point. I took this to be the vector p(n-1) -> p(n+1), which
  can easily be calculated with the inverse tangent function, and gives
  decent looking results. One implication of this is that two dummy
  guide points are needed at each end of the curve, which are used in
  the tangent calculations but not connected to the set of splines.

  Having got these tangents, it becomes fairly easy to calculate the
  spline control points. For a spline between guide points p(a) and
  p(b), the second control point should lie along the positive tangent
  from p(a), and the third control point should lie along the negative
  tangent from p(b). How far they are placed along these tangents
  controls the shape of the curve: I found that applying a 'curviness'
  scaling factor to the distance between p(a) and p(b) works well.

  One thing to note about splines is that the generated points are
  not all equidistant. Instead they tend to bunch up nearer to the
  ends of the spline, which means you will need to apply some fudges
  to get an object to move at a constant speed. On the other hand,
  in situations where the curve has a noticable change of direction
  at each guide point, the effect can be quite nice because it makes
  the object slow down for the curve.

exsyscur

  This program demonstrates the use of hardware accelerated mouse cursors.

exupdate

  This program demonstrates how to support double buffering,
  page flipping, and triple buffering as options within a single
  program, and how to make things run at a constant rate no
  matter what the speed of your computer. You have to use this
  example from the commandline to specify as first parameter a
  number which represents the type of video update you want: 1
  for double buffering with memory bitmaps, 2 for page flipping,

1. for triple buffering and 4 for double buffering with system

  bitmaps. After this, a dialog allows you to select a screen
  resolution and finally you will see a kaleidoscopic animation,
  along with a frames per second counter on the top left of
  the screen.

exswitch

  This program shows how to control the console switching mode, and
  let your program run in the background. These functions don't apply
  to every platform and driver, for example you can't control the
  switching mode from a DOS program.

  Yes, I know the fractal drawing is very slow: that's the point!
  This is so you can easily check whether it goes on working in the
  background after you switch away from the app.

  Depending on the type of selected switching mode, you will see
  whether the contents of the screen are preserved or not.

exstream

  This program shows how to use the audio stream functions to
  transfer large blocks of sample data to the soundcard. In
  this case, the sample data is generated during runtime,
  and the resulting sound reminds of a car engine when you
  are accelerating.

expackf

  This program demonstrates the use of the packfile functions, with some
  simple tests.

  The first test uses the standard packfile functions to transfer a
  bitmap file into a block of memory, then reads the bitmap out of the
  block of memory, using a custom packfile vtable.

  The second test reads in a bitmap with another custom packfile
  vtable, which uses libc's filestream functions.

  The third test demonstrates seeking with a custom vtable.

  The fourth test reads two bitmaps, and dumps them back into a
  single file, using a custom vtable again.