New additions :

 SWI CompressJPEG_WriteLineExtended
 => R0 = JPEG tag
    R1 = flag bits :
           0-2  Log2BPP of data being given (0-5)
            3   Palette has double entries (flashing colours included)
            4   24bpp data is in the form &yyxxxxxx (where yy is ignored)
            5   24bpp data is in the form &xxRRGGBB, or &RRGGBBxx instead
                of &xxBBGGRR or &BBGGRRxx.
           6-31 Reserved
    R2 = pointer to data to write
    R3 = pointer to palette data (for Log2BPP 0-3)
    R4 = number of lines to write
    R5 = bytes between each line (for alignment issues)
 <= R2 = new data pointer    
    R4 = number of lines that were not written
 
 This SWI can be used to write a line to a JPEG from a more generic source
 than with CompressJPEG_WriteLine. Example code for Sprite conversion can
 be supplied.
 
 For a Log2BPP of 7, RGB data is provided in RGBRGBRGB... format, making it
 equivilent to that of CompressJPEG_WriteLine. In this mode, the other flags
 have no effect.

 This extended form of WriteLine requires a greater storage space than that
 of the standard operation. In addition to the normal storage space required :
    width*3  extra bytes are required for colour JPEGs
    width    extra bytes are required for monochrome JPEGs


 SWI CompressJPEG_Comment
 => R0 = JPEG tag
    R1 = flag bits :
           0    Data is a string, ignore length and use control termination
                (10 and 9 are accepted as non-control characters)
          1-31  Reserved, must be 0
    R2 = pointer to comment data
    R3 = length of comment data (if b0 clear)
 
 This SWI can be used to add a comment to a JPEG in the process of being
 created. It should be used immediately after CompressJPEG_Start. Comment
 data may contain multiple lines and/or binary data (although this is
 discouraged).
 
 SWI CompressJPEG_Transcode
 => R0 = flag bits :
           0    Generate a progressive JPEG, described by R7
          1-2   Operation on 'unknown elements' :
                 0 copy no additional elements
                 1 copy comments
                 2 undefined
                 3 copy all elements
          3-6   Transformation type :
                 0 no transformation
                 1 flip horizontally
                 2 flip vertically
                 3 rotate 90 degrees clockwise
                 4 rotate 180 degrees
                 5 rotate 90 degrees anticlockwise
                 6 transpose (rotate 90 degrees clockwise + flip horizontally)
                 7 transverse transpose (rotate 90 degrees anticlockwise + flip
                   vertically)
                others reserved
           7    Trim the edges of the output transform
           8    Generate greyscale output
           9    Optimise for a smaller image
    R1 = pointer to original JPEG
    R2 = length of original JPEG
    R3 = pointer to output JPEG buffer
    R4 = length of output JPEG buffer
    R5 = pointer to workspace, or 0 to read the length
    R6 = length of workspace
    R7 = pointer to scan description block, or 0 for simple progressive
         (if R0 bit 0 set) :
           +0  Number of scans present
           <repeated scans>
             +0     components within scan
             +4-+16 component indices
             +20    Spectral selection start (Ss)
             +24    Spectral selection end (Se)
             +28    Approximation high value (Ah)
             +32    Approximation low value (Al)
 
 This SWI is used to transcode a JPEG - that is, convert a JPEG in one form
 to another form. The most common use for this call is to convert a
 multi-pass JPEG into a single-pass JPEG suitable for rendering with the built
 in renderer. For more details about the scan description block, consult the
 Independant JPEG Groups JPEG library version 6b document 'Experts'.

 
