Allegro Manual: Structures and types defined by Allegro

# Structures and types defined by Allegro

- al_ffblk — Cross platform structure storing file information.
- AUDIOSTREAM — Stores an audiostream.
- BITMAP — Stores the contents of a bitmap.
- COLOR_MAP — Stores a color map to accelerate drawing.
- COMPILED_SPRITE — Stores the contents of a compiled sprite.
- DATAFILE — Stores an Allegro datafile in memory.
- DIALOG — Stores a GUI description.
- DIALOG_PLAYER — Stores GUI data internally used by Allegro.
- fixed — Fixed point integer to replace floats.
- FONT — Stores an Allegro font.
- GFX_MODE — Stores video mode information.
- GFX_MODE_LIST — Stores an array of GFX_MODE structures.
- JOYSTICK_AXIS_INFO — Stores joystick axis information.
- JOYSTICK_BUTTON_INFO — Stores joystick button information.
- JOYSTICK_INFO — Stores information about joysticks.
- JOYSTICK_STICK_INFO — Stores joystick stick information.
- LZSS_PACK_DATA — Opaque structure for handling LZSS compression.
- LZSS_UNPACK_DATA — Opaque structure for handling LZSS decompression.
- MATRIX — Fixed point matrix structure.
- MATRIX_f — Floating point matrix structure.
- MENU — Stores the entries of a menu.
- MENU_PLAYER — Stores GUI data internally used by Allegro.
- MIDI — Stores MIDI data.
- PACKFILE — Packfile structure, similar to the libc FILE structure.
- PACKFILE_VTABLE — Packfile vtable structure, for custom packfiles.
- PAL_SIZE — Number of entries in a palette.
- PALETTE — Stores palette information.
- QUAT — Stores quaternion information.
- RGB — Single palette entry.
- RGB_MAP — Stores an rgb map to accelerate conversions.
- RLE_SPRITE — Stores the contents of an RLE sprite.
- SAMPLE — Stores sound data.
- V3D — Fixed point vertex structure used by 3d functions.
- V3D_f — Floating point vertex structure used by 3d functions.
- ZBUFFER — Stores 3d zbuffer information.

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 appropriate 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.

> Examples using this: ex12bit, ex3buf, ex3d, excustom, exfixed, exspline, exsprite, exstars, exupdate.

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 that of the clipping API, 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_rect() instead.

> See also: create_bitmap, set_clip_rect, bitmap_color_depth, RLE_SPRITE, COMPILED_SPRITE, Direct access to video memory.

> Examples using this: Available Allegro examples.

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 axes do we
>                                           have? (note the misspelling)
>        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 JOYSTICK_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.

#define PAL_SIZE
Preprocessor constant equal to 256.

> See also: RGB, PALETTE, COLOR_MAP.

typedef PALETTE RGB[PAL_SIZE]
Allegro palettes are arrays of PAL_SIZE RGB entries.

> See also: RGB, Palette routines.

> Examples using this: Available Allegro examples.

typedef struct RGB

>        unsigned char r, g, b;

Palette entry. It contains an additional field for the purpose of padding but you should not usually care about it. Read chapter "Palette routines" for a description on how to obtain/use this structure.

> See also: Palette routines, PALETTE.

> Examples using this: ex12bit, ex3d, excolmap, exconfig, expal, exrgbhsv, exscroll, exshade, extrans, extruec.

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.

> Examples using this: ex3d.

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. Read the description of polygon3d_f() for a description on how to obtain/use this structure.

> See also: V3D, polygon3d_f, Fixed point trig.

> Examples using this: excamera, exscn3d, exzbuf.

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.

> Examples using this: ex3d, excolmap, exlights, exshade, extrans.

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.

> Examples using this: ex3d, excolmap, exrgbhsv, exshade, extrans.

struct al_ffblk

>        int attrib;       - actual attributes of the file found
>        time_t time;      - modification time 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, al_ffblk_get_size.

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.

