Google

Windows specifics



A Windows program that uses the Allegro library is only required to include one or more header files from the include/allegro tree, or allegro.h; however, if it also needs to directly call non portable Win32 API functions, it must include the Windows-specific header file winalleg.h after the Allegro headers, and before any Win32 API header file. By default winalleg.h includes the main Win32 C API header file windows.h. If instead you want to use the C++ interface to the Win32 API (a.k.a. the Microsoft Foundation Classes), define the preprocessor symbol ALLEGRO_AND_MFC before including any Allegro header so that afxwin.h will be included. Note that, in this latter case, the Allegro debugging macros ASSERT() and TRACE() are renamed AL_ASSERT() and AL_TRACE() respectively.

Windows GUI applications start with a WinMain() entry point, rather than the standard main() entry point. Allegro is configured to build GUI applications by default and to do some magic in order to make a regular main() work with them, but you have to help it out a bit by writing END_OF_MAIN() right after your main() function. If you don't want to do that, you can just include winalleg.h and write a WinMain() function. Note that this magic may bring about conflicts with a few programs using direct calls to Win32 API functions; for these programs, the regular WinMain() is required and the magic must be disabled by defining the preprocessor symbol ALLEGRO_NO_MAGIC_MAIN before including Allegro headers.

If you want to build a console application using Allegro, you have to define the preprocessor symbol USE_CONSOLE before including Allegro headers; it will instruct the library to use console features and also to disable the special processing of the main() function described above.

When creating the main window, Allegro searches the executable for an ICON resource named "allegro_icon". If it is present, Allegro automatically loads it and uses it as its application icon. Otherwise, Allegro uses the default IDI_APPLICATION icon.

DirectX requires that system and video bitmaps (including the screen) be locked before you can draw onto them. This will be done automatically, but you can usually get much better performance by doing it yourself: see the acquire_bitmap() function for details.

Due to a major oversight in the design of DirectX, there is no way to preserve the contents of video memory when the user switches away from your program. You need to be prepared for the fact that your screen contents, and the contents of any video memory bitmaps, may be destroyed at any point. You can use the set_display_switch_callback() function to find out when this happens.

On the Windows platform, the only return values for the desktop_color_depth() function are 8, 16, 24 and 32. This means that 15-bit and 16-bit desktops cannot be differentiated and are both reported as 16-bit desktops. See below for the consequences for windowed and overlay DirectX drivers.

