PNG module SWI interfaces
-------------------------

The PNG module SWI interfaces have been described in the main documentation
for the module itself. It is recommended that clients use the C PNG library
to manipulate PNG files. However, for those authors wishing to use other
languages, the SWI bindings for the API are discussed here. This file is not
intended as a guide to using the PNG library; refer to the libPNG
documentation for more details.


PNG_Signature
-------------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call handles checking the signature of the PNG file.

Reason  Name and registers

0       png_set_sig_bytes
        R1 = pointer to PNG read structure to update
        R2 = number of signature bytes which have been skipped
        Returns none.
        This call is used to inform the library that some data has been
        skipped from the start of the file.

1       png_sig_cmp
        R1 = pointer to start of file
        R2 = number of bytes into file to start at
        R3 = number of bytes to read
        Returns 1 if the data supplied does not match the signature, or 0
        if the data supplied does match.
        This call is used to check whether the signature is correct for
        a PNG.

2       png_check_sig
        R1 = pointer to start of file
        R2 = number of bytes to check
        Returns 1 if the signature matches that of a PNG file, 0 if the data
        does not match; that is, the return state is the reverse of that in
        png_sig_cmp.


PNG_Structure
-------------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call manipulates the core PNG structures used for conversion of
files.

Reason  Name and registers

0       png_create_read_struct
        R1 = pointer to expected PNG library version string
        R2 = pointer to opaque value to pass to warning and error functions
        R3 = pointer to function to call for error handling
        R4 = pointer to function to call for warning handling
        Returns pointer to a read structure
        This call is used to create a structure for reading data from a PNG
        file.

1       png_create_write_struct
        R1 = pointer to expected PNG library version string
        R2 = pointer to opaque value to pass to warning and error functions
        R3 = pointer to function to call for error handling
        R4 = pointer to function to call for warning handling
        Returns pointer to a write structure
        This call is used to create a structure for writing data to a PNG
        file.

2       png_destroy_read_struct
        R1 = pointer to a pointer to the PNG read structure to destroy
        R2 = pointer to a pointer to the PNG information structure to destroy
        R3 = pointer to a pointer to the PNG 'end information' structure to
             destroy
        Returns nothing
        This call is used to destroy a structure used for reading a PNG
        file.
        Usually reason 4 will be used in preference to this call from
        languages other than C .

3       png_destroy_write_struct
        R1 = pointer to a pointer to the PNG write structure to destroy
        R2 = pointer to a pointer to the PNG information structure to destroy
        Returns nothing
        This call is used to destroy a structure used for writing a PNG
        file.
        Usually reason 5 will be used in preference to this call from
        languages other than C.

4       png_destroy_read_struct_noptr
        R1 = pointer to a pointer to the PNG read structure to destroy
        R2 = pointer to a pointer to the PNG information structure to destroy
        R3 = pointer to a pointer to the PNG 'end information' structure to
             destroy
        Returns nothing
        This call is used to destroy a structure used for reading a PNG
        file.
        Usually reason 4 will be used in preference to this call from
        languages other than C .

5       png_destroy_write_struct_noptr
        R1 = pointer to the PNG write structure to destroy
        R2 = pointer to the PNG information structure to destroy
        Returns nothing
        This call is used to destroy a structure used for writing a PNG
        file.
        Usually reason 5 will be used in preference to this call from
        languages other than C.

6       png_create_read_struct_2
        R1 = pointer to expected PNG library version string
        R2 = pointer to opaque value to pass to warning and error functions
        R3 = pointer to function to call for error handling
        R4 = pointer to function to call for warning handling
        R5 = pointer to opaque value to pass to memory handling functions
        R6 = pointer to function to call to allocate memory
        R7 = pointer to function to call to free memory
        Returns pointer to a read structure
        This call is used to create a structure for reading data from a PNG
        file with special functions available for memory management.
        This entry may not be available on all versions of the module.

