← Back to branch summary

~cosme/ubuntu/precise/freeimage/freeimage-3.15.1

« back to all changes in this revision

Viewing changes to Source/LibPNG/libpng.3

  • Committer: Bazaar Package Importer
  • Author(s): Cosme Domínguez Díaz
  • Date: 2010-07-20 13:42:15 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20100720134215-xt1454zaedv3b604
Tags: 3.13.1-0ubuntu1
https://launchpad.net/bugs/607800
* New upstream release. Closes: (LP: #607800)
 - Updated debian/freeimage-get-orig-source script.
 - Removing no longer necessary debian/patches/* and
   the patch system in debian/rules.
 - Updated debian/rules to work with the new Makefiles.
 - Drop from -O3 to -O2 and use lzma compression saves
   ~10 MB of free space. 
* lintian stuff
 - fixed debhelper-but-no-misc-depends
 - fixed ldconfig-symlink-missing-for-shlib

Show diffs side-by-side

added added

removed removed

Lines of Context:
Source/LibPNG/libpng.3
1
 
.TH LIBPNG 3 "November 6, 2007"
 
1
.TH LIBPNG 3 "December 3, 2009"
2
2
.SH NAME
3
 
libpng \- Portable Network Graphics (PNG) Reference Library 1.2.23
 
3
libpng \- Portable Network Graphics (PNG) Reference Library 1.2.41
4
4
.SH SYNOPSIS
5
5
\fI\fB
6
6
 
821
821
.SH LIBPNG.TXT
822
822
libpng.txt - A description on how to use and modify libpng
823
823
 
824
 
 libpng version 1.2.23 - November 6, 2007
 
824
 libpng version 1.2.41 - December 3, 2009
825
825
 Updated and distributed by Glenn Randers-Pehrson
826
826
 <glennrp at users.sourceforge.net>
827
 
 Copyright (c) 1998-2007 Glenn Randers-Pehrson
828
 
 For conditions of distribution and use, see copyright
829
 
 notice in png.h.
830
 
 
831
 
 based on:
 
827
 Copyright (c) 1998-2009 Glenn Randers-Pehrson
 
828
 
 
829
 This document is released under the libpng license.
 
830
 For conditions of distribution and use, see the disclaimer
 
831
 and license in png.h
 
832
 
 
833
 Based on:
 
834
 
 
835
 libpng versions 0.97, January 1998, through 1.2.41 - December 3, 2009
 
836
 Updated and distributed by Glenn Randers-Pehrson
 
837
 Copyright (c) 1998-2009 Glenn Randers-Pehrson
832
838
 
833
839
 libpng 1.0 beta 6  version 0.96 May 28, 1997
834
840
 Updated and distributed by Andreas Dilger
855
861
INSTALL file for instructions on how to install libpng.
856
862
 
857
863
For examples of libpng usage, see the files "example.c", "pngtest.c",
858
 
and the files in the "contrib" directory, all of which are included in the
859
 
libpng distribution.
 
864
and the files in the "contrib" directory, all of which are included in
 
865
the libpng distribution.
860
866
 
861
867
Libpng was written as a companion to the PNG specification, as a way
862
868
of reducing the amount of time and effort it takes to support the PNG
868
874
The W3C and ISO documents have identical technical content.
869
875
 
870
876
The PNG-1.2 specification is available at
871
 
<http://www.libpng.org/pub/png/documents/>
 
877
<http://www.libpng.org/pub/png/documents/>.  It is technically equivalent
 
878
to the PNG specification (second edition) but has some additional material.
872
879
 
873
880
The PNG-1.0 specification is available
874
881
as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
875
 
W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some
876
 
additional chunks are described in the special-purpose public chunks
 
882
W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
 
883
 
 
884
Some additional chunks are described in the special-purpose public chunks
877
885
documents at <http://www.libpng.org/pub/png/documents/>.
878
886
 
879
887
Other information
956
964
will also want to insure that you are, in fact, dealing with a PNG
957
965
file.  Libpng provides a simple check to see if a file is a PNG file.
958
966
To use it, pass in the first 1 to 8 bytes of the file to the function
959
 
png_sig_cmp(), and it will return 0 if the bytes match the corresponding
960
 
bytes of the PNG signature, or nonzero otherwise.  Of course, the more bytes
961
 
you pass in, the greater the accuracy of the prediction.
 
967
png_sig_cmp(), and it will return 0 (false) if the bytes match the
 
968
corresponding bytes of the PNG signature, or nonzero (true) otherwise.
 
969
Of course, the more bytes you pass in, the greater the accuracy of the
 
970
prediction.
962
971
 
963
972
If you are intending to keep the file pointer open for use in libpng,
964
973
you must ensure you don't read more than 8 bytes from the beginning
1081
1090
         png_unknown_chunkp chunk);
1082
1091
    {
1083
1092
       /* The unknown chunk structure contains your
1084
 
          chunk data: */
 
1093
          chunk data, along with similar data for any other
 
1094
          unknown chunks: */
 
1095
 
1085
1096
           png_byte name[5];
1086
1097
           png_byte *data;
1087
1098
           png_size_t size;
 
1099
 
1088
1100
       /* Note that libpng has already taken care of
1089
1101
          the CRC handling */
1090
1102
 
1091
 
       /* put your code here.  Return one of the
1092
 
          following: */
 
1103
       /* put your code here.  Search for your chunk in the
 
1104
          unknown chunk structure, process it, and return one
 
1105
          of the following: */
1093
1106
 
1094
1107
       return (-n); /* chunk had an error */
1095
1108
       return (0); /* did not recognize */
1109
1122
 
1110
1123
    png_get_user_chunk_ptr(png_ptr);
1111
1124
 
 
1125
If you call the png_set_read_user_chunk_fn() function, then all unknown
 
1126
chunks will be saved when read, in case your callback function will need
 
1127
one or more of them.  This behavior can be changed with the
 
1128
png_set_keep_unknown_chunks() function, described below.
 
1129
 
1112
1130
At this point, you can set up a callback function that will be
1113
1131
called after each row has been read, which you can use to control
1114
1132
a progress meter or the like.  It's demonstrated in pngtest.c.
1126
1144
 
1127
1145
    png_set_read_status_fn(png_ptr, read_row_callback);
1128
1146
 
1129
 
.SS Width and height limits
1130
 
 
1131
 
The PNG specification allows the width and height of an image to be as
1132
 
large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
1133
 
Since very few applications really need to process such large images,
1134
 
we have imposed an arbitrary 1-million limit on rows and columns.
1135
 
Larger images will be rejected immediately with a png_error() call. If
1136
 
you wish to override this limit, you can use
1137
 
 
1138
 
   png_set_user_limits(png_ptr, width_max, height_max);
1139
 
 
1140
 
to set your own limits, or use width_max = height_max = 0x7fffffffL
1141
 
to allow all valid dimensions (libpng may reject some very large images
1142
 
anyway because of potential buffer overflow conditions).
1143
 
 
1144
 
You should put this statement after you create the PNG structure and
1145
 
before calling png_read_info(), png_read_png(), or png_process_data().
1146
 
If you need to retrieve the limits that are being applied, use
1147
 
 
1148
 
   width_max = png_get_user_width_max(png_ptr);
1149
 
   height_max = png_get_user_height_max(png_ptr);
1150
 
 
1151
1147
.SS Unknown-chunk handling
1152
1148
 
1153
1149
Now you get to set the way the library processes unknown chunks in the
1154
1150
input PNG stream. Both known and unknown chunks will be read.  Normal
1155
1151
behavior is that known chunks will be parsed into information in
1156
 
various info_ptr members; unknown chunks will be discarded. To change
1157
 
this, you can call:
 
1152
various info_ptr members while unknown chunks will be discarded. This
 
1153
behavior can be wasteful if your application will never use some known
 
1154
chunk types. To change this, you can call:
1158
1155
 
1159
1156
    png_set_keep_unknown_chunks(png_ptr, keep,
1160
1157
        chunk_list, num_chunks);
1161
 
    keep       - 0: do not handle as unknown
1162
 
                 1: do not keep
 
1158
    keep       - 0: default unknown chunk handling
 
1159
                 1: ignore; do not keep
1163
1160
                 2: keep only if safe-to-copy
1164
1161
                 3: keep even if unsafe-to-copy
1165
1162
               You can use these definitions:
1182
1179
take precedence.  The IHDR and IEND chunks should not be named in
1183
1180
chunk_list; if they are, libpng will process them normally anyway.
1184
1181
 
 
1182
Here is an example of the usage of png_set_keep_unknown_chunks(),
 
1183
where the private "vpAg" chunk will later be processed by a user chunk
 
1184
callback function:
 
1185
 
 
1186
    png_byte vpAg[5]={118, 112,  65, 103, (png_byte) '\0'};
 
1187
 
 
1188
    #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
 
1189
      png_byte unused_chunks[]=
 
1190
      {
 
1191
        104,  73,  83,  84, (png_byte) '\0',   /* hIST */
 
1192
        105,  84,  88, 116, (png_byte) '\0',   /* iTXt */
 
1193
        112,  67,  65,  76, (png_byte) '\0',   /* pCAL */
 
1194
        115,  67,  65,  76, (png_byte) '\0',   /* sCAL */
 
1195
        115,  80,  76,  84, (png_byte) '\0',   /* sPLT */
 
1196
        116,  73,  77,  69, (png_byte) '\0',   /* tIME */
 
1197
      };
 
1198
    #endif
 
1199
 
 
1200
    ...
 
1201
 
 
1202
    #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
 
1203
      /* ignore all unknown chunks: */
 
1204
      png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
 
1205
      /* except for vpAg: */
 
1206
      png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
 
1207
      /* also ignore unused known chunks: */
 
1208
      png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
 
1209
         (int)sizeof(unused_chunks)/5);
 
