Changeset 43 for vendor/libpng/libpng.3

Timestamp:

02/15/10 11:37:15 (2 years ago)

Author:

Carsten

Message:

Upgraded vendor/libpng from 1.2.40 to 1.2.42.

Files:

• vendor/libpng/libpng.3 (modified) (38 diffs)

vendor/libpng/libpng.3

@@ -1 @@
-.TH LIBPNG 3 "September 10, 2009"
+.TH LIBPNG 3 "January 3, 2010"
 .SH NAME
-libpng \- Portable Network Graphics (PNG) Reference Library 1.2.40
+libpng \- Portable Network Graphics (PNG) Reference Library 1.2.42
 .SH SYNOPSIS
 \fI\fB
@@ -822 +822 @@
 libpng.txt - A description on how to use and modify libpng
 
- libpng version 1.2.40 - September 10, 2009
+ libpng version 1.2.42 - January 3, 2010
  Updated and distributed by Glenn Randers-Pehrson
  <glennrp at users.sourceforge.net>
@@ -833 +833 @@
  Based on:
 
- libpng versions 0.97, January 1998, through 1.2.40 - September 10, 2009
+ libpng versions 0.97, January 1998, through 1.2.42 - January 3, 2010
  Updated and distributed by Glenn Randers-Pehrson
  Copyright (c) 1998-2009 Glenn Randers-Pehrson
@@ -862 +862 @@
 
 For examples of libpng usage, see the files "example.c", "pngtest.c",
-and the files in the "contrib" directory, all of which are included in the
-libpng distribution.
+and the files in the "contrib" directory, all of which are included in
+the libpng distribution.
 
 Libpng was written as a companion to the PNG specification, as a way
@@ -1231 +1231 @@
    width_max = png_get_user_width_max(png_ptr);
    height_max = png_get_user_height_max(png_ptr);
+
+The PNG specification sets no limit on the number of ancillary chunks
+allowed in a PNG datastream.  You can impose a limit on the total number
+of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
+
+   png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
+
+where 0x7fffffffL means unlimited.  You can retrieve this limit with
+
+   chunk_cache_max = png_get_chunk_cache_max(png_ptr);
+
+This limit also applies to the number of buffers that can be allocated
+by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
 
 .SS The high-level read interface
@@ -1259 +1272 @@
                                 to transparency
     PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
