Structures and types defined by Allegro

There are several structures and types defined by Allegro which are used in many functions (like the BITMAP structure). This section of the manual describes their useful content from a user point of view when they don't fit very well any of the existing manual sections, and redirects you to the appropiate section when it's already described there. Note that unless stated otherwise, the contents shown here are just for read only purposes, there might be other internal flags, but you shouldn't depend on them being available in past/future versions of Allegro.


typedef long fixed

This is a fixed point integer which can replace float with similar results and is faster than float on low end machines. Read chapter "Fixed point math routines" for the full explanation.
See also: Fixed point math routines.
typedef struct BITMAP

   int w, h;               - size of the bitmap in pixels
   int clip;               - non-zero if clipping is turned on
   int cl, cr, ct, cb;     - clip rectangle left, right, top,
                             and bottom
   unsigned char *line[];  - pointers to the start of each line
There is some other stuff in the structure as well, but it is liable to change and you shouldn't use anything except the above. The w and h fields can be used to obtain the size of an existing bitmap: 
      bmp = load_bitmap("file.bmp", pal);
      allegro_message("Bitmap size: (%dx%d)\n", bmp->w, bmp->h);
The clipping rectangle is inclusive on the left and top (0 allows drawing to position 0) but exclusive on the right and bottom (10 allows drawing to position 9, but not to 10). Note this is not the same format as you pass to set_clip(), which takes inclusive coordinates for all four corners. All the values of this structure should be regarded as read-only, with the exception of the line field, whose access is described in depth in the "Direct access to video memory" section of the manual. If you want to modify the clipping region, please refrain from changing this structure, use set_clip() instead.
See also: create_bitmap, set_clip, bitmap_color_depth, RLE_SPRITE, COMPILED_SPRITE, Direct access to video memory.
typedef struct RLE_SPRITE

   int w, h;           - width and height in pixels
   int color_depth;    - color depth of the image
RLE sprites store the image in a simple run-length encoded format, where repeated zero pixels are replaced by a single length count, and strings of non-zero pixels are preceded by a counter giving the length of the solid run. Read chapter "RLE sprites" for a description of the restrictions and how to obtain/use this structure.
See also: get_rle_sprite, BITMAP, COMPILED_SPRITE, RLE sprites.
typedef struct COMPILED_SPRITE

   short planar;        - set if it's a planar (mode-X) sprite
   short color_depth;   - color depth of the image
   short w, h;          - size of the sprite
Compiled sprites are stored as actual machine code instructions that draw a specific image onto a bitmap, using mov instructions with immediate data values. Read chapter "Compiled sprites" for a description of the restrictions and how to obtain/use this structure.
See also: get_compiled_sprite, BITMAP, RLE_SPRITE, Compiled sprites.
typedef struct JOYSTICK_INFO

   int flags;                       - status flags for this
                                      joystick
   int num_sticks;                  - how many stick inputs?
   int num_buttons;                 - how many buttons?
   JOYSTICK_STICK_INFO stick[n];    - stick state information
   JOYSTICK_BUTTON_INFO button[n];  - button state information
Read chapter "Joystick routines" for a description on how to obtain/use this structure.
See also: joy, Joystick routines.
typedef struct JOYSTICK_BUTTON_INFO

   int b;                           - boolean on/off flag
   char *name;                      - description of this
                                      button
Read chapter "Joystick routines" for a description on how to obtain/use this structure.
See also: joy, Joystick routines.
typedef struct JOYSTICK_STICK_INFO

   int flags;                       - status flags for this
                                      input
   int num_axis;                    - how many axis do we
                                      have?
   JOYSTICK_AXIS_INFO axis[n];      - axis state information
   char *name;                      - description of this
                                      input
Read chapter "Joystick routines" for a description on how to obtain/use this structure.
See also: joy, Joystick routines.
typedef struct JOYSTIC_AXIS_INFO

   int pos;                         - analogue axis position
   int d1, d2;                      - digital axis position
   char *name;                      - description of this axis
Read chapter "Joystick routines" for a description on how to obtain/use this structure.
See also: joy, Joystick routines.
typedef struct GFX_MODE_LIST

   int num_modes;
   GFX_MODE *mode;
Structure returned by get_gfx_mode_list, which contains an array of GFX_MODE structures.
See also: GFX_MODE, get_gfx_mode_list.
typedef struct GFX_MODE

   int width, height, bpp;
Structure contained in GFX_MODE_LIST.
See also: GFX_MODE_LIST, get_gfx_mode_list.
typedef RGB PALETTE[PAL_SIZE]

Allegro palettes are arrays of PAL_SIZE(256) RGB entries.
See also: RGB, Palette routines.
typedef struct RGB

   unsigned char r, g, b;
Palette entry. Read chapter "Palette routines" for a description on how to obtain/use this structure.
See also: Palette routines, PALETTE.
typedef struct V3D

   fixed x, y, z;       - position
   fixed u, v;          - texture map coordinates
   int c;               - color