7       png_create_write_struct_2
        R1 = pointer to expected PNG library version string
        R2 = pointer to opaque value to pass to warning and error functions
        R3 = pointer to function to call for error handling
        R4 = pointer to function to call for warning handling
        Returns pointer to a write structure
        This call is used to create a structure for writing data to a PNG
        file with special functions available for memory management.
        This entry may not be available on all versions of the module.


PNG_Chunk
---------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call operates on raw chunks being written to the PNG file.

Reason  Name and registers

0       png_write_chunk
        R1 = pointer to PNG write structure
        R2 = pointer to chunk name
        R3 = pointer to data to write
        R4 = length of data to write
        Returns none.
        This call is used to write a raw chunk to a PNG. It is intended for
        advanced users only.

1       png_write_chunk_start
        R1 = pointer to PNG write structure
        R2 = pointer to chunk name
        R3 = total length of data
        Returns none.
        This call is used to start writing a chunk to a PNG. It is intended
        for advanced users only.

2       png_write_chunk_data
        R1 = pointer to PNG write structure
        R2 = pointer to data to write
        R3 = length of data
        Returns none.
        This call is used to write data to a chunk started with a
        png_write_chunk_start call. It is intended for advanced users only.

3       png_write_chunk_end
        R1 = pointer to PNG write structure
        Returns none.
        This call is used to end writing to a chunk started with
        png_write_chunk_start. It is intended for advanced users only.


PNG_Info
--------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call manipulates information structures within a PNG session.

Reason  Name and registers

0       png_create_info_struct
        R1 = pointer to core PNG structure (read or write)
        Returns pointer to information structure.
        This call is used to create an information structure used to provide
        information on the chunks within the PNG being manipulated.

1       png_destroy_info_struct
        R1 = pointer to core PNG structure (read or write)
        R2 = pointer to a pointer to information structure to destroy
        Returns none.
        This call is used to destroy an information structure. Usually
        reason 2 will be used in preference to this call from languages
        other than C.

2       png_destroy_info_struct_noptr
        R1 = pointer to core PNG structure (read or write)
        R2 = pointer to information structure to destroy
        Returns none.
        This call is used to destroy an information structure.
        
3       png_write_info
        R1 = pointer to PNG write structure
        R2 = pointer to information structure to write
        Returns none.
        This call is used to write all data cached in the information structure
        to the PNG file.
        
4       png_read_info
        R1 = pointer to PNG read structure
        R2 = pointer to information structure to read into
        Returns none.
        This call is used to read all data cached in the information structure
        to the PNG file.


PNG_Time
--------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call manipulates informaion structures within a PNG session.

Reason  Name and registers

0       png_convert_to_rfc1123
        R1 = pointer to core PNG structure
        R2 = pointer to PNG time strcuture (as returned from png_get_tIME)
        Returns pointer to RFC 1123 format time string.
        This call is used to convert a PNG time structure into a readable
        RFC 1123 format time string.

1       png_convert_from_struct_tm
        R1 = pointer to PNG time structure (to fill in)
        R2 = pointer to 'struct tm' to fill in
        Returns none.
        This call is used to convert from a 'struct tm' decoded structure
        into a PNG time structure.

2       png_convert_from_time_t
        R1 = pointer to PNG time structure to fill in
        R2 = pointer to time_t data to convert
        Returns none.
        This call is used to convert a time_t structure to a PNG time
        structure.


PNG_Set
-------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call sets up PNG conversion structure information to allow conversion
in different ways.

Reason  Name and registers

0       png_set_expand
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that the output data should be in 24bit
        RGB or 8bit grayscale, with alpha channel if available.

1       png_set_gray_1_2_4_to_8
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that grayscale output should be expanded
        to 8bit, with alpha channel if available.

2       png_set_palette_to_rgb
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that paletted images should be expanded
        to 24bit RGB.

3       png_set_tRNS_to_alpha
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that tRNS chunks should be expanded to
        provide an alpha channel.

4       png_set_bgr
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that the output data should be in the
        order blue, green red rather than red, green, blue.

5       png_set_gray_to_rgb
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that a grayscale image should be
        converted to RGB colour.