1210
    #endif
 
1211
 
 
1212
.SS User limits
 
1213
 
 
1214
The PNG specification allows the width and height of an image to be as
 
1215
large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
 
1216
Since very few applications really need to process such large images,
 
1217
we have imposed an arbitrary 1-million limit on rows and columns.
 
1218
Larger images will be rejected immediately with a png_error() call. If
 
1219
you wish to override this limit, you can use
 
1220
 
 
1221
   png_set_user_limits(png_ptr, width_max, height_max);
 
1222
 
 
1223
to set your own limits, or use width_max = height_max = 0x7fffffffL
 
1224
to allow all valid dimensions (libpng may reject some very large images
 
1225
anyway because of potential buffer overflow conditions).
 
1226
 
 
1227
You should put this statement after you create the PNG structure and
 
1228
before calling png_read_info(), png_read_png(), or png_process_data().
 
1229
If you need to retrieve the limits that are being applied, use
 
1230
 
 
1231
   width_max = png_get_user_width_max(png_ptr);
 
1232
   height_max = png_get_user_height_max(png_ptr);
 
1233
 
 
1234
The PNG specification sets no limit on the number of ancillary chunks
 
1235
allowed in a PNG datastream.  You can impose a limit on the total number
 
1236
of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
 
1237
 
 
1238
   png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
 
1239
 
 
1240
where 0x7fffffffL means unlimited.  You can retrieve this limit with
 
1241
 
 
1242
   chunk_cache_max = png_get_chunk_cache_max(png_ptr);
 
1243
 
 
1244
This limit also applies to the number of buffers that can be allocated
 
1245
by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
 
1246
 
1185
1247
.SS The high-level read interface
1186
1248
 
1187
1249
At this point there are two ways to proceed; through the high-level
1209
1271
    PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
1210
1272
                                to transparency
1211
1273
    PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
 
1274
    PNG_TRANSFORM_GRAY_TO_RGB   Expand grayscale samples
 
1275
                                to RGB (or GA to RGBA)
1212
1276
 
1213
1277
(This excludes setting a background color, doing gamma transformation,
1214
1278
dithering, and setting filler.)  If this is the case, simply do this:
1215
1279
 
1216
1280
    png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1217
1281
 
1218
 
where png_transforms is an integer containing the bitwise OR of
1219
 
some set of transformation flags.  This call is equivalent to png_read_info(),
 
1282
where png_transforms is an integer containing the bitwise OR of some
 
1283
set of transformation flags.  This call is equivalent to png_read_info(),
1220
1284
followed the set of transformations indicated by the transform mask,
1221
1285
then png_read_image(), and finally png_read_end().
1222
1286
 
1247
1311
   row_pointers = png_malloc(png_ptr,
1248
1312
      height*png_sizeof(png_bytep));
1249
1313
   for (int i=0; i<height, i++)
 
1314
      row_pointers[i]=NULL;  /* security precaution */
 
1315
   for (int i=0; i<height, i++)
1250
1316
      row_pointers[i]=png_malloc(png_ptr,
1251
1317
         width*pixel_size);
1252
1318
   png_set_rows(png_ptr, info_ptr, &row_pointers);
1315
1381
                     for PNG 1.0)
1316
1382
    interlace_type - (PNG_INTERLACE_NONE or
1317
1383
                     PNG_INTERLACE_ADAM7)
1318
 
    Any or all of interlace_type, compression_type, of
 
1384
 
 
1385
    Any or all of interlace_type, compression_type, or
1319
1386
    filter_method can be NULL if you are
1320
1387
    not interested in their values.
1321
1388
 
 
1389
    Note that png_get_IHDR() returns 32-bit data into
 
1390
    the application's width and height variables.
 
1391
    This is an unsafe situation if these are 16-bit
 
1392
    variables.  In such situations, the
 
1393
    png_get_image_width() and png_get_image_height()
 
1394
    functions described below are safer.
 
1395
 
 
1396
    width            = png_get_image_width(png_ptr,
 
1397
                         info_ptr);
 
1398
    height           = png_get_image_height(png_ptr,
 
1399
                         info_ptr);
 
1400
    bit_depth        = png_get_bit_depth(png_ptr,
 
1401
                         info_ptr);
 
1402
    color_type       = png_get_color_type(png_ptr,
 
1403
                         info_ptr);
 
1404
    filter_method    = png_get_filter_type(png_ptr,
 
1405
                         info_ptr);
 
