CompressPNG
-----------
The basic usage is:
1. Call CompressPNG_Start with a description of the source image and its
   destination (memory or a file).  This returns a handle for future calls.
2. Call CompressPNG_WriteLine for each line of the source image.
3. Call CompressPNG_Finish to complete the operation.

SWIs
----
CompressPNG_Start                                              SWI &59E00

Begin a PNG stream session.

On entry
   R0 -> output buffer (or 0 to request size)
   R1 =  buffer size
   R2 -> parameter block
         +0 image width (pixels)
         +4 image height (pixels)
         +8 horizontal DPI
        +12 vertical DPI
        +16 flags
            bit 0: R0 points to filename rather than output buffer if set
            bit 1: Alpha channel is present if set
            bit 2: Greyscale source image if set; true colour if clear
            bit 3: Ignore 'A' bytes in source data (no alpha channel but data
                   is in form RGB0 or G0)
        followed by a set of user-defined parameters
         +0 parameter type (see below) or 0 for end of list
         +4 depends on parameter - see below
         +8 depends on parameter - see below

On exit
   R0 = tag value to pass to future calls
   Or V set and R0 -> error block

Possible user-defined parameters:
Type 1: Textual comment for the file as a key/value pair
        as per PNG specifications
+4: pointer to key string
+8: pointer to value string

Type 2 : image gamma value, where 0 > gAMA >= 21474.83
+4: value as an 8 byte floating point 'double'.

Type 3: image compression level
+4: compression level (0-9)
+8: 0 (unused)

Type 4: image interlace
+4: interlace (0 for off or 1 for on)
+8: 0 (unused)

Type 5: palette data for images with <= 256 colours
+4: number of palette entries present (2, 4, 16 or 256)
+8: pointer to palette data as a list of colour values in the form &BBGGRR00

Type 6: transparency information for images with <=256 colours
+4: number of transparency entries (2, 4, 16 or 256).  Must match the
    palette given in type 5.
+8: pointer to alpha level data, one byte per colour, from 255 for opaque
    to 0 for transparent.

Parameter type 1 may occur more than once as there may be multiple text keys
present.

CompressPNG_Comment                                            SWI &59E01

Add a text key/value pair to a PNG stream.

On entry
   R0 = tag value from CompressPNG_Start
   R1 -> key
   R2 -> value

On exit
   Registers preserved
   Or V set and R0 -> error block

This is an alternative way to add a text key/value pair to a PNG rather than
including them all in CompressPNG_Start.  Allows a task to read out from its
writeable fields one at a time instead of having to allocate a new buffer for
the combined set.  For a preset list of things, then just using the
CompressPNG_Start parameters would be better.


CompressPNG_WriteLine                                          SWI &59E02

Adds a line of image data to the PNG.  The data is presented as a stream of
bytes depending on the PNG format selected when the compression was started.

On entry
   R0 = tag value from CompressPNG_Start
   R1 -> row pixel data (see below)

On exit
   Registers preserved
   Or V set and R0 -> error block

24 bit colour:
+0 R (0-255)
+1 G (0-255)
+2 B (0-255)

24 bit colour with alpha channel:
+0 R (0-255)
+1 G (0-255)
+2 B (0-255)
+3 alpha value (0-255)

24 bit colour with 'ignore alpha' flag set:
+0 R (0-255)
+1 G (0-255)
+2 B (0-255)
+3 ignored

8 bit greyscale:
+0 grey level (0-255)

8 bit greyscale with alpha channel:
+0 grey level (0-255)
+1 alpha value (0-255)

8 bit greyscale with 'ignore alpha' flag set:
+0 grey level (0-255)
+1 ignored

If a palette has been requested (parameter type 4 above), the row data consists
of a list of palette values.  There is one byte per pixel.  The resulting
image will have a reduced number of bits per pixel.
+0 palette index (0-255)
The alpha channel is allocated a palette index and replaces any pixels of that
colour.  It is created using the transparency block (parameter type 5 above).


CompressPNG_Finish                                             SWI &59E03

Call to complete the PNG, or used to tidy up if there was an error.
Frees workspace and closes any output file if necessary.

On entry
   R0 = tag value from CompressPNG_Start

On exit
   If outputting to a buffer and a buffer was supplied
   R0 -> output buffer
   R1 = bytes used
   Or V set and R0 -> error block

   If wanting to output to a buffer but 0 was passed to CompressPNG_Start,
   R0 = 0
   R1 = required buffer size
   Or V set and R0 -> error block

   Otherwise all preserved.