> Examples using this: excustom, exdata, exexedat, exgui, exsprite, exunicod.

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.

> Examples using this: ex12bit, ex3d, exstars.

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.

> Examples using this: excamera, exquat, exscn3d, exzbuf.

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.

> Examples using this: exquat.

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.

> Examples using this: excustom, exgui, exrgbhsv.

typedef struct MENU

>        char *text;          - the text to display for the menu item
>        int (*proc)(void);   - 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.

> Examples using this: exgui.

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. Read chapter "Fonts" for a description on how to load/destroy fonts, and chapter "Text output" for a description on how to show text.

> See also: font.

> Examples using this: excustom, exfont, exunicod.

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.

> Examples using this: exzbuf.

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
>        void *data;                 - raw sample data

A sample structure, which holds sound data, used by the digital sample routines. You can consider all of these fields as read only except priority, loop_start and loop_end, which you can change them for example after loading a sample from disk.

The priority is a value from 0 to 255 (by default set to 128) and controls how hardware voices on the sound card are allocated if you attempt to play more than the driver can handle. This may be used to ensure that the less important sounds are cut off while the important ones are preserved.

The variables loop_start and loop_end specify the loop position in sample units, and are set by default to the start and end of the sample.

If you are creating your own samples on the fly, you might also want to modify the raw data of the sample pointed by the data field. The sample data are always in unsigned format. This means that if you are loading a PCM encoded sound file with signed 16-bit samples, you would have to XOR every two bytes (i.e. every sample value) with 0x8000 to change the signedness.

> See also: load_sample, Digital sample routines, Voice control.

> Examples using this: exsample.

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).

> Examples using this: exmidi.

typedef struct AUDIOSTREAM

>        int voice;  - the hardware voice used for the sample

A structure holding an audiostream, which is a convenience wrapper around a SAMPLE structure to double buffer sounds too big to fit into memory, or do clever things like generating the sound wave real time.

While you shouldn't modify directly the value of the voice, you can use all of the voice functions in chapter "Digital sample routines" to modify the properties of the sound, like the frequency.

> See also: play_audio_stream, Audio stream routines, Voice control.

> Examples using this: exstream.

typedef struct PACKFILE
A packfile structure, similar to the libc FILE structure. Read chapter "File and compression routines" for a description on how to obtain/use this structure. Note that prior to version 4.1.18, some internal fields were accidentally documented - but PACKFILE should be treated as an opaque structure, just like the libc FILE type.

> See also: File and compression routines, pack_fopen, pack_fopen_chunk, pack_fopen_vtable.

> Examples using this: expackf.

typedef struct PACKFILE_VTABLE

>        int pf_fclose(void *userdata);
>        int pf_getc(void *userdata);
>        int pf_ungetc(int c, void *userdata);
>        long pf_fread(void *p, long n, void *userdata);
>        int pf_putc(int c, void *userdata);
>        long pf_fwrite(const void *p, long n, void *userdata);
>        int pf_fseek(void *userdata, int offset);
>        int pf_feof(void *userdata);
>        int pf_ferror(void *userdata);

This is the vtable which must be provided for custom packfiles, which then can read from and write to wherever you like (eg. files in memory). You should provide all the entries of the vtable, even if they are empty stubs doing nothing, to avoid Allegro (or you) calling a NULL method at some point.

> See also: File and compression routines, pack_fopen_vtable.

> Examples using this: expackf.

typedef struct LZSS_PACK_DATA
Opaque structure for handling LZSS compression. Read chapter "File and compression routines for a description on how to obtain/use this structure.

> See also: File and compression routines, create_lzss_pack_data.

typedef struct LZSS_UNPACK_DATA
Opaque structure for handling LZSS decompression. Read chapter "File and compression routines for a description on how to obtain/use this structure.

> See also: File and compression routines, create_lzss_unpack_data.

Back to contents