| Home
| Previous
| Next
| Up

MGL_loadJPEG

Load a JPEG bitmap file from disk.

Declaration

bitmap_t * MGLAPI MGL_loadJPEG(
const char *JPEGName,
int num8BitColors)

Prototype In

mgraph.h

Parameters

JPEGName | Name of JPEG file to load
num8BitColors | Number of colors for 8-bit image, 0 for RGB images, -1 for grayscale

Return Value

Pointer to the loaded JPEG file, NULL on error.

Description

Locates the specified JPEG file and loads it into a lightweight bitmap structure. Because JPEG files are inherently 24-bit, when you load a JPEG file with this function it will always be decoded as a 24-bit RGB bitmap file, unless you set num8BitColors parameter. If the num8BitColors parameter is set to a value other than 0, it causes the JPEG decoder to quantize down to an 8 bits per pixel bitmap with an optimized floyd-steinberg dither (better than the MGL's simple halftone dithering, but the bitmap will contain a custom palette). The number of significant colors in the output image will be set to the value you specify, so you can use this to quantise down to a color table smaller than 8-bits per pixel. To decode as a 24-bit image, simply set this field to 0.

Note that if you set num8BitColors to -1, the JPEG decoder will decode the image as a grayscale bitmap which is faster than decoding the full color image (useful for preview operations etc). Note that images that are decoded as grayscale are 8-bits per pixel with a grayscale color map and should display as true grayscale images in all color depths.

If you wish to load the bitmap as a different color depth or pixel format use the MGL_loadJPEGIntoDC function. The MGL will however properly decode grayscale JPEG files, but they will be loaded as a 24-bit bitmap since the MGL does not natively support grayscale bitmaps.

When MGL is searching for JPEG files it will first attempt to find the files just by using the filename itself. Hence if you wish to look for a specific JPEG 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.JPG”), 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 JPEG file was not found, or an error occurred while reading the JPEG 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 JPEG file, which loads the bitmap with the minimum memory overheads. You can draw the JPEG file on any device context surface using the MGL_putBitmap function, but you don't have the full flexibility of using a 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 data and load the bitmap with the MGL_loadJPEGIntoDC function.

See Also

MGL_unloadBitmap, MGL_availableJPEG, MGL_getJPEGSize, MGL_loadJPEGIntoDC, MGL_saveJPEGFromDC, MGL_putBitmap, MGL_loadJPEGExt

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