+    PNG_TRANSFORM_GRAY_TO_RGB   Expand grayscale samples
+                                to RGB (or GA to RGBA)
 
 (This excludes setting a background color, doing gamma transformation,
@@ -1265 +1280 @@
     png_read_png(png_ptr, info_ptr, png_transforms, NULL)
 
-where png_transforms is an integer containing the bitwise OR of
-some set of transformation flags.  This call is equivalent to png_read_info(),
+where png_transforms is an integer containing the bitwise 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,
 then png_read_image(), and finally png_read_end().
@@ -1367 +1382 @@
     interlace_type - (PNG_INTERLACE_NONE or
                      PNG_INTERLACE_ADAM7)
-    Any or all of interlace_type, compression_type, of
+
+    Any or all of interlace_type, compression_type, or
     filter_method can be NULL if you are
     not interested in their values.
 
-    channels = png_get_channels(png_ptr, info_ptr);
-    channels       - number of channels of info for the
-                     color type (valid values are 1 (GRAY,
-                     PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
-                     4 (RGB_ALPHA or RGB + filler byte))
-    rowbytes = png_get_rowbytes(png_ptr, info_ptr);
-    rowbytes       - number of bytes needed to hold a row
-
-    signature = png_get_signature(png_ptr, info_ptr);
-    signature      - holds the signature read from the
-                     file (if any).  The data is kept in
-                     the same offset it would be if the
-                     whole signature were read (i.e. if an
-                     application had already read in 4
-                     bytes of signature before starting
-                     libpng, the remaining 4 bytes would
-                     be in signature[4] through signature[7]
-                     (see png_set_sig_bytes())).
-
+    Note that png_get_IHDR() returns 32-bit data into
+    the application's width and height variables.
+    This is an unsafe situation if these are 16-bit
+    variables.  In such situations, the
+    png_get_image_width() and png_get_image_height()
+    functions described below are safer.
 
     width            = png_get_image_width(png_ptr,
@@ -1406 +1409 @@
                          info_ptr);
 
+    channels = png_get_channels(png_ptr, info_ptr);
+    channels       - number of channels of info for the
+                     color type (valid values are 1 (GRAY,
+                     PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
+                     4 (RGB_ALPHA or RGB + filler byte))
+    rowbytes = png_get_rowbytes(png_ptr, info_ptr);
+    rowbytes       - number of bytes needed to hold a row
+
+    signature = png_get_signature(png_ptr, info_ptr);
+    signature      - holds the signature read from the
+                     file (if any).  The data is kept in
+                     the same offset it would be if the
+                     whole signature were read (i.e. if an
+                     application had already read in 4
+                     bytes of signature before starting
+                     libpng, the remaining 4 bytes would
+                     be in signature[4] through signature[7]
+                     (see png_set_sig_bytes())).
 
 These are also important, but their validity depends on whether the chunk
@@ -1411 +1432 @@
 png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
 data has been read, or zero if it is missing.  The parameters to the
-png_get_<chunk> are set directly if they are simple data types, or a pointer
-into the info_ptr is returned for any complex types.
+png_get_<chunk> are set directly if they are simple data types, or a
+pointer into the info_ptr is returned for any complex types.
 
     png_get_PLTE(png_ptr, info_ptr, &palette,
@@ -1452 +1473 @@
     png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
                      &trans_values);
-    trans          - array of transparent entries for
-                     palette (PNG_INFO_tRNS)
+    trans          - array of transparent
+                     entries for palette (PNG_INFO_tRNS)
     trans_values   - graylevel or color sample values of
                      the single transparent color for
@@ -1496 +1517 @@
     text_ptr[i].lang_key  - keyword in UTF-8
                          (empty string for unknown).
+    Note that the itxt_length, lang, and lang_key
+    members of the text_ptr structure only exist
+    when the library is built with iTXt chunk support.
+
     num_text       - number of comments (same as
                      num_comments; you can put NULL here
@@ -1675 +1700 @@
 added.  It expands the sample depth without changing tRNS to alpha.
 
+As of libpng version 1.2.42, not all possible expansions are supported.
+
+In the following table, the 01 means grayscale with depth<8, 31 means
+indexed with depth<8, other numerals represent the color type, "T" means
+the tRNS chunk is present, A means an alpha channel is present, and O
+means tRNS or alpha is present but all pixels in the image are opaque.
+
+  FROM  01  31   0  0T  0O   2  2T  2O   3  3T  3O  4A  4O  6A  6O 
+   TO
+   01    -                   
+   31        -
+    0    1       -           
+   0T                -
+   0O                    -
+    2           GX           -
+   2T                            -
+   2O                                -
+    3        1                           -
+   3T                                        -
+   3O                                            -
+   4A                T                               -
+   4O                                                    -
+   6A               GX         TX           TX               -
+   6O                   GX                      TX               -
+
+Within the matrix,
+     "-" means the transformation is not supported.
+     "X" means the transformation is obtained by png_set_expand().
+     "1" means the transformation is obtained by
+         png_set_expand_gray_1_2_4_to_8
+     "G" means the transformation is obtained by
+         png_set_gray_to_rgb().
+     "P" means the transformation is obtained by
+         png_set_expand_palette_to_rgb().
+     "T" means the transformation is obtained by
+         png_set_tRNS_to_alpha().
+
 PNG can have files with 16 bits per channel.  If you only can handle
 8 bits per channel, this will strip the pixels down to 8 bit.
@@ -1698 +1760 @@
     png_set_invert_alpha(png_ptr);
 
+The PNG format only supports pixels with postmultiplied alpha.
+If you want to replace the pixels, after reading them, with pixels
+that have premultiplied color samples, you can do this with
+
+    png_set_premultiply_alpha(png_ptr);
+
+If you do this, any input with a tRNS chunk will be expanded to
+have an alpha channel.
+
 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
 they can, resulting in, for example, 8 pixels per byte for 1 bit
@@ -1708 +1779 @@
 PNG files have possible bit depths of 1, 2, 4, 8, and 16.  All pixels
 stored in a PNG image have been "scaled" or "shifted" up to the next
-higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
-8 bits/sample in the range [0, 255]).  However, it is also possible to
-convert the PNG pixel data back to the original bit depth of the image.
-This call reduces the pixels back down to the original bit depth:
+higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
+to 8 bits/sample in the range [0, 255]).  However, it is also possible
+to convert the PNG pixel data back to the original bit depth of the
+image.  This call reduces the pixels back down to the original bit depth:
 
     png_color_8p sig_bit;
@@ -2158 +2229 @@
 This function may be safely called when the relevant storage has
 already been freed, or has not yet been allocated, or was allocated
-by the user and not by libpng,  and will in those
-cases do nothing.  The "seq" parameter is ignored if only one item
-of the selected data type, such as PLTE, is allowed.  If "seq" is not
--1, and multiple items are allowed for the data type identified in
-the mask, such as text or sPLT, only the n'th item in the structure
-is freed, where n is "seq".
+by the user and not by libpng,  and will in those cases do nothing.
+The "seq" parameter is ignored if only one item of the selected data
+type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
+are allowed for the data type identified in the mask, such as text or
+sPLT, only the n'th item in the structure is freed, where n is "seq".
 
 The default behavior is only to free data that was allocated internally
@@ -2202 +2272 @@
 
 The png_free_data() function will turn off the "valid" flag for anything
-it frees.  If you need to turn the flag off for a chunk that was freed by your
-application instead of by libpng, you can use
+it frees.  If you need to turn the flag off for a chunk that was freed by
+your application instead of by libpng, you can use
 
     png_set_invalid(png_ptr, info_ptr, mask);
@@ -2513 +2583 @@
 a PNG datastream that is to be embedded in a MNG datastream).  The third
 parameter is a flag that indicates which filter type(s) are to be tested
-for each scanline.  See the PNG specification for details on the specific filter
-types.
+for each scanline.  See the PNG specification for details on the specific
+filter types.
 
 
@@ -2682 +2752 @@
     png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
        trans_values);