1406
    compression_type = png_get_compression_type(png_ptr,
 
1407
                         info_ptr);
 
1408
    interlace_type   = png_get_interlace_type(png_ptr,
 
1409
                         info_ptr);
 
1410
 
1322
1411
    channels = png_get_channels(png_ptr, info_ptr);
1323
1412
    channels       - number of channels of info for the
1324
1413
                     color type (valid values are 1 (GRAY,
1338
1427
                     be in signature[4] through signature[7]
1339
1428
                     (see png_set_sig_bytes())).
1340
1429
 
1341
 
 
1342
 
    width            = png_get_image_width(png_ptr,
1343
 
                         info_ptr);
1344
 
    height           = png_get_image_height(png_ptr,
1345
 
                         info_ptr);
1346
 
    bit_depth        = png_get_bit_depth(png_ptr,
1347
 
                         info_ptr);
1348
 
    color_type       = png_get_color_type(png_ptr,
1349
 
                         info_ptr);
1350
 
    filter_method    = png_get_filter_type(png_ptr,
1351
 
                         info_ptr);
1352
 
    compression_type = png_get_compression_type(png_ptr,
1353
 
                         info_ptr);
1354
 
    interlace_type   = png_get_interlace_type(png_ptr,
1355
 
                         info_ptr);
1356
 
 
1357
 
 
1358
1430
These are also important, but their validity depends on whether the chunk
1359
1431
has been read.  The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
1360
1432
png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
1361
1433
data has been read, or zero if it is missing.  The parameters to the
1362
 
png_get_<chunk> are set directly if they are simple data types, or a pointer
1363
 
into the info_ptr is returned for any complex types.
 
1434
png_get_<chunk> are set directly if they are simple data types, or a
 
1435
pointer into the info_ptr is returned for any complex types.
1364
1436
 
1365
1437
    png_get_PLTE(png_ptr, info_ptr, &palette,
1366
1438
                     &num_palette);
1400
1472
 
1401
1473
    png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
1402
1474
                     &trans_values);
1403
 
    trans          - array of transparent entries for
1404
 
                     palette (PNG_INFO_tRNS)
 
1475
    trans          - array of transparent
 
1476
                     entries for palette (PNG_INFO_tRNS)
1405
1477
    trans_values   - graylevel or color sample values of
1406
1478
                     the single transparent color for
1407
1479
                     non-paletted images (PNG_INFO_tRNS)
1444
1516
                         string for unknown).
1445
1517
    text_ptr[i].lang_key  - keyword in UTF-8
1446
1518
                         (empty string for unknown).
 
1519
    Note that the itxt_length, lang, and lang_key
 
1520
    members of the text_ptr structure only exist
 
1521
    when the library is built with iTXt chunk support.
 
1522
 
1447
1523
    num_text       - number of comments (same as
1448
1524
                     num_comments; you can put NULL here
1449
1525
                     to avoid the duplication)
1622
1698
 
1623
1699
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
1624
1700
added.  It expands the sample depth without changing tRNS to alpha.
1625
 
At the same time, png_set_gray_1_2_4_to_8() was deprecated, and it
1626
 
will be removed from a future version.
 
1701
 
 
1702
As of libpng version 1.2.41, not all possible expansions are supported.
 
1703
 
 
1704
In the following table, the 01 means grayscale with depth<8, 31 means
 
1705
indexed with depth<8, other numerals represent the color type, "T" means
 
1706
the tRNS chunk is present, A means an alpha channel is present, and O
 
1707
means tRNS or alpha is present but all pixels in the image are opaque.
 
1708
 
 
1709
  FROM  01  31   0  0T  0O   2  2T  2O   3  3T  3O  4A  4O  6A  6O 
 
1710
   TO
 
1711
   01    -                   
 
1712
   31        -
 
1713
    0    1       -           
 
1714
   0T                -
 
1715
   0O                    -
 
1716
    2           GX           -
 
1717
   2T                            -
 
1718
   2O                                -
 
1719
    3        1                           -
 
1720
   3T                                        -
 
1721
   3O                                            -
 
1722
   4A                T                               -
 
1723
   4O                                                    -
 
1724
   6A               GX         TX           TX               -
 
1725
   6O                   GX                      TX               -
 
1726
 
 
1727
Within the matrix,
 
1728
     "-" means the transformation is not supported.
 
1729
     "X" means the transformation is obtained by png_set_expand().
 
1730
     "1" means the transformation is obtained by
 
1731
         png_set_expand_gray_1_2_4_to_8
 
1732
     "G" means the transformation is obtained by
 
1733
         png_set_gray_to_rgb().
 
1734
     "P" means the transformation is obtained by
 
1735
         png_set_expand_palette_to_rgb().
 
1736
     "T" means the transformation is obtained by
 
1737
         png_set_tRNS_to_alpha().
1627
1738
 
1628
1739
PNG can have files with 16 bits per channel.  If you only can handle
1629
1740
8 bits per channel, this will strip the pixels down to 8 bit.
1648
1759
 
1649
1760
    png_set_invert_alpha(png_ptr);
1650
1761
 
 
1762
The PNG format only supports pixels with postmultiplied alpha.
 
1763
If you want to replace the pixels, after reading them, with pixels
 
1764
that have premultiplied color samples, you can do this with
 
1765
 
 
1766
    png_set_premultiply_alpha(png_ptr);
 
1767
 
 
1768
If you do this, any input with a tRNS chunk will be expanded to
 
1769
have an alpha channel.
 
1770
 
1651
1771
PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1652
1772
they can, resulting in, for example, 8 pixels per byte for 1 bit
1653
1773
files.  This code expands to 1 pixel per byte without changing the
1658
1778
 
1659
1779
PNG files have possible bit depths of 1, 2, 4, 8, and 16.  All pixels
1660
1780
stored in a PNG image have been "scaled" or "shifted" up to the next
1661
 
higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
1662
 
8 bits/sample in the range [0, 255]).  However, it is also possible to
1663
 
convert the PNG pixel data back to the original bit depth of the image.
1664
 
This call reduces the pixels back down to the original bit depth:
 
1781
higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
 
1782
to 8 bits/sample in the range [0, 255]).  However, it is also possible
 
1783
to convert the PNG pixel data back to the original bit depth of the
 
1784
image.  This call reduces the pixels back down to the original bit depth:
1665
1785
 
1666
1786
    png_color_8p sig_bit;
1667
1787
 
2108
2228
 
2109
2229
This function may be safely called when the relevant storage has
2110
2230
already been freed, or has not yet been allocated, or was allocated
2111
 
by the user and not by libpng,  and will in those
2112
 
cases do nothing.  The "seq" parameter is ignored if only one item
2113
 
of the selected data type, such as PLTE, is allowed.  If "seq" is not
2114
 
-1, and multiple items are allowed for the data type identified in
2115
 
the mask, such as text or sPLT, only the n'th item in the structure
2116
 
is freed, where n is "seq".
 
2231
by the user and not by libpng,  and will in those cases do nothing.
 
2232
The "seq" parameter is ignored if only one item of the selected data
 
2233
type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
 
2234
are allowed for the data type identified in the mask, such as text or
 
