Introduction
------------
The ImageFileFileConvert module provides an interface for converting between
different image formats through a simple defined interface. Whilst this
interface may not be perfectly suited to all image formats, it can be
extended through flagged operations to provide greater flexibility and to
allow more functional conversions to be made.

Because ImageFileConvert and ImageFileRender complement one another, it is
recommended that users of one familiarise themselves with the other.
Documentation for ImageFileRender is publically available to Select 2 users.


Caveat
------
This document is NOT complete. It has been provided as a reference from 
the programmers notes. It is expected that this document be embelished
and corrected as faults are found and in order to make it suitable for
general release.


ImageFileConvert_Convert
------------------------
=> R0 = flags for operation :
          b0-7   Reserved for options common to output filetype
          b8-15  Reserved for options common to input filetype
          b16-23 Reserved for options specific to the input/output pair
          b24-31 Reserved
   R1 = conversion requested :
          b0-11  Destination filetype
          b12-15 Reserved, must be 0
          b16-25 Source filetype
          b26-31 Reserved, must be 0
   R2 = pointer to input image data
   R3 = length of input image data
   R4 = pointer to output image buffer, or 0 to read size
   R5 = size of output image buffer, or 0 to read size
   R6 = background colour, or -1 for default (may be ignored by some
        converters)
   R7-R9 = passed to conversion process
<= R5 = size of output image buffer required, or -1 if not known (if R4 = 0
        on entry)
        size of output image buffer used (if R4 not 0 on entry)

This SWI is used to convert an image from one format to another.


Flags common to output type 'Sprite'
------------------------------------
Because sprite is a common type to convert to, a number of flags are defined
as being used for all conversions. 

Bit 0: Create a sprite, rather than a sprite file.
       (this option is provided by the ImageFileConvert module)
Bit 1-7: Reserved


Flags common to input type 'Sprite'
-----------------------------------
Because sprite is a common filetype to convert from, a number of flags are
defined as being used for all conversions.

Bit 8-15: Reserved


ImageFileConvert_MiscOp
-----------------------
=> R0 = flag bits :
          b0-7   Reserved for options common to output filetype
          b8-15  Reserved for options common to input filetype
          b16-23 Reserved for options specific to the input/output pair
          b24-31 Reserved
   R1 = conversion requested :
          b0-11  Destination filetype
          b12-15 Reserved, must be 0
          b16-25 Source filetype
          b26-31 Reserved, must be 0
   R2 = pointer to input image data
   R3 = length of input image data
   R4 = operation type :
          &000-&3FF Reserved for generic operations on all conversions
          &400-&7FF Reserved for operations specific to the output type
          &800-&BFF Reserved for operations specific to the input type
          &C00-&FFF Reserved for operations specific to the input/output
                    pair
          Other     Reserved for future expansion
   R5-R9 = misc op parameters
<= R0-R9 updated by conversion module

This SWI is used to provide miscellaneous operations to obtain information
about the conversion process.


Operations common to the output type 'Sprite'
---------------------------------------------
=> R4 = &400 (Read information)
   R5-R9 undefined
<= R0 = width in pixels of image
   R1 = height in pixels of image
   R2 = bits per pixel in the image
   R3 = image flags :
          Bit   Meaning
           0    Image has a palette (if <8bpp)
           1    Image is colour (otherwise image is greyscale)
           2    Image has alpha channel or mask
          3-5   Interlace type:
                   0   No interlacing
                   1   Adam7 interlacing
                   2   Vertical interlacing
                 other Reserved
          6-31   Reserved
   R4 = x DPI
   R5 = y DPI

This operation reads information about the image which is common to most
bitmap-type operations.


ImageFileConvert_Register
-------------------------
=> R0 = flags (reserved, must be 0)
   R1 = pointer to definition (all will be copied):
          +0 API version (100)
          +4 converter flags
              b0-31  Reserved, must be 0
          +8 converter type :
              b0-11  Destination filetype
              b12-15 Reserved, must be 0
              b16-25 Source filetype
              b26-31 Reserved, must be 0
         +12 pointer to name of converter in form :
              <name><tab><version x.xx><tab><author>
         +16 workspace value for r12
         +20 pointer to conversion routine
         +24 pointer to miscop routine
<= R1 = API version (even if an error occurs)
   All other registers preserved

This SWI is used to register a new converter.
   

ImageFileConvert_Deregister
---------------------------
=> R0 = flags (reserved, must be 0)
   R1 = filetype pair
   R2 = pointer to name to be copied in format :
          <name><tab><version x.xx><tab><author>
<= All registers preserved

This SWI is used to deregister a converter.


ImageFileConvert_EnumerateConverters
------------------------------------
=> R0 = flags (reserved, must be 0)
   R1 = last filetype pair, or -1 for the first call
<= R0 = pointer to renderer definition (read only)
   R1 = this filetype pair, or -1 if no more

This SWI is used to enumerate the currently registered converters.


ImageFileConvert_ConverterInfo
------------------------------
=> R0 = flags (reserved, must be 0)
   R1 = filetype pair
<= R0 = pointer to renderer definition (read only)
   R1 = pointer to renderer name

This SWI is used to read information on a conversion. If no conversion
can be performed for the requested types, an error will be returned.