-    trans          - array of transparent entries for
-                     palette (PNG_INFO_tRNS)
+    trans          - array of transparent
+                     entries for palette (PNG_INFO_tRNS)
     trans_values   - graylevel or color sample values
                      (in order red, green, blue) of the
@@ -2723 +2793 @@
     text_ptr[i].translated_keyword  - keyword in UTF-8 (NULL
                          or empty for unknown).
+    Note that the itxt_length, lang, and lang_key
+    members of the text_ptr structure only exist
+    when the library is built with iTXt chunk support.
+
     num_text       - number of comments
 
@@ -2928 +3002 @@
 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
+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);
@@ -3118 +3192 @@
     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 the 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
-these images for you, or you can do them yourself.  If you want to
-build them yourself, see the PNG specification for details of which
-pixels to write when.
+When the file is interlaced, things can get a good deal more complicated.
+The only currently (as of the 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 these images for you, or you can do them
+yourself.  If you want to build them yourself, see the PNG specification
+for details of which pixels to write when.
 
 If you don't want libpng to handle the interlacing details, just
@@ -3137 +3210 @@
        png_set_interlace_handling(png_ptr);
 
-This will return the number of passes needed.  Currently, this
-is seven, but may change if another interlace type is added.
+This will return the number of passes needed.  Currently, this is seven,
+but may change if another interlace type is added.
 
 Then write the complete image number_of_passes times.
@@ -3145 +3218 @@
        number_of_rows);
 
-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.
+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.
 
 .SS Finishing a sequential write
@@ -3180 +3253 @@
 This function may be safely called when the relevant storage has
 already been freed, or has not yet been allocated, or was allocated