6       png_set_rgb_to_gray
        R1 = pointer to PNG structure
        R2 = action to perform on errors :
               1 = silently do the conversion
               2 = issue warnings where the conversion is impure (non-grayscale
                   source)
               3 = issue errors and abort where the conversion is impure.
        R3 = fixed point (16.16) weight of red component
        R4 = fixed point (16.16) weight of green component
        Returns none.
        This call is used to indicate that an RGB image should be converted
        to grayscale.

7       png_set_strip_alpha
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that alpha channel should be stripped
        from the output data.

8       png_set_swap_alpha
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that the alpha channel should preceed
        the image data, rather than follow it.

9       png_set_invert_alpha
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that the alpha channel should be 
        inverted in sense before being stored.

10      png_set_filler
        R1 = pointer to PNG structure
        R2 = byte to fill with
        R3 = PNG_FILLER_BEFORE to place filler byte before the image data
             PNG_FILLER_AFTER to place filler byte after the image data
        Returns none.
        This call is used to indicate that the output data should be
        preceeded or followed by a filler byte. The filler byte allows the
        output data to be padded to 4 bytes from 3 which may be necessary
        for certain file formats (for example Sprites).

11      png_set_swap
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that 16bit data should be returned
        in little-endian format, rather than big-endian.

12      png_set_packing
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that data should be output as 1 byte
        per pixel.

13      png_set_packswap
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that data should be output packed in
        the opposite bit order for low depths (1, 2 or 4 bits per pixel)

14      png_set_shift
        R1 = pointer to PNG structure
        R2 = pointer to structure indicating significant bits :
               +0 = red component significant bits
               +1 = green component significant bits
               +2 = blue component significant bits
               +3 = grayscale component significant bits
               +4 = alpha channel component significant bits
        Returns none.
        This call is used to indicate that the data output data should be
        shifted down so that the significant bits indicated by the structure
        are only seen in each byte.

15      png_set_interlace_handling
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that the client understands the
        interlace format and will supply data in a manner suitable for
        providing interlace data. It is intended for advanced users only.

16      png_set_invert_mono
        R1 = pointer to PNG structure
        Returns none.
        This call is used to indicate that monochrome files are to
        be inverted.

17      png_set_background
        R1 = pointer to PNG structure
        R2 = pointer to background colour structure :
                +0 = index of background colour for paletted files
                +2 = red component of background of RGB files
                +4 = green component of background of RGB files
                +6 = blue component of background of RGB files
                +8 = gray component of background of grayscale files
        R3 = PNG_BACKGROUND_GAMMA_FILE if the background supplied uses the
             files gamma
             PNG_BACKGROUND_GAMMA_SCREEN if the background supplied uses the
             screen gamma
             PNG_BACKGROUND_GAMMA_UNIQUE if the background supplied uses the
             gamma level supplied
        R4 = 1 if the colour specified is in the original images colour space
             (for example if supplying a gray component as the background,
             but the output format is RGB)
        R5 = fixed point (16.16) gamma correction
        Returns none.
        This call is used to indicate that a background colour should be
        applied to the image, merging alpha channel or tRNS data with it.

18      png_strip_16
        R1 = pointer to PNG strucuture
        Returns none.
        This call is used to indicate that processing should reduce 16 bit
        input data to 8 bit.
        
19      png_set_dither
        R1 = pointer to PNG structure
        R2 = pointer to palette containing the destination colours :
               +0  padding
               +1  red component
               +2  green component
               +3  blue component
             repeated for R3 entries
        R3 = number of palette entries supplied in the palette
        R4 = maximum number of palette entries available
        R5 = pointer to histogram data for palette :
               +0  usage of the first colour in the palette
               +4  usage of the second colour in the palette
               ...
        R6 = 1 if dithering should be performed, or just palette reduction
        Returns none.
        This call is used to generate a palette suitable for dithering and
        indicate that dithering should be used on the output image. If the
        colours in the palette exceed the maximum requested, the palette
        will be modified to reduce the number of colours to the maximum.