2235
sPLT, only the n'th item in the structure is freed, where n is "seq".
2117
2236
 
2118
2237
The default behavior is only to free data that was allocated internally
2119
2238
by libpng.  This can be changed, so that libpng will not free the data,
2152
2271
application, your application must not separately free those members.
2153
2272
 
2154
2273
The png_free_data() function will turn off the "valid" flag for anything
2155
 
it frees.  If you need to turn the flag off for a chunk that was freed by your
2156
 
application instead of by libpng, you can use
 
2274
it frees.  If you need to turn the flag off for a chunk that was freed by
 
2275
your application instead of by libpng, you can use
2157
2276
 
2158
2277
    png_set_invalid(png_ptr, info_ptr, mask);
2159
2278
    mask - identifies the chunks to be made invalid,
2463
2582
July 1999 PNG specification, version 1.2) or 64 (if you are writing
2464
2583
a PNG datastream that is to be embedded in a MNG datastream).  The third
2465
2584
parameter is a flag that indicates which filter type(s) are to be tested
2466
 
for each scanline.  See the PNG specification for details on the specific filter
2467
 
types.
 
2585
for each scanline.  See the PNG specification for details on the specific
 
2586
filter types.
2468
2587
 
2469
2588
 
2470
2589
    /* turn on or off filtering, and/or choose
2475
2594
       PNG_FILTER_NONE  | PNG_FILTER_VALUE_NONE |
2476
2595
       PNG_FILTER_SUB   | PNG_FILTER_VALUE_SUB  |
2477
2596
       PNG_FILTER_UP    | PNG_FILTER_VALUE_UP   |
2478
 
       PNG_FILTER_AVE   | PNG_FILTER_VALUE_AVE  |
 
2597
       PNG_FILTER_AVG   | PNG_FILTER_VALUE_AVG  |
2479
2598
       PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2480
2599
       PNG_ALL_FILTERS);
2481
2600
 
2564
2683
                     can also be
2565
2684
                     PNG_INTRAPIXEL_DIFFERENCING)
2566
2685
 
 
2686
If you call png_set_IHDR(), the call must appear before any of the
 
2687
other png_set_*() functions, because they might require access to some of
 
2688
the IHDR settings.  The remaining png_set_*() functions can be called
 
2689
in any order.
 
2690
 
 
2691
If you wish, you can reset the compression_type, interlace_type, or
 
2692
filter_method later by calling png_set_IHDR() again; if you do this, the
 
2693
width, height, bit_depth, and color_type must be the same in each call.
 
2694
 
2567
2695
    png_set_PLTE(png_ptr, info_ptr, palette,
2568
2696
       num_palette);
2569
2697
    palette        - the palette for the file
2623
2751
 
2624
2752
    png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
2625
2753
       trans_values);
2626
 
    trans          - array of transparent entries for
2627
 
                     palette (PNG_INFO_tRNS)
2628
 
    trans_values   - graylevel or color sample values of
2629
 
                     the single transparent color for
 
2754
    trans          - array of transparent
 
2755
                     entries for palette (PNG_INFO_tRNS)
 
2756
    trans_values   - graylevel or color sample values
 
2757
                     (in order red, green, blue) of the
 
2758
                     single transparent color for
2630
2759
                     non-paletted images (PNG_INFO_tRNS)
2631
2760
    num_trans      - number of transparent entries
2632
2761
                     (PNG_INFO_tRNS)
2663
2792
                         empty for unknown).
2664
2793
    text_ptr[i].translated_keyword  - keyword in UTF-8 (NULL
2665
2794
                         or empty for unknown).
 
2795
    Note that the itxt_length, lang, and lang_key
 
2796
    members of the text_ptr structure only exist
 
2797
    when the library is built with iTXt chunk support.
 
2798
 
2666
2799
    num_text       - number of comments
2667
2800
 
2668
2801
    png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
2835
2968
    PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
2836
2969
                                to transparency
2837
2970
    PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
2838
 
    PNG_TRANSFORM_STRIP_FILLER  Strip out filler bytes.
 
2971
    PNG_TRANSFORM_STRIP_FILLER        Strip out filler
 
2972
                                      bytes (deprecated).
 
2973
    PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
 
2974
                                      filler bytes
 
2975
    PNG_TRANSFORM_STRIP_FILLER_AFTER  Strip out trailing
 
2976
                                      filler bytes
2839
2977
 
2840
2978
If you have valid image data in the info structure (you can use
2841
2979
png_set_rows() to put image data in the info structure), simply do this:
2863
3001
 
2864
3002
Note that there is one transformation you may need to do before
2865
3003
png_write_info().  In PNG files, the alpha channel in an image is the
2866
 
level of opacity.  If your data is supplied as a level of
2867
 
transparency, you can invert the alpha channel before you write it, so
2868
 
that 0 is fully transparent and 255 (in 8-bit or paletted images) or
2869
 
65535 (in 16-bit images) is fully opaque, with
 
3004
level of opacity.  If your data is supplied as a level of transparency,
 
3005
you can invert the alpha channel before you write it, so that 0 is
 
3006
fully transparent and 255 (in 8-bit or paletted images) or 65535
 
3007
(in 16-bit images) is fully opaque, with
2870
3008
 
2871
3009
    png_set_invert_alpha(png_ptr);
2872
3010
 
3053
3191
 
3054
3192
    png_write_row(png_ptr, row_pointer);
3055
3193
 
3056
 
When the file is interlaced, things can get a good deal more
3057
 
complicated.  The only currently (as of the PNG Specification
3058
 
version 1.2, dated July 1999) defined interlacing scheme for PNG files
3059
 
is the "Adam7" interlace scheme, that breaks down an
3060
 
image into seven smaller images of varying size.  libpng will build
3061
 
these images for you, or you can do them yourself.  If you want to
3062
 
build them yourself, see the PNG specification for details of which
3063
 
pixels to write when.
 
3194
When the file is interlaced, things can get a good deal more complicated.
 
3195
The only currently (as of the PNG Specification version 1.2, dated July
 
3196
1999) defined interlacing scheme for PNG files is the "Adam7" interlace
 
3197
scheme, that breaks down an image into seven smaller images of varying
 
3198
size.  libpng will build these images for you, or you can do them
 
3199
yourself.  If you want to build them yourself, see the PNG specification
 
3200
for details of which pixels to write when.
3064
3201
 
3065
3202
If you don't want libpng to handle the interlacing details, just
3066
3203
use png_set_interlace_handling() and call png_write_rows() the
3072
3209
    number_of_passes =
3073
3210
       png_set_interlace_handling(png_ptr);
3074
3211
 
3075
 
This will return the number of passes needed.  Currently, this
3076
 
is seven, but may change if another interlace type is added.
 
3212
This will return the number of passes needed.  Currently, this is seven,
 
3213
but may change if another interlace type is added.
3077
3214
 
3078
3215
Then write the complete image number_of_passes times.
3079
3216
 
3080
3217
    png_write_rows(png_ptr, row_pointers,
3081
3218
       number_of_rows);
3082
3219
 
3083
 
As some of these rows are not used, and thus return immediately,
3084
 
you may want to read about interlacing in the PNG specification,
3085
 
and only update the rows that are actually used.
 
3220
As some of these rows are not used, and thus return immediately, you may
 
3221
want to read about interlacing in the PNG specification, and only update
 
3222
the rows that are actually used.
3086
3223
 
3087
3224
.SS Finishing a sequential write
3088
3225
 
3115
3252
 
3116
3253
This function may be safely called when the relevant storage has
3117
3254
already been freed, or has not yet been allocated, or was allocated
3118
 
by the user  and not by libpng,  and will in those
3119
 
cases do nothing.  The "seq" parameter is ignored if only one item
3120
 
of the selected data type, such as PLTE, is allowed.  If "seq" is not
3121
 
-1, and multiple items are allowed for the data type identified in
3122
 
the mask, such as text or sPLT, only the n'th item in the structure
3123
 
is freed, where n is "seq".
 
3255
by the user  and not by libpng,  and will in those cases do nothing.
 
3256
The "seq" parameter is ignored if only one item of the selected data
 
3257
type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
 
3258
are allowed for the data type identified in the mask, such as text or
 
3259
sPLT, only the n'th item in the structure is freed, where n is "seq".
3124
3260
 
3125
 
If you allocated data such as a palette that you passed
3126
 
in to libpng with png_set_*, you must not free it until just before the call to
 
3261
If you allocated data such as a palette that you passed in to libpng
 
3262
with png_set_*, you must not free it until just before the call to
3127
3263
png_destroy_write_struct().
3128
3264
 
3129
3265
The default behavior is only to free data that was allocated internally
3189
3325
in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively.  To change
3190
3326
these functions, call the appropriate png_set_*_fn() function.
3191
3327
 
3192
 
Memory allocation is done through the functions png_malloc()
3193
 
and png_free().  These currently just call the standard C functions.  If
3194
 
your pointers can't access more then 64K at a time, you will want to set
3195
 
MAXSEG_64K in zlib.h.  Since it is unlikely that the method of handling
3196
 
memory allocation on a platform will change between applications, these
3197
 
functions must be modified in the library at compile time.  If you prefer
3198
 
to use a different method of allocating and freeing data, you can use
3199
 
png_create_read_struct_2() or png_create_write_struct_2() to register
3200
 
your own functions as described above.
3201
 
These functions also provide a void pointer that can be retrieved via
 
3328
Memory allocation is done through the functions png_malloc(), png_calloc(),
 
3329
and png_free().  These currently just call the standard C functions.
 
3330
png_calloc() calls png_malloc() and then png_memset() to clear the newly
 
3331
allocated memory to zero.  If your pointers can't access more then 64K
 
3332
at a time, you will want to set MAXSEG_64K in zlib.h.  Since it is
 
3333
unlikely that the method of handling memory allocation on a platform
 
3334
will change between applications, these functions must be modified in
 
3335
the library at compile time.  If you prefer to use a different method
 
3336
of allocating and freeing data, you can use png_create_read_struct_2() or
 
3337
png_create_write_struct_2() to register your own functions as described
 
3338
above.  These functions also provide a void pointer that can be retrieved
 
3339
via
3202
3340
 
3203
3341
    mem_ptr=png_get_mem_ptr(png_ptr);
3204
3342
 
3212
3350
function will normally call png_error() if it receives a NULL from the
3213
3351
system memory allocator or from your replacement malloc_fn().
3214
3352
 
 
3353
Your free_fn() will never be called with a NULL ptr, since libpng's
 
3354
png_free() checks for NULL before calling free_fn().
 
3355
 
3215
3356
Input/Output in libpng is done through png_read() and png_write(),
3216
3357
which currently just call fread() and fwrite().  The FILE * is stored in
3217
3358
png_struct and is initialized via png_init_io().  If you wish to change
3239
3380
        png_bytep data, png_size_t length);
3240
3381
    void user_flush_data(png_structp png_ptr);
3241
3382
 
 
3383
The user_read_data() function is responsible for detecting and
 
3384
handling end-of-data errors.
 
3385
 
3242
3386
Supplying NULL for the read, write, or flush functions sets them back
3243
 
to using the default C stream functions.  It is an error to read from
3244
 
a write stream, and vice versa.
 
3387
to using the default C stream functions, which expect the io_ptr to
 
3388
point to a standard *FILE structure.  It is probably a mistake
 
3389
to use NULL for one of write_data_fn and output_flush_fn but not both
 
3390
of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
 
3391
It is an error to read from a write stream, and vice versa.
3245
3392
 
3246
3393
Error handling in libpng is done through png_error() and png_warning().
3247
3394
Errors handled through png_error() are fatal, meaning that png_error()
3281
3428
catch exception handling methods.  This makes the code much easier to write,
3282
3429
as there is no need to check every return code of every function call.
3283
3430
However, there are some uncertainties about the status of local variables
3284
 
after a longjmp, so the user may want to be careful about doing anything after
3285
 
setjmp returns non-zero besides returning itself.  Consult your compiler
3286
 
documentation for more details.  For an alternative approach, you may wish
3287
 
to use the "cexcept" facility (see http://cexcept.sourceforge.net).
 
3431
after a longjmp, so the user may want to be careful about doing anything
 
3432
after setjmp returns non-zero besides returning itself.  Consult your
 
3433
compiler documentation for more details.  For an alternative approach, you
 
3434
may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
3288
3435
 
3289
3436
.SS Custom chunks
3290
3437
 
3296
3443
chunk and existing `intrinsic' chunks.
3297
3444
 
3298
3445
If you need to write a new intrinsic chunk, first read the PNG
3299
 
specification. Acquire a first level of
3300
 
understanding of how it works.  Pay particular attention to the
3301
 
sections that describe chunk names, and look at how other chunks were
3302
 
designed, so you can do things similarly.  Second, check out the
3303
 
sections of libpng that read and write chunks.  Try to find a chunk
3304
 
that is similar to yours and use it as a template.  More details can
3305
 
be found in the comments inside the code.  It is best to handle unknown
3306
 
chunks in a generic method, via callback functions, instead of by
3307
 
modifying libpng functions.
 
3446
specification. Acquire a first level of understanding of how it works.
 
3447
Pay particular attention to the sections that describe chunk names,
 
3448
and look at how other chunks were designed, so you can do things
 
3449
similarly.  Second, check out the sections of libpng that read and
 
3450
write chunks.  Try to find a chunk that is similar to yours and use
 
3451
it as a template.  More details can be found in the comments inside
 
3452
the code.  It is best to handle unknown chunks in a generic method,
 
3453
via callback functions, instead of by modifying libpng functions.
3308
3454
 
3309
3455
If you wish to write your own transformation for the data, look through
3310
3456
the part of the code that does the transformations, and check out some of
3346
3492
 
3347
3493
.SS Configuring for compiler xxx:
3348
3494
 
3349
 
All includes for libpng are in pngconf.h.  If you need to add/change/delete
3350
 
an include, this is the place to do it.  The includes that are not
3351
 
needed outside libpng are protected by the PNG_INTERNAL definition,
3352
 
which is only defined for those routines inside libpng itself.  The
3353
 
files in libpng proper only include png.h, which includes pngconf.h.
 
3495
All includes for libpng are in pngconf.h.  If you need to add, change
 
3496
or delete an include, this is the place to do it.
 
3497
The includes that are not needed outside libpng are protected by the
 
3498
PNG_INTERNAL definition, which is only defined for those routines inside
 
3499
libpng itself.  The files in libpng proper only include png.h, which
 
3500
includes pngconf.h.
3354
3501
 
3355
3502
.SS Configuring zlib:
3356
3503
 
3419
3566
is called for the first time.)
3420
3567
 
3421
3568
    filters = PNG_FILTER_NONE | PNG_FILTER_SUB
3422
 
              PNG_FILTER_UP | PNG_FILTER_AVE |
 
3569
              PNG_FILTER_UP | PNG_FILTER_AVG |
3423
3570
              PNG_FILTER_PAETH | PNG_ALL_FILTERS;
3424
3571
 
3425
3572
    png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
3480
3627
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
3481
3628
or all four,
3482
3629
along with directives to turn on any of the capabilities that you do
3483
 
want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable
3484
 
the extra transformations but still leave the library fully capable of reading
3485
 
and writing PNG files with all known public chunks
3486
 
Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive
3487
 
produces a library that is incapable of reading or writing ancillary chunks.
3488
 
If you are not using the progressive reading capability, you can
3489
 
turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse
3490
 
this with the INTERLACING capability, which you'll still have).
 
3630
want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
 
3631
transformations but still leave the library fully capable of reading
 
3632
and writing PNG files with all known public chunks. Use of the
 
3633
PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
 
3634
that is incapable of reading or writing ancillary chunks.  If you are
 
3635
not using the progressive reading capability, you can turn that off
 
3636
with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
 
3637
capability, which you'll still have).
3491
3638
 
3492
3639
All the reading and writing specific code are in separate files, so the
3493
3640
linker should only grab the files it needs.  However, if you want to
3541
3688
having level = 0 will be printed.  There aren't any such statements in
3542
3689
this version of libpng, but if you insert some they will be printed.
3543
3690
 
3544
 
.SH VII.  MNG support
 
3691
.SH VI.  MNG support
3545
3692
 
3546
3693
The MNG specification (available at http://www.libpng.org/pub/mng) allows
3547
3694
certain extensions to PNG for PNG images that are embedded in MNG datastreams.
3566
3713
them.  You may wish to consider using libmng (available at
3567
3714
http://www.libmng.com) instead.
3568
3715
 
3569
 
.SH VIII.  Changes to Libpng from version 0.88
 
3716
.SH VII.  Changes to Libpng from version 0.88
3570
3717
 
3571
3718
It should be noted that versions of libpng later than 0.96 are not
3572
3719
distributed by the original libpng author, Guy Schalnat, nor by
3615
3762
 
3616
3763
   png_uint_32 application_vn = PNG_LIBPNG_VER;
3617
3764
 
3618
 
.SH IX. Y2K Compliance in libpng
3619
 
 
3620
 
November 6, 2007
 
3765
.SH VIII.  Changes to Libpng from version 1.0.x to 1.2.x
 
3766
 
 
3767
Support for user memory management was enabled by default.  To
 
3768
accomplish this, the functions png_create_read_struct_2(),
 
3769
png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
 
3770
png_malloc_default(), and png_free_default() were added.
 
3771
 
 
3772
Support for the iTXt chunk has been enabled by default as of
 
3773
version 1.2.41.
 
3774
 
 
3775
Support for certain MNG features was enabled.
 
3776
 
 
3777
Support for numbered error messages was added.  However, we never got
 
3778
around to actually numbering the error messages.  The function
 
3779
png_set_strip_error_numbers() was added (Note: the prototype for this
 
3780
function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
 
3781
builds of libpng-1.2.15.  It was restored in libpng-1.2.36).
 
3782
 
 
3783
The png_malloc_warn() function was added at libpng-1.2.3.  This issues
 
3784
a png_warning and returns NULL instead of aborting when it fails to
 
3785
acquire the requested memory allocation.
 
3786
 
 
3787
Support for setting user limits on image width and height was enabled
 
3788
by default.  The functions png_set_user_limits(), png_get_user_width_max(),
 
3789
and png_get_user_height_max() were added at libpng-1.2.6.
 
3790
 
 
3791
The png_set_add_alpha() function was added at libpng-1.2.7.
 
3792
 
 
3793
The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
 
3794
Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
 
3795
tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
 
3796
deprecated.
 
3797
 
 
3798
A number of macro definitions in support of runtime selection of
 
3799
assembler code features (especially Intel MMX code support) were
 
3800
added at libpng-1.2.0:
 
3801
 
 
3802
    PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
 
3803
    PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
 
3804
    PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
 
3805
    PNG_ASM_FLAG_MMX_READ_INTERLACE
 
3806
    PNG_ASM_FLAG_MMX_READ_FILTER_SUB
 
3807
    PNG_ASM_FLAG_MMX_READ_FILTER_UP
 
3808
    PNG_ASM_FLAG_MMX_READ_FILTER_AVG
 
3809
    PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
 
3810
    PNG_ASM_FLAGS_INITIALIZED
 
3811
    PNG_MMX_READ_FLAGS
 
3812
    PNG_MMX_FLAGS
 
3813
    PNG_MMX_WRITE_FLAGS
 
3814
    PNG_MMX_FLAGS
 
3815
 
 
3816
We added the following functions in support of runtime
 
3817
selection of assembler code features:
 
3818
 
 
3819
    png_get_mmx_flagmask()
 
3820
    png_set_mmx_thresholds()
 
3821
    png_get_asm_flags()
 
3822
    png_get_mmx_bitdepth_threshold()
 
3823
    png_get_mmx_rowbytes_threshold()
 
3824
    png_set_asm_flags()
 
3825
 
 
3826
We replaced all of these functions with simple stubs in libpng-1.2.20,
 
3827
when the Intel assembler code was removed due to a licensing issue.
 
3828
 
 
3829
These macros are deprecated:
 
3830
 
 
3831
    PNG_READ_TRANSFORMS_NOT_SUPPORTED
 
3832
    PNG_PROGRESSIVE_READ_NOT_SUPPORTED
 
3833
    PNG_NO_SEQUENTIAL_READ_SUPPORTED
 
3834
    PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
 
3835
    PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
 
3836
    PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
 
3837
 
 
3838
They have been replaced, respectively, by:
 
3839
 
 
3840
    PNG_NO_READ_TRANSFORMS
 
3841
    PNG_NO_PROGRESSIVE_READ
 
3842
    PNG_NO_SEQUENTIAL_READ
 
3843
    PNG_NO_WRITE_TRANSFORMS
 
3844
    PNG_NO_READ_ANCILLARY_CHUNKS
 
3845
    PNG_NO_WRITE_ANCILLARY_CHUNKS
 
3846
 
 
3847
PNG_MAX_UINT was replaced with PNG_UINT_31_MAX.  It has been
 
3848
deprecated since libpng-1.0.16 and libpng-1.2.6.
 
3849
 
 
3850
The function
 
3851
    png_check_sig(sig, num)
 
3852
was replaced with
 
3853
    !png_sig_cmp(sig, 0, num)
 
3854
It has been deprecated since libpng-0.90.
 
3855
 
 
3856
The function
 
3857
    png_set_gray_1_2_4_to_8()
 
3858
which also expands tRNS to alpha was replaced with
 
3859
    png_set_expand_gray_1_2_4_to_8()
 
3860
which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
 
3861
.SH IX.  (Omitted)
 
3862
.SH X. Detecting libpng
 
3863
 
 
3864
The png_get_io_ptr() function has been present since libpng-0.88, has never
 
3865
changed, and is unaffected by conditional compilation macros.  It is the
 
3866
best choice for use in configure scripts for detecting the presence of any
 
3867
libpng version since 0.88.  In an autoconf "configure.in" you could use
 
3868
 
 
3869
    AC_CHECK_LIB(png, png_get_io_ptr, ...
 
3870
 
 
3871
.SH XI. Source code repository
 
3872
 
 
3873
Since about February 2009, version 1.2.34, libpng has been under "git" source
 
3874
control.  The git repository was built from old libpng-x.y.z.tar.gz files
 
3875
going back to version 0.70.  You can access the git repository (read only)
 
3876
at
 
3877
 
 
3878
    git://libpng.git.sourceforge.net/gitroot/libpng
 
3879
 
 
3880
or you can browse it via "gitweb" at
 
3881
 
 
3882
    http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
 
3883
 
 
3884
Patches can be sent to glennrp at users.sourceforge.net or to
 
3885
png-mng-implement at lists.sourceforge.net or you can upload them to
 
3886
the libpng bug tracker at
 
3887
 
 
3888
    http://libpng.sourceforge.net
 
3889
 
 
3890
.SH XII. Coding style
 
3891
 
 
3892
Our coding style is similar to the "Allman" style, with curly
 
3893
braces on separate lines:
 
3894
 
 
3895
    if (condition)
 
3896
    {
 
3897
       action;
 
3898
    }
 
3899
 
 
3900
    else if (another condition)
 
3901
    {
 
3902
       another action;
 
3903
    }
 
3904
 
 
3905
The braces can be omitted from simple one-line actions:
 
3906
 
 
3907
    if (condition)
 
3908
       return (0);
 
3909
 
 
3910
We use 3-space indentation, except for continued statements which
 
3911
are usually indented the same as the first line of the statement
 
3912
plus four more spaces.
 
3913
 
 
3914
For macro definitions we use 2-space indentation, always leaving the "#"
 
3915
in the first column.
 
3916
 
 
3917
    #ifndef PNG_NO_FEATURE
 
3918
    #  ifndef PNG_FEATURE_SUPPORTED
 
3919
    #    define PNG_FEATURE_SUPPORTED
 
3920
    #  endif
 
3921
    #endif
 
3922
 
 
3923
Comments appear with the leading "/*" at the same indentation as
 
3924
the statement that follows the comment:
 
3925
 
 
3926
    /* Single-line comment */
 
