Direct GIF plotting
===================
Previous versions of ImageLib handled GIF images by decompressing into a
sprite, holding the sprite in memory  and then plotting the sprite onto the
screen each time it is redrawn. This is because plotting a GIF direct to the
screen could be a time consuming matter and plotting a part of an image (for
example, during a desktop redraw) particularly time consuming, because the
format of GIF images is such that the whole image always needs to be
decompressed - you can't just decompress part of it. However, the
disadvantage of the sprite approach is the large amount of memory that a
sprite can consume.

ImageLib does direct to screen GIF plotting by making use of a module
called Render (see source files render, lzw_comp and lzw_decomp). This is
designed to take a bitstream in (currently, only 8bit data is supported) and
to compress it with an LZW algorithm, storing the compressed data internally.
It can then plot this image screen direct to the screen, by doing 'live' LZW
decompression. The advantage of this over the GIF format is that we can
define blocks of LZW data to be 8 rows of image data. Then whenever we need
to plot a segment of image, we only have to decompress a maximum of 7 lines
of unwanted data before we reach the data we're after. This contrasts with
the GIF format where we have to decompress the image all the way from the
first line.

A 'client' is responsible for generating a bitstream and passing that to
render. The client must also decode the picture and work out the width,
height and various other variables, plus decide if an image is animated.

In the GIF case, the client code is found in the file c.gif_stream. Routines
in gif_stream are called by c.gif which provides the usual ImageLib functions
such as Load, EndLoad, Render and Delete (described in help file 'Overview').

All this may seem unnecessarily complicated, but it is designed with future
expansion in mind - eventually, other image formats will be plotted direct to
screen, via render, so we need this level of abstraction.

Render
======
Slightly different functions are called depending on if the image is animated
or still. It is up to the client to decide which is the case. This is because
the way animated or still images are handled is drastically different.

The direct to screen GIF plotting stores the data in a compressed format,
plotting each row to a single row sprite and then that sprite to the screen.
This has the advantage that the RISC OS sprite handling code will worry
about scaling to the current screen mode, while a single row sprite doesn't
occupy too much memory.

In the case of animated GIFs, speed is quite critical, so it is necessary
to store each frame of the animation as a sprite.

A function is provided for converting what was previously thought to be a
still image into the first frame of an animation. This is useful in the case
of animated GIFs where it's not possible to tell if a file is an animation
until after the first frame has been processed.

Still Images
============
Below is an outline of the functions provided by render for still images.

render_start
------------
Call render_start when you know the width, height and interlace state of an
image. It will return a handle which should be used in all future communication
with render, plus a pointer to memory to start putting the bitstream (the
row buffer).

render_row
----------
Each time a row of data has been put in the row buffer, a call to render_row
will cause it to be compressed. The call will return a pointer to the memory
location to put the next row of data.

render_return_address_for_rgb_data
----------------------------------
render uses flexlib for memory handling. This means that if a block of memory
is allocated or changed in size, other blocks may move around. Therefore, if
this is likely to have happened, a call to render_return_address_for_rgb_data
will return the current location of the row buffer.

render_end
----------
Call this when all rows of the image have been output.

render_delete
-------------
Call this when an image is finished with, to remove it from memory.

render_return_sprite_address
----------------------------
The single row sprite used by render needs to have a palette the same as the
source image. This call returns to the client a pointer to the single row
sprite data in memory, so that it can fill in the palette data.

render_whole_scaled
-------------------
Use this to plot the image on the screen, specifying a pointer to a
scale_factor structure and an x and y co-ordinate. The image will be clipped
to the current graphics window (normally set by the Window Manager before
issuing a redraw request).

render_mode_change
------------------
Call for each image upon a mode change, to regenerate colour translation
tables and possibly some sprites.

Animated Images
===============
The functions for animated images are of a similar form to those of still
images and are detailed below.

render_animate_start
--------------------
Call this before fetching any image data for any frames. You must specify the
screen width and height (that is, the total area occupied by the animation) -
for more details see the GIF89a specification (reference 1 below).

A handle will be returned which should be used in all future communication
with render about this animation.

render_animate_new_frame
------------------------
Before each new frame's image data is fetched, this must be called, specifying
some details about the new frame. The function will return a pointer to memory
where the first row of this frame should be put.

render_animate_row
------------------
After each row, call this function to return a pointer to the location in
memory to put the next row of data.

render_animate_return_spr_address
---------------------------------
In a similar fashion to still images, if the client does something which may
result in flex blocks (of memory) being moved around, it should call this
function to return the pointer to the start of the row of data currently
being output.

render_animate_done_frame
-------------------------
Call this after each frame's image data has been output.

render_animate_add_local_palette
--------------------------------
Call this when you are ready to supply a frame's palette. It will return a
pointer to memory where a 256 entry, 8bytes per entry palette table can be
put.

render_animate_plot
-------------------
Call this to plot the current frame of an animation at the specified location
and with the specified scale. Render keeps track internally of which frame
needs to be shown at any particular time, based on the delays specified in
the source file and passed to it at each render_animate_new_frame.

render_animate_make_animation
-----------------------------
Given the handle of a still image, this function will turn the image into the
first frame of an animation. It will automatically prepare itself for the next
frame, by calling render_animate_next_frame.

render_animate_delete
---------------------
Remove all memory relating to an animation. Call this when an animation is
finished with.

render_animate_redraw
---------------------
Pass a handle of an animation to this function and it will return a 1 if the
animation needs to be redrawn because a new frame should be shown, or a 0
otherwise.

render_register_filler
----------------------
To get around problems with flickering animations, render relys on the client
supplying a function which will fill in the background of a transparent
animation. The browser will supply the client with this function through
the ImageLib function RegisterFiller.

References
==========
1. GIF89a specification: 
   http://members.aol.com/royalef/gif89a.txt
2. GIF animation on the WWW:
   http://members.aol.com/royalef/gifabout.htm
3. GIF/LZW patent issues:
   http://www-cmpo.mit.edu/met_links/resources/LZW_patent.html
   