ConvertPNG
----------

Developing from the initial PNG module supplied with RISC OS Select release
1, a new module dedicated to converting PNG images to sprites has been
created. This module performs simple conversion of PNG images to standard
RISC OS sprites. For more advanced uses, clients can use the PNG operations
from the PNG module itself without the ConvertPNG module.

SWIs
----
ConvertPNG_Info
=> R0 = flags (all reserved, must be zero)
   R1 = pointer to PNG data
   R2 = length of PNG data
<= R0 = width of PNG
   R1 = height of PNG
   R2 = bit depth (as stored in the PNG, ignoring sBIT chunks)
   R3 = colour type :
          Bit    Meaning if set
           0      Image has palette
           1      Image is colour
           2      Image has alpha channel
           other  reserved
        If bit 0 and bit 1 are clear, the image is greyscale.
   R4 = interlace type :
           0    No interlacing
           1    Adam7 interlacing

This SWI is used to read simple information about a PNG in order to provide
feedback to the user or as an indication of the requirements of an image.
More complex information can be obtained by direct access to the PNG module.

ConvertPNG_CreateSprite
=> R0 = flag bits :
          Bit    Meaning if set
           0     Create sprite area, not sprite
           1     Use the background chunk if provided, or the background
                 colour in R5 if none is provided
          other  reserved, must be zero
   R1 = pointer to PNG data
   R2 = length of PNG data
   R3 = pointer to output sprite buffer, or 0 to read size
   R4 = size of output sprite buffer, or 0 to read size
   R5 = colour (&BBGGRR00) for background, or -1 for default
<= R4 = size of output sprite buffer required (if R3 = 0 on entry)
        size of output sprite buffer used (if R3 not 0 on entry)

This SWI is used to create a sprite from a PNG file. It should usually be
called twice, once to read the memory requirements and again to create the
sprite itself. The space required by the first call may be larger than that
actually used as additional workspace is required for certain conversion
types. R4 on exit from the conversion call will reflect the actual size of
the converted data. The sprite name is undefined and should be set by the
application. Present implementations set the sprite name to '!'. The data
created will be a raw sprite unless bit 1 of the flags is set. Clients
wishing to operate on sprite areas may set bit 1, or to create an area
header to preceed the sprite itself. Clients wishing to merge sprite areas
should ensure that sufficient space exists in the sprite area they are
appending to.
