12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
15 *
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /* png.h - header file for PNG reference library
26 *
27 * This file is available under and governed by the GNU General Public
28 * License version 2 only, as published by the Free Software Foundation.
29 * However, the following notice accompanied the original version of this
30 * file and, per its terms, should not be removed:
31 *
32 * libpng version 1.6.35, July 15, 2018
33 *
34 * Copyright (c) 1998-2002,2004,2006-2018 Glenn Randers-Pehrson
35 * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
36 * (Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
37 *
38 * This code is released under the libpng license (See LICENSE, below)
39 *
40 * Authors and maintainers:
41 * libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat
42 * libpng versions 0.89, June 1996, through 0.96, May 1997: Andreas Dilger
43 * libpng versions 0.97, January 1998, through 1.6.35, July 15, 2018:
44 * Glenn Randers-Pehrson.
45 * See also "Contributing Authors", below.
46 */
47
48 /*
49 * COPYRIGHT NOTICE, DISCLAIMER, and LICENSE:
50 *
51 * If you modify libpng you may insert additional notices immediately following
52 * this sentence.
53 *
54 * This code is released under the libpng license.
55 *
56 * libpng versions 1.0.7, July 1, 2000 through 1.6.35, July 15, 2018 are
57 * Copyright (c) 2000-2002, 2004, 2006-2018 Glenn Randers-Pehrson, are
58 * derived from libpng-1.0.6, and are distributed according to the same
59 * disclaimer and license as libpng-1.0.6 with the following individuals
60 * added to the list of Contributing Authors:
61 *
62 * Simon-Pierre Cadieux
63 * Eric S. Raymond
64 * Mans Rullgard
65 * Cosmin Truta
66 * Gilles Vollant
67 * James Yu
68 * Mandar Sahastrabuddhe
69 * Google Inc.
70 * Vadim Barkov
71 *
72 * and with the following additions to the disclaimer:
73 *
74 * There is no warranty against interference with your enjoyment of the
75 * library or against infringement. There is no warranty that our
76 * efforts or the library will fulfill any of your particular purposes
77 * or needs. This library is provided with all faults, and the entire
78 * risk of satisfactory quality, performance, accuracy, and effort is with
79 * the user.
80 *
81 * Some files in the "contrib" directory and some configure-generated
82 * files that are distributed with libpng have other copyright owners and
83 * are released under other open source licenses.
84 *
85 * libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
86 * Copyright (c) 1998-2000 Glenn Randers-Pehrson, are derived from
87 * libpng-0.96, and are distributed according to the same disclaimer and
88 * license as libpng-0.96, with the following individuals added to the list
89 * of Contributing Authors:
90 *
91 * Tom Lane
92 * Glenn Randers-Pehrson
93 * Willem van Schaik
94 *
95 * libpng versions 0.89, June 1996, through 0.96, May 1997, are
96 * Copyright (c) 1996-1997 Andreas Dilger, are derived from libpng-0.88,
97 * and are distributed according to the same disclaimer and license as
98 * libpng-0.88, with the following individuals added to the list of
99 * Contributing Authors:
100 *
101 * John Bowler
102 * Kevin Bracey
103 * Sam Bushell
104 * Magnus Holmgren
105 * Greg Roelofs
106 * Tom Tanner
107 *
108 * Some files in the "scripts" directory have other copyright owners
109 * but are released under this license.
110 *
111 * libpng versions 0.5, May 1995, through 0.88, January 1996, are
112 * Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
113 *
114 * For the purposes of this copyright and license, "Contributing Authors"
115 * is defined as the following set of individuals:
116 *
117 * Andreas Dilger
118 * Dave Martindale
119 * Guy Eric Schalnat
120 * Paul Schmidt
121 * Tim Wegner
122 *
123 * The PNG Reference Library is supplied "AS IS". The Contributing Authors
124 * and Group 42, Inc. disclaim all warranties, expressed or implied,
125 * including, without limitation, the warranties of merchantability and of
126 * fitness for any purpose. The Contributing Authors and Group 42, Inc.
127 * assume no liability for direct, indirect, incidental, special, exemplary,
128 * or consequential damages, which may result from the use of the PNG
129 * Reference Library, even if advised of the possibility of such damage.
130 *
131 * Permission is hereby granted to use, copy, modify, and distribute this
132 * source code, or portions hereof, for any purpose, without fee, subject
133 * to the following restrictions:
134 *
135 * 1. The origin of this source code must not be misrepresented.
136 *
137 * 2. Altered versions must be plainly marked as such and must not
138 * be misrepresented as being the original source.
139 *
140 * 3. This Copyright notice may not be removed or altered from any
141 * source or altered source distribution.
142 *
143 * The Contributing Authors and Group 42, Inc. specifically permit, without
144 * fee, and encourage the use of this source code as a component to
145 * supporting the PNG file format in commercial products. If you use this
146 * source code in a product, acknowledgment is not required but would be
147 * appreciated.
148 *
149 * END OF COPYRIGHT NOTICE, DISCLAIMER, and LICENSE.
150 *
151 * TRADEMARK:
152 *
153 * The name "libpng" has not been registered by the Copyright owner
154 * as a trademark in any jurisdiction. However, because libpng has
155 * been distributed and maintained world-wide, continually since 1995,
156 * the Copyright owner claims "common-law trademark protection" in any
157 * jurisdiction where common-law trademark is recognized.
158 *
159 * OSI CERTIFICATION:
160 *
161 * Libpng is OSI Certified Open Source Software. OSI Certified Open Source is
162 * a certification mark of the Open Source Initiative. OSI has not addressed
163 * the additional disclaimers inserted at version 1.0.7.
164 *
165 * EXPORT CONTROL:
166 *
167 * The Copyright owner believes that the Export Control Classification
168 * Number (ECCN) for libpng is EAR99, which means not subject to export
169 * controls or International Traffic in Arms Regulations (ITAR) because
170 * it is open source, publicly available software, that does not contain
171 * any encryption software. See the EAR, paragraphs 734.3(b)(3) and
172 * 734.7(b).
173 */
174
175 /*
176 * A "png_get_copyright" function is available, for convenient use in "about"
177 * boxes and the like:
178 *
179 * printf("%s", png_get_copyright(NULL));
180 *
181 * Also, the PNG logo (in PNG format, of course) is supplied in the
182 * files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
183 */
184
185 /*
186 * The contributing authors would like to thank all those who helped
187 * with testing, bug fixes, and patience. This wouldn't have been
188 * possible without all of you.
189 *
190 * Thanks to Frank J. T. Wojcik for helping with the documentation.
191 */
192
218 * 1.0.2a-b 10003 version, except as noted.
219 * 1.0.3 10003
220 * 1.0.3a-d 10004
221 * 1.0.4 10004
222 * 1.0.4a-f 10005
223 * 1.0.5 (+ 2 patches) 10005
224 * 1.0.5a-d 10006
225 * 1.0.5e-r 10100 (not source compatible)
226 * 1.0.5s-v 10006 (not binary compatible)
227 * 1.0.6 (+ 3 patches) 10006 (still binary incompatible)
228 * 1.0.6d-f 10007 (still binary incompatible)
229 * 1.0.6g 10007
230 * 1.0.6h 10007 10.6h (testing xy.z so-numbering)
231 * 1.0.6i 10007 10.6i
232 * 1.0.6j 10007 2.1.0.6j (incompatible with 1.0.0)
233 * 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14 (binary compatible)
234 * 1.0.7beta15-18 1 10007 2.1.0.7beta15-18 (binary compatible)
235 * 1.0.7rc1-2 1 10007 2.1.0.7rc1-2 (binary compatible)
236 * 1.0.7 1 10007 (still compatible)
237 * ...
238 * 1.0.19 10 10019 10.so.0.19[.0]
239 * ...
240 * 1.2.59 13 10257 12.so.0.59[.0]
241 * ...
242 * 1.5.30 15 10527 15.so.15.30[.0]
243 * ...
244 * 1.6.35 16 10635 16.so.16.35[.0]
245 *
246 * Henceforth the source version will match the shared-library major
247 * and minor numbers; the shared-library major version number will be
248 * used for changes in backward compatibility, as it is intended. The
249 * PNG_LIBPNG_VER macro, which is not used within libpng but is available
250 * for applications, is an unsigned integer of the form xyyzz corresponding
251 * to the source version x.y.z (leading zeros in y and z). Beta versions
252 * were given the previous public release number plus a letter, until
253 * version 1.0.6j; from then on they were given the upcoming public
254 * release number plus "betaNN" or "rcNN".
255 *
256 * Binary incompatibility exists only when applications make direct access
257 * to the info_ptr or png_ptr members through png.h, and the compiled
258 * application is loaded with a different version of the library.
259 *
260 * DLLNUM will change each time there are forward or backward changes
261 * in binary compatibility (e.g., when a new feature is added).
262 *
263 * See libpng.txt or libpng.3 for more information. The PNG specification
264 * is available as a W3C Recommendation and as an ISO Specification,
265 * <https://www.w3.org/TR/2003/REC-PNG-20031110/
266 */
267
268 /*
269 * Y2K compliance in libpng:
270 * =========================
271 *
272 * July 15, 2018
273 *
274 * Since the PNG Development group is an ad-hoc body, we can't make
275 * an official declaration.
276 *
277 * This is your unofficial assurance that libpng from version 0.71 and
278 * upward through 1.6.35 are Y2K compliant. It is my belief that
279 * earlier versions were also Y2K compliant.
280 *
281 * Libpng only has two year fields. One is a 2-byte unsigned integer
282 * that will hold years up to 65535. The other, which is deprecated,
283 * holds the date in text format, and will hold years up to 9999.
284 *
285 * The integer is
286 * "png_uint_16 year" in png_time_struct.
287 *
288 * The string is
289 * "char time_buffer[29]" in png_struct. This is no longer used
290 * in libpng-1.6.x and will be removed from libpng-1.7.0.
291 *
292 * There are seven time-related functions:
293 * png.c: png_convert_to_rfc_1123_buffer() in png.c
294 * (formerly png_convert_to_rfc_1123() prior to libpng-1.5.x and
295 * png_convert_to_rfc_1152() in error prior to libpng-0.98)
296 * png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c
297 * png_convert_from_time_t() in pngwrite.c
298 * png_get_tIME() in pngget.c
299 * png_handle_tIME() in pngrutil.c, called in pngread.c
300 * png_set_tIME() in pngset.c
301 * png_write_tIME() in pngwutil.c, called in pngwrite.c
302 *
303 * All handle dates properly in a Y2K environment. The
304 * png_convert_from_time_t() function calls gmtime() to convert from system
305 * clock time, which returns (year - 1900), which we properly convert to
306 * the full 4-digit year. There is a possibility that libpng applications
307 * are not passing 4-digit years into the png_convert_to_rfc_1123_buffer()
308 * function, or that they are incorrectly passing only a 2-digit year
309 * instead of "year - 1900" into the png_convert_from_struct_tm() function,
310 * but this is not under our control. The libpng documentation has always
311 * stated that it works with 4-digit years, and the APIs have been
312 * documented as such.
313 *
314 * The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
315 * integer to hold the year, and can hold years as large as 65535.
316 *
317 * zlib, upon which libpng depends, is also Y2K compliant. It contains
318 * no date-related code.
319 *
320 * Glenn Randers-Pehrson
321 * libpng maintainer
322 * PNG Development Group
323 */
324
325 #ifndef PNG_H
326 #define PNG_H
327
328 /* This is not the place to learn how to use libpng. The file libpng-manual.txt
329 * describes how to use libpng, and the file example.c summarizes it
330 * with some code on which to build. This file is useful for looking
331 * at the actual function definitions and structure components. If that
332 * file has been stripped from your copy of libpng, you can find it at
333 * <http://www.libpng.org/pub/png/libpng-manual.txt>
334 *
335 * If you just need to read a PNG file and don't want to read the documentation
336 * skip to the end of this file and read the section entitled 'simplified API'.
337 */
338
339 /* Version information for png.h - this should match the version in png.c */
340 #define PNG_LIBPNG_VER_STRING "1.6.35"
341 #define PNG_HEADER_VERSION_STRING " libpng version 1.6.35 - July 15, 2018\n"
342
343 #define PNG_LIBPNG_VER_SONUM 16
344 #define PNG_LIBPNG_VER_DLLNUM 16
345
346 /* These should match the first 3 components of PNG_LIBPNG_VER_STRING: */
347 #define PNG_LIBPNG_VER_MAJOR 1
348 #define PNG_LIBPNG_VER_MINOR 6
349 #define PNG_LIBPNG_VER_RELEASE 35
350
351 /* This should match the numeric part of the final component of
352 * PNG_LIBPNG_VER_STRING, omitting any leading zero:
353 */
354
355 #define PNG_LIBPNG_VER_BUILD 02
356
357 /* Release Status */
358 #define PNG_LIBPNG_BUILD_ALPHA 1
359 #define PNG_LIBPNG_BUILD_BETA 2
360 #define PNG_LIBPNG_BUILD_RC 3
361 #define PNG_LIBPNG_BUILD_STABLE 4
362 #define PNG_LIBPNG_BUILD_RELEASE_STATUS_MASK 7
363
364 /* Release-Specific Flags */
365 #define PNG_LIBPNG_BUILD_PATCH 8 /* Can be OR'ed with
366 PNG_LIBPNG_BUILD_STABLE only */
367 #define PNG_LIBPNG_BUILD_PRIVATE 16 /* Cannot be OR'ed with
368 PNG_LIBPNG_BUILD_SPECIAL */
369 #define PNG_LIBPNG_BUILD_SPECIAL 32 /* Cannot be OR'ed with
370 PNG_LIBPNG_BUILD_PRIVATE */
371
372 #define PNG_LIBPNG_BUILD_BASE_TYPE PNG_LIBPNG_BUILD_BETA
373
374 /* Careful here. At one time, Guy wanted to use 082, but that would be octal.
375 * We must not include leading zeros.
376 * Versions 0.7 through 1.0.0 were in the range 0 to 100 here (only
377 * version 1.0.0 was mis-numbered 100 instead of 10000). From
378 * version 1.0.1 it's xxyyzz, where x=major, y=minor, z=release
379 */
380 #define PNG_LIBPNG_VER 10635 /* 1.6.35 */
381
382 /* Library configuration: these options cannot be changed after
383 * the library has been built.
384 */
385 #ifndef PNGLCONF_H
386 /* If pnglibconf.h is missing, you can
387 * copy scripts/pnglibconf.h.prebuilt to pnglibconf.h
388 */
389 # include "pnglibconf.h"
390 #endif
391
392 #ifndef PNG_VERSION_INFO_ONLY
393 /* Machine specific configuration. */
394 # include "pngconf.h"
395 #endif
396
397 /*
398 * Added at libpng-1.2.8
399 *
400 * Ref MSDN: Private as priority over Special
470 * does not use division?
471 * PNG_READ_COMPOSITE_NODIV_SUPPORTED: use the 'no division'
472 * algorithm.
473 * PNG_NO_READ_COMPOSITE_NODIV: use the 'division' algorithm.
474 *
475 * How to handle benign errors if PNG_ALLOW_BENIGN_ERRORS is
476 * false?
477 * PNG_ALLOW_BENIGN_ERRORS: map calls to the benign error
478 * APIs to png_warning.
479 * Otherwise the calls are mapped to png_error.
480 */
481
482 /* Section 3: type definitions, including structures and compile time
483 * constants.
484 * See pngconf.h for base types that vary by machine/system
485 */
486
487 /* This triggers a compiler error in png.c, if png.c and png.h
488 * do not agree upon the version number.
489 */
490 typedef char* png_libpng_version_1_6_35;
491
492 /* Basic control structions. Read libpng-manual.txt or libpng.3 for more info.
493 *
494 * png_struct is the cache of information used while reading or writing a single
495 * PNG file. One of these is always required, although the simplified API
496 * (below) hides the creation and destruction of it.
497 */
498 typedef struct png_struct_def png_struct;
499 typedef const png_struct * png_const_structp;
500 typedef png_struct * png_structp;
501 typedef png_struct * * png_structpp;
502
503 /* png_info contains information read from or to be written to a PNG file. One
504 * or more of these must exist while reading or creating a PNG file. The
505 * information is not used by libpng during read but is used to control what
506 * gets written when a PNG file is created. "png_get_" function calls read
507 * information during read and "png_set_" functions calls write information
508 * when creating a PNG.
509 * been moved into a separate header file that is not accessible to
510 * applications. Read libpng-manual.txt or libpng.3 for more info.
2024 double green_X, double green_Y, double green_Z, double blue_X,
2025 double blue_Y, double blue_Z))
2026 PNG_FIXED_EXPORT(136, void, png_set_cHRM_fixed, (png_const_structrp png_ptr,
2027 png_inforp info_ptr, png_fixed_point int_white_x,
2028 png_fixed_point int_white_y, png_fixed_point int_red_x,
2029 png_fixed_point int_red_y, png_fixed_point int_green_x,
2030 png_fixed_point int_green_y, png_fixed_point int_blue_x,
2031 png_fixed_point int_blue_y))
2032 PNG_FIXED_EXPORT(233, void, png_set_cHRM_XYZ_fixed, (png_const_structrp png_ptr,
2033 png_inforp info_ptr, png_fixed_point int_red_X, png_fixed_point int_red_Y,
2034 png_fixed_point int_red_Z, png_fixed_point int_green_X,
2035 png_fixed_point int_green_Y, png_fixed_point int_green_Z,
2036 png_fixed_point int_blue_X, png_fixed_point int_blue_Y,
2037 png_fixed_point int_blue_Z))
2038 #endif
2039
2040 #ifdef PNG_eXIf_SUPPORTED
2041 PNG_EXPORT(246, png_uint_32, png_get_eXIf, (png_const_structrp png_ptr,
2042 png_inforp info_ptr, png_bytep *exif));
2043 PNG_EXPORT(247, void, png_set_eXIf, (png_const_structrp png_ptr,
2044 png_inforp info_ptr, const png_bytep exif));
2045
2046 PNG_EXPORT(248, png_uint_32, png_get_eXIf_1, (png_const_structrp png_ptr,
2047 png_const_inforp info_ptr, png_uint_32 *num_exif, png_bytep *exif));
2048 PNG_EXPORT(249, void, png_set_eXIf_1, (png_const_structrp png_ptr,
2049 png_inforp info_ptr, const png_uint_32 num_exif, const png_bytep exif));
2050 #endif
2051
2052 #ifdef PNG_gAMA_SUPPORTED
2053 PNG_FP_EXPORT(137, png_uint_32, png_get_gAMA, (png_const_structrp png_ptr,
2054 png_const_inforp info_ptr, double *file_gamma))
2055 PNG_FIXED_EXPORT(138, png_uint_32, png_get_gAMA_fixed,
2056 (png_const_structrp png_ptr, png_const_inforp info_ptr,
2057 png_fixed_point *int_file_gamma))
2058 #endif
2059
2060 #ifdef PNG_gAMA_SUPPORTED
2061 PNG_FP_EXPORT(139, void, png_set_gAMA, (png_const_structrp png_ptr,
2062 png_inforp info_ptr, double file_gamma))
2063 PNG_FIXED_EXPORT(140, void, png_set_gAMA_fixed, (png_const_structrp png_ptr,
2064 png_inforp info_ptr, png_fixed_point int_file_gamma))
2065 #endif
2066
2067 #ifdef PNG_hIST_SUPPORTED
2068 PNG_EXPORT(141, png_uint_32, png_get_hIST, (png_const_structrp png_ptr,
2069 png_inforp info_ptr, png_uint_16p *hist));
2775 * 4: Three color channels and an alpha channel (RGBA).
2776 *
2777 * The components are encoded in one of two ways:
2778 *
2779 * a) As a small integer, value 0..255, contained in a single byte. For the
2780 * alpha channel the original value is simply value/255. For the color or
2781 * luminance channels the value is encoded according to the sRGB specification
2782 * and matches the 8-bit format expected by typical display devices.
2783 *
2784 * The color/gray channels are not scaled (pre-multiplied) by the alpha
2785 * channel and are suitable for passing to color management software.
2786 *
2787 * b) As a value in the range 0..65535, contained in a 2-byte integer. All
2788 * channels can be converted to the original value by dividing by 65535; all
2789 * channels are linear. Color channels use the RGB encoding (RGB end-points) of
2790 * the sRGB specification. This encoding is identified by the
2791 * PNG_FORMAT_FLAG_LINEAR flag below.
2792 *
2793 * When the simplified API needs to convert between sRGB and linear colorspaces,
2794 * the actual sRGB transfer curve defined in the sRGB specification (see the
2795 * article at https://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
2796 * approximation used elsewhere in libpng.
2797 *
2798 * When an alpha channel is present it is expected to denote pixel coverage
2799 * of the color or luminance channels and is returned as an associated alpha
2800 * channel: the color/gray channels are scaled (pre-multiplied) by the alpha
2801 * value.
2802 *
2803 * The samples are either contained directly in the image data, between 1 and 8
2804 * bytes per pixel according to the encoding, or are held in a color-map indexed
2805 * by bytes in the image data. In the case of a color-map the color-map entries
2806 * are individual samples, encoded as above, and the image data has one byte per
2807 * pixel to select the relevant sample from the color-map.
2808 */
2809
2810 /* PNG_FORMAT_*
2811 *
2812 * #defines to be used in png_image::format. Each #define identifies a
2813 * particular layout of sample data and, if present, alpha values. There are
2814 * separate defines for each of the two component encodings.
2815 *
2978 #define PNG_IMAGE_SIZE(image)\
2979 PNG_IMAGE_BUFFER_SIZE(image, PNG_IMAGE_ROW_STRIDE(image))
2980 /* Return the size, in bytes, of the image in memory given just a png_image;
2981 * the row stride is the minimum stride required for the image.
2982 */
2983
2984 #define PNG_IMAGE_COLORMAP_SIZE(image)\
2985 (PNG_IMAGE_SAMPLE_SIZE((image).format) * (image).colormap_entries)
2986 /* Return the size, in bytes, of the color-map of this image. If the image
2987 * format is not a color-map format this will return a size sufficient for
2988 * 256 entries in the given format; check PNG_FORMAT_FLAG_COLORMAP if
2989 * you don't want to allocate a color-map in this case.
2990 */
2991
2992 /* PNG_IMAGE_FLAG_*
2993 *
2994 * Flags containing additional information about the image are held in the
2995 * 'flags' field of png_image.
2996 */
2997 #define PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB 0x01
2998 /* This indicates the the RGB values of the in-memory bitmap do not
2999 * correspond to the red, green and blue end-points defined by sRGB.
3000 */
3001
3002 #define PNG_IMAGE_FLAG_FAST 0x02
3003 /* On write emphasise speed over compression; the resultant PNG file will be
3004 * larger but will be produced significantly faster, particular for large
3005 * images. Do not use this option for images which will be distributed, only
3006 * used it when producing intermediate files that will be read back in
3007 * repeatedly. For a typical 24-bit image the option will double the read
3008 * speed at the cost of increasing the image size by 25%, however for many
3009 * more compressible images the PNG file can be 10 times larger with only a
3010 * slight speed gain.
3011 */
3012
3013 #define PNG_IMAGE_FLAG_16BIT_sRGB 0x04
3014 /* On read if the image is a 16-bit per component image and there is no gAMA
3015 * or sRGB chunk assume that the components are sRGB encoded. Notice that
3016 * images output by the simplified API always have gamma information; setting
3017 * this flag only affects the interpretation of 16-bit images from an
3018 * external source. It is recommended that the application expose this flag
|
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
15 *
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /* png.h - header file for PNG reference library
26 *
27 * This file is available under and governed by the GNU General Public
28 * License version 2 only, as published by the Free Software Foundation.
29 * However, the following notice accompanied the original version of this
30 * file and, per its terms, should not be removed:
31 *
32 * libpng version 1.6.37 - April 14, 2019
33 *
34 * Copyright (c) 2018-2019 Cosmin Truta
35 * Copyright (c) 1998-2002,2004,2006-2018 Glenn Randers-Pehrson
36 * Copyright (c) 1996-1997 Andreas Dilger
37 * Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
38 *
39 * This code is released under the libpng license. (See LICENSE, below.)
40 *
41 * Authors and maintainers:
42 * libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat
43 * libpng versions 0.89, June 1996, through 0.96, May 1997: Andreas Dilger
44 * libpng versions 0.97, January 1998, through 1.6.35, July 2018:
45 * Glenn Randers-Pehrson
46 * libpng versions 1.6.36, December 2018, through 1.6.37, April 2019:
47 * Cosmin Truta
48 * See also "Contributing Authors", below.
49 */
50
51 /*
52 * COPYRIGHT NOTICE, DISCLAIMER, and LICENSE
53 * =========================================
54 *
55 * PNG Reference Library License version 2
56 * ---------------------------------------
57 *
58 * * Copyright (c) 1995-2019 The PNG Reference Library Authors.
59 * * Copyright (c) 2018-2019 Cosmin Truta.
60 * * Copyright (c) 2000-2002, 2004, 2006-2018 Glenn Randers-Pehrson.
61 * * Copyright (c) 1996-1997 Andreas Dilger.
62 * * Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
63 *
64 * The software is supplied "as is", without warranty of any kind,
65 * express or implied, including, without limitation, the warranties
66 * of merchantability, fitness for a particular purpose, title, and
67 * non-infringement. In no event shall the Copyright owners, or
68 * anyone distributing the software, be liable for any damages or
69 * other liability, whether in contract, tort or otherwise, arising
70 * from, out of, or in connection with the software, or the use or
71 * other dealings in the software, even if advised of the possibility
72 * of such damage.
73 *
74 * Permission is hereby granted to use, copy, modify, and distribute
75 * this software, or portions hereof, for any purpose, without fee,
76 * subject to the following restrictions:
77 *
78 * 1. The origin of this software must not be misrepresented; you
79 * must not claim that you wrote the original software. If you
80 * use this software in a product, an acknowledgment in the product
81 * documentation would be appreciated, but is not required.
82 *
83 * 2. Altered source versions must be plainly marked as such, and must
84 * not be misrepresented as being the original software.
85 *
86 * 3. This Copyright notice may not be removed or altered from any
87 * source or altered source distribution.
88 *
89 *
90 * PNG Reference Library License version 1 (for libpng 0.5 through 1.6.35)
91 * -----------------------------------------------------------------------
92 *
93 * libpng versions 1.0.7, July 1, 2000, through 1.6.35, July 15, 2018 are
94 * Copyright (c) 2000-2002, 2004, 2006-2018 Glenn Randers-Pehrson, are
95 * derived from libpng-1.0.6, and are distributed according to the same
96 * disclaimer and license as libpng-1.0.6 with the following individuals
97 * added to the list of Contributing Authors:
98 *
99 * Simon-Pierre Cadieux
100 * Eric S. Raymond
101 * Mans Rullgard
102 * Cosmin Truta
103 * Gilles Vollant
104 * James Yu
105 * Mandar Sahastrabuddhe
106 * Google Inc.
107 * Vadim Barkov
108 *
109 * and with the following additions to the disclaimer:
110 *
111 * There is no warranty against interference with your enjoyment of
112 * the library or against infringement. There is no warranty that our
113 * efforts or the library will fulfill any of your particular purposes
114 * or needs. This library is provided with all faults, and the entire
115 * risk of satisfactory quality, performance, accuracy, and effort is
116 * with the user.
117 *
118 * Some files in the "contrib" directory and some configure-generated
119 * files that are distributed with libpng have other copyright owners, and
120 * are released under other open source licenses.
121 *
122 * libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
123 * Copyright (c) 1998-2000 Glenn Randers-Pehrson, are derived from
124 * libpng-0.96, and are distributed according to the same disclaimer and
125 * license as libpng-0.96, with the following individuals added to the
126 * list of Contributing Authors:
127 *
128 * Tom Lane
129 * Glenn Randers-Pehrson
130 * Willem van Schaik
131 *
132 * libpng versions 0.89, June 1996, through 0.96, May 1997, are
133 * Copyright (c) 1996-1997 Andreas Dilger, are derived from libpng-0.88,
134 * and are distributed according to the same disclaimer and license as
135 * libpng-0.88, with the following individuals added to the list of
136 * Contributing Authors:
137 *
138 * John Bowler
139 * Kevin Bracey
140 * Sam Bushell
141 * Magnus Holmgren
142 * Greg Roelofs
143 * Tom Tanner
144 *
145 * Some files in the "scripts" directory have other copyright owners,
146 * but are released under this license.
147 *
148 * libpng versions 0.5, May 1995, through 0.88, January 1996, are
149 * Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc.
150 *
151 * For the purposes of this copyright and license, "Contributing Authors"
152 * is defined as the following set of individuals:
153 *
154 * Andreas Dilger
155 * Dave Martindale
156 * Guy Eric Schalnat
157 * Paul Schmidt
158 * Tim Wegner
159 *
160 * The PNG Reference Library is supplied "AS IS". The Contributing
161 * Authors and Group 42, Inc. disclaim all warranties, expressed or
162 * implied, including, without limitation, the warranties of
163 * merchantability and of fitness for any purpose. The Contributing
164 * Authors and Group 42, Inc. assume no liability for direct, indirect,
165 * incidental, special, exemplary, or consequential damages, which may
166 * result from the use of the PNG Reference Library, even if advised of
167 * the possibility of such damage.
168 *
169 * Permission is hereby granted to use, copy, modify, and distribute this
170 * source code, or portions hereof, for any purpose, without fee, subject
171 * to the following restrictions:
172 *
173 * 1. The origin of this source code must not be misrepresented.
174 *
175 * 2. Altered versions must be plainly marked as such and must not
176 * be misrepresented as being the original source.
177 *
178 * 3. This Copyright notice may not be removed or altered from any
179 * source or altered source distribution.
180 *
181 * The Contributing Authors and Group 42, Inc. specifically permit,
182 * without fee, and encourage the use of this source code as a component
183 * to supporting the PNG file format in commercial products. If you use
184 * this source code in a product, acknowledgment is not required but would
185 * be appreciated.
186 *
187 * END OF COPYRIGHT NOTICE, DISCLAIMER, and LICENSE.
188 *
189 * TRADEMARK
190 * =========
191 *
192 * The name "libpng" has not been registered by the Copyright owners
193 * as a trademark in any jurisdiction. However, because libpng has
194 * been distributed and maintained world-wide, continually since 1995,
195 * the Copyright owners claim "common-law trademark protection" in any
196 * jurisdiction where common-law trademark is recognized.
197 */
198
199 /*
200 * A "png_get_copyright" function is available, for convenient use in "about"
201 * boxes and the like:
202 *
203 * printf("%s", png_get_copyright(NULL));
204 *
205 * Also, the PNG logo (in PNG format, of course) is supplied in the
206 * files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
207 */
208
209 /*
210 * The contributing authors would like to thank all those who helped
211 * with testing, bug fixes, and patience. This wouldn't have been
212 * possible without all of you.
213 *
214 * Thanks to Frank J. T. Wojcik for helping with the documentation.
215 */
216
242 * 1.0.2a-b 10003 version, except as noted.
243 * 1.0.3 10003
244 * 1.0.3a-d 10004
245 * 1.0.4 10004
246 * 1.0.4a-f 10005
247 * 1.0.5 (+ 2 patches) 10005
248 * 1.0.5a-d 10006
249 * 1.0.5e-r 10100 (not source compatible)
250 * 1.0.5s-v 10006 (not binary compatible)
251 * 1.0.6 (+ 3 patches) 10006 (still binary incompatible)
252 * 1.0.6d-f 10007 (still binary incompatible)
253 * 1.0.6g 10007
254 * 1.0.6h 10007 10.6h (testing xy.z so-numbering)
255 * 1.0.6i 10007 10.6i
256 * 1.0.6j 10007 2.1.0.6j (incompatible with 1.0.0)
257 * 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14 (binary compatible)
258 * 1.0.7beta15-18 1 10007 2.1.0.7beta15-18 (binary compatible)
259 * 1.0.7rc1-2 1 10007 2.1.0.7rc1-2 (binary compatible)
260 * 1.0.7 1 10007 (still compatible)
261 * ...
262 * 1.0.69 10 10069 10.so.0.69[.0]
263 * ...
264 * 1.2.59 13 10259 12.so.0.59[.0]
265 * ...
266 * 1.4.20 14 10420 14.so.0.20[.0]
267 * ...
268 * 1.5.30 15 10530 15.so.15.30[.0]
269 * ...
270 * 1.6.37 16 10637 16.so.16.37[.0]
271 *
272 * Henceforth the source version will match the shared-library major and
273 * minor numbers; the shared-library major version number will be used for
274 * changes in backward compatibility, as it is intended.
275 * The PNG_LIBPNG_VER macro, which is not used within libpng but is
276 * available for applications, is an unsigned integer of the form XYYZZ
277 * corresponding to the source version X.Y.Z (leading zeros in Y and Z).
278 * Beta versions were given the previous public release number plus a
279 * letter, until version 1.0.6j; from then on they were given the upcoming
280 * public release number plus "betaNN" or "rcNN".
281 *
282 * Binary incompatibility exists only when applications make direct access
283 * to the info_ptr or png_ptr members through png.h, and the compiled
284 * application is loaded with a different version of the library.
285 *
286 * DLLNUM will change each time there are forward or backward changes
287 * in binary compatibility (e.g., when a new feature is added).
288 *
289 * See libpng.txt or libpng.3 for more information. The PNG specification
290 * is available as a W3C Recommendation and as an ISO/IEC Standard; see
291 * <https://www.w3.org/TR/2003/REC-PNG-20031110/>
292 */
293
294 #ifndef PNG_H
295 #define PNG_H
296
297 /* This is not the place to learn how to use libpng. The file libpng-manual.txt
298 * describes how to use libpng, and the file example.c summarizes it
299 * with some code on which to build. This file is useful for looking
300 * at the actual function definitions and structure components. If that
301 * file has been stripped from your copy of libpng, you can find it at
302 * <http://www.libpng.org/pub/png/libpng-manual.txt>
303 *
304 * If you just need to read a PNG file and don't want to read the documentation
305 * skip to the end of this file and read the section entitled 'simplified API'.
306 */
307
308 /* Version information for png.h - this should match the version in png.c */
309 #define PNG_LIBPNG_VER_STRING "1.6.37"
310 #define PNG_HEADER_VERSION_STRING " libpng version 1.6.37 - April 14, 2019\n"
311
312 #define PNG_LIBPNG_VER_SONUM 16
313 #define PNG_LIBPNG_VER_DLLNUM 16
314
315 /* These should match the first 3 components of PNG_LIBPNG_VER_STRING: */
316 #define PNG_LIBPNG_VER_MAJOR 1
317 #define PNG_LIBPNG_VER_MINOR 6
318 #define PNG_LIBPNG_VER_RELEASE 37
319
320 /* This should be zero for a public release, or non-zero for a
321 * development version. [Deprecated]
322 */
323 #define PNG_LIBPNG_VER_BUILD 0
324
325 /* Release Status */
326 #define PNG_LIBPNG_BUILD_ALPHA 1
327 #define PNG_LIBPNG_BUILD_BETA 2
328 #define PNG_LIBPNG_BUILD_RC 3
329 #define PNG_LIBPNG_BUILD_STABLE 4
330 #define PNG_LIBPNG_BUILD_RELEASE_STATUS_MASK 7
331
332 /* Release-Specific Flags */
333 #define PNG_LIBPNG_BUILD_PATCH 8 /* Can be OR'ed with
334 PNG_LIBPNG_BUILD_STABLE only */
335 #define PNG_LIBPNG_BUILD_PRIVATE 16 /* Cannot be OR'ed with
336 PNG_LIBPNG_BUILD_SPECIAL */
337 #define PNG_LIBPNG_BUILD_SPECIAL 32 /* Cannot be OR'ed with
338 PNG_LIBPNG_BUILD_PRIVATE */
339
340 #define PNG_LIBPNG_BUILD_BASE_TYPE PNG_LIBPNG_BUILD_STABLE
341
342 /* Careful here. At one time, Guy wanted to use 082, but that
343 * would be octal. We must not include leading zeros.
344 * Versions 0.7 through 1.0.0 were in the range 0 to 100 here
345 * (only version 1.0.0 was mis-numbered 100 instead of 10000).
346 * From version 1.0.1 it is:
347 * XXYYZZ, where XX=major, YY=minor, ZZ=release
348 */
349 #define PNG_LIBPNG_VER 10637 /* 1.6.37 */
350
351 /* Library configuration: these options cannot be changed after
352 * the library has been built.
353 */
354 #ifndef PNGLCONF_H
355 /* If pnglibconf.h is missing, you can
356 * copy scripts/pnglibconf.h.prebuilt to pnglibconf.h
357 */
358 # include "pnglibconf.h"
359 #endif
360
361 #ifndef PNG_VERSION_INFO_ONLY
362 /* Machine specific configuration. */
363 # include "pngconf.h"
364 #endif
365
366 /*
367 * Added at libpng-1.2.8
368 *
369 * Ref MSDN: Private as priority over Special
439 * does not use division?
440 * PNG_READ_COMPOSITE_NODIV_SUPPORTED: use the 'no division'
441 * algorithm.
442 * PNG_NO_READ_COMPOSITE_NODIV: use the 'division' algorithm.
443 *
444 * How to handle benign errors if PNG_ALLOW_BENIGN_ERRORS is
445 * false?
446 * PNG_ALLOW_BENIGN_ERRORS: map calls to the benign error
447 * APIs to png_warning.
448 * Otherwise the calls are mapped to png_error.
449 */
450
451 /* Section 3: type definitions, including structures and compile time
452 * constants.
453 * See pngconf.h for base types that vary by machine/system
454 */
455
456 /* This triggers a compiler error in png.c, if png.c and png.h
457 * do not agree upon the version number.
458 */
459 typedef char* png_libpng_version_1_6_37;
460
461 /* Basic control structions. Read libpng-manual.txt or libpng.3 for more info.
462 *
463 * png_struct is the cache of information used while reading or writing a single
464 * PNG file. One of these is always required, although the simplified API
465 * (below) hides the creation and destruction of it.
466 */
467 typedef struct png_struct_def png_struct;
468 typedef const png_struct * png_const_structp;
469 typedef png_struct * png_structp;
470 typedef png_struct * * png_structpp;
471
472 /* png_info contains information read from or to be written to a PNG file. One
473 * or more of these must exist while reading or creating a PNG file. The
474 * information is not used by libpng during read but is used to control what
475 * gets written when a PNG file is created. "png_get_" function calls read
476 * information during read and "png_set_" functions calls write information
477 * when creating a PNG.
478 * been moved into a separate header file that is not accessible to
479 * applications. Read libpng-manual.txt or libpng.3 for more info.
1993 double green_X, double green_Y, double green_Z, double blue_X,
1994 double blue_Y, double blue_Z))
1995 PNG_FIXED_EXPORT(136, void, png_set_cHRM_fixed, (png_const_structrp png_ptr,
1996 png_inforp info_ptr, png_fixed_point int_white_x,
1997 png_fixed_point int_white_y, png_fixed_point int_red_x,
1998 png_fixed_point int_red_y, png_fixed_point int_green_x,
1999 png_fixed_point int_green_y, png_fixed_point int_blue_x,
2000 png_fixed_point int_blue_y))
2001 PNG_FIXED_EXPORT(233, void, png_set_cHRM_XYZ_fixed, (png_const_structrp png_ptr,
2002 png_inforp info_ptr, png_fixed_point int_red_X, png_fixed_point int_red_Y,
2003 png_fixed_point int_red_Z, png_fixed_point int_green_X,
2004 png_fixed_point int_green_Y, png_fixed_point int_green_Z,
2005 png_fixed_point int_blue_X, png_fixed_point int_blue_Y,
2006 png_fixed_point int_blue_Z))
2007 #endif
2008
2009 #ifdef PNG_eXIf_SUPPORTED
2010 PNG_EXPORT(246, png_uint_32, png_get_eXIf, (png_const_structrp png_ptr,
2011 png_inforp info_ptr, png_bytep *exif));
2012 PNG_EXPORT(247, void, png_set_eXIf, (png_const_structrp png_ptr,
2013 png_inforp info_ptr, png_bytep exif));
2014
2015 PNG_EXPORT(248, png_uint_32, png_get_eXIf_1, (png_const_structrp png_ptr,
2016 png_const_inforp info_ptr, png_uint_32 *num_exif, png_bytep *exif));
2017 PNG_EXPORT(249, void, png_set_eXIf_1, (png_const_structrp png_ptr,
2018 png_inforp info_ptr, png_uint_32 num_exif, png_bytep exif));
2019 #endif
2020
2021 #ifdef PNG_gAMA_SUPPORTED
2022 PNG_FP_EXPORT(137, png_uint_32, png_get_gAMA, (png_const_structrp png_ptr,
2023 png_const_inforp info_ptr, double *file_gamma))
2024 PNG_FIXED_EXPORT(138, png_uint_32, png_get_gAMA_fixed,
2025 (png_const_structrp png_ptr, png_const_inforp info_ptr,
2026 png_fixed_point *int_file_gamma))
2027 #endif
2028
2029 #ifdef PNG_gAMA_SUPPORTED
2030 PNG_FP_EXPORT(139, void, png_set_gAMA, (png_const_structrp png_ptr,
2031 png_inforp info_ptr, double file_gamma))
2032 PNG_FIXED_EXPORT(140, void, png_set_gAMA_fixed, (png_const_structrp png_ptr,
2033 png_inforp info_ptr, png_fixed_point int_file_gamma))
2034 #endif
2035
2036 #ifdef PNG_hIST_SUPPORTED
2037 PNG_EXPORT(141, png_uint_32, png_get_hIST, (png_const_structrp png_ptr,
2038 png_inforp info_ptr, png_uint_16p *hist));
2744 * 4: Three color channels and an alpha channel (RGBA).
2745 *
2746 * The components are encoded in one of two ways:
2747 *
2748 * a) As a small integer, value 0..255, contained in a single byte. For the
2749 * alpha channel the original value is simply value/255. For the color or
2750 * luminance channels the value is encoded according to the sRGB specification
2751 * and matches the 8-bit format expected by typical display devices.
2752 *
2753 * The color/gray channels are not scaled (pre-multiplied) by the alpha
2754 * channel and are suitable for passing to color management software.
2755 *
2756 * b) As a value in the range 0..65535, contained in a 2-byte integer. All
2757 * channels can be converted to the original value by dividing by 65535; all
2758 * channels are linear. Color channels use the RGB encoding (RGB end-points) of
2759 * the sRGB specification. This encoding is identified by the
2760 * PNG_FORMAT_FLAG_LINEAR flag below.
2761 *
2762 * When the simplified API needs to convert between sRGB and linear colorspaces,
2763 * the actual sRGB transfer curve defined in the sRGB specification (see the
2764 * article at <https://en.wikipedia.org/wiki/SRGB>) is used, not the gamma=1/2.2
2765 * approximation used elsewhere in libpng.
2766 *
2767 * When an alpha channel is present it is expected to denote pixel coverage
2768 * of the color or luminance channels and is returned as an associated alpha
2769 * channel: the color/gray channels are scaled (pre-multiplied) by the alpha
2770 * value.
2771 *
2772 * The samples are either contained directly in the image data, between 1 and 8
2773 * bytes per pixel according to the encoding, or are held in a color-map indexed
2774 * by bytes in the image data. In the case of a color-map the color-map entries
2775 * are individual samples, encoded as above, and the image data has one byte per
2776 * pixel to select the relevant sample from the color-map.
2777 */
2778
2779 /* PNG_FORMAT_*
2780 *
2781 * #defines to be used in png_image::format. Each #define identifies a
2782 * particular layout of sample data and, if present, alpha values. There are
2783 * separate defines for each of the two component encodings.
2784 *
2947 #define PNG_IMAGE_SIZE(image)\
2948 PNG_IMAGE_BUFFER_SIZE(image, PNG_IMAGE_ROW_STRIDE(image))
2949 /* Return the size, in bytes, of the image in memory given just a png_image;
2950 * the row stride is the minimum stride required for the image.
2951 */
2952
2953 #define PNG_IMAGE_COLORMAP_SIZE(image)\
2954 (PNG_IMAGE_SAMPLE_SIZE((image).format) * (image).colormap_entries)
2955 /* Return the size, in bytes, of the color-map of this image. If the image
2956 * format is not a color-map format this will return a size sufficient for
2957 * 256 entries in the given format; check PNG_FORMAT_FLAG_COLORMAP if
2958 * you don't want to allocate a color-map in this case.
2959 */
2960
2961 /* PNG_IMAGE_FLAG_*
2962 *
2963 * Flags containing additional information about the image are held in the
2964 * 'flags' field of png_image.
2965 */
2966 #define PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB 0x01
2967 /* This indicates that the RGB values of the in-memory bitmap do not
2968 * correspond to the red, green and blue end-points defined by sRGB.
2969 */
2970
2971 #define PNG_IMAGE_FLAG_FAST 0x02
2972 /* On write emphasise speed over compression; the resultant PNG file will be
2973 * larger but will be produced significantly faster, particular for large
2974 * images. Do not use this option for images which will be distributed, only
2975 * used it when producing intermediate files that will be read back in
2976 * repeatedly. For a typical 24-bit image the option will double the read
2977 * speed at the cost of increasing the image size by 25%, however for many
2978 * more compressible images the PNG file can be 10 times larger with only a
2979 * slight speed gain.
2980 */
2981
2982 #define PNG_IMAGE_FLAG_16BIT_sRGB 0x04
2983 /* On read if the image is a 16-bit per component image and there is no gAMA
2984 * or sRGB chunk assume that the components are sRGB encoded. Notice that
2985 * images output by the simplified API always have gamma information; setting
2986 * this flag only affects the interpretation of 16-bit images from an
2987 * external source. It is recommended that the application expose this flag
|