commit 0a5c9c02faf9c6ceb7acc40e6219e04194581287
author John Bowler <jbowler@acm.org> Sat Jan 22 17:36:34 2011 -0600
committer Glenn Randers-Pehrson <glennrp at users.sourceforge.net> Sat Jan 22 17:36:34 2011 -0600
tree f2f4c9596e5e6af0722beffadb998d9e132a6699
parent 155ce4021812da5629aaebcc9484094944e7d7ae

[devel] Corrected const_png_ in png.h to png_const_ to avoid polluting

 the namespace.  Added png_get_current_row_number and
 png_get_current_pass_number for the
 benefit of the user transform callback.
 Added png_process_data_pause and png_process_data_skip for the benefit of
 progressive readers that need to stop data processing or want to optimize
 skipping of unread data (e.g. if the reader marks a chunk to be skipped.)

libpng-manual.txt

diff --git a/libpng-manual.txt b/libpng-manual.txt
index b34ffcc..3caff8f 100644
--- a/libpng-manual.txt
+++ b/libpng-manual.txt
@@ -1515,7 +1515,20 @@
         row_info, png_bytep data)
 
 See pngtest.c for a working example.  Your function will be called
-after all of the other transformations have been processed.
+after all of the other transformations have been processed.  Take care with
+interlaced images if you do the interlace yourself - the width of the row is the
+width in 'row_info', not the overall image width.
+
+If supported libpng provides two information routines that you can use to find
+where you are in processing the image:
+
+   png_get_current_pass_number(png_structp png_ptr);
+   png_get_current_row_number(png_structp png_ptr);
+
+Don't try using these outside a transform callback - firstly they are only
+supported if user transforms are supported, secondly they may well return
+unexpected results unless the row is actually being processed at the moment they
+are called.
 
 You can also set up a pointer to a user structure for use by your
 callback function, and you can inform libpng that your transform
@@ -1945,6 +1958,12 @@
        so there.
      */
     png_process_data(png_ptr, info_ptr, buffer, length);
+
+    /* At this point you can call png_process_data_skip if
+       you want to handle data the library will skip yourself;
+       it simply returns the number of bytes to skip (and stops
+       libpng skipping that number of bytes on the next
+       png_process_data call).
     return 0;
  }
 
@@ -1968,6 +1987,16 @@
 
        This is where you turn on interlace handling,
        assuming you don't want to do it yourself.
+
+       If you need to you can stop the processing of
+       your original input data at this point by calling
+       png_process_data_pause.  This returns the number
+       of unprocessed bytes from the last png_process_data
+       call - it is up to you to ensure that the next call
+       sees these bytes again.  If you don't want to bother
+       with this you can get libpng to cache the unread
+       bytes by setting the 'save' parameter (see png.h) but
+       then libpng will have to copy the data internally.
      */
  }
 
@@ -2017,6 +2046,9 @@
        for interlaced images), you will have to pass
        the current row, and the function will combine
        the old row and the new row.
+
+       You can also call png_process_data_pause in this
+       callback - see above.
     */
  }
 
@@ -2748,7 +2780,14 @@
        row_info, png_bytep data)
 
 See pngtest.c for a working example.  Your function will be called
-before any of the other transformations are processed.
+before any of the other transformations are processed.  If supported
+libpng also supplies an information routine that may be called from
+your callback:
+
+   png_get_current_row_number(png_ptr);
+
+This returns the current row passed to the transform.  Even with interlaced
+images the value returned is the row in the final output image.
 
 You can also set up a pointer to a user structure for use by your
 callback function.