Imported from libpng-1.0.5q.tarv1.0.5q

1 files changed, 306 insertions, 97 deletions

diff --git a/libpng.txt b/libpng.txt
index 43b8f53f5..d688eac80 100644
--- a/libpng.txt
+++ b/libpng.txt
@@ -1,9 +1,9 @@
 libpng.txt - A description on how to use and modify libpng
 
- libpng version 1.0.5h - December 10, 1999
+ libpng version 1.0.5q - February 5, 2000
  Updated and distributed by Glenn Randers-Pehrson
  <randeg@alum.rpi.edu>
- Copyright (c) 1998, 1999 Glenn Randers-Pehrson
+ Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson
  For conditions of distribution and use, see copyright
  notice in png.h.
 
@@ -19,10 +19,9 @@ libpng.txt - A description on how to use and modify libpng
  Schalnat, Group 42, Inc.
 
  Updated/rewritten per request in the libpng FAQ
- Copyright (c) 1995 Frank J. T. Wojcik
- December 18, 1995 && January 20, 1996
+ Copyright (c) 1995, 1996 Frank J. T. Wojcik
+ December 18, 1995 & January 20, 1996
 
- *
 I. Introduction
 
 This file describes how to use and modify the PNG reference library
@@ -102,13 +101,14 @@ And while I'm on the topic, make sure you include the libpng header file:
 
 III. Reading
 
-Reading PNG files:
-
 We'll now walk you through the possible functions to call when reading
-in a PNG file, briefly explaining the syntax and purpose of each one.
-See example.c and png.h for more detail.  While Progressive reading
-is covered in the next section, you will still need some of the
-functions discussed in this section to read a PNG file.
+in a PNG file sequentially, briefly explaining the syntax and purpose
+of each one.  See example.c and png.h for more detail.  While
+progressive reading is covered in the next section, you will still
+need some of the functions discussed in this section to read a PNG
+file.
+
+Setup
 
 You will want to do the I/O initialization(*) before you get into libpng,
 so if it doesn't work, you don't have much to undo.  Of course, you
@@ -208,6 +208,10 @@ free any memory.
         return;
     }
 
+If you would rather avoid the complexity of setjmp/longjmp issues,
+you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
+errors will result in a call to PNG_ABORT() which defaults to abort().
+
 Now you need to set up the input code.  The default for libpng is to
 use the C function fread().  If you use this, you will need to pass a
 valid FILE * in the function png_init_io().  Be sure that the file is
@@ -224,6 +228,42 @@ libpng know that there are some bytes missing from the start of the file.
 
     png_set_sig_bytes(png_ptr, number);
 
+Setting up callback code
+
+You can set up a callback function to handle any unknown chunks in the
+input stream. You must supply the function
+
+    read_chunk_callback(png_ptr ptr,
+         png_unknown_chunkp chunk);
+    {
+       /* The unknown chunk structure contains your
+          chunk data: */
+           png_byte name[5];
+           png_byte *data;
+           png_size_t size;
+       /* Note that libpng has already taken care of the
+          CRC handling */
+
+       /* put your code here.  Return one of the following: */
+
+       return (-n); /* chunk had an error */
+       return (0); /* did not recognize */
+       return (n); /* success */
+    }
+
+(You can give your function another name that you like instead of
+"read_chunk_callback")
+
+To inform libpng about your function, use
+
+    png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
+        read_chunk_callback);
+
+This names not only the callback function, but also a user pointer that
+you can retrieve with
+
+    png_get_user_chunk_ptr(png_ptr);
+
 At this point, you can set up a callback function that will be
 called after each row has been read, which you can use to control
 a progress meter or the like.  It's demonstrated in pngtest.c.
@@ -240,19 +280,6 @@ To inform libpng about your function, use
 
     png_set_read_status_fn(png_ptr, read_row_callback);
 
-In PNG files, the alpha channel in an image is the level of opacity.
-If you need the alpha channel in an image to be the level of transparency
-instead of opacity, you can invert the alpha channel (or the tRNS chunk
-data) after it's read, so that 0 is fully opaque and 255 (in 8-bit or
-paletted images) or 65535 (in 16-bit images) is fully transparent, with
-
-    png_set_invert_alpha(png_ptr);
-
-This has to appear here rather than later with the other transformations
-because the tRNS chunk data must be modified in the case of paletted images.
-If your image is not a paletted image, the tRNS data (which in such cases
-represents a single color to be rendered as transparent) won't be changed.
-
 Finally, you can write your own transformation function if none of
 the existing ones meets your needs.  This is done by setting a callback
 with
