This function reads a graphic file into memory. Photon supports the
BMP, GIF, JPG,
PCX, and JPEG file formats, among others.
For a complete list of the currently supported formats, see
<photon/PxImage.h>.

The filename argument specifies the name of the
graphic file to load or query.

The methods argument points to a structure that lets you modify the
behavior of the function.
If this argument is NULL,
the function loads the graphic file specified by
filename.
PxMethods_t is defined as:

Memory allocation/deallocation routines that you supply.
The deallocation routine is called only if the image can't be loaded.
The type can be one of the following:

PX_NORMAL - the memory allocation is unspecific.

PX_IMAGE - the memory allocation is
for the image data.

PX_PALETTE - the memory allocation is for
the palette.

*(*px_error)( char *msg );

An error routine that you supply. The loader calls
this function if it encounters a fatal error while loading
the graphic file. The msg argument is a pointer to
an error-message string.

Note that all memory allocated by the loader is freed
before this function is called.

*(*px_warning)( char *msg );

A warning routine that you supply. The loader calls
this function if it encounters a nonfatal error while
loading the graphic file. The msg argument is a
pointer to a warning-message string.

*(*px_progress)( int percent );

A progress routine that you supply. The loader calls this
function after it loads/decodes a scan line.
The percent argument is a
fixed point number in the following format:

####.####

The upper 16 bits are the whole portion;
the lower 16 bits are the decimal portion.

scale

Not currently used.

transparent

This member is used with the PX_TRANSPARENT flag.
If this flag is set, the transparent color in the image is replaced
by the color specified by transparent.
You should set transparent to be a color that isn't used
in the image.

Once the image is loaded, use
PhMakeTransBitmap()
to create a transparency mask for this color.

colors, ncolors

Used in conjunction with the PX_USECOLORS
flag. The colors argument points to a palette, and
ncolors indicates the number of valid entries in the
palette.

The allocated members of the image structure can be freed by calling
PhReleaseImage()
after setting the image's flag member to indicate which
parts of the image should be freed.
You can then free the PhImage_t structure.
For more information, see
PhImage_t.

This example can use either shared or normal memory. The advantage of using
shared memory is that it takes less time to draw the image. If you're not
using shared memory, increasing the draw buffer size causes more drawing to
be buffered before being sent to the graphics driver; this isn't as
important if you're using shared memory.