-by the user  and not by libpng,  and will in those
-cases do nothing.  The "seq" parameter is ignored if only one item
-of the selected data type, such as PLTE, is allowed.  If "seq" is not
--1, and multiple items are allowed for the data type identified in
-the mask, such as text or sPLT, only the n'th item in the structure
-is freed, where n is "seq".
-
-If you allocated data such as a palette that you passed
-in to libpng with png_set_*, you must not free it until just before the call to
+by the user  and not by libpng,  and will in those cases do nothing.
+The "seq" parameter is ignored if only one item of the selected data
+type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
+are allowed for the data type identified in the mask, such as text or
+sPLT, only the n'th item in the structure is freed, where n is "seq".
+
+If you allocated data such as a palette that you passed in to libpng
+with png_set_*, you must not free it until just before the call to
 png_destroy_write_struct().
 
@@ -3254 +3326 @@
 these functions, call the appropriate png_set_*_fn() function.
 
-Memory allocation is done through the functions png_malloc()
-and png_free().  These currently just call the standard C functions.  If
-your pointers can't access more then 64K at a time, you will want to set
-MAXSEG_64K in zlib.h.  Since it is unlikely that the method of handling
-memory allocation on a platform will change between applications, these
-functions must be modified in the library at compile time.  If you prefer
-to use a different method of allocating and freeing data, you can use
-png_create_read_struct_2() or png_create_write_struct_2() to register
-your own functions as described above.
-These functions also provide a void pointer that can be retrieved via
+Memory allocation is done through the functions png_malloc(), png_calloc(),
+and png_free().  These currently just call the standard C functions.
+png_calloc() calls png_malloc() and then png_memset() to clear the newly
+allocated memory to zero.  If your pointers can't access more then 64K
+at a time, you will want to set MAXSEG_64K in zlib.h.  Since it is
+unlikely that the method of handling memory allocation on a platform
+will change between applications, these functions must be modified in
+the library at compile time.  If you prefer to use a different method
+of allocating and freeing data, you can use png_create_read_struct_2() or
+png_create_write_struct_2() to register your own functions as described
+above.  These functions also provide a void pointer that can be retrieved
+via
 
     mem_ptr=png_get_mem_ptr(png_ptr);
@@ -3355 +3429 @@
 as there is no need to check every return code of every function call.
 However, there are some uncertainties about the status of local variables