20      png_set_gamma
        R1 = pointer to PNG structure
        R2 = fixed point (16.16) screen gamma
        R3 = fixed point (16.16) file gamma
        Returns none.
        This call is used to indicate the gamma to be used on generating the
        output image. 

21      png_set_flush
        R1 = pointer to PNG structure
        R2 = number of rows to flush after
        Returns none.
        This call is used to indicate that output should be flushed after a
        number of rows have been specified.



PNG_Compression
---------------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call controls the compression and related information and the storage
of the file.

Reason  Name and registers

0       png_set_crc_action
        R1 = pointer to PNG structure
        R2 = action to take on errors in critical chunks :
                 PNG_CRC_NO_CHANGE  = don't modify current behaviour
                 PNG_CRC_WARN_USE   = warn, but use chunk
                 PNG_CRC_QUIET_USE  = ignore, but use chunk
                 PNG_CRC_ERRUR_QUIT = generate error and terminate
        R3 = action to take on errors in ancillary chunks :
                 PNG_CRC_NO_CHANGE  = don't modify current behaviour
                 PNG_CRC_WARN_USE   = warn, but use chunk
                 PNG_CRC_WARN_DISCARD = warn and discard chunk
                 PNG_CRC_ERRUR_QUIT = generate error and terminate
        Returns none.
        This call controls the action to be taken when CRC errors are
        encountered within the PNG file.

1       png_set_filter
        R1 = pointer to PNG structure
        R2 = filter method (presently 0)
        R3 = filter types to use (to be cobined with an OR operation) :
                 PNG_FILTER_NONE   = No filtering
                 PNG_FILTER_SUB    = Difference between pixel to left
                 PNG_FILTER_UP     = Difference between pixel above
                 PNG_FILTER_AVG    = Difference between average of above and
                                     left
                 PNG_FILTER_PAETH  = Paeth predictor of left, above and
                                     above left
        Returns none.
        This call selects the filters which will be applied to the rows of the
        PNG.

2       png_set_filter_heuristics_int
        R1 = pointer to PNG structure
        R2 = heuristic method :
               PNG_FILTER_HEURISTIC_UNWEIGHTED
               PNG_FILTER_HEURISTIC_WEIGHTED
        R3 = number of weights supplied
        R4 = pointer to integer values for weights of each filter
        R5 = pointer to integer values for costs of each filter
        Returns none.
        This call is used to manipulate the weightings for the use of each
        filter type within rows of a PNG. Weightings are used to indicate how
        important it is to keep the filter type consistent between rows.
        Costs are used to indicate how expensive the cost of a particular
        filter is for decoding. Filters with lower costs are thus less
        intensive of decompression.
        Integer values are signed fixed point 16.16 values.

3       png_set_filter_heursitics
        R1 = pointer to PNG structure
        R2 = heuristic method :
               PNG_FILTER_HEURISTIC_UNWEIGHTED
               PNG_FILTER_HEURISTIC_WEIGHTED
        R3 = number of weights supplied
        R4 = pointer to floating point values for weights of each filter
        R5 = pointer to floating point values for costs of each filter
        Returns none.
        This call is a floating point version of reason 2.

4       png_set_compressiong_level
        R1 = pointer to PNG structure
        R2 = compression level
        Returns none.
        This call is used to set the level of compression that will be used
        when writing the file.

5       png_set_compression_mem_level
        R1 = pointer to PNG structure
        R2 = memory level
        Returns none.
        This call is used to set the amount of memory that will be used when
        compressing the file.

6       png_set_compression_strategy
        R1 = pointer to PNG structure
        R2 = strategy
        Returns none.
        This calls is used to set the compression strategy that will be used.

7       png_set_window_bits
        R1 = pointer to PNG structure
        R2 = window bits
        Returns none.
        This calls is used to set the size of the compression window as a power
        of 2.
        
8       png_set_compression_method
        R1 = pointer to PNG structure
        R2 = method
        Returns none.
        This calls is used to set the method that will be used to compress
        the file.



