ImageLib API
============
The following is an overview of ImageLib functions. A lot of it is repeated
in the file h.imagetrans, which also contains detailed function definitions
and data types. It is recommended that you look at that file in parallel with
this one.

NewImage
--------
For each new image, the browser calls the ImageLib function 'NewImage'.

This call should be passed the MIME type of the image (eg "gif", "jpeg",
"x-xbitmap"). At present GIF, JPEG and XBM are handled internally. Anything
else will be farmed out to ChangeFSI, but the user interface will remain the
same.

If you pass a null pointer (not a null string), the library will attempt
to determine the type of image itself. Note that LoadFromCache will not
work if you do this.

You must not attempt to render the image until width is >0.
When this occurs the image is ready to be rendered (at least in part).

This call may fail due to lack of memory (or an invalid type). In this case
it will return a null pointer.

The function returns a pointer to an Image structure (defined in h.imagetrans).
This contains pointers to functions to perform operations on the images, such
as redrawing it, deleting it etc.

A flags integer is specified. Currently, the only flag to worry about is
IMAGE_FAST (defined in h.imagetrans). If set, then imagelib will try and
process and render the image as quickly as possible, possibly at the expense
of image quality or memory.

So, if we've done...
        im = NewImage(0, 0)
we then use im->Render to plot the image, im->Delete to delete the image etc.

All the functions return pointers to _kernel_oserror structures, or NULL
if no error occurred.

Load
----
Call when you have received some more of an image, passing in a pointer to the
newly fetched data. On exit, width and height will be set if the renderer knows
the size of the image yet. If it does, "changed" (if non-NULL) will be filled
to mark the area of the image that has changed since the last call to
LoadImage. Note that a section of the image may change several times during
loading (eg interlaced GIFs). Coordinates start at (0,0) in the bottom left of
the image, and are measured in OS units.

If the changed box returned is "negative", ie ymax<ymin or xmax<xmin, then
you should treat it as marking the area that doesn't need to be redrawn.
eg if the image is 100 pixels high (ie 200 OS units), ymax is 50 and ymin
is 150, then you should redraw the regions (0<=y<50) and (150<=y<200).
This is used in interlaced GIFs, when a new pass is started

Once enough data has been loaded, the 'animated', 'transparent' and
'mutable_mask' fields of the Image structure will be filled in. mutable_mask
is set if an image is both transparent and interlaced.

EndLoad
-------
When you have passed Load all the data, call EndLoad.

Many image formats will not actually be able to do any rendering until EndLoad
has been called.

If an error is returned, or you wish to abort the loading yourself, stop
calling Load, and call EndLoad. You shouldn't call Load again once it has
returned an error.

After calling EndLoad, you can check whether width != -1. If it isn't, the
image is usable, and you can keep it. If width is -1, then the image is
unuseable, and you should Delete it (see below).

Render
------
Plot an image onto the screen at specified co-ordinates and specified scale.
If x_size and y_size are >0, then the image will be scaled to fit the size
specified, otherwise images will be scaled to the percentage specified in
'scale'.

If not all of an image has been fetched yet, then Render will plot as much
of it as possible.

ModeChange
----------
If the screen display has changed (in resolution or colour), then ModeChange
must be called for each Image structure. This will update any mode dependent
features of the image, such as colour translation tables.

BGCol
-----
This will return the approximate colour of an image. Before calling, place
the background the image is being placed upon into bgcol - this will allow
sensible results where the image contains transparent areas.

If bgcol contains -2 on exit, then the image library cannot determine the
colour of the image - use your best guess. Otherwise, the result is a
standard palette word of the form 0xBBGGRR00 where BB, GG, RR are the
Blue, Green and Red components in the range 0-255.

It is important that this is called for a JPEG image with IMAGE_FAST set, as
otherwise the image will not be plotted quickly.

Delete
------
This function will erase all data associated with an image and remove the
Image structure. Call when you have no further use for an image.

NeedRedaw
---------
This function tests if an image needs redrawing because it has changed
(currently, only applies to animated GIFs). If it returns a 1, then the
whole image should be redrawn. Otherwise, no redraw is necessary due
to the image changing. This doesn't guarantee that a redraw will not be
necessary for some other reason, but it is assumed that these redraws
will be picked up by another mechanism.

RegisterFiller
--------------
This applies to animated images only and is used to supply a function which
will be called to fill in the background of the image. The idea here is
to remove flicker that can occur when a redraw happens because the frame
has changed. What used to happen was that the image would be drawn over
by the background and then the new image plotted on top of that. The flicker
occurred because for a small amount of time, just the background is displayed
until the image is plotted over it.

DumpSprite
----------
This call will dump the image, in sprite format, to a file. You should normally
only need to obtain a sprite copy of the file when transferring to another
application, or saving to disc, so this should be sufficient. maxbpp may
be 1,2,4,8,16,32 or -1 for don't care. This may be ignored. However, 16bpp+
images will only be produced on RISC OS 3.5+ machines.


DumpToCache
-----------
This call is intended to dump an Image into a cache file. The format of
the cache file is undefined. On return (if there is no error) you should
check the value of justuseorig. If it is 1, then no cache file has been
saved. Rather than doing "LoadFromCache", just refeed the image the
original data. This will apply to JPEGs, which are not processed prior
to display.

LoadFromCache
-------------
This call should be made immediately after NewImage. It will create
an image from a file previously saved using "DumpToCache".

StartExport
-----------
Note that the export routines are non-reentrant. Once you have called
StartExport, do not call any export routines for any other images
until you have called EndExport. size will be updated to the total
size for the export.

Export
------
This copies the next len bytes of the sprite into the buffer. len is
updated to say how many bytes were transferred. If len is zero
on return, the export is finished.

EndExport
---------
Call this after taking the last chunk of data, or to abort an export.