-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.  For an alternative approach, you may wish
-to use the "cexcept" facility (see http://cexcept.sourceforge.net).
+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.  For an alternative approach, you
+may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
 
 .SS Custom chunks
@@ -3370 +3444 @@
 
 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.
+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
@@ -3555 +3628 @@
 or all four,
 along with directives to turn on any of the capabilities that you do
-want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable
-the extra transformations but still leave the library fully capable of reading
-and writing PNG files with all known public chunks
-Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive
-produces a library that is incapable of reading or writing ancillary chunks.
-If you are not using the progressive reading capability, you can
-turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse
-this with the INTERLACING capability, which you'll still have).
+want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
+transformations but still leave the library fully capable of reading
+and writing PNG files with all known public chunks. Use of the
+PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
+that is incapable of reading or writing ancillary chunks.  If you are
+not using the progressive reading capability, you can turn that off
+with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
+capability, which you'll still have).
 
 All the reading and writing specific code are in separate files, so the
@@ -3696 +3769 @@
 png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
 png_malloc_default(), and png_free_default() were added.
+
+Support for the iTXt chunk has been enabled by default as of
+version 1.2.41.
 
 Support for certain MNG features was enabled.
@@ -3751 +3827 @@
 when the Intel assembler code was removed due to a licensing issue.
 
+These macros are deprecated:
+
+    PNG_READ_TRANSFORMS_NOT_SUPPORTED
+    PNG_PROGRESSIVE_READ_NOT_SUPPORTED
+    PNG_NO_SEQUENTIAL_READ_SUPPORTED
+    PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
+    PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
+    PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
+
+They have been replaced, respectively, by:
+
+    PNG_NO_READ_TRANSFORMS
+    PNG_NO_PROGRESSIVE_READ
+    PNG_NO_SEQUENTIAL_READ
+    PNG_NO_WRITE_TRANSFORMS
+    PNG_NO_READ_ANCILLARY_CHUNKS
+    PNG_NO_WRITE_ANCILLARY_CHUNKS
+
+PNG_MAX_UINT was replaced with PNG_UINT_31_MAX.  It has been
+deprecated since libpng-1.0.16 and libpng-1.2.6.
+
+The function
+    png_check_sig(sig, num)
+was replaced with
+    !png_sig_cmp(sig, 0, num)
+It has been deprecated since libpng-0.90.
+
+The function
+    png_set_gray_1_2_4_to_8()
+which also expands tRNS to alpha was replaced with
+    png_set_expand_gray_1_2_4_to_8()
+which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
+
 .SH IX.  (Omitted)
+
 
 .SH X. Detecting libpng
@@ -3804 +3914 @@
 are usually indented the same as the first line of the statement
 plus four more spaces.
+
+For macro definitions we use 2-space indentation, always leaving the "#"
+in the first column.
+
+    #ifndef PNG_NO_FEATURE
+    #  ifndef PNG_FEATURE_SUPPORTED
+    #    define PNG_FEATURE_SUPPORTED
+    #  endif
+    #endif
 
 Comments appear with the leading "/*" at the same indentation as
@@ -3869 +3988 @@
 
     for (i = 2; i > 0; --i)
-       x[i] = a(x) + (int)b;
+       y[i] = a(x) + (int)b;
 
 We prefer #ifdef and #ifndef to #if defined() and if !defined()
 when there is only one macro being tested.
 
-Other rules can be inferred by inspecting the libpng
-source.
+We do not use the TAB character for indentation in the C sources.
+
+Lines do not exceed 80 characters.
+
+Other rules can be inferred by inspecting the libpng source.
 
 .SH XIII. Y2K Compliance in libpng
 
-September 10, 2009
+January 3, 2010
 
 Since the PNG Development group is an ad-hoc body, we can't make
@@ -3885 +4007 @@
 
 This is your unofficial assurance that libpng from version 0.71 and
-upward through 1.2.40 are Y2K compliant.  It is my belief that earlier
+upward through 1.2.42 are Y2K compliant.  It is my belief that earlier
 versions were also Y2K compliant.
 
@@ -4164 +4286 @@
  1.0.48              10    10048  10.so.0.48[.0]
  1.2.39              13    10239  12.so.0.39[.0]
+ 1.2.40beta01        13    10240  12.so.0.40[.0]
  1.2.40rc01          13    10240  12.so.0.40[.0]
  1.0.49              10    10049  10.so.0.49[.0]
  1.2.40              13    10240  12.so.0.40[.0]
+ 1.0.50              10    10050  10.so.0.50[.0]
+ 1.2.41beta01-18     13    10241  12.so.0.41[.0]
+ 1.0.51rc01          10    10051  10.so.0.51[.0]
+ 1.2.41rc01-03       13    10241  12.so.0.41[.0]
+ 1.0.51              10    10051  10.so.0.51[.0]
+ 1.2.41              13    10241  12.so.0.41[.0]
+ 1.2.42beta01-02     13    10242  12.so.0.42[.0]
+ 1.2.42rc01-05       13    10242  12.so.0.42[.0]
+ 1.0.52              10    10052  10.so.0.52[.0]
+ 1.2.42              13    10242  12.so.0.42[.0]
 
 Henceforth the source version will match the shared-library minor
@@ -4222 +4355 @@
 Thanks to Frank J. T. Wojcik for helping with the documentation.
 
-Libpng version 1.2.40 - September 10, 2009:
+Libpng version 1.2.42 - January 3, 2010:
 Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
 Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
@@ -4245 +4378 @@
 This code is released under the libpng license.
 
-libpng versions 1.2.6, August 15, 2004, through 1.2.40, September 10, 2009, are
+libpng versions 1.2.6, August 15, 2004, through 1.2.42, January 3, 2010, are
 Copyright (c) 2004,2006-2008 Glenn Randers-Pehrson, and are
 distributed according to the same disclaimer and license as libpng-1.2.5
@@ -4344 +4477 @@
 Glenn Randers-Pehrson
 glennrp at users.sourceforge.net
-September 10, 2009
+January 3, 2010
 
 .\" end of man page