@@ -276,6 +303,8 @@ function
     png_set_user_transform_info(png_ptr, user_ptr,
        user_depth, user_channels);
 
+The user's application, not libpng, is responsible for allocating and
+freeing any memory required for the user structure.
 
 You can retrieve the pointer via the function
 png_get_user_transform_ptr().  For example:
@@ -283,23 +312,100 @@ png_get_user_transform_ptr().  For example:
     voidp read_user_transform_ptr =
        png_get_user_transform_ptr(png_ptr);
 
-You are now ready to read all the file information up to the actual
-image data.  You do this with a call to png_read_info().
+Unknown-chunk handling
+
+Now you get to set the way the library processes unknown chunks in the
+input PNG stream. Both known and unknown chunks will be read.  Normal
+behavior is that known chunks will be parsed into information in
+various info_ptr members; unknown chunks will be discarded. To change
+this, you can call:
+
+    png_set_keep_unknown_chunks(png_ptr, info_ptr, keep,
+        chunk_list, num_chunks);
+    keep       - 0: do not keep
+                 1: keep only if safe-to-copy
+                 2: keep even if unsafe-to-copy
+    chunk_list - list of chunks affected (a byte string,
+                 five bytes per chunk, NULL or '\0' if
+                 num_chunks is 0)
+    num_chunks - number of chunks affected; if 0, all
+                 unknown chunks are affected
+
+Unknown chunks declared in this way will be saved as raw data onto a
+list of png_unknown_chunk structures.  If a chunk that is normally
+known to libpng is named in the list, it will be handled as unknown,
+according to the "keep" directive.  If a chunk is named in successive
+instances of png_set_keep_unknown_chunks(), the final instance will
+take precedence.
+
+The high-level read interface
+
+At this point there are two ways to proceed; through the high-level
+read interface, or through a sequence of low-level read operations.
+You can use the high-level interface if (a) you are willing to read
+the entire image into memory, and (b) the input transformations
+you want to do are limited to the following set:
+
+    PNG_TRANSFORM_IDENTITY      No transformation
+    PNG_TRANSFORM_STRIP_16      Strip 16-bit samples to 8 bits
+    PNG_TRANSFORM_STRIP_ALPHA   Discard the alpha channel
+    PNG_TRANSFORM_PACKING       Expand 1, 2 and 4-bit samples to bytes
+    PNG_TRANSFORM_PACKSWAP      Change order of packed pixels to LSB first
+    PNG_TRANSFORM_EXPAND        Perform set_expand()
+    PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
+    PNG_TRANSFORM_SHIFT         Normalize pixels to the sBIT depth
+    PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA to BGRA
+    PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA to AG
+    PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity to transparency
+    PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
+
+(This excludes setting a background color, doing gamma transformation,
+dithering, and setting filler.)  If this is the case, simply do this:
+
+    png_read_png(png_ptr, info_ptr, png_transforms, NULL)
+
+where png_transforms is an integer containing the logical-or of some set of
+transformation flags.  This call is equivalent to png_read_info(),
+followed the set of transformations indicated by the transform mask,
+followed by png_update_info(), followed by a read of the image bytes
+to the info member `rowpointers', followed by png_read_end().
+
+(The final parameter of this call is not yet used.  Someday it
+will point to transformation parameters.)
+
+The low-level read interface
+
+If you are going the low-level route, you are now ready to read all
+the file information up to the actual image data.  You do this with a
+call to png_read_info().
 
     png_read_info(png_ptr, info_ptr);
 
-This will read all chunks up to but not including the image data.
-Both known and unknown chunks will be read.  Known chunks will be
-parsed into information in various info_ptr members; unknown chunks
-will be discarded, unless you previously called
+This will process all chunks up to but not including the image data.
+
+There is one transformation you may need to set up before doing
+png_read_info(), however.  In PNG files, the alpha channel in an image
+is the level of opacity.  If you need the alpha channel in an image to
+be the level of transparency instead of opacity, you can invert the
+alpha channel (or the tRNS chunk data) after it's read, so that 0 is
+fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
+images) is fully transparent, with
+
+    png_set_invert_alpha(png_ptr);
 
-    png_set_keep_unknown_chunks();
+This must appear before png_write_info() instead of later with the
+other transformations because in the case of paletted images the tRNS
+chunk data has to be inverted before the tRNS chunk is written.
+If your image is not a paletted image, the tRNS data (which in such cases
+represents a single color to be rendered as transparent) won't need to
+be changed, and you can safely do this transformation after your
+png_read_info() call.
 
-in which case they will be saved as raw data onto a list of
-png_unknown_chunk structures (and written out if you subsequently
-call png_write_info and friends).
+Querying the info structure
 
-Functions are used to get the information from the info_ptr:
+Functions are used to get the information from the info_ptr once it
+has been read.  Note that these fields may not be completely filled
+in until png_read_end() has read the chunk data following the image.
 
     png_get_IHDR(png_ptr, info_ptr, &width, &height,
        &bit_depth, &color_type, &interlace_type,
@@ -439,20 +545,28 @@ into the info_ptr is returned for any complex types.
 
     png_get_bKGD(png_ptr, info_ptr, &background);
     background     - background color (PNG_VALID_bKGD)
+                     valid 16-bit red, green and blue
+                     values, regardless of color_type
 
     num_text = png_get_text(png_ptr, info_ptr, &text_ptr);
     text_ptr       - array of png_text holding image
                      comments
-    text_ptr[i]->lang  - language of comment (NULL for unknown).
+    text_ptr[i]->compression - type of compression used
+                 on "text" PNG_TEXT_COMPRESSION_NONE
+                           PNG_TEXT_COMPRESSION_zTXt
+                           PNG_ITXT_COMPRESSION_NONE
+                           PNG_ITXT_COMPRESSION_zTXt
     text_ptr[i]->key   - keyword for comment.
-    text_ptr[i]->translated_keyword  - keyword in UTF-8 (NULL for unknown).
     text_ptr[i]->text  - text comments for current
                          keyword.
-    text_ptr[i]->compression - type of compression used
-                     on "text" PNG_TEXT_COMPRESSION_NONE
-                     or PNG_TEXT_COMPRESSION_zTXt
+    text_ptr[i]->text_length - length of text string,
+                 after decompression, 0 for iTXt
+    text_ptr[i]->itxt_length - length of itxt string,
+                 after decompression, 0 for tEXt/zTXt
+    text_ptr[i]->lang  - language of comment (NULL for unknown).
+    text_ptr[i]->translated_keyword  - keyword in UTF-8 (NULL
+                         for unknown).
     num_text       - number of comments
-
     num_spalettes = png_get_spalettes(png_ptr, info_ptr, &palette_ptr);
     palette_ptr    - array of png_spalette structures holding contents
                      of one or more sPLT chunks read.
@@ -487,6 +601,7 @@ into the info_ptr is returned for any complex types.
     unknowns[i].name  - name of unknown chunk
     unknowns[i].data  - data of unknown chunk
     unknowns[i].size  - size of unknown chunk
+    unknowns[i].location - position of chunk in file
 
 The data from the pHYs chunk can be retrieved in several convenient
 forms:
@@ -531,6 +646,8 @@ make sure you have read all the text chunks, don't mess with these
 until after you read the stuff after the image.  This will be
 mentioned again below in the discussion that goes with png_read_end().
 
+Input transformations
+
 After you've read the header information, you can set up the library
 to handle any special transformations of the image data.  The various
 ways to transform the data will be described in the order that they
@@ -865,6 +982,8 @@ are allocating one large chunk, you will need to build an
 array of pointers to each row, as it will be needed for some
 of the functions below.
 
+Reading image data
+
 After you've allocated memory, you can read the image data.
 The simplest way to do this is in one function call.  If you are
 allocating enough memory to hold the whole image, you can just
@@ -973,12 +1092,14 @@ the second parameter NULL.
     png_read_rows(png_ptr, NULL, row_pointers,
        number_of_rows);
 
-After you are finished reading the image, you can finish reading
-the file.  If you are interested in comments or time, which may be
-stored either before or after the image data, you should pass the
-separate png_info struct if you want to keep the comments from
-before and after the image separate.  If you are not interested, you
-can pass NULL.
+Finishing a sequential read
+
+After you are finished reading the image through either the high- or
+low-level interfaces, you can finish reading the file.  If you are
+interested in comments or time, which may be stored either before or
+after the image data, you should pass the separate png_info struct if
+you want to keep the comments from before and after the image
+separate.  If you are not interested, you can pass NULL.
 
    png_read_end(png_ptr, end_info);
 
@@ -993,16 +1114,20 @@ point to allocated storage with the following functions:
     png_free_text(png_ptr, info_ptr, num)
     num          - number of text item to be freed (-1 for all items)
 
+    png_free_hIST(png_ptr, info_ptr)
+
     png_free_iCCP(png_ptr, info_ptr)
 
     png_free_pCAL(png_ptr, info_ptr)
 
     png_free_sCAL(png_ptr, info_ptr)
 
-    png_free_spalette(png_ptr, info_ptr, num)
+    png_free_spalettes(png_ptr, info_ptr, num)
     num          - number of suggested-paletted entry to be freed
                    (-1 for all suggested palettes)
 
+    png_free_pixels(png_ptr, info_ptr)
+
     png_free_unknown_chunk(png_ptr, info_ptr, num)
     num          - number of unknown chunk to be freed
                    (-1 for all suggested palettes)
@@ -1013,8 +1138,7 @@ case do nothing.
 
 For a more compact example of reading a PNG image, see the file example.c.
 
-
-Reading PNG files progressively:
+Reading PNG files progressively
 
 The progressive reader is slightly different then the non-progressive
 reader.  Instead of calling png_read_info(), png_read_rows(), and
@@ -1191,6 +1315,8 @@ Much of this is very similar to reading.  However, everything of
 importance is repeated here, so you won't have to constantly look
 back up in the reading section to understand writing.
 
+Setup
+
 You will want to do the I/O initialization before you get into libpng,
 so if it doesn't work, you don't have anything to undo. If you are not
 using the standard I/O functions, you will need to replace them with
@@ -1253,6 +1379,10 @@ section below for more information on the libpng error handling.
     ...
     return;
 
+If you would rather avoid the complexity of setjmp/longjmp issues,
+you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
+errors will result in a call to PNG_ABORT() which defaults to abort().
+
 Now you need to set up the output code.  The default for libpng is to
 use the C function fwrite().  If you use this, you will need to pass a
 valid FILE * in the function png_init_io().  Be sure that the file is
@@ -1262,6 +1392,8 @@ Libpng section below.
 
     png_init_io(png_ptr, fp);
 
+Write callbacks
+
 At this point, you can set up a callback function that will be
 called after each row has been written, which you can use to control
 a progress meter or the like.  It's demonstrated in pngtest.c.
@@ -1316,6 +1448,8 @@ data.  See the Compression Library for details on the compression levels.
     png_set_compression_window_bits(png_ptr, 15);
     png_set_compression_method(png_ptr, 8);
 
+Setting the contents of info for output
+
 You now need to fill in the png_info structure with all the data you
 wish to write before the actual image.  Note that the only thing you
 are allowed to write after the image is the text chunks and the time
@@ -1445,15 +1579,22 @@ Some of the more important parts of the png_info are:
     png_set_text(png_ptr, info_ptr, text_ptr, num_text);
     text_ptr       - array of png_text holding image
                      comments
-    text_ptr[i]->lang  - language of comment (NULL for unknown).
+    text_ptr[i]->compression - type of compression used
+                 on "text" PNG_TEXT_COMPRESSION_NONE
+                           PNG_TEXT_COMPRESSION_zTXt
+                           PNG_ITXT_COMPRESSION_NONE
+                           PNG_ITXT_COMPRESSION_zTXt
     text_ptr[i]->key   - keyword for comment.
-    text_ptr[i]->translated_keyword  - keyword in UTF-8 (NULL for unknown).
     text_ptr[i]->text  - text comments for current
                          keyword.
-    text_ptr[i]->compression - type of compression used
-         on "text" PNG_TEXT_COMPRESSION_NONE or
-         PNG_TEXT_COMPRESSION_zTXt
-    num_text    - number of comments in text_ptr
+    text_ptr[i]->text_length - length of text string,
+                 after decompression, 0 for iTXt
+    text_ptr[i]->itxt_length - length of itxt string,
+                 after decompression, 0 for tEXt/zTXt
+    text_ptr[i]->lang  - language of comment (NULL for unknown).
+    text_ptr[i]->translated_keyword  - keyword in UTF-8 (NULL
+                         for unknown).
+    num_text       - number of comments
 
     png_set_spalettes(png_ptr, info_ptr, &palette_ptr, num_spalettes);
     palette_ptr    - array of png_spalette structures to be added to
@@ -1488,20 +1629,15 @@ Some of the more important parts of the png_info are:
     unknowns[i].name  - name of unknown chunk
     unknowns[i].data  - data of unknown chunk
     unknowns[i].size  - size of unknown chunk
-
-In PNG files, the alpha channel in an image is the level of opacity.
-If your data is supplied as a level of transparency, you can invert the
-alpha channel before you write it, so that 0 is fully transparent and 255
-(in 8-bit or paletted images) or 65535 (in 16-bit images) is fully opaque,
-with
-
-    png_set_invert_alpha(png_ptr);
-
-This must appear here instead of later with the other transformations
-because in the case of paletted images the tRNS chunk data has to
-be inverted before the tRNS chunk is written.  If your image is not a
-paletted image, the tRNS data (which in such cases represents a single
-color to be rendered as transparent) won't be changed.
+    unknowns[i].location - position to write chunk in file
+                           0: do not write chunk
+                           PNG_HAVE_IHDR: before PLTE
+                           PNG_HAVE_PLTE: before IDAT
+                           PNG_AFTER_IDAT: after IDAT
+    The "location" member is set automatically according to
+    what part of the output file has already been written.
+    You can change its value after calling png_set_unknown_chunks()
+    as demonstrated in pngtest.c.
 
 A quick word about text and num_text.  text is an array of png_text
 structures.  num_text is the number of valid structures in the array.
@@ -1583,6 +1719,8 @@ by the software.  To facilitate the use of RFC 1123 dates, a function
 png_convert_to_rfc1123(png_timep) is provided to convert from PNG
 time to an RFC 1123 format string.
 
+Writing unknown chunks
+
 You can use the png_set_unknown_chunks function to queue up chunks
 for writing.  You give it a chunk name, raw data, and a size; that's
 all there is to it.  The chunks will be written by the next following
@@ -1591,11 +1729,63 @@ Any chunks previously read into the info structure's unknown-chunk
 list will also be written out in a sequence that satisfies the PNG
 specification's ordering rules.
 
-You are now ready to write all the file information up to the actual
-image data.  You do this with a call to png_write_info().
+The high-level write interface
+
+At this point there are two ways to proceed; through the high-level
+write interface, or through a sequence of low-level write operations.
+You can use the high-level interface if your image data is present
+on the rowpointers member of the info structure.  All defined output
+transformations are pernmitted, enabled by the following masks.
+
+    PNG_TRANSFORM_IDENTITY      No transformation
+    PNG_TRANSFORM_PACKING       Pack 1, 2 and 4-bit samples
+    PNG_TRANSFORM_PACKSWAP      Change order of packed pixels to LSB first
+    PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
+    PNG_TRANSFORM_SHIFT         Normalize pixels to the sBIT depth
+    PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA to BGRA
+    PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA to AG
+    PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity to transparency
+    PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
+    PNG_TRANSFORM_STRIP_FILLER  Strip out filler bytes.
+
+If you have valid image data on the rowpointers member, simply do this:
+
+    png_write_png(png_ptr, info_ptr, png_transforms, NULL)
+
+where png_transforms is an integer containing the logical-or of some set of
+transformation flags.  This call is equivalent to png_write_info(),
+followed by the set of transformations indicated by the transform
+mask, followed by followed by a write of the image bytes to the info
+member `rowpointers', followed by png_write_end().
+
+(The final parameter of this call is not yet used.  Someday it
+may point to output transformation parameters.)
+
+The low-level write interface
+
+If you are going the low-level route instead, you are now ready to
+write all the file information up to the actual image data.  You do
+this with a call to png_write_info().
 
     png_write_info(png_ptr, info_ptr);
 