Drivers: GFX_*/Windows
The Windows library supports the following card parameters for the set_gfx_mode() function:

  • GFX_TEXT
    This closes any graphic mode previously opened with set_gfx_mode.

  • GFX_AUTODETECT
    Let Allegro pick an appropriate graphics driver.

  • GFX_AUTODETECT_FULLSCREEN
    Autodetects a graphics driver, but will only use fullscreen drivers, failing if these are not available on current platform.

  • GFX_AUTODETECT_WINDOWED
    Same as above, but uses only windowed drivers.

  • GFX_SAFE
    Special driver for when you want to reliably set a graphics mode and don't really care what resolution or color depth you get. See the set_gfx_mode() documentation for details.

  • GFX_DIRECTX
    Alias for GFX_DIRECTX_ACCEL.

  • GFX_DIRECTX_ACCEL
    The regular fullscreen DirectX driver, running with hardware acceleration enabled.

  • GFX_DIRECTX_SOFT
    DirectX fullscreen driver that only uses software drawing, rather than any hardware accelerated features.

  • GFX_DIRECTX_SAFE
    Simplified fullscreen DirectX driver that doesn't support any hardware acceleration, video or system bitmaps, etc.

  • GFX_DIRECTX_WIN
    The regular windowed DirectX driver, running in color conversion mode when the color depth doesn't match that of the Windows desktop. Color conversion is much slower than direct drawing and is not supported between 15-bit and 16-bit color depths. This limitation is needed to work around that of desktop_color_depth() (see above) and allows to select the direct drawing mode in a reliable way on desktops reported as 16-bit: 

       if (desktop_color_depth() == 16) {
      set_color_depth(16);
      if (set_gfx_mode(GFX_DIRECTX_WIN, 640, 480, 0, 0) != 0) {
         set_color_depth(15);
         if (set_gfx_mode(GFX_DIRECTX_WIN, 640, 480, 0, 0) != 0) {
            /* 640x480 direct drawing mode not supported */
            goto Error;
         }
      }
      /* ok, we are in direct drawing mode */
   }

  • GFX_DIRECTX_OVL
    The DirectX overlay driver. It uses special hardware features to run your program in a windowed mode: it doesn't work on all hardware, but performance is excellent on cards that are capable of it. It requires the color depth to be the same as that of the Windows desktop. In light of the limitation of desktop_color_depth() (see above), the reliable way of setting the overlay driver on desktops reported as 16-bit is: 

       if (desktop_color_depth() == 16) {
      set_color_depth(16);
      if (set_gfx_mode(GFX_DIRECTX_OVL, 640, 480, 0, 0) != 0) {
         set_color_depth(15);
         if (set_gfx_mode(GFX_DIRECTX_OVL, 640, 480, 0, 0) != 0) {
            /* 640x480 overlay driver not supported */
            goto Error;
         }
      }
      /* ok, the 640x480 overlay driver is running */
   }

  • GFX_GDI
    The windowed GDI driver. It is extremely slow, but is guaranteed to work on all hardware, so it can be useful for situations where you want to run in a window and don't care about performance. Note that this driver features a hardware mouse cursor emulation in order to speed up basic mouse operations (like GUI operations).

Drivers: DIGI_*/Windows
The Windows sound functions support the following digital soundcards: 

      DIGI_AUTODETECT      - let Allegro pick a digital sound driver
      DIGI_NONE            - no digital sound
      DIGI_DIRECTX(n)      - use DirectSound device #n (zero-based) with
                             direct mixing
      DIGI_DIRECTAMX(n)    - use DirectSound device #n (zero-based) with
                             Allegro mixing
      DIGI_WAVOUTID(n)     - high (n=0) or low (n=1) quality WaveOut device
Drivers: MIDI_*/Windows
The Windows sound functions support the following MIDI soundcards: 

      MIDI_AUTODETECT      - let Allegro pick a MIDI sound driver
      MIDI_NONE            - no MIDI sound
      MIDI_WIN32MAPPER     - use win32 MIDI mapper
      MIDI_WIN32(n)        - use win32 device #n (zero-based)
      MIDI_DIGMID          - sample-based software wavetable player

The following functions provide a platform specific interface to seamlessly integrate Allegro into general purpose Win32 programs. To use these routines, you must include winalleg.h after other Allegro headers.

HWND win_get_window(void);
Retrieves a handle to the window used by Allegro. Note that Allegro uses an underlying window even though you don't set any graphics mode, unless you have installed the neutral system driver (SYSTEM_NONE).

void win_set_window(HWND wnd);
Registers an user-created window to be used by Allegro. This functions must be called *before* initializing the library with allegro_init() or installing the autodetected system driver (SYSTEM_AUTODETECT). It lets you attach Allegro to any already existing window and prevents the library from creating its own, thus leaving you total control over the window; in particular, you are responsible for processing the events as usual (Allegro will automatically monitor a few of them, but will not filter out any of them). You can then use every component of the library (mouse, keyboard, sound, timers and so on) except the graphics subsystem, bearing in mind that some Allegro functions are blocking (e.g readkey() if the key buffer is empty) and thus must be carefully manipulated by the window thread.

void win_set_wnd_create_proc(HWND (*proc)(WNDPROC));
Registers an user-defined procedure to be used by Allegro for creating its window. This function must be called *before* initializing the library with allegro_init() or installing the autodetected system driver (SYSTEM_AUTODETECT). It lets you customize Allegro's window but only by its creation: unlike with win_set_window(), you have no control over the window once it has been created (in particular, you are not responsible for processing the events). The registered function will be passed a window procedure (WNDPROC object) that it must make the procedure of the new window of and it must return a handle to the new window. You can then use the full-featured library in the regular way.