A vertex structure used by polygon3d and other polygon rendering functions. Read the description of polygon3d for a description on how to obtain/use this structure.
See also: V3D_f, polygon3d, Fixed point trig.
typedef struct V3D_f

   float x, y, z;       - position
   float u, v;          - texture map coordinates
   int c;               - color
Like V3D but using float values instead of fixed ones.
See also: V3D, polygon3d, Fixed point trig.
typedef struct COLOR_MAP

   unsigned char data[PAL_SIZE][PAL_SIZE];
Read chapter "Transparency and patterned drawing", section "256 color transparency" for a description on how to obtain/use this structure.
See also: 256 color transparency, color_map.
typedef struct RGB_MAP

   unsigned char data[32][32][32];
Read chapter "Converting between color formats" for a description on how to obtain/use this structure.
See also: Converting between color formats, create_rgb_table.
struct al_ffblk

   int attrib;       - actual attributes of the file found
   time_t time;      - modification time of file
   long size;        - size of file
   char name[512];   - name of file
Read the description of al_findfirst for a description on how to obtain/use this structure.
See also: al_findfirst.
typedef struct DATAFILE

   void *dat;     - pointer to the actual data
   int type;      - type of the data
   long size;     - size of the data in bytes
   void *prop;    - list of object properties
Read chapter "Datafile routines", section "Using datafiles" for a description on how to obtain/use this structure.
See also: load_datafile, Using datafiles.
typedef struct MATRIX

   fixed v[3][3];           - 3x3 scaling and rotation component
   fixed t[3];              - x/y/z translation component
Fixed point matrix structure. Read chapter "3D math routines" for a description on how to obtain/use this structure.
See also: MATRIX_f, 3D math routines.
typedef struct MATRIX_f

   float v[3][3];           - 3x3 scaling and rotation component
   float t[3];              - x/y/z translation component
Floating point matrix structure. Read chapter "3D math routines" for a description on how to obtain/use this structure.
See also: MATRIX, 3D math routines.
typedef struct QUAT

   float w, x, y, z;
Read chapter "Quaternion math routines" for a description on how to obtain/use this structure.
See also: Quaternion math routines.
typedef struct DIALOG

   int (*proc)(int, DIALOG *, int); - dialog procedure
                                      (message handler)
   int x, y, w, h;       - position and size of the object
   int fg, bg;           - foreground and background colors
   int key;              - ASCII keyboard shortcut
   int flags;            - flags about the status of the object
   int d1, d2;           - whatever you want to use them for
   void *dp, *dp2, *dp3; - pointers to more object-specific data
This is the structure which contains a GUI object. Read chapter "GUI routines" for a description on how to obtain/use this structure.
See also: do_dialog, GUI routines.
typedef struct MENU

   char *text;          - the text to display for the menu item
   int (*proc)();       - called when the menu item is clicked
   struct MENU *child;  - nested child menu
   int flags;           - disabled or checked state
   void *dp;            - pointer to any data you need
Structure used to hold an entry of a menu. Read chapter "GUI routines", section "GUI menus" for a description on how to obtain/use this structure.
See also: do_menu, GUI menus.
typedef struct DIALOG_PLAYER

A structure which holds GUI data used internally by Allegro. Read the documentation of init_dialog() for a description on how to obtain/use this structure.
See also: init_dialog, update_dialog, shutdown_dialog, GUI routines.
typedef struct MENU_PLAYER

A structure which holds GUI data used internally by Allegro. Read the documentation of init_menu() for a description on how to obtain/use this structure.
See also: init_menu, update_menu, shutdown_menu, GUI menus.
typedef struct FONT

A structure holding an Allegro font, usually created beforehand with the grabber tool or Allegro's default font.
See also: font.
typedef struct BITMAP ZBUFFER

Structure used by Allegro's 3d zbuffered rendering functions. You are not supposed to mix ZBUFFER with BITMAP even though it is currently possible to do so. This is just an internal representation, and it may change in the future.
See also: Zbuffered rendering, BITMAP.
typedef struct SAMPLE

   int bits;                   - 8 or 16
   int stereo;                 - sample type flag
   int freq;                   - sample frequency
   int priority;               - 0-255 */
   unsigned long len;          - length (in samples)
   unsigned long loop_start;   - loop start position
   unsigned long loop_end;     - loop finish position
A sample structure, which holds sound data, used by the digital sample routines.
See also: load_sample, Digital sample routines.
typedef struct MIDI

A structure holding MIDI data. Read chapter "Music routines (MIDI)" for a description on how to obtain/use this structure.
See also: load_midi, Music routines (MIDI).
typedef struct AUDIOSTREAM

A structure holding an audiostream. Read chapter "Audio stream routines" for a description on how to obtain/use this structure.
See also: play_audio_stream, Audio stream routines.
typedef struct PACKFILE

   int hndl;                   - DOS file handle
   int flags;                  - PACKFILE_FLAG_* constants
   char *filename;             - name of the file
A packfile structure, similar to a stdio.h FILE structure. Read chapter "Packfile functions" for a description on how to obtain/use this structure.
See also: pack_fopen, Packfile functions.
Back to contents