Errors:
 Errors use the error base &8183C0 for the core errors, but some errors use
 a base of &81A8C0 :
 &8183c0 : Bad number of bits per pixel passed to CompressJPEG
           The pixel depth of the line is not understood by this version of
           the CompressJPEG module.
 &8183C1 : Bad number of lines passed to CompressJPEG
           Too many lines have been passed to the CompressJPEG module.
 &8183C2 : Bad buffer or workspace block
           Buffers or workspace is not aligned correctly, they overlap, or
           their lengths are too small.
 &8183C3 : Bad width or height
           Width or height are invalid for this version of CompressJPEG.
 &81A880+n : JPEG-specific errors. Not all of these are possible with the
           current version of the module.
         1 : ARITH_NOTIMPL        : Sorry, there are legal restrictions on arithmetic coding
         2 : BAD_ALIGN_TYPE       : ALIGN_TYPE is wrong, please fix
         3 : BAD_ALLOC_CHUNK      : MAX_ALLOC_CHUNK is wrong, please fix
         4 : BAD_BUFFER_MODE      : Bogus buffer control mode
         5 : BAD_COMPONENT_ID     : Invalid component ID %d in SOS
         6 : BAD_DCTSIZE          : IDCT output block size %d not supported
         7 : BAD_IN_COLORSPACE    : Bogus input colorspace
         8 : BAD_J_COLORSPACE     : Bogus JPEG colorspace
         9 : BAD_LENGTH           : Bogus marker length
        10 : BAD_MCU_SIZE         : Sampling factors too large for interleaved scan
        11 : BAD_POOL_ID          : Invalid memory pool code %d
        12 : BAD_PRECISION        : Unsupported JPEG data precision %d
        13 : BAD_SAMPLING         : Bogus sampling factors
        14 : BAD_STATE            : Improper call to JPEG library in state %d
        15 : BAD_VIRTUAL_ACCESS   : Bogus virtual array access
        16 : BUFFER_SIZE          : Buffer passed to JPEG library is too small
        17 : CANT_SUSPEND         : Suspension not allowed here
        18 : CCIR601_NOTIMPL      : CCIR601 sampling not implemented yet
        19 : COMPONENT_COUNT      : Too many color components: %d, max %d
        20 : CONVERSION_NOTIMPL   : Unsupported color conversion request
        21 : DAC_INDEX            : Bogus DAC index %d
        22 : DAC_VALUE            : Bogus DAC value 0x%x
        23 : DHT_INDEX            : Bogus DHT index %d
        24 : DQT_INDEX            : Bogus DQT index %d
        25 : EMPTY_IMAGE          : Empty JPEG image (DNL not supported)
        26 : EOI_EXPECTED         : Didn't expect more than one scan
        27 : FILE_READ            : Input file read error
        28 : FILE_WRITE           : Output file write error --- out of disk space?
        29 : FRACT_SAMPLE_NOTIMPL : Fractional sampling not implemented yet
        30 : HUFF_CLEN_OVERFLOW   : Huffman code size table overflow
        31 : HUFF_MISSING_CODE    : Missing Huffman code table entry
        32 : IMAGE_TOO_BIG        : Maximum supported image dimension is %u pixels
        33 : INPUT_EMPTY          : Empty input file
        34 : INPUT_EOF            : Premature end of input file
        35 : NOTIMPL              : Not implemented yet
        36 : NOT_COMPILED         : Requested feature was omitted at compile time
        37 : NO_BACKING_STORE     : Backing store not supported
        38 : NO_HUFF_TABLE        : Huffman table 0x%02x was not defined
        39 : NO_IMAGE             : JPEG datastream contains no image
        40 : NO_QUANT_TABLE       : Quantization table 0x%02x was not defined
        41 : NO_SOI               : Not a JPEG file: starts with 0x%02x 0x%02x
        42 : OUT_OF_MEMORY        : Insufficient memory (case %d)
        43 : QUANT_COMPONENTS     : Cannot quantize more than %d color components
        44 : QUANT_FEW_COLORS     : Cannot quantize to fewer than %d colors
        45 : QUANT_MANY_COLORS    : Cannot quantize to more than %d colors
        46 : SOF_DUPLICATE        : Invalid JPEG file structure: two SOF markers
        47 : SOF_NO_SOS           : Invalid JPEG file structure: missing SOS marker
        48 : SOF_UNSUPPORTED      : Unsupported JPEG process: SOF type 0x%02x
        49 : SOI_DUPLICATE        : Invalid JPEG file structure: two SOI markers
        50 : SOS_NO_SOF           : Invalid JPEG file structure: SOS before SOF
        51 : TOO_LITTLE_DATA      : Application transferred too few scanlines
        52 : UNKNOWN_MARKER       : Unsupported marker type 0x%02x
        53 : VIRTUAL_BUG          : Virtual array controller messed up
        54 : WIDTH_OVERFLOW       : Image too wide for this implementation
        55 : BAD_DCT_COEF         : DCT coefficient out of range
        56 : BAD_HUFF_TABLE       : Bogus Huffman table definition
        57 : BAD_PROGRESSION      : Invalid progressive parameters Ss=%d Se=%d Ah=%d Al=%d
        58 : BAD_PROG_SCRIPT      : Invalid progressive parameters at scan script entry %d
        59 : BAD_SCAN_SCRIPT      : Invalid scan script at entry %d
        60 : MISMATCHED_QUANT_TABLE : Cannot transcode due to multiple use of quantization table %d
        61 : MISSING_DATA         : Scan script does not transmit all data
        62 : MODE_CHANGE          : Invalid color quantization mode change
        63 : WBUFFER_SIZE         : Workspace buffer passed to JPEG library is too small
 
Bugs/Bad things in CompressJPEG :

 * It's not reentrant. Nothing can take place between calls to
   CompressJPEG_Start and CompressJPEG_Finish. (no CompressJPEG calls anyhow)
   The code that needs changing is the static in start_compress and adding
   some means to free the workspace ones we're done with it.
 * It uses RMA for its workspace. That can't be good.

Fixed things in CompressJPEG :

 *No longer uses 1 as the error number for 'no memory', allocated error block.
 * No longer accepts without question SWIs it doesn't know.
 * (requires CMunge now).

History
-------
30 Dec 1999 0.07 : Original WriteLines specification (WriteLineExtended)
17 Apr 2000 0.08 : Added Comment, bit depth 0 added for ChangeFSI.
14 Oct 2000 0.09 : Error codes returned are now more sensible, and it shouldn't
                   be possible to exit with bad state. Comment now comes before
                   WriteLineExtended.
17 Oct 2000 0.10 : PAD_BEFORE now applies to paletted entries for those sprites
                   that have palettes. That does mean it's non-orthogonal when
                   it comes to processing sprites, but makes sense in Paint
                   (and logically, too)
25 Jul 2002 0.11 : Corrected documentation on size necessary for WriteLine
                   Extended
29 Jul 2002 0.12 : Documented Transcode and error messages.