PNG_GetChunkInfo
----------------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call reads information from chunks in the PNG file.

Reason  Name and registers
        
0       png_get_bKGD
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = pointer to colour structure to return in :
                        +0 = index of background colour for paletted files
                        +2 = red component of background of RGB files
                        +4 = green component of background of RGB files
                        +6 = blue component of background of RGB files
                        +8 = gray component of background of grayscale files
        This call reads the 'bKGD' chunk from a file, if present.

1       png_get_cHRM
        This call is not presently suppported

2       png_get_gAMA
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = fixed point (16.16) gamma value
        This call reads the 'bKGD' chunk from a file, if present.

3       png_get_hIST
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = pointer to histogram data
        This call reads the 'hIST' chunk from a file, if present.

4       png_get_IHDR
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = width of sprite
                R2 = height of sprite
                R3 = bit depth
                R4 = colour type
                R5 = interlace type
                R6 = compression type
                R7 = filter type
        This call reads the 'IHDR' chunk from a file, if present.

5       png_get_oFFs
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = offset x
                R2 = offset y
                R3 = unit type
        This call reads the 'oFFs' chunk from a file, if present.

6       png_get_pCAL
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = pointer to purpose
                R2 = X0
                R3 = X1
                R4 = type
                R5 = number of parameters
                R6 = pointer to units
                R7 = pointer to pointer to params
        This call reads the 'pCAL' chunk from a file, if present.

7       png_get_pHYs
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = x resolution
                R2 = y resolution
                R3 = unit type
        This call reads the 'pHYs' chunk from a file, if present.

8       png_get_PLTE
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = pointer to palette
                R2 = number of entries in the palette
        This call reads the 'PLTE' chunk from a file, if present.

9       png_get_sBIT
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = pointer to palette
                R2 = number of entries in the palette
        This call reads the 'sBIT' chunk from a file, if present.

10      png_get_sRGB
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = intent
        This call reads the 'sRGB' chunk from a file, if present.

11      png_get_text
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = pointer to text chunks
                R2 = number of text chunks
        This call reads the 'text' chunk from a file, if present.

12      png_get_tIME
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = pointer to tIME chunk
        This call reads the 'tIME' chunk from a file, if present.

13      png_get_tRNS
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns R0 = 1 if the chunk was present, 0 if not.
                R1 = pointer to translation bytes
                R2 = number of translation entries
                R3 = pointer to translation values
        This call reads the 'tRNS' chunk from a file, if present.


PNG_SetChunkInfo
----------------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call writes information to chunks in the PNG file.

Reason  Name and registers
        
0       png_set_bKGD
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to colour structure to return in :
                +0 = index of background colour for paletted files
                +2 = red component of background of RGB files
                +4 = green component of background of RGB files
                +6 = blue component of background of RGB files
                +8 = gray component of background of grayscale files
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'bKGD' chunk.

1       png_set_cHRM
        This call is not presently suppported

2       png_set_gAMA
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = fixed point (16.16) gamma value
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'bKGD' chunk.

3       png_set_hIST
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to histogram data
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'hIST' chunk.

4       png_set_IHDR
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = width of sprite
        R4 = height of sprite
        R5 = bit depth
        R6 = colour type
        R7 = interlace type
        R8 = compression type
        R9 = filter type
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'IHDR' chunk.

5       png_set_oFFs
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = offset x
        R4 = offset y
        R5 = unit type
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'oFFs' chunk.

6       png_set_pCAL
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to purpose
        R4 = X0
        R5 = X1
        R6 = type
        R7 = number of parameters
        R8 = pointer to units
        R9 = pointer to pointer to params
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'pCAL' chunk.

7       png_set_pHYs
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = x resolution
        R4 = y resolution
        R5 = unit type
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'pHYs' chunk.

8       png_set_PLTE
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to palette
        R4 = number of entries in the palette
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'PLTE' chunk.

9       png_set_sBIT
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to palette
        R4 = number of entries in the palette
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'sBIT' chunk.

10      png_set_sRGB
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = intent
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'sRGB' chunk.