3927
    statement;
 
3928
 
 
3929
    /* Multiple-line
 
3930
     * comment
 
3931
     */
 
3932
    statement;
 
3933
 
 
3934
Very short comments can be placed at the end of the statement
 
3935
to which they pertain:
 
3936
 
 
3937
    statement;    /* comment */
 
3938
 
 
3939
We don't use C++ style ("//") comments. We have, however,
 
3940
used them in the past in some now-abandoned MMX assembler
 
3941
code.
 
3942
 
 
3943
Functions and their curly braces are not indented, and
 
3944
exported functions are marked with PNGAPI:
 
3945
 
 
3946
 /* This is a public function that is visible to
 
3947
  * application programers. It does thus-and-so.
 
3948
  */
 
3949
 void PNGAPI
 
3950
 png_exported_function(png_ptr, png_info, foo)
 
3951
 {
 
3952
    body;
 
3953
 }
 
3954
 
 
3955
The prototypes for all exported functions appear in png.h,
 
3956
above the comment that says
 
3957
 
 
3958
    /* Maintainer: Put new public prototypes here ... */
 
3959
 
 
3960
We mark all non-exported functions with "/* PRIVATE */"":
 
3961
 
 
3962
 void /* PRIVATE */
 
3963
 png_non_exported_function(png_ptr, png_info, foo)
 
