MGL_loadBitmap

Load a lightweight bitmap file from disk.

Declaration

bitmap_t * MGLAPI MGL_loadBitmap(
const char *bitmapName,
ibool loadPalette)

Prototype In

mgraph.h

Parameters

bitmapName | Name of bitmap file to load
loadPalette | True if the palette should also be loaded

Return Value

Pointer to the loaded bitmap file, NULL on error.

Description

Locates the specified bitmap file and loads it into a lightweight bitmap structure. MGL can load any Windows 3.x style bitmap files, including new format bitmap files with colors depths of 15/16 and 32 bits per pixel. Consult the Windows SDK documentation for the format of Windows bitmap files.

If loadPalette is true, the palette values for the bitmap will be loaded into the structure as well (if there is no palette, it will not be loaded), otherwise the palette entry for the bitmap will be NULL. For small bitmaps you can save space by not loading the palette for the bitmap.

When MGL is searching for bitmap files it will first attempt to find the files just be using the filename itself. Hence if you wish to look for a specific bitmap file, you should pass the full pathname to the file that you are interested in. If the filename is a simple relative filename (i.e. MYBMP.BMP), MGL will then search in the BITMAPS directory relative to the path specified in mglpath variable that was passed to MGL_init. As a final resort MGL will also look for the files in the BITMAPS directory relative to the MGL_ROOT environment variable.

If the bitmap file was not found, or an error occurred while reading the bitmap file, this function will return NULL. You can check the MGL_result error code to determine the cause.

The routine allocates a lightweight bitmap structure for holding the bitmap, which loads the bitmap with the minimum memory overheads. You can draw the bitmap on any device context surface using the MGL_putBitmap function, but you don't have the full flexibility of using a full memory device context for the bitmap surface. If you need more control over the bitmap, you can allocate a memory device context to hold the bitmap surface and load the bitmap with the MGL_loadBitmapIntoDC function.

See Also

MGL_unloadBitmap, MGL_availableBitmap, MGL_getBitmapSize, MGL_loadBitmapIntoDC, MGL_saveBitmapFromDC, MGL_putBitmap, MGL_loadBitmapExt

Copyright © 2002 SciTech Software, Inc. Visit our web site at http://www.scitechsoft.com