11      png_set_sRGB_gAMA_and_cHRM
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = intent
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'sRGB', 'gAMA', and 'cHRM' chunks.

12      png_set_text
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to text chunks
        R4 = number of text chunks
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'text' chunk.

13      png_set_tIME
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to tIME chunk
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'tIME' chunk.

14      png_set_tRNS
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to translation bytes
        R4 = number of translation entries
        R5 = pointer to translation values
        Returns 1 if the chunk was present, 0 if not.
        This call sets the 'tRNS' chunk.

15      png_set_text
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to text chunks
        R4 = number of text chunks
        Returns 1 if the chunk was present, 0 if not.
        This call sets one the element in the 'text' chunk.


PNG_Functions
-------------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call controls the callback functions that will be used whilst
processing the PNG file.

Reason  Name and registers

0       png_set_error_fn
        R1 = pointer to PNG structure
        R2 = private value to pass to error functions
        R3 = pointer to function to call for errors
        R4 = pointer to function to call for warnings
        Returns none.
        This call sets the functions that are called for errors and warnings.
        Note: These functions are not presently called.

1       png_get_error_ptr
        R1 = pointer to PNG structure
        Returns private value for error functions.
        This call retrieves the private value used for error functions.

2       png_set_write_fn
        R1 = pointer to PNG structure
        R2 = private value to pass to I/O functions
        R3 = pointer to function to write data to stream
        R4 = pointer to function to flush data to stream
        Returns none.
        This call sets the functions that are called to write data to a
        stream.

3       png_set_read_fn
        R1 = pointer to PNG structure
        R2 = private value to pass to I/O functions
        R3 = pointer to function to read data from stream
        Returns none.
        This call sets the function that is called to read data from
        a stream.

4       png_get_io_ptr
        R1 = pointer to PNG structure
        Returns private value for I/O functions.
        This call retreives the private value used for I/O functions.

5       png_set_read_status_fn
        R1 = pointer to PNG structure
        R2 = pointer to function to call for to give information about
             read progress
        Returns none.
        This call sets the function that will be called when rows are
        complete.

6       png_set_write_status_fn
        R1 = pointer to PNG structure
        R2 = pointer to function to call for to give information about
             write progress
        Returns none.
        This call sets the function that will be called when rows are
        complete.

7       png_set_read_user_transform_fn
        R1 = pointer to PNG structure
        R2 = pointer to function to call to perform transformation on data
             after decoding
        Returns none.
        This call sets the function that will be used to transform image
        data after the other transformations have been performed when
        reading PNGs.

8       png_set_write_user_transform_fn
        R1 = pointer to PNG structure
        R2 = pointer to function to call to perform transformation on data
             before encoding
        Returns none.
        This call sets the function that will be used to transform image
        data before other transformations are performed when creating PNGs.

9       png_set_user_transform_info
        R1 = pointer to PNG structure
        R2 = private value to pass to transformation functions
        R3 = depth transform converts to (ignored for read operations)
        R4 = channels transform converts to (ignored for read operations)
        Returns none.
        This call sets the values that will be passed to the transformation
        functions and informs the library of the depth and channels that the
        data will be produced in for write operations.

10      png_get_user_transform_ptr
        R1 = pointer to PNG structure
        Returns private value for transformation functions.
        This call retrieves the private value used for transformations.

11      png_set_progressive_read_fn
        R1 = pointer to PNG structure
        R2 = private value to pass to progressive functions
        R3 = pointer to function to call for information about progress
        R4 = pointer to function to call when a row decoding completes
        R5 = pointer to function to call when the image decoding completes
        Returns none.
        This call is used to set the functions that will be used during
        progressive image decoding.

12      png_get_progressive_ptr
        R1 = pointer to PNG structure
        Returns private value used for progressive operations.
        This call retrieves the private value used in progressive
        operations.

13      png_init_io
        R1 = pointer to PNG structure
        R2 = pointer to file handle (as returned by OS_Find)
        Returns none.
        This call sets the file to be used for I/O operations.

