These 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) when you call install_allegro().
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 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.h. This will include windows.h for you, doing some magic to make it work correctly.
void set_gdi_color_format();
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.