In terms of file redistribution, the Windows platform behaves practically the same as the DOS platform. Read section chapter "Dos specifics" in the manual to learn more about this.
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 ALLEGRO_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. See the manual of your compiler for a method to create an ICON resource, or use the wfixicon utility from the tools/win directory.
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.
See also: install_joystick.
Note that, mainly for performance reasons, this driver requires the width of the screen to be a multiple of 4. This driver is capable of displaying a hardware cursor, but there are size restrictions. Typically, the cursor image cannot be more than 32x32 pixels.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 */ }
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 */ }
See also: set_gfx_mode.
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
See also: detect_digi_driver, install_sound, install_sound_input.
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
See also: detect_midi_driver, install_sound, install_sound_input.
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.
However you can also call it after the library has been initialised, provided that no graphics mode is set. In this case the keyboard, mouse, joystick, sound and sound recording modules will be restarted.
Passing NULL instructs Allegro to switch back to its built-in window if an user-created window was registered, or to request a new handle from Windows for its built-in window if this was already in use.
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.
See also: convert_hpalette_to_palette.
See also: convert_palette_to_hpalette.
See also: convert_hbitmap_to_bitmap.
See also: convert_bitmap_to_hbitmap.
See also: blit_to_hdc, stretch_blit_to_hdc, draw_sprite.
See also: draw_to_hdc, stretch_blit_to_hdc, blit_from_hdc, blit.
See also: draw_to_hdc, blit_to_hdc, stretch_blit_from_hdc, stretch_blit.
See also: stretch_blit_from_hdc, blit_to_hdc, blit.
See also: blit_from_hdc, stretch_blit_to_hdc, stretch_blit.