14      png_set_memory_fn
        R1 = pointer to PNG structure
        R2 = pointer to input data
        R3 = length of input data block
        R4 = pointer to output data
        R5 = length of output data block
        Returns none.
        This call sets up an area of memory to be used for data input or
        output.

15      png_get_warning
        R1 = pointer to PNG structure
        Returns a pointer to the next warning, or 0 if no more warnings.
        This call extracts the next warning. By default, warnings are cached
        in memory when they occur and can be extracted after the file
        conversion has completed. This allows warnings to be buffered without
        a warning handler.

16      png_set_mem_fn
        R1 = pointer to PNG structure
        R2 = private value for memory allocation routines
        R3 = pointer to function to allocate memory
        R4 = pointer to function to free memory
        Returns none.
        This call sets the functions to use for memory handling.
        This entry may not be available on all versions of the module.

17      png_get_mem_ptr
        R1 = pointer to PNG structure
        Returns private value for memory handling
        This call retrieves the private value used for memory handling.
        This entry may not be available on all versions of the module.


PNG_Greyscale
-------------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call handles greyscale PNGs.

Reason  Name and registers

0       png_get_rgb_to_gray_status
        R1 = pointer to PNG structure
        Returns 0 if the image contained grayscale data
                1 if the image contained non-grayscale data
        This call returns information about the status of
        png_set_rgb_to_gray after processing the image.
        
1       png_build_grayscale_palette
        R1 = bit depth
        R2 = pointer to palette data to create
        Returns none.
        This call generates a grayscale palette in the block supplied.



PNG_Process
-----------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call controls the processing of PNG files.

Reason  Name and registers

0       png_permit_empty_plte
        R1 = pointer to PNG structure
        R2 = 1 if empty PLTE chunks are allowed 
             0 if empty PLTE chunks are not allowed
        Returns none.
        This call indicates that empty PLTE chunks are allowed.
        
1       png_write_flush
        R1 = pointer to PNG structure
        Returns none.
        This call flushes the output stream of any pending data.
        
2       png_start_read_image
        R1 = pointer to PNG structure
        Returns none.
        This call starts the PNG decoding process.
        
3       png_read_update_info
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns none.
        This call updates the colour information structures after selections
        have been made for the conversion type.
        
4       png_read_rows
        R1 = pointer to PNG structure
        R2 = pointer to an array of pointers to output data
             (for writing data to)
        R3 = pointer to an array of pointers to output data scanlines
             (to update with details from the decoded scanlines)
        R4 = number of rows to process
        Returns none.
        This call converts a number of rows at a time. R3 may be set to
        0 if you do not wish to display the image between scans. R2 may
        be set to 0 if you wish to use the image between scans. Refer to
        libpng documentation for details.
        
5       png_read_row
        R1 = pointer to PNG structure
        R2 = pointer to output data
        R3 = pointer to output data scanlines
        Returns none
        This call does a similar process to that in reason 4, but only
        a single line is processed.
        
6       png_read_image
        R1 = pointer to PNG structure
        R2 = pointer to an array of pointers to output data
        Returns none.
        This call processes the entire image, writing the output to the
        locations pointed to by the array of pointers.
        
7       png_write_row
        R1 = pointer to PNG structure
        R2 = pointer to row to write
        Returns none.
        This call writes a row to the PNG.
        
8       png_write_rows
        R1 = pointer to PNG structure
        R2 = pointer to an array of pointers to data to write
        R3 = number of rows to write
        Returns none.
        This call writes a number of rows to a PNG.
        
9       png_write_image
        R1 = pointer to PNG structure
        R2 = pointer to an array of pointers to data to write
        Returns none.
        This call writes an entire image worth of rows to a PNG.
        
10      png_write_end
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure for remaining chunks
        Returns none.
        This call terminates the writing process and flushes data to the
        output stream.
        
11      png_read_end
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns none.
        This call finishes reading the file and updates the information
        structure with any additional information which was stored after
        the image data.
        