3964
 {
 
3965
    body;
 
3966
 }
 
3967
 
 
3968
The prototypes for non-exported functions (except for those in
 
3969
pngtest) appear in
 
3970
the PNG_INTERNAL section of png.h
 
3971
above the comment that says
 
3972
 
 
3973
  /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
 
3974
 
 
3975
The names of all exported functions and variables begin
 
3976
with  "png_", and all publicly visible C preprocessor
 
3977
macros begin with "PNG_".
 
3978
 
 
3979
We put a space after each comma and after each semicolon
 
3980
in "for" statments, and we put spaces before and after each
 
3981
C binary operator and after "for" or "while".  We don't
 
3982
put a space between a typecast and the expression being
 
3983
cast, nor do we put one between a function name and the
 
3984
left parenthesis that follows it:
 
3985
 
 
3986
    for (i = 2; i > 0; --i)
 
3987
       y[i] = a(x) + (int)b;
 
3988
 
 
3989
We prefer #ifdef and #ifndef to #if defined() and if !defined()
 
3990
when there is only one macro being tested.
 
3991
 
 
3992
We do not use the TAB character for indentation in the C sources.
 
3993
 
 
3994
Other rules can be inferred by inspecting the libpng source.
 
3995
 
 
3996
.SH XIII. Y2K Compliance in libpng
 