+Note that there is one transformation you may need to do before
+png_write_info().  In PNG files, the alpha channel in an image is the
+level of opacity.  If your data is supplied as a level of
+transparency, you can invert the alpha channel before you write it, so
+that 0 is fully transparent and 255 (in 8-bit or paletted images) or
+65535 (in 16-bit images) is fully opaque, with
+
+    png_set_invert_alpha(png_ptr);
+
+This must appear before png_write_info() instead of later with the
+other transformations because in the case of paletted images the tRNS
+chunk data has to be inverted before the tRNS chunk is written.  If
+your image is not a paletted image, the tRNS data (which in such cases
+represents a single color to be rendered as transparent) won't need to
+be changed, and you can safely do this transformation after your
+png_write_info() call.
+
 If you need to write a private chunk that you want to appear before
 the PLTE chunk when PLTE is present, you can write the PNG info in
 two steps, and insert code to write your own chunk between them:
@@ -1736,6 +1926,8 @@ may be acceptable for real-time applications).  Infrequent flushing will
 only degrade the compression performance by a few percent over images
 that do not use flushing.
 
+Writing the image data
+
 That's it for the transformations.  Now you can write the image data.
 The simplest way to do this is in one function call.  If have the
 whole image in memory, you can just call png_write_image() and libpng
