                          ========================
                          = image loader example =
                          ========================


Overview
--------

This example program demonstrates how to load image files to surfaces for use
in PTC and how to convert the loaded images to the pixel format required.




Loading the image
-----------------

>    // load image
>    Surface surface(ptc,"image.tga");
>    if (!surface.ok())
>    {
>        ptc.Close();
>        cout << "could not load image\n";
>        return 1;
>    }

This code creates a surface to load the targa image file "image.tga". Note
that you can also use Surface::Load to load an image to a surface after
creation like so:

    Surface surface;
    .....
    surface.Load(ptc,"image.tga");

Finally, note that when the PTC object is passed to the load function or load
constructor, the surface will be bound to that PTC object. If you wish to load
an image to an unbound surface, then do not pass the PTC object. For example:

    Surface surface;
    .....
    surface.Load("image.tga"); 





Converting the surface
----------------------

>    // convert image
>    if (!surface.Convert(ARGB8888))
>    {
>        // failure
>        ptc.Close();
>        cout << "could not convert image\n";
>        return 1;
>    }

The code above converts the surface pixel format from *whatever* format it is, 
to ARGB8888 format (32bits per pixel). This is done because an image is loaded
in whatever format it exists on disk. If you load a 16bit targa image then
after loading the surface will have that same 16bit pixel format. In this
example, the file "image.tga" is a 24bit targa file. Because PTC doesnt
support fast pixel format conversion from 24bit -> X (instead it uses a slower
general converter routine for all "unsupported" pixel format conversions), it
is best to convert the image to another better supported pixel format such as
RGB565 or ARGB8888.