3997
 
 
3998
December 3, 2009
3621
3999
 
3622
4000
Since the PNG Development group is an ad-hoc body, we can't make
3623
4001
an official declaration.
3624
4002
 
3625
4003
This is your unofficial assurance that libpng from version 0.71 and
3626
 
upward through 1.2.23 are Y2K compliant.  It is my belief that earlier
 
4004
upward through 1.2.41 are Y2K compliant.  It is my belief that earlier
3627
4005
versions were also Y2K compliant.
3628
4006
 
3629
4007
Libpng only has three year fields.  One is a 2-byte unsigned integer that
3834
4212
 1.2.23beta01-05     13    10223  12.so.0.23[.0]
3835
4213
 1.2.23rc01          13    10223  12.so.0.23[.0]
3836
4214
 1.2.23              13    10223  12.so.0.23[.0]
 
4215
 1.2.24beta01-02     13    10224  12.so.0.24[.0]
 
4216
 1.2.24rc01          13    10224  12.so.0.24[.0]
 
4217
 1.2.24              13    10224  12.so.0.24[.0]
 
4218
 1.2.25beta01-06     13    10225  12.so.0.25[.0]
 
4219
 1.2.25rc01-02       13    10225  12.so.0.25[.0]
 
4220
 1.0.31              10    10031  10.so.0.31[.0]
 
4221
 1.2.25              13    10225  12.so.0.25[.0]
 
4222
 1.2.26beta01-06     13    10226  12.so.0.26[.0]
 
