PNG developers kit
==================

Introduction
------------
This developers kit provides information and resources for developers of
applications which manipulate PNG files. It is expected that users be
familiar with RISC OS interfaces, and using SWIs. Knowledge of libpng
and the PNG specification is not required but may be beneficial. Dependent
on the library being used, knowledge of C or BASIC may be desirable.



The PNG module
--------------
The PNG module supplies a shared interface to the PNG library. Due to
developments from many quarters, including Acorn, the PNG library is able to
produce its output, or read its input, in a number of ways.

In general, the SWI interface binding provides the same parameters as that
of the PNG library. The general principles for accessing the SWIs are :

 * Functions are split into categories which will are accessed via SWIs
 * Each SWI has R0 giving the sub-code for the function being accessed.
   [Reason: There are not enough SWIs in a chunk for all of the functions to
            have one each]
 * Input values are in the registers going into the SWI.
   Return values come out in R0.
   Output values are in the registers coming out of the SWI at the next
   free register (R0 if there is a return parameter, or R1 if not)
 * Floating point values are returned (or passed) scaled by &10000 (that is,
   converted to fixed point values with the point at bit 16).

In addition to this, a small number of RISC OS-specific interfaces have been
added to make the use of the library simpler. Refer to the SWIs/txt document
for more details of the specifics of the SWIs.


SWI Example
-----------
png_uint_32  png_get_gAMA  (png_structp png_ptr, png_infop info_ptr, double *file_gamma)  ;

Becomes:

SWI PNG_GetChunkInfo
=> R0 = 2 (reason code for get_gAMA)
   R1 = pointer to png structure returned from create_read_struct
   R2 = pointer to png information structure returned from 
        png_create_info_struct
<= R0 = returned value (0 if no gAMA chunk, non-0 if gAMA chunk present)
   R1 = gamma value * &10000


Linking with C
--------------
When linking with C, it should be easy to include h.png and link with o.png
to use the module. Future changes to the SWI interface will be reflected in
the AOF library such that a recompile is all that is required.


Caveats
-------
The cHRM (chromaticity) chunk is not currently supported. The implementation
is such that this does not work the way that the SWI interface is currently
designed.

Errors are returned correctly via the jmpbuf interface. Warnings are presently
not reported to the calling application. Warnings are collected in an array
to be returned at some later date.


Examples
--------
These are the simple test programs for PNG, supplied as examples of how to
use the PNG module. BASIC and C programs can (and have) been built from the
PNG library supplied. These examples are simple and in no way represent the
extent of development, or the full features of the PNG module (or library).

Two classes of example are provided -

  * BASIC
    Examples using BASIC to call the PNG module SWIs directly.
    These examples are demonstrations of reading and creating PNGs using
    the SWIs described in SWIs/txt.
  
  * C
    An example in C, using the standard libpng interface library.
    This example converts PNG files to and from PNM files. The original
    version of this source is publically available and only very minor
    (non-PNG related) changes
    
Please refer to the !ReadMe files for each of the examples sections for
more information.


More information
----------------
Firstly, you should read the libpng/txt documentation. This will provide you
with most of the necessary information. If you require further information,
please contact mailto:png@riscos.com