12      png_process_data
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = pointer to data to supply to the decoder
        R4 = size of data supplied
        Returns none.
        This call processes the data supplied to it and then returns.
        
13      png_progressive_combine_row
        R1 = pointer to PNG structure
        R2 = pointer to decoded row
        R3 = pointer to destination row for combine
        Returns none.
        This call merges the output from a row being processed with that
        already present.
        


PNG_Memory
----------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call allows access to the memory handling functions of the PNG
library. It is intended for advanced users and those trying to port code
from other systems only.

Reason  Name and registers

0       png_malloc
        R1 = pointer to PNG structure
        R2 = size to allocate
        Returns pointer to the memory allocated.
        This call allocates memory.
        
1       png_free
        R1 = pointer to PNG structure
        R2 = pointer to memory to free
        Returns none.
        This call frees memory previously allocated by png_malloc.
        
2       png_memcpy_check
        R1 = pointer to PNG structure
        R2 = pointer to destination
        R3 = pointer to source
        R4 = size of data to copy
        Returns none.
        This call copies a block of memory. It is much more efficient to do
        this yourself.
        
3       png_memset_check
        R1 = pointer to PNG structure
        R2 = pointer to block to initialise
        R3 = value to initialise with
        R4 = size of memory to initailise
        Returns none.
        This call initialises a block of memory.
        


PNG_GetInfo
-----------
=> R0 = reason code
   other registers dependant on the reason code
<= dependant on the reason code

This SWI call returns information about the PNG file.

Reason  Name and registers

0       png_get_valid
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        R3 = PNG chunk name
        Returns 1 if the image contains the given chunk.
                0 if the image does not contain the given chunk
        This call checks whether a chunk is valid for the file; that is,
        whether the chunk exists.
        
1       png_get_rowbytes
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the number of bytes necessary to hold a row.
        This call returns the number of bytes which are needed to hold a
        row of data
        
2       png_get_channels
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the number of channels
        This call returns the number of channels of data supplied in the image.
        
3       png_get_image_width
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the width of the image.
        This call returns the width of the image.
        
4       png_get_image_height
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the height of the image.
        This call returns the height of the image.
        
5       png_get_bit_depth
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the bit depth.
        This call returns the bit depth of the image
        
6       png_get_color_type
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the colour type of the image.
        This call returns the colour type of the image.
        
7       png_get_filter_type
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the filter type of the image.
        This call returns the filter type of the image.
        
8       png_get_interlace_type
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the interlace type of the image.
        This call returns the interlace type of the image.
        
9       png_get_compression_type
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the compression type of the image.
        This call returns the compression type of the image.
        
10      png_get_pixels_per_meter
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the number of pixels per metre.
        This call returns the number of pixels per metre.
        
11      png_get_x_pixels_per_meter
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the number of x pixels per metre.
        This call returns the number of x pixels per metre.
        
12      png_get_y_pixels_per_meter
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the number of y pixels per metre.
        This call returns the number of y pixels per metre.
        
13      png_get_pixel_aspect_ratio
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the pixel aspect ratio.
        This call returns the pixel aspect ratio.
        
14      png_get_x_offset_pixels
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the x offset in pixels
        This call the x offset in pixels
        
15      png_get_y_offset_pixels
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the y offset in pixels
        This call the y offset in pixels
        
16      png_get_x_offset_microns
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the x offset in microns
        This call the x offset in microns
        
17      png_get_y_offset_microns
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns the y offset in microns
        This call the y offset in microns
        
18      png_get_signature
        R1 = pointer to PNG structure
        R2 = pointer to PNG information structure
        Returns a pointer to the signature as read from the PNG.
        This call returns a pointer to the signature as read from the PNG.
        
19      png_get_copyright
        R1 = pointer to PNG structure
        Returns a pointer to the PNG copyright string
        This call returns a pointer to a copyright string for the PNG library
        which may be printed.
        
20      png_get_header_version
        R1 = pointer to PNG structure
        Returns pointer to a string 
        This call returns a string which may be used to display the version of
        the library.
        