4223
 1.2.26rc01          13    10226  12.so.0.26[.0]
 
4224
 1.2.26              13    10226  12.so.0.26[.0]
 
4225
 1.0.32              10    10032  10.so.0.32[.0]
 
4226
 1.2.27beta01-06     13    10227  12.so.0.27[.0]
 
4227
 1.2.27rc01          13    10227  12.so.0.27[.0]
 
4228
 1.0.33              10    10033  10.so.0.33[.0]
 
4229
 1.2.27              13    10227  12.so.0.27[.0]
 
4230
 1.0.34              10    10034  10.so.0.34[.0]
 
4231
 1.2.28              13    10228  12.so.0.28[.0]
 
4232
 1.2.29beta01-03     13    10229  12.so.0.29[.0]
 
4233
 1.2.29rc01          13    10229  12.so.0.29[.0]
 
4234
 1.0.35              10    10035  10.so.0.35[.0]
 
4235
 1.2.29              13    10229  12.so.0.29[.0]
 
4236
 1.0.37              10    10037  10.so.0.37[.0]
 
4237
 1.2.30beta01-04     13    10230  12.so.0.30[.0]
 
4238
 1.0.38rc01-08       10    10038  10.so.0.38[.0]
 
4239
 1.2.30rc01-08       13    10230  12.so.0.30[.0]
 
4240
 1.0.38              10    10038  10.so.0.38[.0]
 
4241
 1.2.30              13    10230  12.so.0.30[.0]
 
4242
 1.0.39rc01-03       10    10039  10.so.0.39[.0]
 
4243
 1.2.31rc01-03       13    10231  12.so.0.31[.0]
 
4244
 1.0.39              10    10039  10.so.0.39[.0]
 
4245
 1.2.31              13    10231  12.so.0.31[.0]
 
4246
 1.2.32beta01-02     13    10232  12.so.0.32[.0]
 
4247
 1.0.40rc01          10    10040  10.so.0.40[.0]
 
4248
 1.2.32rc01          13    10232  12.so.0.32[.0]
 
4249
 1.0.40              10    10040  10.so.0.40[.0]
 
4250
 1.2.32              13    10232  12.so.0.32[.0]
 
4251
 1.2.33beta01-02     13    10233  12.so.0.33[.0]
 
4252
 1.2.33rc01-02       13    10233  12.so.0.33[.0]
 
4253
 1.0.41rc01          10    10041  10.so.0.41[.0]
 
4254
 1.2.33              13    10233  12.so.0.33[.0]
 
4255
 1.0.41              10    10041  10.so.0.41[.0]
 
4256
 1.2.34beta01-07     13    10234  12.so.0.34[.0]
 
4257
 1.0.42rc01          10    10042  10.so.0.42[.0]
 
4258
 1.2.34rc01          13    10234  12.so.0.34[.0]
 
4259
 1.0.42              10    10042  10.so.0.42[.0]
 
4260
 1.2.34              13    10234  12.so.0.34[.0]
 
4261
 1.2.35beta01-03     13    10235  12.so.0.35[.0]
 
4262
 1.0.43rc01-02       10    10043  10.so.0.43[.0]
 
4263
 1.2.35rc01-02       13    10235  12.so.0.35[.0]
 
4264
 1.0.43              10    10043  10.so.0.43[.0]
 
4265
 1.2.35              13    10235  12.so.0.35[.0]
 
4266
 1.2.36beta01-05     13    10236  12.so.0.36[.0]
 
4267
 1.2.36rc01          13    10236  12.so.0.36[.0]
 
4268
 1.0.44              10    10044  10.so.0.44[.0]
 
4269
 1.2.36              13    10236  12.so.0.36[.0]
 
4270
 1.2.37beta01-03     13    10237  12.so.0.37[.0]
 
4271
 1.2.37rc01          13    10237  12.so.0.37[.0]
 
4272
 1.2.37              13    10237  12.so.0.37[.0]
 
4273
 1.2.45              10    10045  12.so.0.45[.0]
 
4274
 1.0.46              10    10046  10.so.0.46[.0]
 
4275
 1.2.38beta01        13    10238  12.so.0.38[.0]
 
4276
 1.2.38rc01-03       13    10238  12.so.0.38[.0]
 
4277
 1.0.47              10    10047  10.so.0.47[.0]
 
4278
 1.2.38              13    10238  12.so.0.38[.0]
 
4279
 1.2.39beta01-05     13    10239  12.so.0.39[.0]
 
4280
 1.2.39rc01          13    10239  12.so.0.39[.0]
 
4281
 1.0.48              10    10048  10.so.0.48[.0]
 
4282
 1.2.39              13    10239  12.so.0.39[.0]
 
4283
 1.2.40beta01        13    10240  12.so.0.40[.0]
 
4284
 1.2.40rc01          13    10240  12.so.0.40[.0]
 
4285
 1.0.49              10    10049  10.so.0.49[.0]
 
4286
 1.2.40              13    10240  12.so.0.40[.0]
 
4287
 1.0.50              10    10050  10.so.0.50[.0]
 
4288
 1.2.41beta01-18     13    10241  12.so.0.41[.0]
 
4289
 1.0.51rc01          10    10051  10.so.0.51[.0]
 
4290
 1.2.41rc01-03       13    10241  12.so.0.41[.0]
 
4291
 1.0.51              10    10051  10.so.0.51[.0]
 
4292
 1.2.41              13    10241  12.so.0.41[.0]
3837
4293
 
3838
4294
Henceforth the source version will match the shared-library minor
3839
4295
and patch numbers; the shared-library major version number will be
3869
4325
.I libpng
3870
4326
or at
3871
4327
.br
3872
 
ftp://ds.internic.net/rfc/rfc2083.txt
 
4328
ftp://ftp.rfc-editor.org:/in-notes/rfc2083.txt
3873
4329
.br
3874
4330
or (as a W3C Recommendation) at
3875
4331
.br
3889
4345
 
3890
4346
Thanks to Frank J. T. Wojcik for helping with the documentation.
3891
4347
 
3892
 
Libpng version 1.2.23 - November 6, 2007:
 
4348
Libpng version 1.2.41 - December 3, 2009:
3893
4349
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
3894
4350
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
3895
4351
 
3910
4366
If you modify libpng you may insert additional notices immediately following
3911
4367
this sentence.
3912
4368
 
3913
 
libpng versions 1.2.6, August 15, 2004, through 1.2.23, November 6, 2007, are
3914
 
Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
 
4369
This code is released under the libpng license.
 
4370
 
 
4371
libpng versions 1.2.6, August 15, 2004, through 1.2.41, December 3, 2009, are
 
4372
Copyright (c) 2004,2006-2008 Glenn Randers-Pehrson, and are
3915
4373
distributed according to the same disclaimer and license as libpng-1.2.5
3916
4374
with the following individual added to the list of Contributing Authors
3917
4375
 
4009
4467
 
4010
4468
Glenn Randers-Pehrson
4011
4469
glennrp at users.sourceforge.net
4012
 
November 6, 2007
 
4470
December 3, 2009
4013
4471
 
4014
4472
.\" end of man page
4015
4473