@@ -1769,7 +1961,7 @@ row_pointers:
     png_write_row(png_ptr, &row_pointer);
 
 When the file is interlaced, things can get a good deal more
-complicated.  The only currently (as of August 1999 -- PNG Specification
+complicated.  The only currently (as of January 2000 -- PNG Specification
 version 1.2, dated July 1999) defined interlacing scheme for PNG files
 is the "Adam7" interlace scheme, that breaks down an
 image into seven smaller images of varying size.  libpng will build
@@ -1799,6 +1991,8 @@ As some of these rows are not used, and thus return immediately,
 you may want to read about interlacing in the PNG specification,
 and only update the rows that are actually used.
 
+Finishing a sequential write
+
 After you are finished writing the image, you should finish writing
 the file.  If you are interested in writing comments or time, you should
 pass an appropriately filled png_info pointer.  If you are not interested,
@@ -1816,16 +2010,20 @@ point to allocated storage with the following functions:
     png_free_text(png_ptr, info_ptr, num)
     num          - number of text item to be freed (-1 for all items)
 
+    png_free_hIST(png_ptr, info_ptr)
+
     png_free_iCCP(png_ptr, info_ptr)
 
     png_free_pCAL(png_ptr, info_ptr)
 
     png_free_sCAL(png_ptr, info_ptr)
 
-    png_free_spalette(png_ptr, info_ptr, num)
+    png_free_spalettes(png_ptr, info_ptr, num)
     num          - number of suggested-paletted entry to be freed
                    (-1 for all suggested palettes)
 
+    png_free_pixels(png_ptr, info_ptr)
+
     png_free_unknown_chunk(png_ptr, info_ptr, num)
     num          - number of unknown chunk entry to be freed
                    (-1 for all suggested palettes)
@@ -1834,8 +2032,7 @@ These functions may be safely called when the relevant storage has
 already been freed, or has not yet been allocated, and will in that
 case do nothing.
 
-You must free any data you allocated for info_ptr, such as comments,
-palette, or histogram, before the call to png_destroy_write_struct();
+If you allocated palette data, you must free it before the call to png_destroy_write_struct();
 
 For a more compact example of writing a PNG image, see the file example.c.
 
@@ -1895,8 +2092,11 @@ a write stream, and vice versa.
 Error handling in libpng is done through png_error() and png_warning().
 Errors handled through png_error() are fatal, meaning that png_error()
 should never return to its caller.  Currently, this is handled via
-setjmp() and longjmp(), but you could change this to do things like
-exit() if you should wish.  On non-fatal errors, png_warning() is called
+setjmp() and longjmp() (unless you have compiled libpng with
+PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
+but you could change this to do things like exit() if you should wish.
+
+On non-fatal errors, png_warning() is called
 to print a warning message, and then control returns to the calling code.
 By default png_error() and png_warning() print a message on stderr via
 fprintf() unless the library is compiled with PNG_NO_STDIO defined.  If
@@ -1929,16 +2129,25 @@ after a longjmp, so the user may want to be careful about doing anything after
 setjmp returns non-zero besides returning itself.  Consult your compiler
 documentation for more details.
 
-If you need to read or write custom chunks, you will need to get deeper
-into the libpng code, as a mechanism has not yet been supplied for user
-callbacks with custom chunks.  First, read the PNG specification, and have
-a first level of understanding of how it works.  Pay particular attention
-to the sections that describe chunk names, and look at how other chunks
-were designed, so you can do things similarly.  Second, check out the
-sections of libpng that read and write chunks.  Try to find a chunk that
-is similar to yours and use it as a template.  More details can be found in the
-comments inside the code.  A way of handling unknown chunks in a generic
-method, potentially via callback functions, would be best.
+Custom chunks
+
+If you need to read or write custom chunks, you may need to get deeper
+into the libpng code.  The library now has mechanisms for storing
+and writing chunks of unknown type; you can even declare callbacks
+for custom chunks.  Hoewver, this may not be good enough if the
+library code itself needs to know about interactions between your
+chunk and existing `intrinsic' chunks.
+
+If you need to write a new intrinsic chunk, first read the PNG
+specification. Acquire a first level of
+understanding of how it works.  Pay particular attention to the
+sections that describe chunk names, and look at how other chunks were
+designed, so you can do things similarly.  Second, check out the
+sections of libpng that read and write chunks.  Try to find a chunk
+that is similar to yours and use it as a template.  More details can
+be found in the comments inside the code.  It is best to handle unknown
+chunks in a generic method, via callback functions, instead of by
+modifying libpng functions.
 
 If you wish to write your own transformation for the data, look through
 the part of the code that does the transformations, and check out some of
@@ -1946,7 +2155,7 @@ the simpler ones to get an idea of how they work.  Try to find a similar
 transformation to the one you want to add and copy off of it.  More details
 can be found in the comments inside the code itself.
 
-Configuring for 16 bit platforms:
+Configuring for 16 bit platforms
 
 You may need to change the png_large_malloc() and png_large_free()
 routines in pngmem.c, as these are required to allocate 64K, although
@@ -1955,13 +2164,13 @@ you will want to look into zconf.h to tell zlib (and thus libpng) that
 it cannot allocate more then 64K at a time.  Even if you can, the memory
 won't be accessible.  So limit zlib and libpng to 64K by defining MAXSEG_64K.
 
-Configuring for DOS:
+Configuring for DOS
 
 For DOS users who only have access to the lower 640K, you will
 have to limit zlib's memory usage via a png_set_compression_mem_level()
 call.  See zlib.h or zconf.h in the zlib library for more information.
 
-Configuring for Medium Model:
+Configuring for Medium Model
 
 Libpng's support for medium model has been tested on most of the popular
 compilers.  Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
@@ -1969,7 +2178,7 @@ defined, and FAR gets defined to far in pngconf.h, and you should be
 all set.  Everything in the library (except for zlib's structure) is
 expecting far data.  You must use the typedefs with the p or pp on
 the end for pointers (or at least look at them and be careful).  Make
-note that the row's of data are defined as png_bytepp, which is an
+note that the rows of data are defined as png_bytepp, which is an
 unsigned char far * far *.
 
 Configuring for gui/windowing platforms:
@@ -2021,7 +2230,7 @@ zlib.h for more information on what these mean.
         window_bits);
     png_set_compression_method(png_ptr, method);
 
-Controlling row filtering:
+Controlling row filtering
 
 If you want to control whether libpng uses filtering or not, which
 filters are used, and how it goes about picking row filters, you
@@ -2087,7 +2296,7 @@ Note that the numbers above were invented purely for this example and
 are given only to help explain the function usage.  Little testing has
 been done to find optimum values for either the costs or the weights.
 
-Removing unwanted object code:
+Removing unwanted object code
 
 There are a bunch of #define's in pngconf.h that control what parts of
 libpng are compiled.  All the defines end in _SUPPORTED.  If you are
@@ -2125,7 +2334,7 @@ library to fail if they call functions not available in your library.
 The size of the library itself should not be an issue, because only
 those sections that are actually used will be loaded into memory.
 
-Requesting debug printout:
+Requesting debug printout
 
 The macro definition PNG_DEBUG can be used to request debugging
 printout.  Set it to an integer value in the range 0 to 3.  Higher
@@ -2197,13 +2406,13 @@ the old method.
 
 VII. Y2K Compliance in libpng
 
-December 10, 1999
+February 5, 2000
 
 Since the PNG Development group is an ad-hoc body, we can't make
 an official declaration.
 
 This is your unofficial assurance that libpng from version 0.71 and
-upward through 1.0.5h are Y2K compliant.  It is my belief that earlier
+upward through 1.0.5q are Y2K compliant.  It is my belief that earlier
 versions were also Y2K compliant.
 
 Libpng only has three year fields.  One is a 2-byte unsigned integer that