HDC win_get_dc(BITMAP *bmp);
Retrieves a handle to the device context of a DirectX video or system bitmap.

void win_release_dc(BITMAP *bmp, HDC dc);
Releases a handle to the device context of the bitmap that was previously retrieved with win_get_dc().


The following GDI routines are a very platform specific thing, to allow drawing Allegro memory bitmaps onto a Windows device context. When you want to use this, you'll have to install the neutral system driver (SYSTEM_NONE) or attach Allegro to an external window with win_set_window().

There are two ways to draw your Allegro bitmaps to the Windows GDI. When you are using static bitmaps (for example just some pictures loaded from a datafile), you can convert them to DDB (device-dependent bitmaps) with convert_bitmap_to_hbitmap() and then just use Win32's BitBlt() to draw it.

When you are using dynamic bitmaps (for example some things which react to user input), it's better to use set_palette_to_hdc() and blit_to_hdc() functions, which work with DIB (device-independent bitmaps).

There are also functions to blit from a device context into an Allegro BITMAP, so you can do things like screen capture.

All the drawing and conversion functions use the current palette as a color conversion table. You can alter the current palette with the set_palette_to_hdc() or select_palette() functions. Warning: when the GDI system color palette is explicitly changed, (by another application, for example) the current Allegro palette is not updated along with it!

To use these routines, you must include winalleg.h after Allegro headers.

void set_gdi_color_format(void);
Tells Allegro to use the GDI color layout for truecolor images. This is optional, but it will make the conversions work faster. If you are going to call this, you should do it right after initialising Allegro and before creating any graphics.

void set_palette_to_hdc(HDC dc, PALETTE pal);
Selects and realizes an Allegro palette on the specified device context.

HPALETTE convert_palette_to_hpalette(PALETTE pal);
Converts an Allegro palette to a Windows palette and returns a handle to it. You should call DeleteObject() when you no longer need it.

void convert_hpalette_to_palette(HPALETTE hpal, PALETTE pal);
Converts a Windows palette to an Allegro palette.

HBITMAP convert_bitmap_to_hbitmap(BITMAP *bitmap);
Converts an Allegro memory bitmap to a Windows DDB and returns a handle to it. This bitmap uses its own memory, so you can destroy the original bitmap without affecting the converted one. You should call DeleteObject() when you no longer need this bitmap.

BITMAP *convert_hbitmap_to_bitmap(HBITMAP bitmap);
Creates an Allegro memory bitmap from a Windows DDB.

void draw_to_hdc(HDC dc, BITMAP *bitmap, int x, int y);
Draws an entire Allegro bitmap to a Windows device context, using the same parameters as the draw_sprite() function.

void blit_to_hdc(BITMAP *bitmap, HDC dc, int sx, sy, dx, dy, w, h);
Blits an Allegro memory bitmap to a Windows device context, using the same parameters as the blit() function.

void stretch_blit_to_hdc(BITMAP *bitmap, HDC dc, int sx, sy, sw, sh, int dx, dy, dw, dh);
Blits an Allegro memory bitmap to a Windows device context, using the same parameters as the stretch_blit() function.

void blit_from_hdc(HDC hdc, BITMAP *bitmap, int sx, sy, dx, dy, w, h);
Blits from a Windows device context to an Allegro memory bitmap, using the same parameters as the blit() function. See stretch_blit_from_hdc() for details.

void stretch_blit_from_hdc(HDC hcd, BITMAP *bitmap, int sx, sy, sw, sh, int dx, dy, dw, dh);
Blits from a Windows device context to an Allegro memory bitmap, using the same parameters as the stretch_blit() function. It uses the current Allegro palette and does conversion to this palette, regardless of the current DC palette. So if you are blitting from 8 bit mode, you should first set the DC palette with the set_palette_to_hdc() function.