1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libpng/libpng-manual.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,5293 @@
1.4 +libpng-manual.txt - A description on how to use and modify libpng
1.5 +
1.6 + libpng version 1.6.9 - February 6, 2014
1.7 + Updated and distributed by Glenn Randers-Pehrson
1.8 + <glennrp at users.sourceforge.net>
1.9 + Copyright (c) 1998-2014 Glenn Randers-Pehrson
1.10 +
1.11 + This document is released under the libpng license.
1.12 + For conditions of distribution and use, see the disclaimer
1.13 + and license in png.h
1.14 +
1.15 + Based on:
1.16 +
1.17 + libpng versions 0.97, January 1998, through 1.6.9 - February 6, 2014
1.18 + Updated and distributed by Glenn Randers-Pehrson
1.19 + Copyright (c) 1998-2014 Glenn Randers-Pehrson
1.20 +
1.21 + libpng 1.0 beta 6 version 0.96 May 28, 1997
1.22 + Updated and distributed by Andreas Dilger
1.23 + Copyright (c) 1996, 1997 Andreas Dilger
1.24 +
1.25 + libpng 1.0 beta 2 - version 0.88 January 26, 1996
1.26 + For conditions of distribution and use, see copyright
1.27 + notice in png.h. Copyright (c) 1995, 1996 Guy Eric
1.28 + Schalnat, Group 42, Inc.
1.29 +
1.30 + Updated/rewritten per request in the libpng FAQ
1.31 + Copyright (c) 1995, 1996 Frank J. T. Wojcik
1.32 + December 18, 1995 & January 20, 1996
1.33 +
1.34 + TABLE OF CONTENTS
1.35 +
1.36 + I. Introduction
1.37 + II. Structures
1.38 + III. Reading
1.39 + IV. Writing
1.40 + V. Simplified API
1.41 + VI. Modifying/Customizing libpng
1.42 + VII. MNG support
1.43 + VIII. Changes to Libpng from version 0.88
1.44 + IX. Changes to Libpng from version 1.0.x to 1.2.x
1.45 + X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
1.46 + XI. Changes to Libpng from version 1.4.x to 1.5.x
1.47 + XII. Changes to Libpng from version 1.5.x to 1.6.x
1.48 + XIII. Detecting libpng
1.49 + XIV. Source code repository
1.50 + XV. Coding style
1.51 + XVI. Y2K Compliance in libpng
1.52 +
1.53 +I. Introduction
1.54 +
1.55 +This file describes how to use and modify the PNG reference library
1.56 +(known as libpng) for your own use. In addition to this
1.57 +file, example.c is a good starting point for using the library, as
1.58 +it is heavily commented and should include everything most people
1.59 +will need. We assume that libpng is already installed; see the
1.60 +INSTALL file for instructions on how to install libpng.
1.61 +
1.62 +For examples of libpng usage, see the files "example.c", "pngtest.c",
1.63 +and the files in the "contrib" directory, all of which are included in
1.64 +the libpng distribution.
1.65 +
1.66 +Libpng was written as a companion to the PNG specification, as a way
1.67 +of reducing the amount of time and effort it takes to support the PNG
1.68 +file format in application programs.
1.69 +
1.70 +The PNG specification (second edition), November 2003, is available as
1.71 +a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at
1.72 +<http://www.w3.org/TR/2003/REC-PNG-20031110/
1.73 +The W3C and ISO documents have identical technical content.
1.74 +
1.75 +The PNG-1.2 specification is available at
1.76 +<http://www.libpng.org/pub/png/documents/>. It is technically equivalent
1.77 +to the PNG specification (second edition) but has some additional material.
1.78 +
1.79 +The PNG-1.0 specification is available
1.80 +as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
1.81 +W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
1.82 +
1.83 +Some additional chunks are described in the special-purpose public chunks
1.84 +documents at <http://www.libpng.org/pub/png/documents/>.
1.85 +
1.86 +Other information
1.87 +about PNG, and the latest version of libpng, can be found at the PNG home
1.88 +page, <http://www.libpng.org/pub/png/>.
1.89 +
1.90 +Most users will not have to modify the library significantly; advanced
1.91 +users may want to modify it more. All attempts were made to make it as
1.92 +complete as possible, while keeping the code easy to understand.
1.93 +Currently, this library only supports C. Support for other languages
1.94 +is being considered.
1.95 +
1.96 +Libpng has been designed to handle multiple sessions at one time,
1.97 +to be easily modifiable, to be portable to the vast majority of
1.98 +machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
1.99 +to use. The ultimate goal of libpng is to promote the acceptance of
1.100 +the PNG file format in whatever way possible. While there is still
1.101 +work to be done (see the TODO file), libpng should cover the
1.102 +majority of the needs of its users.
1.103 +
1.104 +Libpng uses zlib for its compression and decompression of PNG files.
1.105 +Further information about zlib, and the latest version of zlib, can
1.106 +be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
1.107 +The zlib compression utility is a general purpose utility that is
1.108 +useful for more than PNG files, and can be used without libpng.
1.109 +See the documentation delivered with zlib for more details.
1.110 +You can usually find the source files for the zlib utility wherever you
1.111 +find the libpng source files.
1.112 +
1.113 +Libpng is thread safe, provided the threads are using different
1.114 +instances of the structures. Each thread should have its own
1.115 +png_struct and png_info instances, and thus its own image.
1.116 +Libpng does not protect itself against two threads using the
1.117 +same instance of a structure.
1.118 +
1.119 +II. Structures
1.120 +
1.121 +There are two main structures that are important to libpng, png_struct
1.122 +and png_info. Both are internal structures that are no longer exposed
1.123 +in the libpng interface (as of libpng 1.5.0).
1.124 +
1.125 +The png_info structure is designed to provide information about the
1.126 +PNG file. At one time, the fields of png_info were intended to be
1.127 +directly accessible to the user. However, this tended to cause problems
1.128 +with applications using dynamically loaded libraries, and as a result
1.129 +a set of interface functions for png_info (the png_get_*() and png_set_*()
1.130 +functions) was developed, and direct access to the png_info fields was
1.131 +deprecated..
1.132 +
1.133 +The png_struct structure is the object used by the library to decode a
1.134 +single image. As of 1.5.0 this structure is also not exposed.
1.135 +
1.136 +Almost all libpng APIs require a pointer to a png_struct as the first argument.
1.137 +Many (in particular the png_set and png_get APIs) also require a pointer
1.138 +to png_info as the second argument. Some application visible macros
1.139 +defined in png.h designed for basic data access (reading and writing
1.140 +integers in the PNG format) don't take a png_info pointer, but it's almost
1.141 +always safe to assume that a (png_struct*) has to be passed to call an API
1.142 +function.
1.143 +
1.144 +You can have more than one png_info structure associated with an image,
1.145 +as illustrated in pngtest.c, one for information valid prior to the
1.146 +IDAT chunks and another (called "end_info" below) for things after them.
1.147 +
1.148 +The png.h header file is an invaluable reference for programming with libpng.
1.149 +And while I'm on the topic, make sure you include the libpng header file:
1.150 +
1.151 +#include <png.h>
1.152 +
1.153 +and also (as of libpng-1.5.0) the zlib header file, if you need it:
1.154 +
1.155 +#include <zlib.h>
1.156 +
1.157 +Types
1.158 +
1.159 +The png.h header file defines a number of integral types used by the
1.160 +APIs. Most of these are fairly obvious; for example types corresponding
1.161 +to integers of particular sizes and types for passing color values.
1.162 +
1.163 +One exception is how non-integral numbers are handled. For application
1.164 +convenience most APIs that take such numbers have C (double) arguments;
1.165 +however, internally PNG, and libpng, use 32 bit signed integers and encode
1.166 +the value by multiplying by 100,000. As of libpng 1.5.0 a convenience
1.167 +macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
1.168 +which is simply (png_int_32).
1.169 +
1.170 +All APIs that take (double) arguments also have a matching API that
1.171 +takes the corresponding fixed point integer arguments. The fixed point
1.172 +API has the same name as the floating point one with "_fixed" appended.
1.173 +The actual range of values permitted in the APIs is frequently less than
1.174 +the full range of (png_fixed_point) (-21474 to +21474). When APIs require
1.175 +a non-negative argument the type is recorded as png_uint_32 above. Consult
1.176 +the header file and the text below for more information.
1.177 +
1.178 +Special care must be take with sCAL chunk handling because the chunk itself
1.179 +uses non-integral values encoded as strings containing decimal floating point
1.180 +numbers. See the comments in the header file.
1.181 +
1.182 +Configuration
1.183 +
1.184 +The main header file function declarations are frequently protected by C
1.185 +preprocessing directives of the form:
1.186 +
1.187 + #ifdef PNG_feature_SUPPORTED
1.188 + declare-function
1.189 + #endif
1.190 + ...
1.191 + #ifdef PNG_feature_SUPPORTED
1.192 + use-function
1.193 + #endif
1.194 +
1.195 +The library can be built without support for these APIs, although a
1.196 +standard build will have all implemented APIs. Application programs
1.197 +should check the feature macros before using an API for maximum
1.198 +portability. From libpng 1.5.0 the feature macros set during the build
1.199 +of libpng are recorded in the header file "pnglibconf.h" and this file
1.200 +is always included by png.h.
1.201 +
1.202 +If you don't need to change the library configuration from the default, skip to
1.203 +the next section ("Reading").
1.204 +
1.205 +Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all
1.206 +of the build project files in the 'projects' directory simply copy
1.207 +scripts/pnglibconf.h.prebuilt to pnglibconf.h. This means that these build
1.208 +systems do not permit easy auto-configuration of the library - they only
1.209 +support the default configuration.
1.210 +
1.211 +The easiest way to make minor changes to the libpng configuration when
1.212 +auto-configuration is supported is to add definitions to the command line
1.213 +using (typically) CPPFLAGS. For example:
1.214 +
1.215 +CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC
1.216 +
1.217 +will change the internal libpng math implementation for gamma correction and
1.218 +other arithmetic calculations to fixed point, avoiding the need for fast
1.219 +floating point support. The result can be seen in the generated pnglibconf.h -
1.220 +make sure it contains the changed feature macro setting.
1.221 +
1.222 +If you need to make more extensive configuration changes - more than one or two
1.223 +feature macro settings - you can either add -DPNG_USER_CONFIG to the build
1.224 +command line and put a list of feature macro settings in pngusr.h or you can set
1.225 +DFA_XTRA (a makefile variable) to a file containing the same information in the
1.226 +form of 'option' settings.
1.227 +
1.228 +A. Changing pnglibconf.h
1.229 +
1.230 +A variety of methods exist to build libpng. Not all of these support
1.231 +reconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either be
1.232 +rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
1.233 +
1.234 +Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
1.235 +pnglibconf.h and changing the lines defining the supported features, paying
1.236 +very close attention to the 'option' information in scripts/pnglibconf.dfa
1.237 +that describes those features and their requirements. This is easy to get
1.238 +wrong.
1.239 +
1.240 +B. Configuration using DFA_XTRA
1.241 +
1.242 +Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
1.243 +variant such as 'nawk' or 'gawk', is available. The configure build will
1.244 +automatically find an appropriate awk and build pnglibconf.h.
1.245 +The scripts/pnglibconf.mak file contains a set of make rules for doing the
1.246 +same thing if configure is not used, and many of the makefiles in the scripts
1.247 +directory use this approach.
1.248 +
1.249 +When rebuilding simply write a new file containing changed options and set
1.250 +DFA_XTRA to the name of this file. This causes the build to append the new file
1.251 +to the end of scripts/pnglibconf.dfa. The pngusr.dfa file should contain lines
1.252 +of the following forms:
1.253 +
1.254 +everything = off
1.255 +
1.256 +This turns all optional features off. Include it at the start of pngusr.dfa to
1.257 +make it easier to build a minimal configuration. You will need to turn at least
1.258 +some features on afterward to enable either reading or writing code, or both.
1.259 +
1.260 +option feature on
1.261 +option feature off
1.262 +
1.263 +Enable or disable a single feature. This will automatically enable other
1.264 +features required by a feature that is turned on or disable other features that
1.265 +require a feature which is turned off. Conflicting settings will cause an error
1.266 +message to be emitted by awk.
1.267 +
1.268 +setting feature default value
1.269 +
1.270 +Changes the default value of setting 'feature' to 'value'. There are a small
1.271 +number of settings listed at the top of pnglibconf.h, they are documented in the
1.272 +source code. Most of these values have performance implications for the library
1.273 +but most of them have no visible effect on the API. Some can also be overridden
1.274 +from the API.
1.275 +
1.276 +This method of building a customized pnglibconf.h is illustrated in
1.277 +contrib/pngminim/*. See the "$(PNGCONF):" target in the makefile and
1.278 +pngusr.dfa in these directories.
1.279 +
1.280 +C. Configuration using PNG_USR_CONFIG
1.281 +
1.282 +If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
1.283 +pngusr.h will automatically be included before the options in
1.284 +scripts/pnglibconf.dfa are processed. Your pngusr.h file should contain only
1.285 +macro definitions turning features on or off or setting settings.
1.286 +
1.287 +Apart from the global setting "everything = off" all the options listed above
1.288 +can be set using macros in pngusr.h:
1.289 +
1.290 +#define PNG_feature_SUPPORTED
1.291 +
1.292 +is equivalent to:
1.293 +
1.294 +option feature on
1.295 +
1.296 +#define PNG_NO_feature
1.297 +
1.298 +is equivalent to:
1.299 +
1.300 +option feature off
1.301 +
1.302 +#define PNG_feature value
1.303 +
1.304 +is equivalent to:
1.305 +
1.306 +setting feature default value
1.307 +
1.308 +Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the
1.309 +pngusr file you supply override the contents of scripts/pnglibconf.dfa
1.310 +
1.311 +If confusing or incomprehensible behavior results it is possible to
1.312 +examine the intermediate file pnglibconf.dfn to find the full set of
1.313 +dependency information for each setting and option. Simply locate the
1.314 +feature in the file and read the C comments that precede it.
1.315 +
1.316 +This method is also illustrated in the contrib/pngminim/* makefiles and
1.317 +pngusr.h.
1.318 +
1.319 +III. Reading
1.320 +
1.321 +We'll now walk you through the possible functions to call when reading
1.322 +in a PNG file sequentially, briefly explaining the syntax and purpose
1.323 +of each one. See example.c and png.h for more detail. While
1.324 +progressive reading is covered in the next section, you will still
1.325 +need some of the functions discussed in this section to read a PNG
1.326 +file.
1.327 +
1.328 +Setup
1.329 +
1.330 +You will want to do the I/O initialization(*) before you get into libpng,
1.331 +so if it doesn't work, you don't have much to undo. Of course, you
1.332 +will also want to insure that you are, in fact, dealing with a PNG
1.333 +file. Libpng provides a simple check to see if a file is a PNG file.
1.334 +To use it, pass in the first 1 to 8 bytes of the file to the function
1.335 +png_sig_cmp(), and it will return 0 (false) if the bytes match the
1.336 +corresponding bytes of the PNG signature, or nonzero (true) otherwise.
1.337 +Of course, the more bytes you pass in, the greater the accuracy of the
1.338 +prediction.
1.339 +
1.340 +If you are intending to keep the file pointer open for use in libpng,
1.341 +you must ensure you don't read more than 8 bytes from the beginning
1.342 +of the file, and you also have to make a call to png_set_sig_bytes_read()
1.343 +with the number of bytes you read from the beginning. Libpng will
1.344 +then only check the bytes (if any) that your program didn't read.
1.345 +
1.346 +(*): If you are not using the standard I/O functions, you will need
1.347 +to replace them with custom functions. See the discussion under
1.348 +Customizing libpng.
1.349 +
1.350 +
1.351 + FILE *fp = fopen(file_name, "rb");
1.352 + if (!fp)
1.353 + {
1.354 + return (ERROR);
1.355 + }
1.356 +
1.357 + fread(header, 1, number, fp);
1.358 + is_png = !png_sig_cmp(header, 0, number);
1.359 +
1.360 + if (!is_png)
1.361 + {
1.362 + return (NOT_PNG);
1.363 + }
1.364 +
1.365 +
1.366 +Next, png_struct and png_info need to be allocated and initialized. In
1.367 +order to ensure that the size of these structures is correct even with a
1.368 +dynamically linked libpng, there are functions to initialize and
1.369 +allocate the structures. We also pass the library version, optional
1.370 +pointers to error handling functions, and a pointer to a data struct for
1.371 +use by the error functions, if necessary (the pointer and functions can
1.372 +be NULL if the default error handlers are to be used). See the section
1.373 +on Changes to Libpng below regarding the old initialization functions.
1.374 +The structure allocation functions quietly return NULL if they fail to
1.375 +create the structure, so your application should check for that.
1.376 +
1.377 + png_structp png_ptr = png_create_read_struct
1.378 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1.379 + user_error_fn, user_warning_fn);
1.380 +
1.381 + if (!png_ptr)
1.382 + return (ERROR);
1.383 +
1.384 + png_infop info_ptr = png_create_info_struct(png_ptr);
1.385 +
1.386 + if (!info_ptr)
1.387 + {
1.388 + png_destroy_read_struct(&png_ptr,
1.389 + (png_infopp)NULL, (png_infopp)NULL);
1.390 + return (ERROR);
1.391 + }
1.392 +
1.393 +If you want to use your own memory allocation routines,
1.394 +use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
1.395 +png_create_read_struct_2() instead of png_create_read_struct():
1.396 +
1.397 + png_structp png_ptr = png_create_read_struct_2
1.398 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1.399 + user_error_fn, user_warning_fn, (png_voidp)
1.400 + user_mem_ptr, user_malloc_fn, user_free_fn);
1.401 +
1.402 +The error handling routines passed to png_create_read_struct()
1.403 +and the memory alloc/free routines passed to png_create_struct_2()
1.404 +are only necessary if you are not using the libpng supplied error
1.405 +handling and memory alloc/free functions.
1.406 +
1.407 +When libpng encounters an error, it expects to longjmp back
1.408 +to your routine. Therefore, you will need to call setjmp and pass
1.409 +your png_jmpbuf(png_ptr). If you read the file from different
1.410 +routines, you will need to update the longjmp buffer every time you enter
1.411 +a new routine that will call a png_*() function.
1.412 +
1.413 +See your documentation of setjmp/longjmp for your compiler for more
1.414 +information on setjmp/longjmp. See the discussion on libpng error
1.415 +handling in the Customizing Libpng section below for more information
1.416 +on the libpng error handling. If an error occurs, and libpng longjmp's
1.417 +back to your setjmp, you will want to call png_destroy_read_struct() to
1.418 +free any memory.
1.419 +
1.420 + if (setjmp(png_jmpbuf(png_ptr)))
1.421 + {
1.422 + png_destroy_read_struct(&png_ptr, &info_ptr,
1.423 + &end_info);
1.424 + fclose(fp);
1.425 + return (ERROR);
1.426 + }
1.427 +
1.428 +Pass (png_infopp)NULL instead of &end_info if you didn't create
1.429 +an end_info structure.
1.430 +
1.431 +If you would rather avoid the complexity of setjmp/longjmp issues,
1.432 +you can compile libpng with PNG_NO_SETJMP, in which case
1.433 +errors will result in a call to PNG_ABORT() which defaults to abort().
1.434 +
1.435 +You can #define PNG_ABORT() to a function that does something
1.436 +more useful than abort(), as long as your function does not
1.437 +return.
1.438 +
1.439 +Now you need to set up the input code. The default for libpng is to
1.440 +use the C function fread(). If you use this, you will need to pass a
1.441 +valid FILE * in the function png_init_io(). Be sure that the file is
1.442 +opened in binary mode. If you wish to handle reading data in another
1.443 +way, you need not call the png_init_io() function, but you must then
1.444 +implement the libpng I/O methods discussed in the Customizing Libpng
1.445 +section below.
1.446 +
1.447 + png_init_io(png_ptr, fp);
1.448 +
1.449 +If you had previously opened the file and read any of the signature from
1.450 +the beginning in order to see if this was a PNG file, you need to let
1.451 +libpng know that there are some bytes missing from the start of the file.
1.452 +
1.453 + png_set_sig_bytes(png_ptr, number);
1.454 +
1.455 +You can change the zlib compression buffer size to be used while
1.456 +reading compressed data with
1.457 +
1.458 + png_set_compression_buffer_size(png_ptr, buffer_size);
1.459 +
1.460 +where the default size is 8192 bytes. Note that the buffer size
1.461 +is changed immediately and the buffer is reallocated immediately,
1.462 +instead of setting a flag to be acted upon later.
1.463 +
1.464 +If you want CRC errors to be handled in a different manner than
1.465 +the default, use
1.466 +
1.467 + png_set_crc_action(png_ptr, crit_action, ancil_action);
1.468 +
1.469 +The values for png_set_crc_action() say how libpng is to handle CRC errors in
1.470 +ancillary and critical chunks, and whether to use the data contained
1.471 +therein. Note that it is impossible to "discard" data in a critical
1.472 +chunk.
1.473 +
1.474 +Choices for (int) crit_action are
1.475 + PNG_CRC_DEFAULT 0 error/quit
1.476 + PNG_CRC_ERROR_QUIT 1 error/quit
1.477 + PNG_CRC_WARN_USE 3 warn/use data
1.478 + PNG_CRC_QUIET_USE 4 quiet/use data
1.479 + PNG_CRC_NO_CHANGE 5 use the current value
1.480 +
1.481 +Choices for (int) ancil_action are
1.482 + PNG_CRC_DEFAULT 0 error/quit
1.483 + PNG_CRC_ERROR_QUIT 1 error/quit
1.484 + PNG_CRC_WARN_DISCARD 2 warn/discard data
1.485 + PNG_CRC_WARN_USE 3 warn/use data
1.486 + PNG_CRC_QUIET_USE 4 quiet/use data
1.487 + PNG_CRC_NO_CHANGE 5 use the current value
1.488 +
1.489 +Setting up callback code
1.490 +
1.491 +You can set up a callback function to handle any unknown chunks in the
1.492 +input stream. You must supply the function
1.493 +
1.494 + read_chunk_callback(png_structp png_ptr,
1.495 + png_unknown_chunkp chunk);
1.496 + {
1.497 + /* The unknown chunk structure contains your
1.498 + chunk data, along with similar data for any other
1.499 + unknown chunks: */
1.500 +
1.501 + png_byte name[5];
1.502 + png_byte *data;
1.503 + png_size_t size;
1.504 +
1.505 + /* Note that libpng has already taken care of
1.506 + the CRC handling */
1.507 +
1.508 + /* put your code here. Search for your chunk in the
1.509 + unknown chunk structure, process it, and return one
1.510 + of the following: */
1.511 +
1.512 + return (-n); /* chunk had an error */
1.513 + return (0); /* did not recognize */
1.514 + return (n); /* success */
1.515 + }
1.516 +
1.517 +(You can give your function another name that you like instead of
1.518 +"read_chunk_callback")
1.519 +
1.520 +To inform libpng about your function, use
1.521 +
1.522 + png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
1.523 + read_chunk_callback);
1.524 +
1.525 +This names not only the callback function, but also a user pointer that
1.526 +you can retrieve with
1.527 +
1.528 + png_get_user_chunk_ptr(png_ptr);
1.529 +
1.530 +If you call the png_set_read_user_chunk_fn() function, then all unknown
1.531 +chunks which the callback does not handle will be saved when read. You can
1.532 +cause them to be discarded by returning '1' ("handled") instead of '0'. This
1.533 +behavior will change in libpng 1.7 and the default handling set by the
1.534 +png_set_keep_unknown_chunks() function, described below, will be used when the
1.535 +callback returns 0. If you want the existing behavior you should set the global
1.536 +default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current
1.537 +versions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep the
1.538 +default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.
1.539 +
1.540 +At this point, you can set up a callback function that will be
1.541 +called after each row has been read, which you can use to control
1.542 +a progress meter or the like. It's demonstrated in pngtest.c.
1.543 +You must supply a function
1.544 +
1.545 + void read_row_callback(png_structp png_ptr,
1.546 + png_uint_32 row, int pass);
1.547 + {
1.548 + /* put your code here */
1.549 + }
1.550 +
1.551 +(You can give it another name that you like instead of "read_row_callback")
1.552 +
1.553 +To inform libpng about your function, use
1.554 +
1.555 + png_set_read_status_fn(png_ptr, read_row_callback);
1.556 +
1.557 +When this function is called the row has already been completely processed and
1.558 +the 'row' and 'pass' refer to the next row to be handled. For the
1.559 +non-interlaced case the row that was just handled is simply one less than the
1.560 +passed in row number, and pass will always be 0. For the interlaced case the
1.561 +same applies unless the row value is 0, in which case the row just handled was
1.562 +the last one from one of the preceding passes. Because interlacing may skip a
1.563 +pass you cannot be sure that the preceding pass is just 'pass-1', if you really
1.564 +need to know what the last pass is record (row,pass) from the callback and use
1.565 +the last recorded value each time.
1.566 +
1.567 +As with the user transform you can find the output row using the
1.568 +PNG_ROW_FROM_PASS_ROW macro.
1.569 +
1.570 +Unknown-chunk handling
1.571 +
1.572 +Now you get to set the way the library processes unknown chunks in the
1.573 +input PNG stream. Both known and unknown chunks will be read. Normal
1.574 +behavior is that known chunks will be parsed into information in
1.575 +various info_ptr members while unknown chunks will be discarded. This
1.576 +behavior can be wasteful if your application will never use some known
1.577 +chunk types. To change this, you can call:
1.578 +
1.579 + png_set_keep_unknown_chunks(png_ptr, keep,
1.580 + chunk_list, num_chunks);
1.581 +
1.582 + keep - 0: default unknown chunk handling
1.583 + 1: ignore; do not keep
1.584 + 2: keep only if safe-to-copy
1.585 + 3: keep even if unsafe-to-copy
1.586 +
1.587 + You can use these definitions:
1.588 + PNG_HANDLE_CHUNK_AS_DEFAULT 0
1.589 + PNG_HANDLE_CHUNK_NEVER 1
1.590 + PNG_HANDLE_CHUNK_IF_SAFE 2
1.591 + PNG_HANDLE_CHUNK_ALWAYS 3
1.592 +
1.593 + chunk_list - list of chunks affected (a byte string,
1.594 + five bytes per chunk, NULL or '\0' if
1.595 + num_chunks is positive; ignored if
1.596 + numchunks <= 0).
1.597 +
1.598 + num_chunks - number of chunks affected; if 0, all
1.599 + unknown chunks are affected. If positive,
1.600 + only the chunks in the list are affected,
1.601 + and if negative all unknown chunks and
1.602 + all known chunks except for the IHDR,
1.603 + PLTE, tRNS, IDAT, and IEND chunks are
1.604 + affected.
1.605 +
1.606 +Unknown chunks declared in this way will be saved as raw data onto a
1.607 +list of png_unknown_chunk structures. If a chunk that is normally
1.608 +known to libpng is named in the list, it will be handled as unknown,
1.609 +according to the "keep" directive. If a chunk is named in successive
1.610 +instances of png_set_keep_unknown_chunks(), the final instance will
1.611 +take precedence. The IHDR and IEND chunks should not be named in
1.612 +chunk_list; if they are, libpng will process them normally anyway.
1.613 +If you know that your application will never make use of some particular
1.614 +chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below.
1.615 +
1.616 +Here is an example of the usage of png_set_keep_unknown_chunks(),
1.617 +where the private "vpAg" chunk will later be processed by a user chunk
1.618 +callback function:
1.619 +
1.620 + png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'};
1.621 +
1.622 + #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1.623 + png_byte unused_chunks[]=
1.624 + {
1.625 + 104, 73, 83, 84, (png_byte) '\0', /* hIST */
1.626 + 105, 84, 88, 116, (png_byte) '\0', /* iTXt */
1.627 + 112, 67, 65, 76, (png_byte) '\0', /* pCAL */
1.628 + 115, 67, 65, 76, (png_byte) '\0', /* sCAL */
1.629 + 115, 80, 76, 84, (png_byte) '\0', /* sPLT */
1.630 + 116, 73, 77, 69, (png_byte) '\0', /* tIME */
1.631 + };
1.632 + #endif
1.633 +
1.634 + ...
1.635 +
1.636 + #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1.637 + /* ignore all unknown chunks
1.638 + * (use global setting "2" for libpng16 and earlier):
1.639 + */
1.640 + png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0);
1.641 +
1.642 + /* except for vpAg: */
1.643 + png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
1.644 +
1.645 + /* also ignore unused known chunks: */
1.646 + png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
1.647 + (int)(sizeof unused_chunks)/5);
1.648 + #endif
1.649 +
1.650 +User limits
1.651 +
1.652 +The PNG specification allows the width and height of an image to be as
1.653 +large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
1.654 +Since very few applications really need to process such large images,
1.655 +we have imposed an arbitrary 1-million limit on rows and columns.
1.656 +Larger images will be rejected immediately with a png_error() call. If
1.657 +you wish to change this limit, you can use
1.658 +
1.659 + png_set_user_limits(png_ptr, width_max, height_max);
1.660 +
1.661 +to set your own limits, or use width_max = height_max = 0x7fffffffL
1.662 +to allow all valid dimensions (libpng may reject some very large images
1.663 +anyway because of potential buffer overflow conditions).
1.664 +
1.665 +You should put this statement after you create the PNG structure and
1.666 +before calling png_read_info(), png_read_png(), or png_process_data().
1.667 +
1.668 +When writing a PNG datastream, put this statement before calling
1.669 +png_write_info() or png_write_png().
1.670 +
1.671 +If you need to retrieve the limits that are being applied, use
1.672 +
1.673 + width_max = png_get_user_width_max(png_ptr);
1.674 + height_max = png_get_user_height_max(png_ptr);
1.675 +
1.676 +The PNG specification sets no limit on the number of ancillary chunks
1.677 +allowed in a PNG datastream. You can impose a limit on the total number
1.678 +of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
1.679 +
1.680 + png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
1.681 +
1.682 +where 0x7fffffffL means unlimited. You can retrieve this limit with
1.683 +
1.684 + chunk_cache_max = png_get_chunk_cache_max(png_ptr);
1.685 +
1.686 +You can also set a limit on the amount of memory that a compressed chunk
1.687 +other than IDAT can occupy, with
1.688 +
1.689 + png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
1.690 +
1.691 +and you can retrieve the limit with
1.692 +
1.693 + chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
1.694 +
1.695 +Any chunks that would cause either of these limits to be exceeded will
1.696 +be ignored.
1.697 +
1.698 +Information about your system
1.699 +
1.700 +If you intend to display the PNG or to incorporate it in other image data you
1.701 +need to tell libpng information about your display or drawing surface so that
1.702 +libpng can convert the values in the image to match the display.
1.703 +
1.704 +From libpng-1.5.4 this information can be set before reading the PNG file
1.705 +header. In earlier versions png_set_gamma() existed but behaved incorrectly if
1.706 +called before the PNG file header had been read and png_set_alpha_mode() did not
1.707 +exist.
1.708 +
1.709 +If you need to support versions prior to libpng-1.5.4 test the version number
1.710 +as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures
1.711 +described in the appropriate manual page.
1.712 +
1.713 +You give libpng the encoding expected by your system expressed as a 'gamma'
1.714 +value. You can also specify a default encoding for the PNG file in
1.715 +case the required information is missing from the file. By default libpng
1.716 +assumes that the PNG data matches your system, to keep this default call:
1.717 +
1.718 + png_set_gamma(png_ptr, screen_gamma, 1/screen_gamma/*file gamma*/);
1.719 +
1.720 +or you can use the fixed point equivalent:
1.721 +
1.722 + png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma,
1.723 + PNG_FP_1/screen_gamma);
1.724 +
1.725 +If you don't know the gamma for your system it is probably 2.2 - a good
1.726 +approximation to the IEC standard for display systems (sRGB). If images are
1.727 +too contrasty or washed out you got the value wrong - check your system
1.728 +documentation!
1.729 +
1.730 +Many systems permit the system gamma to be changed via a lookup table in the
1.731 +display driver, a few systems, including older Macs, change the response by
1.732 +default. As of 1.5.4 three special values are available to handle common
1.733 +situations:
1.734 +
1.735 + PNG_DEFAULT_sRGB: Indicates that the system conforms to the
1.736 + IEC 61966-2-1 standard. This matches almost
1.737 + all systems.
1.738 + PNG_GAMMA_MAC_18: Indicates that the system is an older
1.739 + (pre Mac OS 10.6) Apple Macintosh system with
1.740 + the default settings.
1.741 + PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates
1.742 + that the system expects data with no gamma
1.743 + encoding.
1.744 +
1.745 +You would use the linear (unencoded) value if you need to process the pixel
1.746 +values further because this avoids the need to decode and re-encode each
1.747 +component value whenever arithmetic is performed. A lot of graphics software
1.748 +uses linear values for this reason, often with higher precision component values
1.749 +to preserve overall accuracy.
1.750 +
1.751 +The second thing you may need to tell libpng about is how your system handles
1.752 +alpha channel information. Some, but not all, PNG files contain an alpha
1.753 +channel. To display these files correctly you need to compose the data onto a
1.754 +suitable background, as described in the PNG specification.
1.755 +
1.756 +Libpng only supports composing onto a single color (using png_set_background;
1.757 +see below). Otherwise you must do the composition yourself and, in this case,
1.758 +you may need to call png_set_alpha_mode:
1.759 +
1.760 + #if PNG_LIBPNG_VER >= 10504
1.761 + png_set_alpha_mode(png_ptr, mode, screen_gamma);
1.762 + #else
1.763 + png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
1.764 + #endif
1.765 +
1.766 +The screen_gamma value is the same as the argument to png_set_gamma; however,
1.767 +how it affects the output depends on the mode. png_set_alpha_mode() sets the
1.768 +file gamma default to 1/screen_gamma, so normally you don't need to call
1.769 +png_set_gamma. If you need different defaults call png_set_gamma() before
1.770 +png_set_alpha_mode() - if you call it after it will override the settings made
1.771 +by png_set_alpha_mode().
1.772 +
1.773 +The mode is as follows:
1.774 +
1.775 + PNG_ALPHA_PNG: The data is encoded according to the PNG specification. Red,
1.776 +green and blue, or gray, components are gamma encoded color
1.777 +values and are not premultiplied by the alpha value. The
1.778 +alpha value is a linear measure of the contribution of the
1.779 +pixel to the corresponding final output pixel.
1.780 +
1.781 +You should normally use this format if you intend to perform
1.782 +color correction on the color values; most, maybe all, color
1.783 +correction software has no handling for the alpha channel and,
1.784 +anyway, the math to handle pre-multiplied component values is
1.785 +unnecessarily complex.
1.786 +
1.787 +Before you do any arithmetic on the component values you need
1.788 +to remove the gamma encoding and multiply out the alpha
1.789 +channel. See the PNG specification for more detail. It is
1.790 +important to note that when an image with an alpha channel is
1.791 +scaled, linear encoded, pre-multiplied component values must
1.792 +be used!
1.793 +
1.794 +The remaining modes assume you don't need to do any further color correction or
1.795 +that if you do, your color correction software knows all about alpha (it
1.796 +probably doesn't!)
1.797 +
1.798 + PNG_ALPHA_STANDARD: The data libpng produces
1.799 +is encoded in the standard way
1.800 +assumed by most correctly written graphics software.
1.801 +The gamma encoding will be removed by libpng and the
1.802 +linear component values will be pre-multiplied by the
1.803 +alpha channel.
1.804 +
1.805 +With this format the final image must be re-encoded to
1.806 +match the display gamma before the image is displayed.
1.807 +If your system doesn't do that, yet still seems to
1.808 +perform arithmetic on the pixels without decoding them,
1.809 +it is broken - check out the modes below.
1.810 +
1.811 +With PNG_ALPHA_STANDARD libpng always produces linear
1.812 +component values, whatever screen_gamma you supply. The
1.813 +screen_gamma value is, however, used as a default for
1.814 +the file gamma if the PNG file has no gamma information.
1.815 +
1.816 +If you call png_set_gamma() after png_set_alpha_mode() you
1.817 +will override the linear encoding. Instead the
1.818 +pre-multiplied pixel values will be gamma encoded but
1.819 +the alpha channel will still be linear. This may
1.820 +actually match the requirements of some broken software,
1.821 +but it is unlikely.
1.822 +
1.823 +While linear 8-bit data is often used it has
1.824 +insufficient precision for any image with a reasonable
1.825 +dynamic range. To avoid problems, and if your software
1.826 +supports it, use png_set_expand_16() to force all
1.827 +components to 16 bits.
1.828 +
1.829 + PNG_ALPHA_OPTIMIZED: This mode is the same
1.830 +as PNG_ALPHA_STANDARD except that
1.831 +completely opaque pixels are gamma encoded according to
1.832 +the screen_gamma value. Pixels with alpha less than 1.0
1.833 +will still have linear components.
1.834 +
1.835 +Use this format if you have control over your
1.836 +compositing software and so don't do other arithmetic
1.837 +(such as scaling) on the data you get from libpng. Your
1.838 +compositing software can simply copy opaque pixels to
1.839 +the output but still has linear values for the
1.840 +non-opaque pixels.
1.841 +
1.842 +In normal compositing, where the alpha channel encodes
1.843 +partial pixel coverage (as opposed to broad area
1.844 +translucency), the inaccuracies of the 8-bit
1.845 +representation of non-opaque pixels are irrelevant.
1.846 +
1.847 +You can also try this format if your software is broken;
1.848 +it might look better.
1.849 +
1.850 + PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD;
1.851 +however, all component values,
1.852 +including the alpha channel are gamma encoded. This is
1.853 +an appropriate format to try if your software, or more
1.854 +likely hardware, is totally broken, i.e., if it performs
1.855 +linear arithmetic directly on gamma encoded values.
1.856 +
1.857 +In most cases of broken software or hardware the bug in the final display
1.858 +manifests as a subtle halo around composited parts of the image. You may not
1.859 +even perceive this as a halo; the composited part of the image may simply appear
1.860 +separate from the background, as though it had been cut out of paper and pasted
1.861 +on afterward.
1.862 +
1.863 +If you don't have to deal with bugs in software or hardware, or if you can fix
1.864 +them, there are three recommended ways of using png_set_alpha_mode():
1.865 +
1.866 + png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
1.867 + screen_gamma);
1.868 +
1.869 +You can do color correction on the result (libpng does not currently
1.870 +support color correction internally). When you handle the alpha channel
1.871 +you need to undo the gamma encoding and multiply out the alpha.
1.872 +
1.873 + png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
1.874 + screen_gamma);
1.875 + png_set_expand_16(png_ptr);
1.876 +
1.877 +If you are using the high level interface, don't call png_set_expand_16();
1.878 +instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
1.879 +
1.880 +With this mode you can't do color correction, but you can do arithmetic,
1.881 +including composition and scaling, on the data without further processing.
1.882 +
1.883 + png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
1.884 + screen_gamma);
1.885 +
1.886 +You can avoid the expansion to 16-bit components with this mode, but you
1.887 +lose the ability to scale the image or perform other linear arithmetic.
1.888 +All you can do is compose the result onto a matching output. Since this
1.889 +mode is libpng-specific you also need to write your own composition
1.890 +software.
1.891 +
1.892 +If you don't need, or can't handle, the alpha channel you can call
1.893 +png_set_background() to remove it by compositing against a fixed color. Don't
1.894 +call png_set_strip_alpha() to do this - it will leave spurious pixel values in
1.895 +transparent parts of this image.
1.896 +
1.897 + png_set_background(png_ptr, &background_color,
1.898 + PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
1.899 +
1.900 +The background_color is an RGB or grayscale value according to the data format
1.901 +libpng will produce for you. Because you don't yet know the format of the PNG
1.902 +file, if you call png_set_background at this point you must arrange for the
1.903 +format produced by libpng to always have 8-bit or 16-bit components and then
1.904 +store the color as an 8-bit or 16-bit color as appropriate. The color contains
1.905 +separate gray and RGB component values, so you can let libpng produce gray or
1.906 +RGB output according to the input format, but low bit depth grayscale images
1.907 +must always be converted to at least 8-bit format. (Even though low bit depth
1.908 +grayscale images can't have an alpha channel they can have a transparent
1.909 +color!)
1.910 +
1.911 +You set the transforms you need later, either as flags to the high level
1.912 +interface or libpng API calls for the low level interface. For reference the
1.913 +settings and API calls required are:
1.914 +
1.915 +8-bit values:
1.916 + PNG_TRANSFORM_SCALE_16 | PNG_EXPAND
1.917 + png_set_expand(png_ptr); png_set_scale_16(png_ptr);
1.918 +
1.919 + If you must get exactly the same inaccurate results
1.920 + produced by default in versions prior to libpng-1.5.4,
1.921 + use PNG_TRANSFORM_STRIP_16 and png_set_strip_16(png_ptr)
1.922 + instead.
1.923 +
1.924 +16-bit values:
1.925 + PNG_TRANSFORM_EXPAND_16
1.926 + png_set_expand_16(png_ptr);
1.927 +
1.928 +In either case palette image data will be expanded to RGB. If you just want
1.929 +color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
1.930 +to the list.
1.931 +
1.932 +Calling png_set_background before the PNG file header is read will not work
1.933 +prior to libpng-1.5.4. Because the failure may result in unexpected warnings or
1.934 +errors it is therefore much safer to call png_set_background after the head has
1.935 +been read. Unfortunately this means that prior to libpng-1.5.4 it cannot be
1.936 +used with the high level interface.
1.937 +
1.938 +The high-level read interface
1.939 +
1.940 +At this point there are two ways to proceed; through the high-level
1.941 +read interface, or through a sequence of low-level read operations.
1.942 +You can use the high-level interface if (a) you are willing to read
1.943 +the entire image into memory, and (b) the input transformations
1.944 +you want to do are limited to the following set:
1.945 +
1.946 + PNG_TRANSFORM_IDENTITY No transformation
1.947 + PNG_TRANSFORM_SCALE_16 Strip 16-bit samples to
1.948 + 8-bit accurately
1.949 + PNG_TRANSFORM_STRIP_16 Chop 16-bit samples to
1.950 + 8-bit less accurately
1.951 + PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
1.952 + PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
1.953 + samples to bytes
1.954 + PNG_TRANSFORM_PACKSWAP Change order of packed
1.955 + pixels to LSB first
1.956 + PNG_TRANSFORM_EXPAND Perform set_expand()
1.957 + PNG_TRANSFORM_INVERT_MONO Invert monochrome images
1.958 + PNG_TRANSFORM_SHIFT Normalize pixels to the
1.959 + sBIT depth
1.960 + PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
1.961 + to BGRA
1.962 + PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
1.963 + to AG
1.964 + PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
1.965 + to transparency
1.966 + PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
1.967 + PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
1.968 + to RGB (or GA to RGBA)
1.969 + PNG_TRANSFORM_EXPAND_16 Expand samples to 16 bits
1.970 +
1.971 +(This excludes setting a background color, doing gamma transformation,
1.972 +quantizing, and setting filler.) If this is the case, simply do this:
1.973 +
1.974 + png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1.975 +
1.976 +where png_transforms is an integer containing the bitwise OR of some
1.977 +set of transformation flags. This call is equivalent to png_read_info(),
1.978 +followed the set of transformations indicated by the transform mask,
1.979 +then png_read_image(), and finally png_read_end().
1.980 +
1.981 +(The final parameter of this call is not yet used. Someday it might point
1.982 +to transformation parameters required by some future input transform.)
1.983 +
1.984 +You must use png_transforms and not call any png_set_transform() functions
1.985 +when you use png_read_png().
1.986 +
1.987 +After you have called png_read_png(), you can retrieve the image data
1.988 +with
1.989 +
1.990 + row_pointers = png_get_rows(png_ptr, info_ptr);
1.991 +
1.992 +where row_pointers is an array of pointers to the pixel data for each row:
1.993 +
1.994 + png_bytep row_pointers[height];
1.995 +
1.996 +If you know your image size and pixel size ahead of time, you can allocate
1.997 +row_pointers prior to calling png_read_png() with
1.998 +
1.999 + if (height > PNG_UINT_32_MAX/(sizeof (png_byte)))
1.1000 + png_error (png_ptr,
1.1001 + "Image is too tall to process in memory");
1.1002 +
1.1003 + if (width > PNG_UINT_32_MAX/pixel_size)
1.1004 + png_error (png_ptr,
1.1005 + "Image is too wide to process in memory");
1.1006 +
1.1007 + row_pointers = png_malloc(png_ptr,
1.1008 + height*(sizeof (png_bytep)));
1.1009 +
1.1010 + for (int i=0; i<height, i++)
1.1011 + row_pointers[i]=NULL; /* security precaution */
1.1012 +
1.1013 + for (int i=0; i<height, i++)
1.1014 + row_pointers[i]=png_malloc(png_ptr,
1.1015 + width*pixel_size);
1.1016 +
1.1017 + png_set_rows(png_ptr, info_ptr, &row_pointers);
1.1018 +
1.1019 +Alternatively you could allocate your image in one big block and define
1.1020 +row_pointers[i] to point into the proper places in your block.
1.1021 +
1.1022 +If you use png_set_rows(), the application is responsible for freeing
1.1023 +row_pointers (and row_pointers[i], if they were separately allocated).
1.1024 +
1.1025 +If you don't allocate row_pointers ahead of time, png_read_png() will
1.1026 +do it, and it'll be free'ed by libpng when you call png_destroy_*().
1.1027 +
1.1028 +The low-level read interface
1.1029 +
1.1030 +If you are going the low-level route, you are now ready to read all
1.1031 +the file information up to the actual image data. You do this with a
1.1032 +call to png_read_info().
1.1033 +
1.1034 + png_read_info(png_ptr, info_ptr);
1.1035 +
1.1036 +This will process all chunks up to but not including the image data.
1.1037 +
1.1038 +This also copies some of the data from the PNG file into the decode structure
1.1039 +for use in later transformations. Important information copied in is:
1.1040 +
1.1041 +1) The PNG file gamma from the gAMA chunk. This overwrites the default value
1.1042 +provided by an earlier call to png_set_gamma or png_set_alpha_mode.
1.1043 +
1.1044 +2) Prior to libpng-1.5.4 the background color from a bKGd chunk. This
1.1045 +damages the information provided by an earlier call to png_set_background
1.1046 +resulting in unexpected behavior. Libpng-1.5.4 no longer does this.
1.1047 +
1.1048 +3) The number of significant bits in each component value. Libpng uses this to
1.1049 +optimize gamma handling by reducing the internal lookup table sizes.
1.1050 +
1.1051 +4) The transparent color information from a tRNS chunk. This can be modified by
1.1052 +a later call to png_set_tRNS.
1.1053 +
1.1054 +Querying the info structure
1.1055 +
1.1056 +Functions are used to get the information from the info_ptr once it
1.1057 +has been read. Note that these fields may not be completely filled
1.1058 +in until png_read_end() has read the chunk data following the image.
1.1059 +
1.1060 + png_get_IHDR(png_ptr, info_ptr, &width, &height,
1.1061 + &bit_depth, &color_type, &interlace_type,
1.1062 + &compression_type, &filter_method);
1.1063 +
1.1064 + width - holds the width of the image
1.1065 + in pixels (up to 2^31).
1.1066 +
1.1067 + height - holds the height of the image
1.1068 + in pixels (up to 2^31).
1.1069 +
1.1070 + bit_depth - holds the bit depth of one of the
1.1071 + image channels. (valid values are
1.1072 + 1, 2, 4, 8, 16 and depend also on
1.1073 + the color_type. See also
1.1074 + significant bits (sBIT) below).
1.1075 +
1.1076 + color_type - describes which color/alpha channels
1.1077 + are present.
1.1078 + PNG_COLOR_TYPE_GRAY
1.1079 + (bit depths 1, 2, 4, 8, 16)
1.1080 + PNG_COLOR_TYPE_GRAY_ALPHA
1.1081 + (bit depths 8, 16)
1.1082 + PNG_COLOR_TYPE_PALETTE
1.1083 + (bit depths 1, 2, 4, 8)
1.1084 + PNG_COLOR_TYPE_RGB
1.1085 + (bit_depths 8, 16)
1.1086 + PNG_COLOR_TYPE_RGB_ALPHA
1.1087 + (bit_depths 8, 16)
1.1088 +
1.1089 + PNG_COLOR_MASK_PALETTE
1.1090 + PNG_COLOR_MASK_COLOR
1.1091 + PNG_COLOR_MASK_ALPHA
1.1092 +
1.1093 + interlace_type - (PNG_INTERLACE_NONE or
1.1094 + PNG_INTERLACE_ADAM7)
1.1095 +
1.1096 + compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1.1097 + for PNG 1.0)
1.1098 +
1.1099 + filter_method - (must be PNG_FILTER_TYPE_BASE
1.1100 + for PNG 1.0, and can also be
1.1101 + PNG_INTRAPIXEL_DIFFERENCING if
1.1102 + the PNG datastream is embedded in
1.1103 + a MNG-1.0 datastream)
1.1104 +
1.1105 + Any or all of interlace_type, compression_type, or
1.1106 + filter_method can be NULL if you are
1.1107 + not interested in their values.
1.1108 +
1.1109 + Note that png_get_IHDR() returns 32-bit data into
1.1110 + the application's width and height variables.
1.1111 + This is an unsafe situation if these are 16-bit
1.1112 + variables. In such situations, the
1.1113 + png_get_image_width() and png_get_image_height()
1.1114 + functions described below are safer.
1.1115 +
1.1116 + width = png_get_image_width(png_ptr,
1.1117 + info_ptr);
1.1118 +
1.1119 + height = png_get_image_height(png_ptr,
1.1120 + info_ptr);
1.1121 +
1.1122 + bit_depth = png_get_bit_depth(png_ptr,
1.1123 + info_ptr);
1.1124 +
1.1125 + color_type = png_get_color_type(png_ptr,
1.1126 + info_ptr);
1.1127 +
1.1128 + interlace_type = png_get_interlace_type(png_ptr,
1.1129 + info_ptr);
1.1130 +
1.1131 + compression_type = png_get_compression_type(png_ptr,
1.1132 + info_ptr);
1.1133 +
1.1134 + filter_method = png_get_filter_type(png_ptr,
1.1135 + info_ptr);
1.1136 +
1.1137 + channels = png_get_channels(png_ptr, info_ptr);
1.1138 +
1.1139 + channels - number of channels of info for the
1.1140 + color type (valid values are 1 (GRAY,
1.1141 + PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1.1142 + 4 (RGB_ALPHA or RGB + filler byte))
1.1143 +
1.1144 + rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1.1145 +
1.1146 + rowbytes - number of bytes needed to hold a row
1.1147 +
1.1148 + signature = png_get_signature(png_ptr, info_ptr);
1.1149 +
1.1150 + signature - holds the signature read from the
1.1151 + file (if any). The data is kept in
1.1152 + the same offset it would be if the
1.1153 + whole signature were read (i.e. if an
1.1154 + application had already read in 4
1.1155 + bytes of signature before starting
1.1156 + libpng, the remaining 4 bytes would
1.1157 + be in signature[4] through signature[7]
1.1158 + (see png_set_sig_bytes())).
1.1159 +
1.1160 +These are also important, but their validity depends on whether the chunk
1.1161 +has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
1.1162 +png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
1.1163 +data has been read, or zero if it is missing. The parameters to the
1.1164 +png_get_<chunk> are set directly if they are simple data types, or a
1.1165 +pointer into the info_ptr is returned for any complex types.
1.1166 +
1.1167 +The colorspace data from gAMA, cHRM, sRGB, iCCP, and sBIT chunks
1.1168 +is simply returned to give the application information about how the
1.1169 +image was encoded. Libpng itself only does transformations using the file
1.1170 +gamma when combining semitransparent pixels with the background color, and,
1.1171 +since libpng-1.6.0, when converting between 8-bit sRGB and 16-bit linear pixels
1.1172 +within the simplified API. Libpng also uses the file gamma when converting
1.1173 +RGB to gray, beginning with libpng-1.0.5, if the application calls
1.1174 +png_set_rgb_to_gray()).
1.1175 +
1.1176 + png_get_PLTE(png_ptr, info_ptr, &palette,
1.1177 + &num_palette);
1.1178 +
1.1179 + palette - the palette for the file
1.1180 + (array of png_color)
1.1181 +
1.1182 + num_palette - number of entries in the palette
1.1183 +
1.1184 + png_get_gAMA(png_ptr, info_ptr, &file_gamma);
1.1185 + png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
1.1186 +
1.1187 + file_gamma - the gamma at which the file is
1.1188 + written (PNG_INFO_gAMA)
1.1189 +
1.1190 + int_file_gamma - 100,000 times the gamma at which the
1.1191 + file is written
1.1192 +
1.1193 + png_get_cHRM(png_ptr, info_ptr, &white_x, &white_y, &red_x,
1.1194 + &red_y, &green_x, &green_y, &blue_x, &blue_y)
1.1195 + png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z,
1.1196 + &green_X, &green_Y, &green_Z, &blue_X, &blue_Y,
1.1197 + &blue_Z)
1.1198 + png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x,
1.1199 + &int_white_y, &int_red_x, &int_red_y,
1.1200 + &int_green_x, &int_green_y, &int_blue_x,
1.1201 + &int_blue_y)
1.1202 + png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y,
1.1203 + &int_red_Z, &int_green_X, &int_green_Y,
1.1204 + &int_green_Z, &int_blue_X, &int_blue_Y,
1.1205 + &int_blue_Z)
1.1206 +
1.1207 + {white,red,green,blue}_{x,y}
1.1208 + A color space encoding specified using the
1.1209 + chromaticities of the end points and the
1.1210 + white point. (PNG_INFO_cHRM)
1.1211 +
1.1212 + {red,green,blue}_{X,Y,Z}
1.1213 + A color space encoding specified using the
1.1214 + encoding end points - the CIE tristimulus
1.1215 + specification of the intended color of the red,
1.1216 + green and blue channels in the PNG RGB data.
1.1217 + The white point is simply the sum of the three
1.1218 + end points. (PNG_INFO_cHRM)
1.1219 +
1.1220 + png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1.1221 +
1.1222 + file_srgb_intent - the rendering intent (PNG_INFO_sRGB)
1.1223 + The presence of the sRGB chunk
1.1224 + means that the pixel data is in the
1.1225 + sRGB color space. This chunk also
1.1226 + implies specific values of gAMA and
1.1227 + cHRM.
1.1228 +
1.1229 + png_get_iCCP(png_ptr, info_ptr, &name,
1.1230 + &compression_type, &profile, &proflen);
1.1231 +
1.1232 + name - The profile name.
1.1233 +
1.1234 + compression_type - The compression type; always
1.1235 + PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1.1236 + You may give NULL to this argument to
1.1237 + ignore it.
1.1238 +
1.1239 + profile - International Color Consortium color
1.1240 + profile data. May contain NULs.
1.1241 +
1.1242 + proflen - length of profile data in bytes.
1.1243 +
1.1244 + png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1.1245 +
1.1246 + sig_bit - the number of significant bits for
1.1247 + (PNG_INFO_sBIT) each of the gray,
1.1248 + red, green, and blue channels,
1.1249 + whichever are appropriate for the
1.1250 + given color type (png_color_16)
1.1251 +
1.1252 + png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
1.1253 + &num_trans, &trans_color);
1.1254 +
1.1255 + trans_alpha - array of alpha (transparency)
1.1256 + entries for palette (PNG_INFO_tRNS)
1.1257 +
1.1258 + num_trans - number of transparent entries
1.1259 + (PNG_INFO_tRNS)
1.1260 +
1.1261 + trans_color - graylevel or color sample values of
1.1262 + the single transparent color for
1.1263 + non-paletted images (PNG_INFO_tRNS)
1.1264 +
1.1265 + png_get_hIST(png_ptr, info_ptr, &hist);
1.1266 + (PNG_INFO_hIST)
1.1267 +
1.1268 + hist - histogram of palette (array of
1.1269 + png_uint_16)
1.1270 +
1.1271 + png_get_tIME(png_ptr, info_ptr, &mod_time);
1.1272 +
1.1273 + mod_time - time image was last modified
1.1274 + (PNG_VALID_tIME)
1.1275 +
1.1276 + png_get_bKGD(png_ptr, info_ptr, &background);
1.1277 +
1.1278 + background - background color (of type
1.1279 + png_color_16p) (PNG_VALID_bKGD)
1.1280 + valid 16-bit red, green and blue
1.1281 + values, regardless of color_type
1.1282 +
1.1283 + num_comments = png_get_text(png_ptr, info_ptr,
1.1284 + &text_ptr, &num_text);
1.1285 +
1.1286 + num_comments - number of comments
1.1287 +
1.1288 + text_ptr - array of png_text holding image
1.1289 + comments
1.1290 +
1.1291 + text_ptr[i].compression - type of compression used
1.1292 + on "text" PNG_TEXT_COMPRESSION_NONE
1.1293 + PNG_TEXT_COMPRESSION_zTXt
1.1294 + PNG_ITXT_COMPRESSION_NONE
1.1295 + PNG_ITXT_COMPRESSION_zTXt
1.1296 +
1.1297 + text_ptr[i].key - keyword for comment. Must contain
1.1298 + 1-79 characters.
1.1299 +
1.1300 + text_ptr[i].text - text comments for current
1.1301 + keyword. Can be empty.
1.1302 +
1.1303 + text_ptr[i].text_length - length of text string,
1.1304 + after decompression, 0 for iTXt
1.1305 +
1.1306 + text_ptr[i].itxt_length - length of itxt string,
1.1307 + after decompression, 0 for tEXt/zTXt
1.1308 +
1.1309 + text_ptr[i].lang - language of comment (empty
1.1310 + string for unknown).
1.1311 +
1.1312 + text_ptr[i].lang_key - keyword in UTF-8
1.1313 + (empty string for unknown).
1.1314 +
1.1315 + Note that the itxt_length, lang, and lang_key
1.1316 + members of the text_ptr structure only exist when the
1.1317 + library is built with iTXt chunk support. Prior to
1.1318 + libpng-1.4.0 the library was built by default without
1.1319 + iTXt support. Also note that when iTXt is supported,
1.1320 + they contain NULL pointers when the "compression"
1.1321 + field contains PNG_TEXT_COMPRESSION_NONE or
1.1322 + PNG_TEXT_COMPRESSION_zTXt.
1.1323 +
1.1324 + num_text - number of comments (same as
1.1325 + num_comments; you can put NULL here
1.1326 + to avoid the duplication)
1.1327 +
1.1328 + Note while png_set_text() will accept text, language,
1.1329 + and translated keywords that can be NULL pointers, the
1.1330 + structure returned by png_get_text will always contain
1.1331 + regular zero-terminated C strings. They might be
1.1332 + empty strings but they will never be NULL pointers.
1.1333 +
1.1334 + num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1.1335 + &palette_ptr);
1.1336 +
1.1337 + num_spalettes - number of sPLT chunks read.
1.1338 +
1.1339 + palette_ptr - array of palette structures holding
1.1340 + contents of one or more sPLT chunks
1.1341 + read.
1.1342 +
1.1343 + png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
1.1344 + &unit_type);
1.1345 +
1.1346 + offset_x - positive offset from the left edge
1.1347 + of the screen (can be negative)
1.1348 +
1.1349 + offset_y - positive offset from the top edge
1.1350 + of the screen (can be negative)
1.1351 +
1.1352 + unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1.1353 +
1.1354 + png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
1.1355 + &unit_type);
1.1356 +
1.1357 + res_x - pixels/unit physical resolution in
1.1358 + x direction
1.1359 +
1.1360 + res_y - pixels/unit physical resolution in
1.1361 + x direction
1.1362 +
1.1363 + unit_type - PNG_RESOLUTION_UNKNOWN,
1.1364 + PNG_RESOLUTION_METER
1.1365 +
1.1366 + png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1.1367 + &height)
1.1368 +
1.1369 + unit - physical scale units (an integer)
1.1370 +
1.1371 + width - width of a pixel in physical scale units
1.1372 +
1.1373 + height - height of a pixel in physical scale units
1.1374 + (width and height are doubles)
1.1375 +
1.1376 + png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1.1377 + &height)
1.1378 +
1.1379 + unit - physical scale units (an integer)
1.1380 +
1.1381 + width - width of a pixel in physical scale units
1.1382 + (expressed as a string)
1.1383 +
1.1384 + height - height of a pixel in physical scale units
1.1385 + (width and height are strings like "2.54")
1.1386 +
1.1387 + num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1.1388 + info_ptr, &unknowns)
1.1389 +
1.1390 + unknowns - array of png_unknown_chunk
1.1391 + structures holding unknown chunks
1.1392 +
1.1393 + unknowns[i].name - name of unknown chunk
1.1394 +
1.1395 + unknowns[i].data - data of unknown chunk
1.1396 +
1.1397 + unknowns[i].size - size of unknown chunk's data
1.1398 +
1.1399 + unknowns[i].location - position of chunk in file
1.1400 +
1.1401 + The value of "i" corresponds to the order in which the
1.1402 + chunks were read from the PNG file or inserted with the
1.1403 + png_set_unknown_chunks() function.
1.1404 +
1.1405 + The value of "location" is a bitwise "or" of
1.1406 +
1.1407 + PNG_HAVE_IHDR (0x01)
1.1408 + PNG_HAVE_PLTE (0x02)
1.1409 + PNG_AFTER_IDAT (0x08)
1.1410 +
1.1411 +The data from the pHYs chunk can be retrieved in several convenient
1.1412 +forms:
1.1413 +
1.1414 + res_x = png_get_x_pixels_per_meter(png_ptr,
1.1415 + info_ptr)
1.1416 +
1.1417 + res_y = png_get_y_pixels_per_meter(png_ptr,
1.1418 + info_ptr)
1.1419 +
1.1420 + res_x_and_y = png_get_pixels_per_meter(png_ptr,
1.1421 + info_ptr)
1.1422 +
1.1423 + res_x = png_get_x_pixels_per_inch(png_ptr,
1.1424 + info_ptr)
1.1425 +
1.1426 + res_y = png_get_y_pixels_per_inch(png_ptr,
1.1427 + info_ptr)
1.1428 +
1.1429 + res_x_and_y = png_get_pixels_per_inch(png_ptr,
1.1430 + info_ptr)
1.1431 +
1.1432 + aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
1.1433 + info_ptr)
1.1434 +
1.1435 + Each of these returns 0 [signifying "unknown"] if
1.1436 + the data is not present or if res_x is 0;
1.1437 + res_x_and_y is 0 if res_x != res_y
1.1438 +
1.1439 + Note that because of the way the resolutions are
1.1440 + stored internally, the inch conversions won't
1.1441 + come out to exactly even number. For example,
1.1442 + 72 dpi is stored as 0.28346 pixels/meter, and
1.1443 + when this is retrieved it is 71.9988 dpi, so
1.1444 + be sure to round the returned value appropriately
1.1445 + if you want to display a reasonable-looking result.
1.1446 +
1.1447 +The data from the oFFs chunk can be retrieved in several convenient
1.1448 +forms:
1.1449 +
1.1450 + x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1.1451 +
1.1452 + y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1.1453 +
1.1454 + x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1.1455 +
1.1456 + y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1.1457 +
1.1458 + Each of these returns 0 [signifying "unknown" if both
1.1459 + x and y are 0] if the data is not present or if the
1.1460 + chunk is present but the unit is the pixel. The
1.1461 + remark about inexact inch conversions applies here
1.1462 + as well, because a value in inches can't always be
1.1463 + converted to microns and back without some loss
1.1464 + of precision.
1.1465 +
1.1466 +For more information, see the
1.1467 +PNG specification for chunk contents. Be careful with trusting
1.1468 +rowbytes, as some of the transformations could increase the space
1.1469 +needed to hold a row (expand, filler, gray_to_rgb, etc.).
1.1470 +See png_read_update_info(), below.
1.1471 +
1.1472 +A quick word about text_ptr and num_text. PNG stores comments in
1.1473 +keyword/text pairs, one pair per chunk, with no limit on the number
1.1474 +of text chunks, and a 2^31 byte limit on their size. While there are
1.1475 +suggested keywords, there is no requirement to restrict the use to these
1.1476 +strings. It is strongly suggested that keywords and text be sensible
1.1477 +to humans (that's the point), so don't use abbreviations. Non-printing
1.1478 +symbols are not allowed. See the PNG specification for more details.
1.1479 +There is also no requirement to have text after the keyword.
1.1480 +
1.1481 +Keywords should be limited to 79 Latin-1 characters without leading or
1.1482 +trailing spaces, but non-consecutive spaces are allowed within the
1.1483 +keyword. It is possible to have the same keyword any number of times.
1.1484 +The text_ptr is an array of png_text structures, each holding a
1.1485 +pointer to a language string, a pointer to a keyword and a pointer to
1.1486 +a text string. The text string, language code, and translated
1.1487 +keyword may be empty or NULL pointers. The keyword/text
1.1488 +pairs are put into the array in the order that they are received.
1.1489 +However, some or all of the text chunks may be after the image, so, to
1.1490 +make sure you have read all the text chunks, don't mess with these
1.1491 +until after you read the stuff after the image. This will be
1.1492 +mentioned again below in the discussion that goes with png_read_end().
1.1493 +
1.1494 +Input transformations
1.1495 +
1.1496 +After you've read the header information, you can set up the library
1.1497 +to handle any special transformations of the image data. The various
1.1498 +ways to transform the data will be described in the order that they
1.1499 +should occur. This is important, as some of these change the color
1.1500 +type and/or bit depth of the data, and some others only work on
1.1501 +certain color types and bit depths.
1.1502 +
1.1503 +Transformations you request are ignored if they don't have any meaning for a
1.1504 +particular input data format. However some transformations can have an effect
1.1505 +as a result of a previous transformation. If you specify a contradictory set of
1.1506 +transformations, for example both adding and removing the alpha channel, you
1.1507 +cannot predict the final result.
1.1508 +
1.1509 +The color used for the transparency values should be supplied in the same
1.1510 +format/depth as the current image data. It is stored in the same format/depth
1.1511 +as the image data in a tRNS chunk, so this is what libpng expects for this data.
1.1512 +
1.1513 +The color used for the background value depends on the need_expand argument as
1.1514 +described below.
1.1515 +
1.1516 +Data will be decoded into the supplied row buffers packed into bytes
1.1517 +unless the library has been told to transform it into another format.
1.1518 +For example, 4 bit/pixel paletted or grayscale data will be returned
1.1519 +2 pixels/byte with the leftmost pixel in the high-order bits of the
1.1520 +byte, unless png_set_packing() is called. 8-bit RGB data will be stored
1.1521 +in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
1.1522 +is called to insert filler bytes, either before or after each RGB triplet.
1.1523 +16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
1.1524 +byte of the color value first, unless png_set_scale_16() is called to
1.1525 +transform it to regular RGB RGB triplets, or png_set_filler() or
1.1526 +png_set_add alpha() is called to insert filler bytes, either before or
1.1527 +after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
1.1528 +be modified with png_set_filler(), png_set_add_alpha(), png_set_strip_16(),
1.1529 +or png_set_scale_16().
1.1530 +
1.1531 +The following code transforms grayscale images of less than 8 to 8 bits,
1.1532 +changes paletted images to RGB, and adds a full alpha channel if there is
1.1533 +transparency information in a tRNS chunk. This is most useful on
1.1534 +grayscale images with bit depths of 2 or 4 or if there is a multiple-image
1.1535 +viewing application that wishes to treat all images in the same way.
1.1536 +
1.1537 + if (color_type == PNG_COLOR_TYPE_PALETTE)
1.1538 + png_set_palette_to_rgb(png_ptr);
1.1539 +
1.1540 + if (png_get_valid(png_ptr, info_ptr,
1.1541 + PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1.1542 +
1.1543 + if (color_type == PNG_COLOR_TYPE_GRAY &&
1.1544 + bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
1.1545 +
1.1546 +The first two functions are actually aliases for png_set_expand(), added
1.1547 +in libpng version 1.0.4, with the function names expanded to improve code
1.1548 +readability. In some future version they may actually do different
1.1549 +things.
1.1550 +
1.1551 +As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
1.1552 +added. It expands the sample depth without changing tRNS to alpha.
1.1553 +
1.1554 +As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as
1.1555 +png_set_expand(); however, the resultant channels have 16 bits rather than 8.
1.1556 +Use this when the output color or gray channels are made linear to avoid fairly
1.1557 +severe accuracy loss.
1.1558 +
1.1559 + if (bit_depth < 16)
1.1560 + png_set_expand_16(png_ptr);
1.1561 +
1.1562 +PNG can have files with 16 bits per channel. If you only can handle
1.1563 +8 bits per channel, this will strip the pixels down to 8-bit.
1.1564 +
1.1565 + if (bit_depth == 16)
1.1566 +#if PNG_LIBPNG_VER >= 10504
1.1567 + png_set_scale_16(png_ptr);
1.1568 +#else
1.1569 + png_set_strip_16(png_ptr);
1.1570 +#endif
1.1571 +
1.1572 +(The more accurate "png_set_scale_16()" API became available in libpng version
1.1573 +1.5.4).
1.1574 +
1.1575 +If you need to process the alpha channel on the image separately from the image
1.1576 +data (for example if you convert it to a bitmap mask) it is possible to have
1.1577 +libpng strip the channel leaving just RGB or gray data:
1.1578 +
1.1579 + if (color_type & PNG_COLOR_MASK_ALPHA)
1.1580 + png_set_strip_alpha(png_ptr);
1.1581 +
1.1582 +If you strip the alpha channel you need to find some other way of dealing with
1.1583 +the information. If, instead, you want to convert the image to an opaque
1.1584 +version with no alpha channel use png_set_background; see below.
1.1585 +
1.1586 +As of libpng version 1.5.2, almost all useful expansions are supported, the
1.1587 +major ommissions are conversion of grayscale to indexed images (which can be
1.1588 +done trivially in the application) and conversion of indexed to grayscale (which
1.1589 +can be done by a trivial manipulation of the palette.)
1.1590 +
1.1591 +In the following table, the 01 means grayscale with depth<8, 31 means
1.1592 +indexed with depth<8, other numerals represent the color type, "T" means
1.1593 +the tRNS chunk is present, A means an alpha channel is present, and O
1.1594 +means tRNS or alpha is present but all pixels in the image are opaque.
1.1595 +
1.1596 + FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
1.1597 + TO
1.1598 + 01 - [G] - - - - - - - - - - - - -
1.1599 + 31 [Q] Q [Q] [Q] [Q] Q Q Q Q Q Q [Q] [Q] Q Q
1.1600 + 0 1 G + . . G G G G G G B B GB GB
1.1601 + 0T lt Gt t + . Gt G G Gt G G Bt Bt GBt GBt
1.1602 + 0O lt Gt t . + Gt Gt G Gt Gt G Bt Bt GBt GBt
1.1603 + 2 C P C C C + . . C - - CB CB B B
1.1604 + 2T Ct - Ct C C t + t - - - CBt CBt Bt Bt
1.1605 + 2O Ct - Ct C C t t + - - - CBt CBt Bt Bt
1.1606 + 3 [Q] p [Q] [Q] [Q] Q Q Q + . . [Q] [Q] Q Q
1.1607 + 3T [Qt] p [Qt][Q] [Q] Qt Qt Qt t + t [Qt][Qt] Qt Qt
1.1608 + 3O [Qt] p [Qt][Q] [Q] Qt Qt Qt t t + [Qt][Qt] Qt Qt
1.1609 + 4A lA G A T T GA GT GT GA GT GT + BA G GBA
1.1610 + 4O lA GBA A T T GA GT GT GA GT GT BA + GBA G
1.1611 + 6A CA PA CA C C A T tT PA P P C CBA + BA
1.1612 + 6O CA PBA CA C C A tT T PA P P CBA C BA +
1.1613 +
1.1614 +Within the matrix,
1.1615 + "+" identifies entries where 'from' and 'to' are the same.
1.1616 + "-" means the transformation is not supported.
1.1617 + "." means nothing is necessary (a tRNS chunk can just be ignored).
1.1618 + "t" means the transformation is obtained by png_set_tRNS.
1.1619 + "A" means the transformation is obtained by png_set_add_alpha().
1.1620 + "X" means the transformation is obtained by png_set_expand().
1.1621 + "1" means the transformation is obtained by
1.1622 + png_set_expand_gray_1_2_4_to_8() (and by png_set_expand()
1.1623 + if there is no transparency in the original or the final
1.1624 + format).
1.1625 + "C" means the transformation is obtained by png_set_gray_to_rgb().
1.1626 + "G" means the transformation is obtained by png_set_rgb_to_gray().
1.1627 + "P" means the transformation is obtained by
1.1628 + png_set_expand_palette_to_rgb().
1.1629 + "p" means the transformation is obtained by png_set_packing().
1.1630 + "Q" means the transformation is obtained by png_set_quantize().
1.1631 + "T" means the transformation is obtained by
1.1632 + png_set_tRNS_to_alpha().
1.1633 + "B" means the transformation is obtained by
1.1634 + png_set_background(), or png_strip_alpha().
1.1635 +
1.1636 +When an entry has multiple transforms listed all are required to cause the
1.1637 +right overall transformation. When two transforms are separated by a comma
1.1638 +either will do the job. When transforms are enclosed in [] the transform should
1.1639 +do the job but this is currently unimplemented - a different format will result
1.1640 +if the suggested transformations are used.
1.1641 +
1.1642 +In PNG files, the alpha channel in an image
1.1643 +is the level of opacity. If you need the alpha channel in an image to
1.1644 +be the level of transparency instead of opacity, you can invert the
1.1645 +alpha channel (or the tRNS chunk data) after it's read, so that 0 is
1.1646 +fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
1.1647 +images) is fully transparent, with
1.1648 +
1.1649 + png_set_invert_alpha(png_ptr);
1.1650 +
1.1651 +PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1.1652 +they can, resulting in, for example, 8 pixels per byte for 1 bit
1.1653 +files. This code expands to 1 pixel per byte without changing the
1.1654 +values of the pixels:
1.1655 +
1.1656 + if (bit_depth < 8)
1.1657 + png_set_packing(png_ptr);
1.1658 +
1.1659 +PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
1.1660 +stored in a PNG image have been "scaled" or "shifted" up to the next
1.1661 +higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
1.1662 +to 8 bits/sample in the range [0, 255]). However, it is also possible
1.1663 +to convert the PNG pixel data back to the original bit depth of the
1.1664 +image. This call reduces the pixels back down to the original bit depth:
1.1665 +
1.1666 + png_color_8p sig_bit;
1.1667 +
1.1668 + if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1.1669 + png_set_shift(png_ptr, sig_bit);
1.1670 +
1.1671 +PNG files store 3-color pixels in red, green, blue order. This code
1.1672 +changes the storage of the pixels to blue, green, red:
1.1673 +
1.1674 + if (color_type == PNG_COLOR_TYPE_RGB ||
1.1675 + color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1.1676 + png_set_bgr(png_ptr);
1.1677 +
1.1678 +PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
1.1679 +into 4 or 8 bytes for windowing systems that need them in this format:
1.1680 +
1.1681 + if (color_type == PNG_COLOR_TYPE_RGB)
1.1682 + png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
1.1683 +
1.1684 +where "filler" is the 8 or 16-bit number to fill with, and the location is
1.1685 +either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1.1686 +you want the filler before the RGB or after. This transformation
1.1687 +does not affect images that already have full alpha channels. To add an
1.1688 +opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
1.1689 +will generate RGBA pixels.
1.1690 +
1.1691 +Note that png_set_filler() does not change the color type. If you want
1.1692 +to do that, you can add a true alpha channel with
1.1693 +
1.1694 + if (color_type == PNG_COLOR_TYPE_RGB ||
1.1695 + color_type == PNG_COLOR_TYPE_GRAY)
1.1696 + png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1.1697 +
1.1698 +where "filler" contains the alpha value to assign to each pixel.
1.1699 +This function was added in libpng-1.2.7.
1.1700 +
1.1701 +If you are reading an image with an alpha channel, and you need the
1.1702 +data as ARGB instead of the normal PNG format RGBA:
1.1703 +
1.1704 + if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1.1705 + png_set_swap_alpha(png_ptr);
1.1706 +
1.1707 +For some uses, you may want a grayscale image to be represented as
1.1708 +RGB. This code will do that conversion:
1.1709 +
1.1710 + if (color_type == PNG_COLOR_TYPE_GRAY ||
1.1711 + color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1.1712 + png_set_gray_to_rgb(png_ptr);
1.1713 +
1.1714 +Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
1.1715 +with alpha.
1.1716 +
1.1717 + if (color_type == PNG_COLOR_TYPE_RGB ||
1.1718 + color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1.1719 + png_set_rgb_to_gray(png_ptr, error_action,
1.1720 + double red_weight, double green_weight);
1.1721 +
1.1722 + error_action = 1: silently do the conversion
1.1723 +
1.1724 + error_action = 2: issue a warning if the original
1.1725 + image has any pixel where
1.1726 + red != green or red != blue
1.1727 +
1.1728 + error_action = 3: issue an error and abort the
1.1729 + conversion if the original
1.1730 + image has any pixel where
1.1731 + red != green or red != blue
1.1732 +
1.1733 + red_weight: weight of red component
1.1734 +
1.1735 + green_weight: weight of green component
1.1736 + If either weight is negative, default
1.1737 + weights are used.
1.1738 +
1.1739 +In the corresponding fixed point API the red_weight and green_weight values are
1.1740 +simply scaled by 100,000:
1.1741 +
1.1742 + png_set_rgb_to_gray(png_ptr, error_action,
1.1743 + png_fixed_point red_weight,
1.1744 + png_fixed_point green_weight);
1.1745 +
1.1746 +If you have set error_action = 1 or 2, you can
1.1747 +later check whether the image really was gray, after processing
1.1748 +the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1.1749 +It will return a png_byte that is zero if the image was gray or
1.1750 +1 if there were any non-gray pixels. Background and sBIT data
1.1751 +will be silently converted to grayscale, using the green channel
1.1752 +data for sBIT, regardless of the error_action setting.
1.1753 +
1.1754 +The default values come from the PNG file cHRM chunk if present; otherwise, the
1.1755 +defaults correspond to the ITU-R recommendation 709, and also the sRGB color
1.1756 +space, as recommended in the Charles Poynton's Colour FAQ,
1.1757 +<http://www.poynton.com/>, in section 9:
1.1758 +
1.1759 + <http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9>
1.1760 +
1.1761 + Y = 0.2126 * R + 0.7152 * G + 0.0722 * B
1.1762 +
1.1763 +Previous versions of this document, 1998 through 2002, recommended a slightly
1.1764 +different formula:
1.1765 +
1.1766 + Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1.1767 +
1.1768 +Libpng uses an integer approximation:
1.1769 +
1.1770 + Y = (6968 * R + 23434 * G + 2366 * B)/32768
1.1771 +
1.1772 +The calculation is done in a linear colorspace, if the image gamma
1.1773 +can be determined.
1.1774 +
1.1775 +The png_set_background() function has been described already; it tells libpng to
1.1776 +composite images with alpha or simple transparency against the supplied
1.1777 +background color. For compatibility with versions of libpng earlier than
1.1778 +libpng-1.5.4 it is recommended that you call the function after reading the file
1.1779 +header, even if you don't want to use the color in a bKGD chunk, if one exists.
1.1780 +
1.1781 +If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
1.1782 +you may use this color, or supply another color more suitable for
1.1783 +the current display (e.g., the background color from a web page). You
1.1784 +need to tell libpng how the color is represented, both the format of the
1.1785 +component values in the color (the number of bits) and the gamma encoding of the
1.1786 +color. The function takes two arguments, background_gamma_mode and need_expand
1.1787 +to convey this information; however, only two combinations are likely to be
1.1788 +useful:
1.1789 +
1.1790 + png_color_16 my_background;
1.1791 + png_color_16p image_background;
1.1792 +
1.1793 + if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1.1794 + png_set_background(png_ptr, image_background,
1.1795 + PNG_BACKGROUND_GAMMA_FILE, 1/*needs to be expanded*/, 1);
1.1796 + else
1.1797 + png_set_background(png_ptr, &my_background,
1.1798 + PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1);
1.1799 +
1.1800 +The second call was described above - my_background is in the format of the
1.1801 +final, display, output produced by libpng. Because you now know the format of
1.1802 +the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
1.1803 +output and to retain palette images (the palette colors will be modified
1.1804 +appropriately and the tRNS chunk removed.) However, if you are doing this,
1.1805 +take great care not to ask for transformations without checking first that
1.1806 +they apply!
1.1807 +
1.1808 +In the first call the background color has the original bit depth and color type
1.1809 +of the PNG file. So, for palette images the color is supplied as a palette
1.1810 +index and for low bit greyscale images the color is a reduced bit value in
1.1811 +image_background->gray.
1.1812 +
1.1813 +If you didn't call png_set_gamma() before reading the file header, for example
1.1814 +if you need your code to remain compatible with older versions of libpng prior
1.1815 +to libpng-1.5.4, this is the place to call it.
1.1816 +
1.1817 +Do not call it if you called png_set_alpha_mode(); doing so will damage the
1.1818 +settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is
1.1819 +supported then you can certainly do png_set_gamma() before reading the PNG
1.1820 +header.)
1.1821 +
1.1822 +This API unconditionally sets the screen and file gamma values, so it will
1.1823 +override the value in the PNG file unless it is called before the PNG file
1.1824 +reading starts. For this reason you must always call it with the PNG file
1.1825 +value when you call it in this position:
1.1826 +
1.1827 + if (png_get_gAMA(png_ptr, info_ptr, &file_gamma))
1.1828 + png_set_gamma(png_ptr, screen_gamma, file_gamma);
1.1829 +
1.1830 + else
1.1831 + png_set_gamma(png_ptr, screen_gamma, 0.45455);
1.1832 +
1.1833 +If you need to reduce an RGB file to a paletted file, or if a paletted
1.1834 +file has more entries then will fit on your screen, png_set_quantize()
1.1835 +will do that. Note that this is a simple match quantization that merely
1.1836 +finds the closest color available. This should work fairly well with
1.1837 +optimized palettes, but fairly badly with linear color cubes. If you
1.1838 +pass a palette that is larger than maximum_colors, the file will
1.1839 +reduce the number of colors in the palette so it will fit into
1.1840 +maximum_colors. If there is a histogram, libpng will use it to make
1.1841 +more intelligent choices when reducing the palette. If there is no
1.1842 +histogram, it may not do as good a job.
1.1843 +
1.1844 + if (color_type & PNG_COLOR_MASK_COLOR)
1.1845 + {
1.1846 + if (png_get_valid(png_ptr, info_ptr,
1.1847 + PNG_INFO_PLTE))
1.1848 + {
1.1849 + png_uint_16p histogram = NULL;
1.1850 +
1.1851 + png_get_hIST(png_ptr, info_ptr,
1.1852 + &histogram);
1.1853 + png_set_quantize(png_ptr, palette, num_palette,
1.1854 + max_screen_colors, histogram, 1);
1.1855 + }
1.1856 +
1.1857 + else
1.1858 + {
1.1859 + png_color std_color_cube[MAX_SCREEN_COLORS] =
1.1860 + { ... colors ... };
1.1861 +
1.1862 + png_set_quantize(png_ptr, std_color_cube,
1.1863 + MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1.1864 + NULL,0);
1.1865 + }
1.1866 + }
1.1867 +
1.1868 +PNG files describe monochrome as black being zero and white being one.
1.1869 +The following code will reverse this (make black be one and white be
1.1870 +zero):
1.1871 +
1.1872 + if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
1.1873 + png_set_invert_mono(png_ptr);
1.1874 +
1.1875 +This function can also be used to invert grayscale and gray-alpha images:
1.1876 +
1.1877 + if (color_type == PNG_COLOR_TYPE_GRAY ||
1.1878 + color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1.1879 + png_set_invert_mono(png_ptr);
1.1880 +
1.1881 +PNG files store 16-bit pixels in network byte order (big-endian,
1.1882 +ie. most significant bits first). This code changes the storage to the
1.1883 +other way (little-endian, i.e. least significant bits first, the
1.1884 +way PCs store them):
1.1885 +
1.1886 + if (bit_depth == 16)
1.1887 + png_set_swap(png_ptr);
1.1888 +
1.1889 +If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1.1890 +need to change the order the pixels are packed into bytes, you can use:
1.1891 +
1.1892 + if (bit_depth < 8)
1.1893 + png_set_packswap(png_ptr);
1.1894 +
1.1895 +Finally, you can write your own transformation function if none of
1.1896 +the existing ones meets your needs. This is done by setting a callback
1.1897 +with
1.1898 +
1.1899 + png_set_read_user_transform_fn(png_ptr,
1.1900 + read_transform_fn);
1.1901 +
1.1902 +You must supply the function
1.1903 +
1.1904 + void read_transform_fn(png_structp png_ptr, png_row_infop
1.1905 + row_info, png_bytep data)
1.1906 +
1.1907 +See pngtest.c for a working example. Your function will be called
1.1908 +after all of the other transformations have been processed. Take care with
1.1909 +interlaced images if you do the interlace yourself - the width of the row is the
1.1910 +width in 'row_info', not the overall image width.
1.1911 +
1.1912 +If supported, libpng provides two information routines that you can use to find
1.1913 +where you are in processing the image:
1.1914 +
1.1915 + png_get_current_pass_number(png_structp png_ptr);
1.1916 + png_get_current_row_number(png_structp png_ptr);
1.1917 +
1.1918 +Don't try using these outside a transform callback - firstly they are only
1.1919 +supported if user transforms are supported, secondly they may well return
1.1920 +unexpected results unless the row is actually being processed at the moment they
1.1921 +are called.
1.1922 +
1.1923 +With interlaced
1.1924 +images the value returned is the row in the input sub-image image. Use
1.1925 +PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
1.1926 +find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
1.1927 +
1.1928 +The discussion of interlace handling above contains more information on how to
1.1929 +use these values.
1.1930 +
1.1931 +You can also set up a pointer to a user structure for use by your
1.1932 +callback function, and you can inform libpng that your transform
1.1933 +function will change the number of channels or bit depth with the
1.1934 +function
1.1935 +
1.1936 + png_set_user_transform_info(png_ptr, user_ptr,
1.1937 + user_depth, user_channels);
1.1938 +
1.1939 +The user's application, not libpng, is responsible for allocating and
1.1940 +freeing any memory required for the user structure.
1.1941 +
1.1942 +You can retrieve the pointer via the function
1.1943 +png_get_user_transform_ptr(). For example:
1.1944 +
1.1945 + voidp read_user_transform_ptr =
1.1946 + png_get_user_transform_ptr(png_ptr);
1.1947 +
1.1948 +The last thing to handle is interlacing; this is covered in detail below,
1.1949 +but you must call the function here if you want libpng to handle expansion
1.1950 +of the interlaced image.
1.1951 +
1.1952 + number_of_passes = png_set_interlace_handling(png_ptr);
1.1953 +
1.1954 +After setting the transformations, libpng can update your png_info
1.1955 +structure to reflect any transformations you've requested with this
1.1956 +call.
1.1957 +
1.1958 + png_read_update_info(png_ptr, info_ptr);
1.1959 +
1.1960 +This is most useful to update the info structure's rowbytes
1.1961 +field so you can use it to allocate your image memory. This function
1.1962 +will also update your palette with the correct screen_gamma and
1.1963 +background if these have been given with the calls above. You may
1.1964 +only call png_read_update_info() once with a particular info_ptr.
1.1965 +
1.1966 +After you call png_read_update_info(), you can allocate any
1.1967 +memory you need to hold the image. The row data is simply
1.1968 +raw byte data for all forms of images. As the actual allocation
1.1969 +varies among applications, no example will be given. If you
1.1970 +are allocating one large chunk, you will need to build an
1.1971 +array of pointers to each row, as it will be needed for some
1.1972 +of the functions below.
1.1973 +
1.1974 +Remember: Before you call png_read_update_info(), the png_get_*()
1.1975 +functions return the values corresponding to the original PNG image.
1.1976 +After you call png_read_update_info the values refer to the image
1.1977 +that libpng will output. Consequently you must call all the png_set_
1.1978 +functions before you call png_read_update_info(). This is particularly
1.1979 +important for png_set_interlace_handling() - if you are going to call
1.1980 +png_read_update_info() you must call png_set_interlace_handling() before
1.1981 +it unless you want to receive interlaced output.
1.1982 +
1.1983 +Reading image data
1.1984 +
1.1985 +After you've allocated memory, you can read the image data.
1.1986 +The simplest way to do this is in one function call. If you are
1.1987 +allocating enough memory to hold the whole image, you can just
1.1988 +call png_read_image() and libpng will read in all the image data
1.1989 +and put it in the memory area supplied. You will need to pass in
1.1990 +an array of pointers to each row.
1.1991 +
1.1992 +This function automatically handles interlacing, so you don't
1.1993 +need to call png_set_interlace_handling() (unless you call
1.1994 +png_read_update_info()) or call this function multiple times, or any
1.1995 +of that other stuff necessary with png_read_rows().
1.1996 +
1.1997 + png_read_image(png_ptr, row_pointers);
1.1998 +
1.1999 +where row_pointers is:
1.2000 +
1.2001 + png_bytep row_pointers[height];
1.2002 +
1.2003 +You can point to void or char or whatever you use for pixels.
1.2004 +
1.2005 +If you don't want to read in the whole image at once, you can
1.2006 +use png_read_rows() instead. If there is no interlacing (check
1.2007 +interlace_type == PNG_INTERLACE_NONE), this is simple:
1.2008 +
1.2009 + png_read_rows(png_ptr, row_pointers, NULL,
1.2010 + number_of_rows);
1.2011 +
1.2012 +where row_pointers is the same as in the png_read_image() call.
1.2013 +
1.2014 +If you are doing this just one row at a time, you can do this with
1.2015 +a single row_pointer instead of an array of row_pointers:
1.2016 +
1.2017 + png_bytep row_pointer = row;
1.2018 + png_read_row(png_ptr, row_pointer, NULL);
1.2019 +
1.2020 +If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
1.2021 +get somewhat harder. The only current (PNG Specification version 1.2)
1.2022 +interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7);
1.2023 +a somewhat complicated 2D interlace scheme, known as Adam7, that
1.2024 +breaks down an image into seven smaller images of varying size, based
1.2025 +on an 8x8 grid. This number is defined (from libpng 1.5) as
1.2026 +PNG_INTERLACE_ADAM7_PASSES in png.h
1.2027 +
1.2028 +libpng can fill out those images or it can give them to you "as is".
1.2029 +It is almost always better to have libpng handle the interlacing for you.
1.2030 +If you want the images filled out, there are two ways to do that. The one
1.2031 +mentioned in the PNG specification is to expand each pixel to cover
1.2032 +those pixels that have not been read yet (the "rectangle" method).
1.2033 +This results in a blocky image for the first pass, which gradually
1.2034 +smooths out as more pixels are read. The other method is the "sparkle"
1.2035 +method, where pixels are drawn only in their final locations, with the
1.2036 +rest of the image remaining whatever colors they were initialized to
1.2037 +before the start of the read. The first method usually looks better,
1.2038 +but tends to be slower, as there are more pixels to put in the rows.
1.2039 +
1.2040 +If, as is likely, you want libpng to expand the images, call this before
1.2041 +calling png_start_read_image() or png_read_update_info():
1.2042 +
1.2043 + if (interlace_type == PNG_INTERLACE_ADAM7)
1.2044 + number_of_passes
1.2045 + = png_set_interlace_handling(png_ptr);
1.2046 +
1.2047 +This will return the number of passes needed. Currently, this is seven,
1.2048 +but may change if another interlace type is added. This function can be
1.2049 +called even if the file is not interlaced, where it will return one pass.
1.2050 +You then need to read the whole image 'number_of_passes' times. Each time
1.2051 +will distribute the pixels from the current pass to the correct place in
1.2052 +the output image, so you need to supply the same rows to png_read_rows in
1.2053 +each pass.
1.2054 +
1.2055 +If you are not going to display the image after each pass, but are
1.2056 +going to wait until the entire image is read in, use the sparkle
1.2057 +effect. This effect is faster and the end result of either method
1.2058 +is exactly the same. If you are planning on displaying the image
1.2059 +after each pass, the "rectangle" effect is generally considered the
1.2060 +better looking one.
1.2061 +
1.2062 +If you only want the "sparkle" effect, just call png_read_rows() as
1.2063 +normal, with the third parameter NULL. Make sure you make pass over
1.2064 +the image number_of_passes times, and you don't change the data in the
1.2065 +rows between calls. You can change the locations of the data, just
1.2066 +not the data. Each pass only writes the pixels appropriate for that
1.2067 +pass, and assumes the data from previous passes is still valid.
1.2068 +
1.2069 + png_read_rows(png_ptr, row_pointers, NULL,
1.2070 + number_of_rows);
1.2071 +
1.2072 +If you only want the first effect (the rectangles), do the same as
1.2073 +before except pass the row buffer in the third parameter, and leave
1.2074 +the second parameter NULL.
1.2075 +
1.2076 + png_read_rows(png_ptr, NULL, row_pointers,
1.2077 + number_of_rows);
1.2078 +
1.2079 +If you don't want libpng to handle the interlacing details, just call
1.2080 +png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
1.2081 +Each of the images is a valid image by itself; however, you will almost
1.2082 +certainly need to distribute the pixels from each sub-image to the
1.2083 +correct place. This is where everything gets very tricky.
1.2084 +
1.2085 +If you want to retrieve the separate images you must pass the correct
1.2086 +number of rows to each successive call of png_read_rows(). The calculation
1.2087 +gets pretty complicated for small images, where some sub-images may
1.2088 +not even exist because either their width or height ends up zero.
1.2089 +libpng provides two macros to help you in 1.5 and later versions:
1.2090 +
1.2091 + png_uint_32 width = PNG_PASS_COLS(image_width, pass_number);
1.2092 + png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number);
1.2093 +
1.2094 +Respectively these tell you the width and height of the sub-image
1.2095 +corresponding to the numbered pass. 'pass' is in in the range 0 to 6 -
1.2096 +this can be confusing because the specification refers to the same passes
1.2097 +as 1 to 7! Be careful, you must check both the width and height before
1.2098 +calling png_read_rows() and not call it for that pass if either is zero.
1.2099 +
1.2100 +You can, of course, read each sub-image row by row. If you want to
1.2101 +produce optimal code to make a pixel-by-pixel transformation of an
1.2102 +interlaced image this is the best approach; read each row of each pass,
1.2103 +transform it, and write it out to a new interlaced image.
1.2104 +
1.2105 +If you want to de-interlace the image yourself libpng provides further
1.2106 +macros to help that tell you where to place the pixels in the output image.
1.2107 +Because the interlacing scheme is rectangular - sub-image pixels are always
1.2108 +arranged on a rectangular grid - all you need to know for each pass is the
1.2109 +starting column and row in the output image of the first pixel plus the
1.2110 +spacing between each pixel. As of libpng 1.5 there are four macros to
1.2111 +retrieve this information:
1.2112 +
1.2113 + png_uint_32 x = PNG_PASS_START_COL(pass);
1.2114 + png_uint_32 y = PNG_PASS_START_ROW(pass);
1.2115 + png_uint_32 xStep = 1U << PNG_PASS_COL_SHIFT(pass);
1.2116 + png_uint_32 yStep = 1U << PNG_PASS_ROW_SHIFT(pass);
1.2117 +
1.2118 +These allow you to write the obvious loop:
1.2119 +
1.2120 + png_uint_32 input_y = 0;
1.2121 + png_uint_32 output_y = PNG_PASS_START_ROW(pass);
1.2122 +
1.2123 + while (output_y < output_image_height)
1.2124 + {
1.2125 + png_uint_32 input_x = 0;
1.2126 + png_uint_32 output_x = PNG_PASS_START_COL(pass);
1.2127 +
1.2128 + while (output_x < output_image_width)
1.2129 + {
1.2130 + image[output_y][output_x] =
1.2131 + subimage[pass][input_y][input_x++];
1.2132 +
1.2133 + output_x += xStep;
1.2134 + }
1.2135 +
1.2136 + ++input_y;
1.2137 + output_y += yStep;
1.2138 + }
1.2139 +
1.2140 +Notice that the steps between successive output rows and columns are
1.2141 +returned as shifts. This is possible because the pixels in the subimages
1.2142 +are always a power of 2 apart - 1, 2, 4 or 8 pixels - in the original
1.2143 +image. In practice you may need to directly calculate the output coordinate
1.2144 +given an input coordinate. libpng provides two further macros for this
1.2145 +purpose:
1.2146 +
1.2147 + png_uint_32 output_x = PNG_COL_FROM_PASS_COL(input_x, pass);
1.2148 + png_uint_32 output_y = PNG_ROW_FROM_PASS_ROW(input_y, pass);
1.2149 +
1.2150 +Finally a pair of macros are provided to tell you if a particular image
1.2151 +row or column appears in a given pass:
1.2152 +
1.2153 + int col_in_pass = PNG_COL_IN_INTERLACE_PASS(output_x, pass);
1.2154 + int row_in_pass = PNG_ROW_IN_INTERLACE_PASS(output_y, pass);
1.2155 +
1.2156 +Bear in mind that you will probably also need to check the width and height
1.2157 +of the pass in addition to the above to be sure the pass even exists!
1.2158 +
1.2159 +With any luck you are convinced by now that you don't want to do your own
1.2160 +interlace handling. In reality normally the only good reason for doing this
1.2161 +is if you are processing PNG files on a pixel-by-pixel basis and don't want
1.2162 +to load the whole file into memory when it is interlaced.
1.2163 +
1.2164 +libpng includes a test program, pngvalid, that illustrates reading and
1.2165 +writing of interlaced images. If you can't get interlacing to work in your
1.2166 +code and don't want to leave it to libpng (the recommended approach), see
1.2167 +how pngvalid.c does it.
1.2168 +
1.2169 +Finishing a sequential read
1.2170 +
1.2171 +After you are finished reading the image through the
1.2172 +low-level interface, you can finish reading the file. If you are
1.2173 +interested in comments or time, which may be stored either before or
1.2174 +after the image data, you should pass the separate png_info struct if
1.2175 +you want to keep the comments from before and after the image
1.2176 +separate.
1.2177 +
1.2178 + png_infop end_info = png_create_info_struct(png_ptr);
1.2179 +
1.2180 + if (!end_info)
1.2181 + {
1.2182 + png_destroy_read_struct(&png_ptr, &info_ptr,
1.2183 + (png_infopp)NULL);
1.2184 + return (ERROR);
1.2185 + }
1.2186 +
1.2187 + png_read_end(png_ptr, end_info);
1.2188 +
1.2189 +If you are not interested, you should still call png_read_end()
1.2190 +but you can pass NULL, avoiding the need to create an end_info structure.
1.2191 +
1.2192 + png_read_end(png_ptr, (png_infop)NULL);
1.2193 +
1.2194 +If you don't call png_read_end(), then your file pointer will be
1.2195 +left pointing to the first chunk after the last IDAT, which is probably
1.2196 +not what you want if you expect to read something beyond the end of
1.2197 +the PNG datastream.
1.2198 +
1.2199 +When you are done, you can free all memory allocated by libpng like this:
1.2200 +
1.2201 + png_destroy_read_struct(&png_ptr, &info_ptr,
1.2202 + &end_info);
1.2203 +
1.2204 +or, if you didn't create an end_info structure,
1.2205 +
1.2206 + png_destroy_read_struct(&png_ptr, &info_ptr,
1.2207 + (png_infopp)NULL);
1.2208 +
1.2209 +It is also possible to individually free the info_ptr members that
1.2210 +point to libpng-allocated storage with the following function:
1.2211 +
1.2212 + png_free_data(png_ptr, info_ptr, mask, seq)
1.2213 +
1.2214 + mask - identifies data to be freed, a mask
1.2215 + containing the bitwise OR of one or
1.2216 + more of
1.2217 + PNG_FREE_PLTE, PNG_FREE_TRNS,
1.2218 + PNG_FREE_HIST, PNG_FREE_ICCP,
1.2219 + PNG_FREE_PCAL, PNG_FREE_ROWS,
1.2220 + PNG_FREE_SCAL, PNG_FREE_SPLT,
1.2221 + PNG_FREE_TEXT, PNG_FREE_UNKN,
1.2222 + or simply PNG_FREE_ALL
1.2223 +
1.2224 + seq - sequence number of item to be freed
1.2225 + (-1 for all items)
1.2226 +
1.2227 +This function may be safely called when the relevant storage has
1.2228 +already been freed, or has not yet been allocated, or was allocated
1.2229 +by the user and not by libpng, and will in those cases do nothing.
1.2230 +The "seq" parameter is ignored if only one item of the selected data
1.2231 +type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
1.2232 +are allowed for the data type identified in the mask, such as text or
1.2233 +sPLT, only the n'th item in the structure is freed, where n is "seq".
1.2234 +
1.2235 +The default behavior is only to free data that was allocated internally
1.2236 +by libpng. This can be changed, so that libpng will not free the data,
1.2237 +or so that it will free data that was allocated by the user with png_malloc()
1.2238 +or png_calloc() and passed in via a png_set_*() function, with
1.2239 +
1.2240 + png_data_freer(png_ptr, info_ptr, freer, mask)
1.2241 +
1.2242 + freer - one of
1.2243 + PNG_DESTROY_WILL_FREE_DATA
1.2244 + PNG_SET_WILL_FREE_DATA
1.2245 + PNG_USER_WILL_FREE_DATA
1.2246 +
1.2247 + mask - which data elements are affected
1.2248 + same choices as in png_free_data()
1.2249 +
1.2250 +This function only affects data that has already been allocated.
1.2251 +You can call this function after reading the PNG data but before calling
1.2252 +any png_set_*() functions, to control whether the user or the png_set_*()
1.2253 +function is responsible for freeing any existing data that might be present,
1.2254 +and again after the png_set_*() functions to control whether the user
1.2255 +or png_destroy_*() is supposed to free the data. When the user assumes
1.2256 +responsibility for libpng-allocated data, the application must use
1.2257 +png_free() to free it, and when the user transfers responsibility to libpng
1.2258 +for data that the user has allocated, the user must have used png_malloc()
1.2259 +or png_calloc() to allocate it.
1.2260 +
1.2261 +If you allocated your row_pointers in a single block, as suggested above in
1.2262 +the description of the high level read interface, you must not transfer
1.2263 +responsibility for freeing it to the png_set_rows or png_read_destroy function,
1.2264 +because they would also try to free the individual row_pointers[i].
1.2265 +
1.2266 +If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
1.2267 +separately, do not transfer responsibility for freeing text_ptr to libpng,
1.2268 +because when libpng fills a png_text structure it combines these members with
1.2269 +the key member, and png_free_data() will free only text_ptr.key. Similarly,
1.2270 +if you transfer responsibility for free'ing text_ptr from libpng to your
1.2271 +application, your application must not separately free those members.
1.2272 +
1.2273 +The png_free_data() function will turn off the "valid" flag for anything
1.2274 +it frees. If you need to turn the flag off for a chunk that was freed by
1.2275 +your application instead of by libpng, you can use
1.2276 +
1.2277 + png_set_invalid(png_ptr, info_ptr, mask);
1.2278 +
1.2279 + mask - identifies the chunks to be made invalid,
1.2280 + containing the bitwise OR of one or
1.2281 + more of
1.2282 + PNG_INFO_gAMA, PNG_INFO_sBIT,
1.2283 + PNG_INFO_cHRM, PNG_INFO_PLTE,
1.2284 + PNG_INFO_tRNS, PNG_INFO_bKGD,
1.2285 + PNG_INFO_hIST, PNG_INFO_pHYs,
1.2286 + PNG_INFO_oFFs, PNG_INFO_tIME,
1.2287 + PNG_INFO_pCAL, PNG_INFO_sRGB,
1.2288 + PNG_INFO_iCCP, PNG_INFO_sPLT,
1.2289 + PNG_INFO_sCAL, PNG_INFO_IDAT
1.2290 +
1.2291 +For a more compact example of reading a PNG image, see the file example.c.
1.2292 +
1.2293 +Reading PNG files progressively
1.2294 +
1.2295 +The progressive reader is slightly different from the non-progressive
1.2296 +reader. Instead of calling png_read_info(), png_read_rows(), and
1.2297 +png_read_end(), you make one call to png_process_data(), which calls
1.2298 +callbacks when it has the info, a row, or the end of the image. You
1.2299 +set up these callbacks with png_set_progressive_read_fn(). You don't
1.2300 +have to worry about the input/output functions of libpng, as you are
1.2301 +giving the library the data directly in png_process_data(). I will
1.2302 +assume that you have read the section on reading PNG files above,
1.2303 +so I will only highlight the differences (although I will show
1.2304 +all of the code).
1.2305 +
1.2306 +png_structp png_ptr;
1.2307 +png_infop info_ptr;
1.2308 +
1.2309 + /* An example code fragment of how you would
1.2310 + initialize the progressive reader in your
1.2311 + application. */
1.2312 + int
1.2313 + initialize_png_reader()
1.2314 + {
1.2315 + png_ptr = png_create_read_struct
1.2316 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1.2317 + user_error_fn, user_warning_fn);
1.2318 +
1.2319 + if (!png_ptr)
1.2320 + return (ERROR);
1.2321 +
1.2322 + info_ptr = png_create_info_struct(png_ptr);
1.2323 +
1.2324 + if (!info_ptr)
1.2325 + {
1.2326 + png_destroy_read_struct(&png_ptr,
1.2327 + (png_infopp)NULL, (png_infopp)NULL);
1.2328 + return (ERROR);
1.2329 + }
1.2330 +
1.2331 + if (setjmp(png_jmpbuf(png_ptr)))
1.2332 + {
1.2333 + png_destroy_read_struct(&png_ptr, &info_ptr,
1.2334 + (png_infopp)NULL);
1.2335 + return (ERROR);
1.2336 + }
1.2337 +
1.2338 + /* This one's new. You can provide functions
1.2339 + to be called when the header info is valid,
1.2340 + when each row is completed, and when the image
1.2341 + is finished. If you aren't using all functions,
1.2342 + you can specify NULL parameters. Even when all
1.2343 + three functions are NULL, you need to call
1.2344 + png_set_progressive_read_fn(). You can use
1.2345 + any struct as the user_ptr (cast to a void pointer
1.2346 + for the function call), and retrieve the pointer
1.2347 + from inside the callbacks using the function
1.2348 +
1.2349 + png_get_progressive_ptr(png_ptr);
1.2350 +
1.2351 + which will return a void pointer, which you have
1.2352 + to cast appropriately.
1.2353 + */
1.2354 + png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
1.2355 + info_callback, row_callback, end_callback);
1.2356 +
1.2357 + return 0;
1.2358 + }
1.2359 +
1.2360 + /* A code fragment that you call as you receive blocks
1.2361 + of data */
1.2362 + int
1.2363 + process_data(png_bytep buffer, png_uint_32 length)
1.2364 + {
1.2365 + if (setjmp(png_jmpbuf(png_ptr)))
1.2366 + {
1.2367 + png_destroy_read_struct(&png_ptr, &info_ptr,
1.2368 + (png_infopp)NULL);
1.2369 + return (ERROR);
1.2370 + }
1.2371 +
1.2372 + /* This one's new also. Simply give it a chunk
1.2373 + of data from the file stream (in order, of
1.2374 + course). On machines with segmented memory
1.2375 + models machines, don't give it any more than
1.2376 + 64K. The library seems to run fine with sizes
1.2377 + of 4K. Although you can give it much less if
1.2378 + necessary (I assume you can give it chunks of
1.2379 + 1 byte, I haven't tried less then 256 bytes
1.2380 + yet). When this function returns, you may
1.2381 + want to display any rows that were generated
1.2382 + in the row callback if you don't already do
1.2383 + so there.
1.2384 + */
1.2385 + png_process_data(png_ptr, info_ptr, buffer, length);
1.2386 +
1.2387 + /* At this point you can call png_process_data_skip if
1.2388 + you want to handle data the library will skip yourself;
1.2389 + it simply returns the number of bytes to skip (and stops
1.2390 + libpng skipping that number of bytes on the next
1.2391 + png_process_data call).
1.2392 + return 0;
1.2393 + }
1.2394 +
1.2395 + /* This function is called (as set by
1.2396 + png_set_progressive_read_fn() above) when enough data
1.2397 + has been supplied so all of the header has been
1.2398 + read.
1.2399 + */
1.2400 + void
1.2401 + info_callback(png_structp png_ptr, png_infop info)
1.2402 + {
1.2403 + /* Do any setup here, including setting any of
1.2404 + the transformations mentioned in the Reading
1.2405 + PNG files section. For now, you _must_ call
1.2406 + either png_start_read_image() or
1.2407 + png_read_update_info() after all the
1.2408 + transformations are set (even if you don't set
1.2409 + any). You may start getting rows before
1.2410 + png_process_data() returns, so this is your
1.2411 + last chance to prepare for that.
1.2412 +
1.2413 + This is where you turn on interlace handling,
1.2414 + assuming you don't want to do it yourself.
1.2415 +
1.2416 + If you need to you can stop the processing of
1.2417 + your original input data at this point by calling
1.2418 + png_process_data_pause. This returns the number
1.2419 + of unprocessed bytes from the last png_process_data
1.2420 + call - it is up to you to ensure that the next call
1.2421 + sees these bytes again. If you don't want to bother
1.2422 + with this you can get libpng to cache the unread
1.2423 + bytes by setting the 'save' parameter (see png.h) but
1.2424 + then libpng will have to copy the data internally.
1.2425 + */
1.2426 + }
1.2427 +
1.2428 + /* This function is called when each row of image
1.2429 + data is complete */
1.2430 + void
1.2431 + row_callback(png_structp png_ptr, png_bytep new_row,
1.2432 + png_uint_32 row_num, int pass)
1.2433 + {
1.2434 + /* If the image is interlaced, and you turned
1.2435 + on the interlace handler, this function will
1.2436 + be called for every row in every pass. Some
1.2437 + of these rows will not be changed from the
1.2438 + previous pass. When the row is not changed,
1.2439 + the new_row variable will be NULL. The rows
1.2440 + and passes are called in order, so you don't
1.2441 + really need the row_num and pass, but I'm
1.2442 + supplying them because it may make your life
1.2443 + easier.
1.2444 +
1.2445 + If you did not turn on interlace handling then
1.2446 + the callback is called for each row of each
1.2447 + sub-image when the image is interlaced. In this
1.2448 + case 'row_num' is the row in the sub-image, not
1.2449 + the row in the output image as it is in all other
1.2450 + cases.
1.2451 +
1.2452 + For the non-NULL rows of interlaced images when
1.2453 + you have switched on libpng interlace handling,
1.2454 + you must call png_progressive_combine_row()
1.2455 + passing in the row and the old row. You can
1.2456 + call this function for NULL rows (it will just
1.2457 + return) and for non-interlaced images (it just
1.2458 + does the memcpy for you) if it will make the
1.2459 + code easier. Thus, you can just do this for
1.2460 + all cases if you switch on interlace handling;
1.2461 + */
1.2462 +
1.2463 + png_progressive_combine_row(png_ptr, old_row,
1.2464 + new_row);
1.2465 +
1.2466 + /* where old_row is what was displayed for
1.2467 + previously for the row. Note that the first
1.2468 + pass (pass == 0, really) will completely cover
1.2469 + the old row, so the rows do not have to be
1.2470 + initialized. After the first pass (and only
1.2471 + for interlaced images), you will have to pass
1.2472 + the current row, and the function will combine
1.2473 + the old row and the new row.
1.2474 +
1.2475 + You can also call png_process_data_pause in this
1.2476 + callback - see above.
1.2477 + */
1.2478 + }
1.2479 +
1.2480 + void
1.2481 + end_callback(png_structp png_ptr, png_infop info)
1.2482 + {
1.2483 + /* This function is called after the whole image
1.2484 + has been read, including any chunks after the
1.2485 + image (up to and including the IEND). You
1.2486 + will usually have the same info chunk as you
1.2487 + had in the header, although some data may have
1.2488 + been added to the comments and time fields.
1.2489 +
1.2490 + Most people won't do much here, perhaps setting
1.2491 + a flag that marks the image as finished.
1.2492 + */
1.2493 + }
1.2494 +
1.2495 +
1.2496 +
1.2497 +IV. Writing
1.2498 +
1.2499 +Much of this is very similar to reading. However, everything of
1.2500 +importance is repeated here, so you won't have to constantly look
1.2501 +back up in the reading section to understand writing.
1.2502 +
1.2503 +Setup
1.2504 +
1.2505 +You will want to do the I/O initialization before you get into libpng,
1.2506 +so if it doesn't work, you don't have anything to undo. If you are not
1.2507 +using the standard I/O functions, you will need to replace them with
1.2508 +custom writing functions. See the discussion under Customizing libpng.
1.2509 +
1.2510 + FILE *fp = fopen(file_name, "wb");
1.2511 +
1.2512 + if (!fp)
1.2513 + return (ERROR);
1.2514 +
1.2515 +Next, png_struct and png_info need to be allocated and initialized.
1.2516 +As these can be both relatively large, you may not want to store these
1.2517 +on the stack, unless you have stack space to spare. Of course, you
1.2518 +will want to check if they return NULL. If you are also reading,
1.2519 +you won't want to name your read structure and your write structure
1.2520 +both "png_ptr"; you can call them anything you like, such as
1.2521 +"read_ptr" and "write_ptr". Look at pngtest.c, for example.
1.2522 +
1.2523 + png_structp png_ptr = png_create_write_struct
1.2524 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1.2525 + user_error_fn, user_warning_fn);
1.2526 +
1.2527 + if (!png_ptr)
1.2528 + return (ERROR);
1.2529 +
1.2530 + png_infop info_ptr = png_create_info_struct(png_ptr);
1.2531 + if (!info_ptr)
1.2532 + {
1.2533 + png_destroy_write_struct(&png_ptr,
1.2534 + (png_infopp)NULL);
1.2535 + return (ERROR);
1.2536 + }
1.2537 +
1.2538 +If you want to use your own memory allocation routines,
1.2539 +define PNG_USER_MEM_SUPPORTED and use
1.2540 +png_create_write_struct_2() instead of png_create_write_struct():
1.2541 +
1.2542 + png_structp png_ptr = png_create_write_struct_2
1.2543 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1.2544 + user_error_fn, user_warning_fn, (png_voidp)
1.2545 + user_mem_ptr, user_malloc_fn, user_free_fn);
1.2546 +
1.2547 +After you have these structures, you will need to set up the
1.2548 +error handling. When libpng encounters an error, it expects to
1.2549 +longjmp() back to your routine. Therefore, you will need to call
1.2550 +setjmp() and pass the png_jmpbuf(png_ptr). If you
1.2551 +write the file from different routines, you will need to update
1.2552 +the png_jmpbuf(png_ptr) every time you enter a new routine that will
1.2553 +call a png_*() function. See your documentation of setjmp/longjmp
1.2554 +for your compiler for more information on setjmp/longjmp. See
1.2555 +the discussion on libpng error handling in the Customizing Libpng
1.2556 +section below for more information on the libpng error handling.
1.2557 +
1.2558 + if (setjmp(png_jmpbuf(png_ptr)))
1.2559 + {
1.2560 + png_destroy_write_struct(&png_ptr, &info_ptr);
1.2561 + fclose(fp);
1.2562 + return (ERROR);
1.2563 + }
1.2564 + ...
1.2565 + return;
1.2566 +
1.2567 +If you would rather avoid the complexity of setjmp/longjmp issues,
1.2568 +you can compile libpng with PNG_NO_SETJMP, in which case
1.2569 +errors will result in a call to PNG_ABORT() which defaults to abort().
1.2570 +
1.2571 +You can #define PNG_ABORT() to a function that does something
1.2572 +more useful than abort(), as long as your function does not
1.2573 +return.
1.2574 +
1.2575 +Checking for invalid palette index on write was added at libpng
1.2576 +1.5.10. If a pixel contains an invalid (out-of-range) index libpng issues
1.2577 +a benign error. This is enabled by default because this condition is an
1.2578 +error according to the PNG specification, Clause 11.3.2, but the error can
1.2579 +be ignored in each png_ptr with
1.2580 +
1.2581 + png_set_check_for_invalid_index(png_ptr, 0);
1.2582 +
1.2583 +If the error is ignored, or if png_benign_error() treats it as a warning,
1.2584 +any invalid pixels are written as-is by the encoder, resulting in an
1.2585 +invalid PNG datastream as output. In this case the application is
1.2586 +responsible for ensuring that the pixel indexes are in range when it writes
1.2587 +a PLTE chunk with fewer entries than the bit depth would allow.
1.2588 +
1.2589 +Now you need to set up the output code. The default for libpng is to
1.2590 +use the C function fwrite(). If you use this, you will need to pass a
1.2591 +valid FILE * in the function png_init_io(). Be sure that the file is
1.2592 +opened in binary mode. Again, if you wish to handle writing data in
1.2593 +another way, see the discussion on libpng I/O handling in the Customizing
1.2594 +Libpng section below.
1.2595 +
1.2596 + png_init_io(png_ptr, fp);
1.2597 +
1.2598 +If you are embedding your PNG into a datastream such as MNG, and don't
1.2599 +want libpng to write the 8-byte signature, or if you have already
1.2600 +written the signature in your application, use
1.2601 +
1.2602 + png_set_sig_bytes(png_ptr, 8);
1.2603 +
1.2604 +to inform libpng that it should not write a signature.
1.2605 +
1.2606 +Write callbacks
1.2607 +
1.2608 +At this point, you can set up a callback function that will be
1.2609 +called after each row has been written, which you can use to control
1.2610 +a progress meter or the like. It's demonstrated in pngtest.c.
1.2611 +You must supply a function
1.2612 +
1.2613 + void write_row_callback(png_structp png_ptr, png_uint_32 row,
1.2614 + int pass);
1.2615 + {
1.2616 + /* put your code here */
1.2617 + }
1.2618 +
1.2619 +(You can give it another name that you like instead of "write_row_callback")
1.2620 +
1.2621 +To inform libpng about your function, use
1.2622 +
1.2623 + png_set_write_status_fn(png_ptr, write_row_callback);
1.2624 +
1.2625 +When this function is called the row has already been completely processed and
1.2626 +it has also been written out. The 'row' and 'pass' refer to the next row to be
1.2627 +handled. For the
1.2628 +non-interlaced case the row that was just handled is simply one less than the
1.2629 +passed in row number, and pass will always be 0. For the interlaced case the
1.2630 +same applies unless the row value is 0, in which case the row just handled was
1.2631 +the last one from one of the preceding passes. Because interlacing may skip a
1.2632 +pass you cannot be sure that the preceding pass is just 'pass-1', if you really
1.2633 +need to know what the last pass is record (row,pass) from the callback and use
1.2634 +the last recorded value each time.
1.2635 +
1.2636 +As with the user transform you can find the output row using the
1.2637 +PNG_ROW_FROM_PASS_ROW macro.
1.2638 +
1.2639 +You now have the option of modifying how the compression library will
1.2640 +run. The following functions are mainly for testing, but may be useful
1.2641 +in some cases, like if you need to write PNG files extremely fast and
1.2642 +are willing to give up some compression, or if you want to get the
1.2643 +maximum possible compression at the expense of slower writing. If you
1.2644 +have no special needs in this area, let the library do what it wants by
1.2645 +not calling this function at all, as it has been tuned to deliver a good
1.2646 +speed/compression ratio. The second parameter to png_set_filter() is
1.2647 +the filter method, for which the only valid values are 0 (as of the
1.2648 +July 1999 PNG specification, version 1.2) or 64 (if you are writing
1.2649 +a PNG datastream that is to be embedded in a MNG datastream). The third
1.2650 +parameter is a flag that indicates which filter type(s) are to be tested
1.2651 +for each scanline. See the PNG specification for details on the specific
1.2652 +filter types.
1.2653 +
1.2654 +
1.2655 + /* turn on or off filtering, and/or choose
1.2656 + specific filters. You can use either a single
1.2657 + PNG_FILTER_VALUE_NAME or the bitwise OR of one
1.2658 + or more PNG_FILTER_NAME masks.
1.2659 + */
1.2660 + png_set_filter(png_ptr, 0,
1.2661 + PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
1.2662 + PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
1.2663 + PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
1.2664 + PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |
1.2665 + PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
1.2666 + PNG_ALL_FILTERS);
1.2667 +
1.2668 +If an application wants to start and stop using particular filters during
1.2669 +compression, it should start out with all of the filters (to ensure that
1.2670 +the previous row of pixels will be stored in case it's needed later),
1.2671 +and then add and remove them after the start of compression.
1.2672 +
1.2673 +If you are writing a PNG datastream that is to be embedded in a MNG
1.2674 +datastream, the second parameter can be either 0 or 64.
1.2675 +
1.2676 +The png_set_compression_*() functions interface to the zlib compression
1.2677 +library, and should mostly be ignored unless you really know what you are
1.2678 +doing. The only generally useful call is png_set_compression_level()
1.2679 +which changes how much time zlib spends on trying to compress the image
1.2680 +data. See the Compression Library (zlib.h and algorithm.txt, distributed
1.2681 +with zlib) for details on the compression levels.
1.2682 +
1.2683 + #include zlib.h
1.2684 +
1.2685 + /* Set the zlib compression level */
1.2686 + png_set_compression_level(png_ptr,
1.2687 + Z_BEST_COMPRESSION);
1.2688 +
1.2689 + /* Set other zlib parameters for compressing IDAT */
1.2690 + png_set_compression_mem_level(png_ptr, 8);
1.2691 + png_set_compression_strategy(png_ptr,
1.2692 + Z_DEFAULT_STRATEGY);
1.2693 + png_set_compression_window_bits(png_ptr, 15);
1.2694 + png_set_compression_method(png_ptr, 8);
1.2695 + png_set_compression_buffer_size(png_ptr, 8192)
1.2696 +
1.2697 + /* Set zlib parameters for text compression
1.2698 + * If you don't call these, the parameters
1.2699 + * fall back on those defined for IDAT chunks
1.2700 + */
1.2701 + png_set_text_compression_mem_level(png_ptr, 8);
1.2702 + png_set_text_compression_strategy(png_ptr,
1.2703 + Z_DEFAULT_STRATEGY);
1.2704 + png_set_text_compression_window_bits(png_ptr, 15);
1.2705 + png_set_text_compression_method(png_ptr, 8);
1.2706 +
1.2707 +Setting the contents of info for output
1.2708 +
1.2709 +You now need to fill in the png_info structure with all the data you
1.2710 +wish to write before the actual image. Note that the only thing you
1.2711 +are allowed to write after the image is the text chunks and the time
1.2712 +chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
1.2713 +the latest PNG specification for more information on that. If you
1.2714 +wish to write them before the image, fill them in now, and flag that
1.2715 +data as being valid. If you want to wait until after the data, don't
1.2716 +fill them until png_write_end(). For all the fields in png_info and
1.2717 +their data types, see png.h. For explanations of what the fields
1.2718 +contain, see the PNG specification.
1.2719 +
1.2720 +Some of the more important parts of the png_info are:
1.2721 +
1.2722 + png_set_IHDR(png_ptr, info_ptr, width, height,
1.2723 + bit_depth, color_type, interlace_type,
1.2724 + compression_type, filter_method)
1.2725 +
1.2726 + width - holds the width of the image
1.2727 + in pixels (up to 2^31).
1.2728 +
1.2729 + height - holds the height of the image
1.2730 + in pixels (up to 2^31).
1.2731 +
1.2732 + bit_depth - holds the bit depth of one of the
1.2733 + image channels.
1.2734 + (valid values are 1, 2, 4, 8, 16
1.2735 + and depend also on the
1.2736 + color_type. See also significant
1.2737 + bits (sBIT) below).
1.2738 +
1.2739 + color_type - describes which color/alpha
1.2740 + channels are present.
1.2741 + PNG_COLOR_TYPE_GRAY
1.2742 + (bit depths 1, 2, 4, 8, 16)
1.2743 + PNG_COLOR_TYPE_GRAY_ALPHA
1.2744 + (bit depths 8, 16)
1.2745 + PNG_COLOR_TYPE_PALETTE
1.2746 + (bit depths 1, 2, 4, 8)
1.2747 + PNG_COLOR_TYPE_RGB
1.2748 + (bit_depths 8, 16)
1.2749 + PNG_COLOR_TYPE_RGB_ALPHA
1.2750 + (bit_depths 8, 16)
1.2751 +
1.2752 + PNG_COLOR_MASK_PALETTE
1.2753 + PNG_COLOR_MASK_COLOR
1.2754 + PNG_COLOR_MASK_ALPHA
1.2755 +
1.2756 + interlace_type - PNG_INTERLACE_NONE or
1.2757 + PNG_INTERLACE_ADAM7
1.2758 +
1.2759 + compression_type - (must be
1.2760 + PNG_COMPRESSION_TYPE_DEFAULT)
1.2761 +
1.2762 + filter_method - (must be PNG_FILTER_TYPE_DEFAULT
1.2763 + or, if you are writing a PNG to
1.2764 + be embedded in a MNG datastream,
1.2765 + can also be
1.2766 + PNG_INTRAPIXEL_DIFFERENCING)
1.2767 +
1.2768 +If you call png_set_IHDR(), the call must appear before any of the
1.2769 +other png_set_*() functions, because they might require access to some of
1.2770 +the IHDR settings. The remaining png_set_*() functions can be called
1.2771 +in any order.
1.2772 +
1.2773 +If you wish, you can reset the compression_type, interlace_type, or
1.2774 +filter_method later by calling png_set_IHDR() again; if you do this, the
1.2775 +width, height, bit_depth, and color_type must be the same in each call.
1.2776 +
1.2777 + png_set_PLTE(png_ptr, info_ptr, palette,
1.2778 + num_palette);
1.2779 +
1.2780 + palette - the palette for the file
1.2781 + (array of png_color)
1.2782 + num_palette - number of entries in the palette
1.2783 +
1.2784 + png_set_gAMA(png_ptr, info_ptr, file_gamma);
1.2785 + png_set_gAMA_fixed(png_ptr, info_ptr, int_file_gamma);
1.2786 +
1.2787 + file_gamma - the gamma at which the image was
1.2788 + created (PNG_INFO_gAMA)
1.2789 +
1.2790 + int_file_gamma - 100,000 times the gamma at which
1.2791 + the image was created
1.2792 +
1.2793 + png_set_cHRM(png_ptr, info_ptr, white_x, white_y, red_x, red_y,
1.2794 + green_x, green_y, blue_x, blue_y)
1.2795 + png_set_cHRM_XYZ(png_ptr, info_ptr, red_X, red_Y, red_Z, green_X,
1.2796 + green_Y, green_Z, blue_X, blue_Y, blue_Z)
1.2797 + png_set_cHRM_fixed(png_ptr, info_ptr, int_white_x, int_white_y,
1.2798 + int_red_x, int_red_y, int_green_x, int_green_y,
1.2799 + int_blue_x, int_blue_y)
1.2800 + png_set_cHRM_XYZ_fixed(png_ptr, info_ptr, int_red_X, int_red_Y,
1.2801 + int_red_Z, int_green_X, int_green_Y, int_green_Z,
1.2802 + int_blue_X, int_blue_Y, int_blue_Z)
1.2803 +
1.2804 + {white,red,green,blue}_{x,y}
1.2805 + A color space encoding specified using the chromaticities
1.2806 + of the end points and the white point.
1.2807 +
1.2808 + {red,green,blue}_{X,Y,Z}
1.2809 + A color space encoding specified using the encoding end
1.2810 + points - the CIE tristimulus specification of the intended
1.2811 + color of the red, green and blue channels in the PNG RGB
1.2812 + data. The white point is simply the sum of the three end
1.2813 + points.
1.2814 +
1.2815 + png_set_sRGB(png_ptr, info_ptr, srgb_intent);
1.2816 +
1.2817 + srgb_intent - the rendering intent
1.2818 + (PNG_INFO_sRGB) The presence of
1.2819 + the sRGB chunk means that the pixel
1.2820 + data is in the sRGB color space.
1.2821 + This chunk also implies specific
1.2822 + values of gAMA and cHRM. Rendering
1.2823 + intent is the CSS-1 property that
1.2824 + has been defined by the International
1.2825 + Color Consortium
1.2826 + (http://www.color.org).
1.2827 + It can be one of
1.2828 + PNG_sRGB_INTENT_SATURATION,
1.2829 + PNG_sRGB_INTENT_PERCEPTUAL,
1.2830 + PNG_sRGB_INTENT_ABSOLUTE, or
1.2831 + PNG_sRGB_INTENT_RELATIVE.
1.2832 +
1.2833 +
1.2834 + png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
1.2835 + srgb_intent);
1.2836 +
1.2837 + srgb_intent - the rendering intent
1.2838 + (PNG_INFO_sRGB) The presence of the
1.2839 + sRGB chunk means that the pixel
1.2840 + data is in the sRGB color space.
1.2841 + This function also causes gAMA and
1.2842 + cHRM chunks with the specific values
1.2843 + that are consistent with sRGB to be
1.2844 + written.
1.2845 +
1.2846 + png_set_iCCP(png_ptr, info_ptr, name, compression_type,
1.2847 + profile, proflen);
1.2848 +
1.2849 + name - The profile name.
1.2850 +
1.2851 + compression_type - The compression type; always
1.2852 + PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1.2853 + You may give NULL to this argument to
1.2854 + ignore it.
1.2855 +
1.2856 + profile - International Color Consortium color
1.2857 + profile data. May contain NULs.
1.2858 +
1.2859 + proflen - length of profile data in bytes.
1.2860 +
1.2861 + png_set_sBIT(png_ptr, info_ptr, sig_bit);
1.2862 +
1.2863 + sig_bit - the number of significant bits for
1.2864 + (PNG_INFO_sBIT) each of the gray, red,
1.2865 + green, and blue channels, whichever are
1.2866 + appropriate for the given color type
1.2867 + (png_color_16)
1.2868 +
1.2869 + png_set_tRNS(png_ptr, info_ptr, trans_alpha,
1.2870 + num_trans, trans_color);
1.2871 +
1.2872 + trans_alpha - array of alpha (transparency)
1.2873 + entries for palette (PNG_INFO_tRNS)
1.2874 +
1.2875 + num_trans - number of transparent entries
1.2876 + (PNG_INFO_tRNS)
1.2877 +
1.2878 + trans_color - graylevel or color sample values
1.2879 + (in order red, green, blue) of the
1.2880 + single transparent color for
1.2881 + non-paletted images (PNG_INFO_tRNS)
1.2882 +
1.2883 + png_set_hIST(png_ptr, info_ptr, hist);
1.2884 +
1.2885 + hist - histogram of palette (array of
1.2886 + png_uint_16) (PNG_INFO_hIST)
1.2887 +
1.2888 + png_set_tIME(png_ptr, info_ptr, mod_time);
1.2889 +
1.2890 + mod_time - time image was last modified
1.2891 + (PNG_VALID_tIME)
1.2892 +
1.2893 + png_set_bKGD(png_ptr, info_ptr, background);
1.2894 +
1.2895 + background - background color (of type
1.2896 + png_color_16p) (PNG_VALID_bKGD)
1.2897 +
1.2898 + png_set_text(png_ptr, info_ptr, text_ptr, num_text);
1.2899 +
1.2900 + text_ptr - array of png_text holding image
1.2901 + comments
1.2902 +
1.2903 + text_ptr[i].compression - type of compression used
1.2904 + on "text" PNG_TEXT_COMPRESSION_NONE
1.2905 + PNG_TEXT_COMPRESSION_zTXt
1.2906 + PNG_ITXT_COMPRESSION_NONE
1.2907 + PNG_ITXT_COMPRESSION_zTXt
1.2908 + text_ptr[i].key - keyword for comment. Must contain
1.2909 + 1-79 characters.
1.2910 + text_ptr[i].text - text comments for current
1.2911 + keyword. Can be NULL or empty.
1.2912 + text_ptr[i].text_length - length of text string,
1.2913 + after decompression, 0 for iTXt
1.2914 + text_ptr[i].itxt_length - length of itxt string,
1.2915 + after decompression, 0 for tEXt/zTXt
1.2916 + text_ptr[i].lang - language of comment (NULL or
1.2917 + empty for unknown).
1.2918 + text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
1.2919 + or empty for unknown).
1.2920 +
1.2921 + Note that the itxt_length, lang, and lang_key
1.2922 + members of the text_ptr structure only exist when the
1.2923 + library is built with iTXt chunk support. Prior to
1.2924 + libpng-1.4.0 the library was built by default without
1.2925 + iTXt support. Also note that when iTXt is supported,
1.2926 + they contain NULL pointers when the "compression"
1.2927 + field contains PNG_TEXT_COMPRESSION_NONE or
1.2928 + PNG_TEXT_COMPRESSION_zTXt.
1.2929 +
1.2930 + num_text - number of comments
1.2931 +
1.2932 + png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
1.2933 + num_spalettes);
1.2934 +
1.2935 + palette_ptr - array of png_sPLT_struct structures
1.2936 + to be added to the list of palettes
1.2937 + in the info structure.
1.2938 + num_spalettes - number of palette structures to be
1.2939 + added.
1.2940 +
1.2941 + png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
1.2942 + unit_type);
1.2943 +
1.2944 + offset_x - positive offset from the left
1.2945 + edge of the screen
1.2946 +
1.2947 + offset_y - positive offset from the top
1.2948 + edge of the screen
1.2949 +
1.2950 + unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1.2951 +
1.2952 + png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
1.2953 + unit_type);
1.2954 +
1.2955 + res_x - pixels/unit physical resolution
1.2956 + in x direction
1.2957 +
1.2958 + res_y - pixels/unit physical resolution
1.2959 + in y direction
1.2960 +
1.2961 + unit_type - PNG_RESOLUTION_UNKNOWN,
1.2962 + PNG_RESOLUTION_METER
1.2963 +
1.2964 + png_set_sCAL(png_ptr, info_ptr, unit, width, height)
1.2965 +
1.2966 + unit - physical scale units (an integer)
1.2967 +
1.2968 + width - width of a pixel in physical scale units
1.2969 +
1.2970 + height - height of a pixel in physical scale units
1.2971 + (width and height are doubles)
1.2972 +
1.2973 + png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
1.2974 +
1.2975 + unit - physical scale units (an integer)
1.2976 +
1.2977 + width - width of a pixel in physical scale units
1.2978 + expressed as a string
1.2979 +
1.2980 + height - height of a pixel in physical scale units
1.2981 + (width and height are strings like "2.54")
1.2982 +
1.2983 + png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
1.2984 + num_unknowns)
1.2985 +
1.2986 + unknowns - array of png_unknown_chunk
1.2987 + structures holding unknown chunks
1.2988 + unknowns[i].name - name of unknown chunk
1.2989 + unknowns[i].data - data of unknown chunk
1.2990 + unknowns[i].size - size of unknown chunk's data
1.2991 + unknowns[i].location - position to write chunk in file
1.2992 + 0: do not write chunk
1.2993 + PNG_HAVE_IHDR: before PLTE
1.2994 + PNG_HAVE_PLTE: before IDAT
1.2995 + PNG_AFTER_IDAT: after IDAT
1.2996 +
1.2997 +The "location" member is set automatically according to
1.2998 +what part of the output file has already been written.
1.2999 +You can change its value after calling png_set_unknown_chunks()
1.3000 +as demonstrated in pngtest.c. Within each of the "locations",
1.3001 +the chunks are sequenced according to their position in the
1.3002 +structure (that is, the value of "i", which is the order in which
1.3003 +the chunk was either read from the input file or defined with
1.3004 +png_set_unknown_chunks).
1.3005 +
1.3006 +A quick word about text and num_text. text is an array of png_text
1.3007 +structures. num_text is the number of valid structures in the array.
1.3008 +Each png_text structure holds a language code, a keyword, a text value,
1.3009 +and a compression type.
1.3010 +
1.3011 +The compression types have the same valid numbers as the compression
1.3012 +types of the image data. Currently, the only valid number is zero.
1.3013 +However, you can store text either compressed or uncompressed, unlike
1.3014 +images, which always have to be compressed. So if you don't want the
1.3015 +text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
1.3016 +Because tEXt and zTXt chunks don't have a language field, if you
1.3017 +specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
1.3018 +any language code or translated keyword will not be written out.
1.3019 +
1.3020 +Until text gets around a few hundred bytes, it is not worth compressing it.
1.3021 +After the text has been written out to the file, the compression type
1.3022 +is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
1.3023 +so that it isn't written out again at the end (in case you are calling
1.3024 +png_write_end() with the same struct).
1.3025 +
1.3026 +The keywords that are given in the PNG Specification are:
1.3027 +
1.3028 + Title Short (one line) title or
1.3029 + caption for image
1.3030 +
1.3031 + Author Name of image's creator
1.3032 +
1.3033 + Description Description of image (possibly long)
1.3034 +
1.3035 + Copyright Copyright notice
1.3036 +
1.3037 + Creation Time Time of original image creation
1.3038 + (usually RFC 1123 format, see below)
1.3039 +
1.3040 + Software Software used to create the image
1.3041 +
1.3042 + Disclaimer Legal disclaimer
1.3043 +
1.3044 + Warning Warning of nature of content
1.3045 +
1.3046 + Source Device used to create the image
1.3047 +
1.3048 + Comment Miscellaneous comment; conversion
1.3049 + from other image format
1.3050 +
1.3051 +The keyword-text pairs work like this. Keywords should be short
1.3052 +simple descriptions of what the comment is about. Some typical
1.3053 +keywords are found in the PNG specification, as is some recommendations
1.3054 +on keywords. You can repeat keywords in a file. You can even write
1.3055 +some text before the image and some after. For example, you may want
1.3056 +to put a description of the image before the image, but leave the
1.3057 +disclaimer until after, so viewers working over modem connections
1.3058 +don't have to wait for the disclaimer to go over the modem before
1.3059 +they start seeing the image. Finally, keywords should be full
1.3060 +words, not abbreviations. Keywords and text are in the ISO 8859-1
1.3061 +(Latin-1) character set (a superset of regular ASCII) and can not
1.3062 +contain NUL characters, and should not contain control or other
1.3063 +unprintable characters. To make the comments widely readable, stick
1.3064 +with basic ASCII, and avoid machine specific character set extensions
1.3065 +like the IBM-PC character set. The keyword must be present, but
1.3066 +you can leave off the text string on non-compressed pairs.
1.3067 +Compressed pairs must have a text string, as only the text string
1.3068 +is compressed anyway, so the compression would be meaningless.
1.3069 +
1.3070 +PNG supports modification time via the png_time structure. Two
1.3071 +conversion routines are provided, png_convert_from_time_t() for
1.3072 +time_t and png_convert_from_struct_tm() for struct tm. The
1.3073 +time_t routine uses gmtime(). You don't have to use either of
1.3074 +these, but if you wish to fill in the png_time structure directly,
1.3075 +you should provide the time in universal time (GMT) if possible
1.3076 +instead of your local time. Note that the year number is the full
1.3077 +year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
1.3078 +that months start with 1.
1.3079 +
1.3080 +If you want to store the time of the original image creation, you should
1.3081 +use a plain tEXt chunk with the "Creation Time" keyword. This is
1.3082 +necessary because the "creation time" of a PNG image is somewhat vague,
1.3083 +depending on whether you mean the PNG file, the time the image was
1.3084 +created in a non-PNG format, a still photo from which the image was
1.3085 +scanned, or possibly the subject matter itself. In order to facilitate
1.3086 +machine-readable dates, it is recommended that the "Creation Time"
1.3087 +tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
1.3088 +although this isn't a requirement. Unlike the tIME chunk, the
1.3089 +"Creation Time" tEXt chunk is not expected to be automatically changed
1.3090 +by the software. To facilitate the use of RFC 1123 dates, a function
1.3091 +png_convert_to_rfc1123_buffer(png_ptr, buffer, png_timep) is provided to
1.3092 +convert from PNG time to an RFC 1123 format string. The caller must provide
1.3093 +a writeable buffer of at least 29 bytes.
1.3094 +
1.3095 +Writing unknown chunks
1.3096 +
1.3097 +You can use the png_set_unknown_chunks function to queue up private chunks
1.3098 +for writing. You give it a chunk name, location, raw data, and a size. You
1.3099 +also must use png_set_keep_unknown_chunks() to ensure that libpng will
1.3100 +handle them. That's all there is to it. The chunks will be written by the
1.3101 +next following png_write_info_before_PLTE, png_write_info, or png_write_end
1.3102 +function, depending upon the specified location. Any chunks previously
1.3103 +read into the info structure's unknown-chunk list will also be written out
1.3104 +in a sequence that satisfies the PNG specification's ordering rules.
1.3105 +
1.3106 +Here is an example of writing two private chunks, prVt and miNE:
1.3107 +
1.3108 + #ifdef PNG_WRITE_UNKNOWN_CHUNKS_SUPPORTED
1.3109 + /* Set unknown chunk data */
1.3110 + png_unknown_chunk unk_chunk[2];
1.3111 + strcpy((char *) unk_chunk[0].name, "prVt";
1.3112 + unk_chunk[0].data = (unsigned char *) "PRIVATE DATA";
1.3113 + unk_chunk[0].size = strlen(unk_chunk[0].data)+1;
1.3114 + unk_chunk[0].location = PNG_HAVE_IHDR;
1.3115 + strcpy((char *) unk_chunk[1].name, "miNE";
1.3116 + unk_chunk[1].data = (unsigned char *) "MY CHUNK DATA";
1.3117 + unk_chunk[1].size = strlen(unk_chunk[0].data)+1;
1.3118 + unk_chunk[1].location = PNG_AFTER_IDAT;
1.3119 + png_set_unknown_chunks(write_ptr, write_info_ptr,
1.3120 + unk_chunk, 2);
1.3121 + /* Needed because miNE is not safe-to-copy */
1.3122 + png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS,
1.3123 + (png_bytep) "miNE", 1);
1.3124 + # if PNG_LIBPNG_VER < 10600
1.3125 + /* Deal with unknown chunk location bug in 1.5.x and earlier */
1.3126 + png_set_unknown_chunk_location(png, info, 0, PNG_HAVE_IHDR);
1.3127 + png_set_unknown_chunk_location(png, info, 1, PNG_AFTER_IDAT);
1.3128 + # endif
1.3129 + # if PNG_LIBPNG_VER < 10500
1.3130 + /* PNG_AFTER_IDAT writes two copies of the chunk prior to libpng-1.5.0,
1.3131 + * one before IDAT and another after IDAT, so don't use it; only use
1.3132 + * PNG_HAVE_IHDR location. This call resets the location previously
1.3133 + * set by assignment and png_set_unknown_chunk_location() for chunk 1.
1.3134 + */
1.3135 + png_set_unknown_chunk_location(png, info, 1, PNG_HAVE_IHDR);
1.3136 + # endif
1.3137 + #endif
1.3138 +
1.3139 +The high-level write interface
1.3140 +
1.3141 +At this point there are two ways to proceed; through the high-level
1.3142 +write interface, or through a sequence of low-level write operations.
1.3143 +You can use the high-level interface if your image data is present
1.3144 +in the info structure. All defined output
1.3145 +transformations are permitted, enabled by the following masks.
1.3146 +
1.3147 + PNG_TRANSFORM_IDENTITY No transformation
1.3148 + PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
1.3149 + PNG_TRANSFORM_PACKSWAP Change order of packed
1.3150 + pixels to LSB first
1.3151 + PNG_TRANSFORM_INVERT_MONO Invert monochrome images
1.3152 + PNG_TRANSFORM_SHIFT Normalize pixels to the
1.3153 + sBIT depth
1.3154 + PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
1.3155 + to BGRA
1.3156 + PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
1.3157 + to AG
1.3158 + PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
1.3159 + to transparency
1.3160 + PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
1.3161 + PNG_TRANSFORM_STRIP_FILLER Strip out filler
1.3162 + bytes (deprecated).
1.3163 + PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
1.3164 + filler bytes
1.3165 + PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing
1.3166 + filler bytes
1.3167 +
1.3168 +If you have valid image data in the info structure (you can use
1.3169 +png_set_rows() to put image data in the info structure), simply do this:
1.3170 +
1.3171 + png_write_png(png_ptr, info_ptr, png_transforms, NULL)
1.3172 +
1.3173 +where png_transforms is an integer containing the bitwise OR of some set of
1.3174 +transformation flags. This call is equivalent to png_write_info(),
1.3175 +followed the set of transformations indicated by the transform mask,
1.3176 +then png_write_image(), and finally png_write_end().
1.3177 +
1.3178 +(The final parameter of this call is not yet used. Someday it might point
1.3179 +to transformation parameters required by some future output transform.)
1.3180 +
1.3181 +You must use png_transforms and not call any png_set_transform() functions
1.3182 +when you use png_write_png().
1.3183 +
1.3184 +The low-level write interface
1.3185 +
1.3186 +If you are going the low-level route instead, you are now ready to
1.3187 +write all the file information up to the actual image data. You do
1.3188 +this with a call to png_write_info().
1.3189 +
1.3190 + png_write_info(png_ptr, info_ptr);
1.3191 +
1.3192 +Note that there is one transformation you may need to do before
1.3193 +png_write_info(). In PNG files, the alpha channel in an image is the
1.3194 +level of opacity. If your data is supplied as a level of transparency,
1.3195 +you can invert the alpha channel before you write it, so that 0 is
1.3196 +fully transparent and 255 (in 8-bit or paletted images) or 65535
1.3197 +(in 16-bit images) is fully opaque, with
1.3198 +
1.3199 + png_set_invert_alpha(png_ptr);
1.3200 +
1.3201 +This must appear before png_write_info() instead of later with the
1.3202 +other transformations because in the case of paletted images the tRNS
1.3203 +chunk data has to be inverted before the tRNS chunk is written. If
1.3204 +your image is not a paletted image, the tRNS data (which in such cases
1.3205 +represents a single color to be rendered as transparent) won't need to
1.3206 +be changed, and you can safely do this transformation after your
1.3207 +png_write_info() call.
1.3208 +
1.3209 +If you need to write a private chunk that you want to appear before
1.3210 +the PLTE chunk when PLTE is present, you can write the PNG info in
1.3211 +two steps, and insert code to write your own chunk between them:
1.3212 +
1.3213 + png_write_info_before_PLTE(png_ptr, info_ptr);
1.3214 + png_set_unknown_chunks(png_ptr, info_ptr, ...);
1.3215 + png_write_info(png_ptr, info_ptr);
1.3216 +
1.3217 +After you've written the file information, you can set up the library
1.3218 +to handle any special transformations of the image data. The various
1.3219 +ways to transform the data will be described in the order that they
1.3220 +should occur. This is important, as some of these change the color
1.3221 +type and/or bit depth of the data, and some others only work on
1.3222 +certain color types and bit depths. Even though each transformation
1.3223 +checks to see if it has data that it can do something with, you should
1.3224 +make sure to only enable a transformation if it will be valid for the
1.3225 +data. For example, don't swap red and blue on grayscale data.
1.3226 +
1.3227 +PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
1.3228 +the library to strip input data that has 4 or 8 bytes per pixel down
1.3229 +to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
1.3230 +bytes per pixel).
1.3231 +
1.3232 + png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
1.3233 +
1.3234 +where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
1.3235 +PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
1.3236 +is stored XRGB or RGBX.
1.3237 +
1.3238 +PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1.3239 +they can, resulting in, for example, 8 pixels per byte for 1 bit files.
1.3240 +If the data is supplied at 1 pixel per byte, use this code, which will
1.3241 +correctly pack the pixels into a single byte:
1.3242 +
1.3243 + png_set_packing(png_ptr);
1.3244 +
1.3245 +PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
1.3246 +data is of another bit depth, you can write an sBIT chunk into the
1.3247 +file so that decoders can recover the original data if desired.
1.3248 +
1.3249 + /* Set the true bit depth of the image data */
1.3250 + if (color_type & PNG_COLOR_MASK_COLOR)
1.3251 + {
1.3252 + sig_bit.red = true_bit_depth;
1.3253 + sig_bit.green = true_bit_depth;
1.3254 + sig_bit.blue = true_bit_depth;
1.3255 + }
1.3256 +
1.3257 + else
1.3258 + {
1.3259 + sig_bit.gray = true_bit_depth;
1.3260 + }
1.3261 +
1.3262 + if (color_type & PNG_COLOR_MASK_ALPHA)
1.3263 + {
1.3264 + sig_bit.alpha = true_bit_depth;
1.3265 + }
1.3266 +
1.3267 + png_set_sBIT(png_ptr, info_ptr, &sig_bit);
1.3268 +
1.3269 +If the data is stored in the row buffer in a bit depth other than
1.3270 +one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
1.3271 +this will scale the values to appear to be the correct bit depth as
1.3272 +is required by PNG.
1.3273 +
1.3274 + png_set_shift(png_ptr, &sig_bit);
1.3275 +
1.3276 +PNG files store 16-bit pixels in network byte order (big-endian,
1.3277 +ie. most significant bits first). This code would be used if they are
1.3278 +supplied the other way (little-endian, i.e. least significant bits
1.3279 +first, the way PCs store them):
1.3280 +
1.3281 + if (bit_depth > 8)
1.3282 + png_set_swap(png_ptr);
1.3283 +
1.3284 +If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1.3285 +need to change the order the pixels are packed into bytes, you can use:
1.3286 +
1.3287 + if (bit_depth < 8)
1.3288 + png_set_packswap(png_ptr);
1.3289 +
1.3290 +PNG files store 3 color pixels in red, green, blue order. This code
1.3291 +would be used if they are supplied as blue, green, red:
1.3292 +
1.3293 + png_set_bgr(png_ptr);
1.3294 +
1.3295 +PNG files describe monochrome as black being zero and white being
1.3296 +one. This code would be used if the pixels are supplied with this reversed
1.3297 +(black being one and white being zero):
1.3298 +
1.3299 + png_set_invert_mono(png_ptr);
1.3300 +
1.3301 +Finally, you can write your own transformation function if none of
1.3302 +the existing ones meets your needs. This is done by setting a callback
1.3303 +with
1.3304 +
1.3305 + png_set_write_user_transform_fn(png_ptr,
1.3306 + write_transform_fn);
1.3307 +
1.3308 +You must supply the function
1.3309 +
1.3310 + void write_transform_fn(png_structp png_ptr, png_row_infop
1.3311 + row_info, png_bytep data)
1.3312 +
1.3313 +See pngtest.c for a working example. Your function will be called
1.3314 +before any of the other transformations are processed. If supported
1.3315 +libpng also supplies an information routine that may be called from
1.3316 +your callback:
1.3317 +
1.3318 + png_get_current_row_number(png_ptr);
1.3319 + png_get_current_pass_number(png_ptr);
1.3320 +
1.3321 +This returns the current row passed to the transform. With interlaced
1.3322 +images the value returned is the row in the input sub-image image. Use
1.3323 +PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
1.3324 +find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
1.3325 +
1.3326 +The discussion of interlace handling above contains more information on how to
1.3327 +use these values.
1.3328 +
1.3329 +You can also set up a pointer to a user structure for use by your
1.3330 +callback function.
1.3331 +
1.3332 + png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
1.3333 +
1.3334 +The user_channels and user_depth parameters of this function are ignored
1.3335 +when writing; you can set them to zero as shown.
1.3336 +
1.3337 +You can retrieve the pointer via the function png_get_user_transform_ptr().
1.3338 +For example:
1.3339 +
1.3340 + voidp write_user_transform_ptr =
1.3341 + png_get_user_transform_ptr(png_ptr);
1.3342 +
1.3343 +It is possible to have libpng flush any pending output, either manually,
1.3344 +or automatically after a certain number of lines have been written. To
1.3345 +flush the output stream a single time call:
1.3346 +
1.3347 + png_write_flush(png_ptr);
1.3348 +
1.3349 +and to have libpng flush the output stream periodically after a certain
1.3350 +number of scanlines have been written, call:
1.3351 +
1.3352 + png_set_flush(png_ptr, nrows);
1.3353 +
1.3354 +Note that the distance between rows is from the last time png_write_flush()
1.3355 +was called, or the first row of the image if it has never been called.
1.3356 +So if you write 50 lines, and then png_set_flush 25, it will flush the
1.3357 +output on the next scanline, and every 25 lines thereafter, unless
1.3358 +png_write_flush() is called before 25 more lines have been written.
1.3359 +If nrows is too small (less than about 10 lines for a 640 pixel wide
1.3360 +RGB image) the image compression may decrease noticeably (although this
1.3361 +may be acceptable for real-time applications). Infrequent flushing will
1.3362 +only degrade the compression performance by a few percent over images
1.3363 +that do not use flushing.
1.3364 +
1.3365 +Writing the image data
1.3366 +
1.3367 +That's it for the transformations. Now you can write the image data.
1.3368 +The simplest way to do this is in one function call. If you have the
1.3369 +whole image in memory, you can just call png_write_image() and libpng
1.3370 +will write the image. You will need to pass in an array of pointers to
1.3371 +each row. This function automatically handles interlacing, so you don't
1.3372 +need to call png_set_interlace_handling() or call this function multiple
1.3373 +times, or any of that other stuff necessary with png_write_rows().
1.3374 +
1.3375 + png_write_image(png_ptr, row_pointers);
1.3376 +
1.3377 +where row_pointers is:
1.3378 +
1.3379 + png_byte *row_pointers[height];
1.3380 +
1.3381 +You can point to void or char or whatever you use for pixels.
1.3382 +
1.3383 +If you don't want to write the whole image at once, you can
1.3384 +use png_write_rows() instead. If the file is not interlaced,
1.3385 +this is simple:
1.3386 +
1.3387 + png_write_rows(png_ptr, row_pointers,
1.3388 + number_of_rows);
1.3389 +
1.3390 +row_pointers is the same as in the png_write_image() call.
1.3391 +
1.3392 +If you are just writing one row at a time, you can do this with
1.3393 +a single row_pointer instead of an array of row_pointers:
1.3394 +
1.3395 + png_bytep row_pointer = row;
1.3396 +
1.3397 + png_write_row(png_ptr, row_pointer);
1.3398 +
1.3399 +When the file is interlaced, things can get a good deal more complicated.
1.3400 +The only currently (as of the PNG Specification version 1.2, dated July
1.3401 +1999) defined interlacing scheme for PNG files is the "Adam7" interlace
1.3402 +scheme, that breaks down an image into seven smaller images of varying
1.3403 +size. libpng will build these images for you, or you can do them
1.3404 +yourself. If you want to build them yourself, see the PNG specification
1.3405 +for details of which pixels to write when.
1.3406 +
1.3407 +If you don't want libpng to handle the interlacing details, just
1.3408 +use png_set_interlace_handling() and call png_write_rows() the
1.3409 +correct number of times to write all the sub-images
1.3410 +(png_set_interlace_handling() returns the number of sub-images.)
1.3411 +
1.3412 +If you want libpng to build the sub-images, call this before you start
1.3413 +writing any rows:
1.3414 +
1.3415 + number_of_passes = png_set_interlace_handling(png_ptr);
1.3416 +
1.3417 +This will return the number of passes needed. Currently, this is seven,
1.3418 +but may change if another interlace type is added.
1.3419 +
1.3420 +Then write the complete image number_of_passes times.
1.3421 +
1.3422 + png_write_rows(png_ptr, row_pointers, number_of_rows);
1.3423 +
1.3424 +Think carefully before you write an interlaced image. Typically code that
1.3425 +reads such images reads all the image data into memory, uncompressed, before
1.3426 +doing any processing. Only code that can display an image on the fly can
1.3427 +take advantage of the interlacing and even then the image has to be exactly
1.3428 +the correct size for the output device, because scaling an image requires
1.3429 +adjacent pixels and these are not available until all the passes have been
1.3430 +read.
1.3431 +
1.3432 +If you do write an interlaced image you will hardly ever need to handle
1.3433 +the interlacing yourself. Call png_set_interlace_handling() and use the
1.3434 +approach described above.
1.3435 +
1.3436 +The only time it is conceivable that you will really need to write an
1.3437 +interlaced image pass-by-pass is when you have read one pass by pass and
1.3438 +made some pixel-by-pixel transformation to it, as described in the read
1.3439 +code above. In this case use the PNG_PASS_ROWS and PNG_PASS_COLS macros
1.3440 +to determine the size of each sub-image in turn and simply write the rows
1.3441 +you obtained from the read code.
1.3442 +
1.3443 +Finishing a sequential write
1.3444 +
1.3445 +After you are finished writing the image, you should finish writing
1.3446 +the file. If you are interested in writing comments or time, you should
1.3447 +pass an appropriately filled png_info pointer. If you are not interested,
1.3448 +you can pass NULL.
1.3449 +
1.3450 + png_write_end(png_ptr, info_ptr);
1.3451 +
1.3452 +When you are done, you can free all memory used by libpng like this:
1.3453 +
1.3454 + png_destroy_write_struct(&png_ptr, &info_ptr);
1.3455 +
1.3456 +It is also possible to individually free the info_ptr members that
1.3457 +point to libpng-allocated storage with the following function:
1.3458 +
1.3459 + png_free_data(png_ptr, info_ptr, mask, seq)
1.3460 +
1.3461 + mask - identifies data to be freed, a mask
1.3462 + containing the bitwise OR of one or
1.3463 + more of
1.3464 + PNG_FREE_PLTE, PNG_FREE_TRNS,
1.3465 + PNG_FREE_HIST, PNG_FREE_ICCP,
1.3466 + PNG_FREE_PCAL, PNG_FREE_ROWS,
1.3467 + PNG_FREE_SCAL, PNG_FREE_SPLT,
1.3468 + PNG_FREE_TEXT, PNG_FREE_UNKN,
1.3469 + or simply PNG_FREE_ALL
1.3470 +
1.3471 + seq - sequence number of item to be freed
1.3472 + (-1 for all items)
1.3473 +
1.3474 +This function may be safely called when the relevant storage has
1.3475 +already been freed, or has not yet been allocated, or was allocated
1.3476 +by the user and not by libpng, and will in those cases do nothing.
1.3477 +The "seq" parameter is ignored if only one item of the selected data
1.3478 +type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
1.3479 +are allowed for the data type identified in the mask, such as text or
1.3480 +sPLT, only the n'th item in the structure is freed, where n is "seq".
1.3481 +
1.3482 +If you allocated data such as a palette that you passed in to libpng
1.3483 +with png_set_*, you must not free it until just before the call to
1.3484 +png_destroy_write_struct().
1.3485 +
1.3486 +The default behavior is only to free data that was allocated internally
1.3487 +by libpng. This can be changed, so that libpng will not free the data,
1.3488 +or so that it will free data that was allocated by the user with png_malloc()
1.3489 +or png_calloc() and passed in via a png_set_*() function, with
1.3490 +
1.3491 + png_data_freer(png_ptr, info_ptr, freer, mask)
1.3492 +
1.3493 + freer - one of
1.3494 + PNG_DESTROY_WILL_FREE_DATA
1.3495 + PNG_SET_WILL_FREE_DATA
1.3496 + PNG_USER_WILL_FREE_DATA
1.3497 +
1.3498 + mask - which data elements are affected
1.3499 + same choices as in png_free_data()
1.3500 +
1.3501 +For example, to transfer responsibility for some data from a read structure
1.3502 +to a write structure, you could use
1.3503 +
1.3504 + png_data_freer(read_ptr, read_info_ptr,
1.3505 + PNG_USER_WILL_FREE_DATA,
1.3506 + PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
1.3507 +
1.3508 + png_data_freer(write_ptr, write_info_ptr,
1.3509 + PNG_DESTROY_WILL_FREE_DATA,
1.3510 + PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
1.3511 +
1.3512 +thereby briefly reassigning responsibility for freeing to the user but
1.3513 +immediately afterwards reassigning it once more to the write_destroy
1.3514 +function. Having done this, it would then be safe to destroy the read
1.3515 +structure and continue to use the PLTE, tRNS, and hIST data in the write
1.3516 +structure.
1.3517 +
1.3518 +This function only affects data that has already been allocated.
1.3519 +You can call this function before calling after the png_set_*() functions
1.3520 +to control whether the user or png_destroy_*() is supposed to free the data.
1.3521 +When the user assumes responsibility for libpng-allocated data, the
1.3522 +application must use
1.3523 +png_free() to free it, and when the user transfers responsibility to libpng
1.3524 +for data that the user has allocated, the user must have used png_malloc()
1.3525 +or png_calloc() to allocate it.
1.3526 +
1.3527 +If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
1.3528 +separately, do not transfer responsibility for freeing text_ptr to libpng,
1.3529 +because when libpng fills a png_text structure it combines these members with
1.3530 +the key member, and png_free_data() will free only text_ptr.key. Similarly,
1.3531 +if you transfer responsibility for free'ing text_ptr from libpng to your
1.3532 +application, your application must not separately free those members.
1.3533 +For a more compact example of writing a PNG image, see the file example.c.
1.3534 +
1.3535 +V. Simplified API
1.3536 +
1.3537 +The simplified API, which became available in libpng-1.6.0, hides the details
1.3538 +of both libpng and the PNG file format itself.
1.3539 +It allows PNG files to be read into a very limited number of
1.3540 +in-memory bitmap formats or to be written from the same formats. If these
1.3541 +formats do not accommodate your needs then you can, and should, use the more
1.3542 +sophisticated APIs above - these support a wide variety of in-memory formats
1.3543 +and a wide variety of sophisticated transformations to those formats as well
1.3544 +as a wide variety of APIs to manipulate ancilliary information.
1.3545 +
1.3546 +To read a PNG file using the simplified API:
1.3547 +
1.3548 + 1) Declare a 'png_image' structure (see below) on the
1.3549 + stack and memset() it to all zero.
1.3550 +
1.3551 + 2) Call the appropriate png_image_begin_read... function.
1.3552 +
1.3553 + 3) Set the png_image 'format' member to the required
1.3554 + format and allocate a buffer for the image.
1.3555 +
1.3556 + 4) Call png_image_finish_read to read the image into
1.3557 + your buffer.
1.3558 +
1.3559 +There are no restrictions on the format of the PNG input itself; all valid
1.3560 +color types, bit depths, and interlace methods are acceptable, and the
1.3561 +input image is transformed as necessary to the requested in-memory format
1.3562 +during the png_image_finish_read() step.
1.3563 +
1.3564 +To write a PNG file using the simplified API:
1.3565 +
1.3566 + 1) Declare a 'png_image' structure on the stack and memset()
1.3567 + it to all zero.
1.3568 +
1.3569 + 2) Initialize the members of the structure that describe the
1.3570 + image, setting the 'format' member to the format of the
1.3571 + image in memory.
1.3572 +
1.3573 + 3) Call the appropriate png_image_write... function with a
1.3574 + pointer to the image to write the PNG data.
1.3575 +
1.3576 +png_image is a structure that describes the in-memory format of an image
1.3577 +when it is being read or define the in-memory format of an image that you
1.3578 +need to write. The "png_image" structure contains the following members:
1.3579 +
1.3580 + png_uint_32 version Set to PNG_IMAGE_VERSION
1.3581 + png_uint_32 width Image width in pixels (columns)
1.3582 + png_uint_32 height Image height in pixels (rows)
1.3583 + png_uint_32 format Image format as defined below
1.3584 + png_uint_32 flags A bit mask containing informational flags
1.3585 + png_controlp opaque Initialize to NULL, free with png_image_free
1.3586 + png_uint_32 colormap_entries; Number of entries in the color-map
1.3587 + png_uint_32 warning_or_error;
1.3588 + char message[64];
1.3589 +
1.3590 +In the event of an error or warning the following field warning_or_error
1.3591 +field will be set to a non-zero value and the 'message' field will contain
1.3592 +a '\0' terminated string with the libpng error or warning message. If both
1.3593 +warnings and an error were encountered, only the error is recorded. If there
1.3594 +are multiple warnings, only the first one is recorded.
1.3595 +
1.3596 +The upper 30 bits of this value are reserved; the low two bits contain
1.3597 +a two bit code such that a value more than 1 indicates a failure in the API
1.3598 +just called:
1.3599 +
1.3600 + 0 - no warning or error
1.3601 + 1 - warning
1.3602 + 2 - error
1.3603 + 3 - error preceded by warning
1.3604 +
1.3605 +The pixels (samples) of the image have one to four channels whose components
1.3606 +have original values in the range 0 to 1.0:
1.3607 +
1.3608 + 1: A single gray or luminance channel (G).
1.3609 + 2: A gray/luminance channel and an alpha channel (GA).
1.3610 + 3: Three red, green, blue color channels (RGB).
1.3611 + 4: Three color channels and an alpha channel (RGBA).
1.3612 +
1.3613 +The channels are encoded in one of two ways:
1.3614 +
1.3615 + a) As a small integer, value 0..255, contained in a single byte. For the
1.3616 +alpha channel the original value is simply value/255. For the color or
1.3617 +luminance channels the value is encoded according to the sRGB specification
1.3618 +and matches the 8-bit format expected by typical display devices.
1.3619 +
1.3620 +The color/gray channels are not scaled (pre-multiplied) by the alpha
1.3621 +channel and are suitable for passing to color management software.
1.3622 +
1.3623 + b) As a value in the range 0..65535, contained in a 2-byte integer. All
1.3624 +channels can be converted to the original value by dividing by 65535; all
1.3625 +channels are linear. Color channels use the RGB encoding (RGB end-points) of
1.3626 +the sRGB specification. This encoding is identified by the
1.3627 +PNG_FORMAT_FLAG_LINEAR flag below.
1.3628 +
1.3629 +When an alpha channel is present it is expected to denote pixel coverage
1.3630 +of the color or luminance channels and is returned as an associated alpha
1.3631 +channel: the color/gray channels are scaled (pre-multiplied) by the alpha
1.3632 +value.
1.3633 +
1.3634 +When a color-mapped image is used as a result of calling
1.3635 +png_image_read_colormap or png_image_write_colormap the channels are encoded
1.3636 +in the color-map and the descriptions above apply to the color-map entries.
1.3637 +The image data is encoded as small integers, value 0..255, that index the
1.3638 +entries in the color-map. One integer (one byte) is stored for each pixel.
1.3639 +
1.3640 +PNG_FORMAT_*
1.3641 +
1.3642 +The #defines to be used in png_image::format. Each #define identifies a
1.3643 +particular layout of channel data and, if present, alpha values. There are
1.3644 +separate defines for each of the two channel encodings.
1.3645 +
1.3646 +A format is built up using single bit flag values. Not all combinations are
1.3647 +valid: use the bit flag values below for testing a format returned by the
1.3648 +read APIs, but set formats from the derived values.
1.3649 +
1.3650 +When reading or writing color-mapped images the format should be set to the
1.3651 +format of the entries in the color-map then png_image_{read,write}_colormap
1.3652 +called to read or write the color-map and set the format correctly for the
1.3653 +image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!
1.3654 +
1.3655 +NOTE: libpng can be built with particular features disabled, if you see
1.3656 +compiler errors because the definition of one of the following flags has been
1.3657 +compiled out it is because libpng does not have the required support. It is
1.3658 +possible, however, for the libpng configuration to enable the format on just
1.3659 +read or just write; in that case you may see an error at run time. You can
1.3660 +guard against this by checking for the definition of:
1.3661 +
1.3662 + PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED
1.3663 +
1.3664 + PNG_FORMAT_FLAG_ALPHA 0x01 format with an alpha channel
1.3665 + PNG_FORMAT_FLAG_COLOR 0x02 color format: otherwise grayscale
1.3666 + PNG_FORMAT_FLAG_LINEAR 0x04 png_uint_16 channels else png_byte
1.3667 + PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only
1.3668 + PNG_FORMAT_FLAG_BGR 0x10 BGR colors, else order is RGB
1.3669 + PNG_FORMAT_FLAG_AFIRST 0x20 alpha channel comes first
1.3670 +
1.3671 +Supported formats are as follows. Future versions of libpng may support more
1.3672 +formats; for compatibility with older versions simply check if the format
1.3673 +macro is defined using #ifdef. These defines describe the in-memory layout
1.3674 +of the components of the pixels of the image.
1.3675 +
1.3676 +First the single byte formats:
1.3677 +
1.3678 + PNG_FORMAT_GRAY 0
1.3679 + PNG_FORMAT_GA PNG_FORMAT_FLAG_ALPHA
1.3680 + PNG_FORMAT_AG (PNG_FORMAT_GA|PNG_FORMAT_FLAG_AFIRST)
1.3681 + PNG_FORMAT_RGB PNG_FORMAT_FLAG_COLOR
1.3682 + PNG_FORMAT_BGR (PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_BGR)
1.3683 + PNG_FORMAT_RGBA (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_ALPHA)
1.3684 + PNG_FORMAT_ARGB (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_AFIRST)
1.3685 + PNG_FORMAT_BGRA (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_ALPHA)
1.3686 + PNG_FORMAT_ABGR (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_AFIRST)
1.3687 +
1.3688 +Then the linear 2-byte formats. When naming these "Y" is used to
1.3689 +indicate a luminance (gray) channel. The component order within the pixel
1.3690 +is always the same - there is no provision for swapping the order of the
1.3691 +components in the linear format.
1.3692 +
1.3693 + PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR
1.3694 + PNG_FORMAT_LINEAR_Y_ALPHA
1.3695 + (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_ALPHA)
1.3696 + PNG_FORMAT_LINEAR_RGB
1.3697 + (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR)
1.3698 + PNG_FORMAT_LINEAR_RGB_ALPHA
1.3699 + (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR|
1.3700 + PNG_FORMAT_FLAG_ALPHA)
1.3701 +
1.3702 +Color-mapped formats are obtained by calling png_image_{read,write}_colormap,
1.3703 +as appropriate after setting png_image::format to the format of the color-map
1.3704 +to be read or written. Applications may check the value of
1.3705 +PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API. The
1.3706 +format of the color-map may be extracted using the following macro.
1.3707 +
1.3708 + PNG_FORMAT_OF_COLORMAP(fmt) ((fmt) & ~PNG_FORMAT_FLAG_COLORMAP)
1.3709 +
1.3710 +PNG_IMAGE macros
1.3711 +
1.3712 +These are convenience macros to derive information from a png_image
1.3713 +structure. The PNG_IMAGE_SAMPLE_ macros return values appropriate to the
1.3714 +actual image sample values - either the entries in the color-map or the
1.3715 +pixels in the image. The PNG_IMAGE_PIXEL_ macros return corresponding values
1.3716 +for the pixels and will always return 1 after a call to
1.3717 +png_image_{read,write}_colormap. The remaining macros return information
1.3718 +about the rows in the image and the complete image.
1.3719 +
1.3720 +NOTE: All the macros that take a png_image::format parameter are compile time
1.3721 +constants if the format parameter is, itself, a constant. Therefore these
1.3722 +macros can be used in array declarations and case labels where required.
1.3723 +Similarly the macros are also pre-processor constants (sizeof is not used) so
1.3724 +they can be used in #if tests.
1.3725 +
1.3726 +First the information about the samples.
1.3727 +
1.3728 + PNG_IMAGE_SAMPLE_CHANNELS(fmt)
1.3729 + Returns the total number of channels in a given format: 1..4
1.3730 +
1.3731 + PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)
1.3732 + Returns the size in bytes of a single component of a pixel or color-map
1.3733 + entry (as appropriate) in the image.
1.3734 +
1.3735 + PNG_IMAGE_SAMPLE_SIZE(fmt)
1.3736 + This is the size of the sample data for one sample. If the image is
1.3737 + color-mapped it is the size of one color-map entry (and image pixels are
1.3738 + one byte in size), otherwise it is the size of one image pixel.
1.3739 +
1.3740 + PNG_IMAGE_COLORMAP_SIZE(fmt)
1.3741 + The size of the color-map required by the format; this is the size of the
1.3742 + color-map buffer passed to the png_image_{read,write}_colormap APIs, it is
1.3743 + a fixed number determined by the format so can easily be allocated on the
1.3744 + stack if necessary.
1.3745 +
1.3746 +#define PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)\
1.3747 + (PNG_IMAGE_SAMPLE_CHANNELS(fmt) * 256)
1.3748 + /* The maximum size of the color-map required by the format expressed in a
1.3749 + * count of components. This can be used to compile-time allocate a
1.3750 + * color-map:
1.3751 + *
1.3752 + * png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
1.3753 + *
1.3754 + * png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
1.3755 + *
1.3756 + * Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
1.3757 + * information from one of the png_image_begin_read_ APIs and dynamically
1.3758 + * allocate the required memory.
1.3759 + */
1.3760 +
1.3761 +
1.3762 +Corresponding information about the pixels
1.3763 +
1.3764 + PNG_IMAGE_PIXEL_(test,fmt)
1.3765 +
1.3766 + PNG_IMAGE_PIXEL_CHANNELS(fmt)
1.3767 + The number of separate channels (components) in a pixel; 1 for a
1.3768 + color-mapped image.
1.3769 +
1.3770 + PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
1.3771 + The size, in bytes, of each component in a pixel; 1 for a color-mapped
1.3772 + image.
1.3773 +
1.3774 + PNG_IMAGE_PIXEL_SIZE(fmt)
1.3775 + The size, in bytes, of a complete pixel; 1 for a color-mapped image.
1.3776 +
1.3777 +Information about the whole row, or whole image
1.3778 +
1.3779 + PNG_IMAGE_ROW_STRIDE(image)
1.3780 + Returns the total number of components in a single row of the image; this
1.3781 + is the minimum 'row stride', the minimum count of components between each
1.3782 + row. For a color-mapped image this is the minimum number of bytes in a
1.3783 + row.
1.3784 +
1.3785 + PNG_IMAGE_BUFFER_SIZE(image, row_stride)
1.3786 + Returns the size, in bytes, of an image buffer given a png_image and a row
1.3787 + stride - the number of components to leave space for in each row.
1.3788 +
1.3789 + PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
1.3790 + This indicates the the RGB values of the in-memory bitmap do not
1.3791 + correspond to the red, green and blue end-points defined by sRGB.
1.3792 +
1.3793 + PNG_IMAGE_FLAG_COLORMAP == 0x02
1.3794 + The PNG is color-mapped. If this flag is set png_image_read_colormap
1.3795 + can be used without further loss of image information. If it is not set
1.3796 + png_image_read_colormap will cause significant loss if the image has any
1.3797 +
1.3798 +READ APIs
1.3799 +
1.3800 + The png_image passed to the read APIs must have been initialized by setting
1.3801 + the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.)
1.3802 +
1.3803 + int png_image_begin_read_from_file( png_imagep image,
1.3804 + const char *file_name)
1.3805 +
1.3806 + The named file is opened for read and the image header
1.3807 + is filled in from the PNG header in the file.
1.3808 +
1.3809 + int png_image_begin_read_from_stdio (png_imagep image,
1.3810 + FILE* file)
1.3811 +
1.3812 + The PNG header is read from the stdio FILE object.
1.3813 +
1.3814 + int png_image_begin_read_from_memory(png_imagep image,
1.3815 + png_const_voidp memory, png_size_t size)
1.3816 +
1.3817 + The PNG header is read from the given memory buffer.
1.3818 +
1.3819 + int png_image_finish_read(png_imagep image,
1.3820 + png_colorp background, void *buffer,
1.3821 + png_int_32 row_stride, void *colormap));
1.3822 +
1.3823 + Finish reading the image into the supplied buffer and
1.3824 + clean up the png_image structure.
1.3825 +
1.3826 + row_stride is the step, in png_byte or png_uint_16 units
1.3827 + as appropriate, between adjacent rows. A positive stride
1.3828 + indicates that the top-most row is first in the buffer -
1.3829 + the normal top-down arrangement. A negative stride
1.3830 + indicates that the bottom-most row is first in the buffer.
1.3831 +
1.3832 + background need only be supplied if an alpha channel must
1.3833 + be removed from a png_byte format and the removal is to be
1.3834 + done by compositing on a solid color; otherwise it may be
1.3835 + NULL and any composition will be done directly onto the
1.3836 + buffer. The value is an sRGB color to use for the
1.3837 + background, for grayscale output the green channel is used.
1.3838 +
1.3839 + For linear output removing the alpha channel is always done
1.3840 + by compositing on black.
1.3841 +
1.3842 + void png_image_free(png_imagep image)
1.3843 +
1.3844 + Free any data allocated by libpng in image->opaque,
1.3845 + setting the pointer to NULL. May be called at any time
1.3846 + after the structure is initialized.
1.3847 +
1.3848 +When the simplified API needs to convert between sRGB and linear colorspaces,
1.3849 +the actual sRGB transfer curve defined in the sRGB specification (see the
1.3850 +article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
1.3851 +approximation used elsewhere in libpng.
1.3852 +
1.3853 +WRITE APIS
1.3854 +
1.3855 +For write you must initialize a png_image structure to describe the image to
1.3856 +be written:
1.3857 +
1.3858 + version: must be set to PNG_IMAGE_VERSION
1.3859 + opaque: must be initialized to NULL
1.3860 + width: image width in pixels
1.3861 + height: image height in rows
1.3862 + format: the format of the data you wish to write
1.3863 + flags: set to 0 unless one of the defined flags applies; set
1.3864 + PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images
1.3865 + where the RGB values do not correspond to the colors in sRGB.
1.3866 + colormap_entries: set to the number of entries in the color-map (0 to 256)
1.3867 +
1.3868 + int png_image_write_to_file, (png_imagep image,
1.3869 + const char *file, int convert_to_8bit, const void *buffer,
1.3870 + png_int_32 row_stride, const void *colormap));
1.3871 +
1.3872 + Write the image to the named file.
1.3873 +
1.3874 + int png_image_write_to_stdio(png_imagep image, FILE *file,
1.3875 + int convert_to_8_bit, const void *buffer,
1.3876 + png_int_32 row_stride, const void *colormap)
1.3877 +
1.3878 + Write the image to the given (FILE*).
1.3879 +
1.3880 +With all write APIs if image is in one of the linear formats with
1.3881 +(png_uint_16) data then setting convert_to_8_bit will cause the output to be
1.3882 +a (png_byte) PNG gamma encoded according to the sRGB specification, otherwise
1.3883 +a 16-bit linear encoded PNG file is written.
1.3884 +
1.3885 +With all APIs row_stride is handled as in the read APIs - it is the spacing
1.3886 +from one row to the next in component sized units (float) and if negative
1.3887 +indicates a bottom-up row layout in the buffer.
1.3888 +
1.3889 +Note that the write API does not support interlacing, sub-8-bit pixels,
1.3890 +and indexed (paletted) images.
1.3891 +
1.3892 +VI. Modifying/Customizing libpng
1.3893 +
1.3894 +There are two issues here. The first is changing how libpng does
1.3895 +standard things like memory allocation, input/output, and error handling.
1.3896 +The second deals with more complicated things like adding new chunks,
1.3897 +adding new transformations, and generally changing how libpng works.
1.3898 +Both of those are compile-time issues; that is, they are generally
1.3899 +determined at the time the code is written, and there is rarely a need
1.3900 +to provide the user with a means of changing them.
1.3901 +
1.3902 +Memory allocation, input/output, and error handling
1.3903 +
1.3904 +All of the memory allocation, input/output, and error handling in libpng
1.3905 +goes through callbacks that are user-settable. The default routines are
1.3906 +in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
1.3907 +these functions, call the appropriate png_set_*_fn() function.
1.3908 +
1.3909 +Memory allocation is done through the functions png_malloc(), png_calloc(),
1.3910 +and png_free(). The png_malloc() and png_free() functions currently just
1.3911 +call the standard C functions and png_calloc() calls png_malloc() and then
1.3912 +clears the newly allocated memory to zero; note that png_calloc(png_ptr, size)
1.3913 +is not the same as the calloc(number, size) function provided by stdlib.h.
1.3914 +There is limited support for certain systems with segmented memory
1.3915 +architectures and the types of pointers declared by png.h match this; you
1.3916 +will have to use appropriate pointers in your application. Since it is
1.3917 +unlikely that the method of handling memory allocation on a platform
1.3918 +will change between applications, these functions must be modified in
1.3919 +the library at compile time. If you prefer to use a different method
1.3920 +of allocating and freeing data, you can use png_create_read_struct_2() or
1.3921 +png_create_write_struct_2() to register your own functions as described
1.3922 +above. These functions also provide a void pointer that can be retrieved
1.3923 +via
1.3924 +
1.3925 + mem_ptr=png_get_mem_ptr(png_ptr);
1.3926 +
1.3927 +Your replacement memory functions must have prototypes as follows:
1.3928 +
1.3929 + png_voidp malloc_fn(png_structp png_ptr,
1.3930 + png_alloc_size_t size);
1.3931 +
1.3932 + void free_fn(png_structp png_ptr, png_voidp ptr);
1.3933 +
1.3934 +Your malloc_fn() must return NULL in case of failure. The png_malloc()
1.3935 +function will normally call png_error() if it receives a NULL from the
1.3936 +system memory allocator or from your replacement malloc_fn().
1.3937 +
1.3938 +Your free_fn() will never be called with a NULL ptr, since libpng's
1.3939 +png_free() checks for NULL before calling free_fn().
1.3940 +
1.3941 +Input/Output in libpng is done through png_read() and png_write(),
1.3942 +which currently just call fread() and fwrite(). The FILE * is stored in
1.3943 +png_struct and is initialized via png_init_io(). If you wish to change
1.3944 +the method of I/O, the library supplies callbacks that you can set
1.3945 +through the function png_set_read_fn() and png_set_write_fn() at run
1.3946 +time, instead of calling the png_init_io() function. These functions
1.3947 +also provide a void pointer that can be retrieved via the function
1.3948 +png_get_io_ptr(). For example:
1.3949 +
1.3950 + png_set_read_fn(png_structp read_ptr,
1.3951 + voidp read_io_ptr, png_rw_ptr read_data_fn)
1.3952 +
1.3953 + png_set_write_fn(png_structp write_ptr,
1.3954 + voidp write_io_ptr, png_rw_ptr write_data_fn,
1.3955 + png_flush_ptr output_flush_fn);
1.3956 +
1.3957 + voidp read_io_ptr = png_get_io_ptr(read_ptr);
1.3958 + voidp write_io_ptr = png_get_io_ptr(write_ptr);
1.3959 +
1.3960 +The replacement I/O functions must have prototypes as follows:
1.3961 +
1.3962 + void user_read_data(png_structp png_ptr,
1.3963 + png_bytep data, png_size_t length);
1.3964 +
1.3965 + void user_write_data(png_structp png_ptr,
1.3966 + png_bytep data, png_size_t length);
1.3967 +
1.3968 + void user_flush_data(png_structp png_ptr);
1.3969 +
1.3970 +The user_read_data() function is responsible for detecting and
1.3971 +handling end-of-data errors.
1.3972 +
1.3973 +Supplying NULL for the read, write, or flush functions sets them back
1.3974 +to using the default C stream functions, which expect the io_ptr to
1.3975 +point to a standard *FILE structure. It is probably a mistake
1.3976 +to use NULL for one of write_data_fn and output_flush_fn but not both
1.3977 +of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
1.3978 +It is an error to read from a write stream, and vice versa.
1.3979 +
1.3980 +Error handling in libpng is done through png_error() and png_warning().
1.3981 +Errors handled through png_error() are fatal, meaning that png_error()
1.3982 +should never return to its caller. Currently, this is handled via
1.3983 +setjmp() and longjmp() (unless you have compiled libpng with
1.3984 +PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
1.3985 +but you could change this to do things like exit() if you should wish,
1.3986 +as long as your function does not return.
1.3987 +
1.3988 +On non-fatal errors, png_warning() is called
1.3989 +to print a warning message, and then control returns to the calling code.
1.3990 +By default png_error() and png_warning() print a message on stderr via
1.3991 +fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
1.3992 +(because you don't want the messages) or PNG_NO_STDIO defined (because
1.3993 +fprintf() isn't available). If you wish to change the behavior of the error
1.3994 +functions, you will need to set up your own message callbacks. These
1.3995 +functions are normally supplied at the time that the png_struct is created.
1.3996 +It is also possible to redirect errors and warnings to your own replacement
1.3997 +functions after png_create_*_struct() has been called by calling:
1.3998 +
1.3999 + png_set_error_fn(png_structp png_ptr,
1.4000 + png_voidp error_ptr, png_error_ptr error_fn,
1.4001 + png_error_ptr warning_fn);
1.4002 +
1.4003 + png_voidp error_ptr = png_get_error_ptr(png_ptr);
1.4004 +
1.4005 +If NULL is supplied for either error_fn or warning_fn, then the libpng
1.4006 +default function will be used, calling fprintf() and/or longjmp() if a
1.4007 +problem is encountered. The replacement error functions should have
1.4008 +parameters as follows:
1.4009 +
1.4010 + void user_error_fn(png_structp png_ptr,
1.4011 + png_const_charp error_msg);
1.4012 +
1.4013 + void user_warning_fn(png_structp png_ptr,
1.4014 + png_const_charp warning_msg);
1.4015 +
1.4016 +The motivation behind using setjmp() and longjmp() is the C++ throw and
1.4017 +catch exception handling methods. This makes the code much easier to write,
1.4018 +as there is no need to check every return code of every function call.
1.4019 +However, there are some uncertainties about the status of local variables
1.4020 +after a longjmp, so the user may want to be careful about doing anything
1.4021 +after setjmp returns non-zero besides returning itself. Consult your
1.4022 +compiler documentation for more details. For an alternative approach, you
1.4023 +may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net),
1.4024 +which is illustrated in pngvalid.c and in contrib/visupng.
1.4025 +
1.4026 +Beginning in libpng-1.4.0, the png_set_benign_errors() API became available.
1.4027 +You can use this to handle certain errors (normally handled as errors)
1.4028 +as warnings.
1.4029 +
1.4030 + png_set_benign_errors (png_ptr, int allowed);
1.4031 +
1.4032 + allowed: 0: treat png_benign_error() as an error.
1.4033 + 1: treat png_benign_error() as a warning.
1.4034 +
1.4035 +As of libpng-1.6.0, the default condition is to treat benign errors as
1.4036 +warnings while reading and as errors while writing.
1.4037 +
1.4038 +Custom chunks
1.4039 +
1.4040 +If you need to read or write custom chunks, you may need to get deeper
1.4041 +into the libpng code. The library now has mechanisms for storing
1.4042 +and writing chunks of unknown type; you can even declare callbacks
1.4043 +for custom chunks. However, this may not be good enough if the
1.4044 +library code itself needs to know about interactions between your
1.4045 +chunk and existing `intrinsic' chunks.
1.4046 +
1.4047 +If you need to write a new intrinsic chunk, first read the PNG
1.4048 +specification. Acquire a first level of understanding of how it works.
1.4049 +Pay particular attention to the sections that describe chunk names,
1.4050 +and look at how other chunks were designed, so you can do things
1.4051 +similarly. Second, check out the sections of libpng that read and
1.4052 +write chunks. Try to find a chunk that is similar to yours and use
1.4053 +it as a template. More details can be found in the comments inside
1.4054 +the code. It is best to handle private or unknown chunks in a generic method,
1.4055 +via callback functions, instead of by modifying libpng functions. This
1.4056 +is illustrated in pngtest.c, which uses a callback function to handle a
1.4057 +private "vpAg" chunk and the new "sTER" chunk, which are both unknown to
1.4058 +libpng.
1.4059 +
1.4060 +If you wish to write your own transformation for the data, look through
1.4061 +the part of the code that does the transformations, and check out some of
1.4062 +the simpler ones to get an idea of how they work. Try to find a similar
1.4063 +transformation to the one you want to add and copy off of it. More details
1.4064 +can be found in the comments inside the code itself.
1.4065 +
1.4066 +Configuring for 16-bit platforms
1.4067 +
1.4068 +You will want to look into zconf.h to tell zlib (and thus libpng) that
1.4069 +it cannot allocate more then 64K at a time. Even if you can, the memory
1.4070 +won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
1.4071 +
1.4072 +Configuring for DOS
1.4073 +
1.4074 +For DOS users who only have access to the lower 640K, you will
1.4075 +have to limit zlib's memory usage via a png_set_compression_mem_level()
1.4076 +call. See zlib.h or zconf.h in the zlib library for more information.
1.4077 +
1.4078 +Configuring for Medium Model
1.4079 +
1.4080 +Libpng's support for medium model has been tested on most of the popular
1.4081 +compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
1.4082 +defined, and FAR gets defined to far in pngconf.h, and you should be
1.4083 +all set. Everything in the library (except for zlib's structure) is
1.4084 +expecting far data. You must use the typedefs with the p or pp on
1.4085 +the end for pointers (or at least look at them and be careful). Make
1.4086 +note that the rows of data are defined as png_bytepp, which is
1.4087 +an "unsigned char far * far *".
1.4088 +
1.4089 +Configuring for gui/windowing platforms:
1.4090 +
1.4091 +You will need to write new error and warning functions that use the GUI
1.4092 +interface, as described previously, and set them to be the error and
1.4093 +warning functions at the time that png_create_*_struct() is called,
1.4094 +in order to have them available during the structure initialization.
1.4095 +They can be changed later via png_set_error_fn(). On some compilers,
1.4096 +you may also have to change the memory allocators (png_malloc, etc.).
1.4097 +
1.4098 +Configuring for compiler xxx:
1.4099 +
1.4100 +All includes for libpng are in pngconf.h. If you need to add, change
1.4101 +or delete an include, this is the place to do it.
1.4102 +The includes that are not needed outside libpng are placed in pngpriv.h,
1.4103 +which is only used by the routines inside libpng itself.
1.4104 +The files in libpng proper only include pngpriv.h and png.h, which
1.4105 +in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
1.4106 +As of libpng-1.5.0, pngpriv.h also includes three other private header
1.4107 +files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
1.4108 +that previously appeared in the public headers.
1.4109 +
1.4110 +Configuring zlib:
1.4111 +
1.4112 +There are special functions to configure the compression. Perhaps the
1.4113 +most useful one changes the compression level, which currently uses
1.4114 +input compression values in the range 0 - 9. The library normally
1.4115 +uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
1.4116 +have shown that for a large majority of images, compression values in
1.4117 +the range 3-6 compress nearly as well as higher levels, and do so much
1.4118 +faster. For online applications it may be desirable to have maximum speed
1.4119 +(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
1.4120 +specify no compression (Z_NO_COMPRESSION = 0), but this would create
1.4121 +files larger than just storing the raw bitmap. You can specify the
1.4122 +compression level by calling:
1.4123 +
1.4124 + #include zlib.h
1.4125 + png_set_compression_level(png_ptr, level);
1.4126 +
1.4127 +Another useful one is to reduce the memory level used by the library.
1.4128 +The memory level defaults to 8, but it can be lowered if you are
1.4129 +short on memory (running DOS, for example, where you only have 640K).
1.4130 +Note that the memory level does have an effect on compression; among
1.4131 +other things, lower levels will result in sections of incompressible
1.4132 +data being emitted in smaller stored blocks, with a correspondingly
1.4133 +larger relative overhead of up to 15% in the worst case.
1.4134 +
1.4135 + #include zlib.h
1.4136 + png_set_compression_mem_level(png_ptr, level);
1.4137 +
1.4138 +The other functions are for configuring zlib. They are not recommended
1.4139 +for normal use and may result in writing an invalid PNG file. See
1.4140 +zlib.h for more information on what these mean.
1.4141 +
1.4142 + #include zlib.h
1.4143 + png_set_compression_strategy(png_ptr,
1.4144 + strategy);
1.4145 +
1.4146 + png_set_compression_window_bits(png_ptr,
1.4147 + window_bits);
1.4148 +
1.4149 + png_set_compression_method(png_ptr, method);
1.4150 +
1.4151 + png_set_compression_buffer_size(png_ptr, size);
1.4152 +
1.4153 +As of libpng version 1.5.4, additional APIs became
1.4154 +available to set these separately for non-IDAT
1.4155 +compressed chunks such as zTXt, iTXt, and iCCP:
1.4156 +
1.4157 + #include zlib.h
1.4158 + #if PNG_LIBPNG_VER >= 10504
1.4159 + png_set_text_compression_level(png_ptr, level);
1.4160 +
1.4161 + png_set_text_compression_mem_level(png_ptr, level);
1.4162 +
1.4163 + png_set_text_compression_strategy(png_ptr,
1.4164 + strategy);
1.4165 +
1.4166 + png_set_text_compression_window_bits(png_ptr,
1.4167 + window_bits);
1.4168 +
1.4169 + png_set_text_compression_method(png_ptr, method);
1.4170 + #endif
1.4171 +
1.4172 +Controlling row filtering
1.4173 +
1.4174 +If you want to control whether libpng uses filtering or not, which
1.4175 +filters are used, and how it goes about picking row filters, you
1.4176 +can call one of these functions. The selection and configuration
1.4177 +of row filters can have a significant impact on the size and
1.4178 +encoding speed and a somewhat lesser impact on the decoding speed
1.4179 +of an image. Filtering is enabled by default for RGB and grayscale
1.4180 +images (with and without alpha), but not for paletted images nor
1.4181 +for any images with bit depths less than 8 bits/pixel.
1.4182 +
1.4183 +The 'method' parameter sets the main filtering method, which is
1.4184 +currently only '0' in the PNG 1.2 specification. The 'filters'
1.4185 +parameter sets which filter(s), if any, should be used for each
1.4186 +scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
1.4187 +to turn filtering on and off, respectively.
1.4188 +
1.4189 +Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
1.4190 +PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
1.4191 +ORed together with '|' to specify one or more filters to use.
1.4192 +These filters are described in more detail in the PNG specification.
1.4193 +If you intend to change the filter type during the course of writing
1.4194 +the image, you should start with flags set for all of the filters
1.4195 +you intend to use so that libpng can initialize its internal
1.4196 +structures appropriately for all of the filter types. (Note that this
1.4197 +means the first row must always be adaptively filtered, because libpng
1.4198 +currently does not allocate the filter buffers until png_write_row()
1.4199 +is called for the first time.)
1.4200 +
1.4201 + filters = PNG_FILTER_NONE | PNG_FILTER_SUB
1.4202 + PNG_FILTER_UP | PNG_FILTER_AVG |
1.4203 + PNG_FILTER_PAETH | PNG_ALL_FILTERS;
1.4204 +
1.4205 + png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
1.4206 + filters);
1.4207 + The second parameter can also be
1.4208 + PNG_INTRAPIXEL_DIFFERENCING if you are
1.4209 + writing a PNG to be embedded in a MNG
1.4210 + datastream. This parameter must be the
1.4211 + same as the value of filter_method used
1.4212 + in png_set_IHDR().
1.4213 +
1.4214 +It is also possible to influence how libpng chooses from among the
1.4215 +available filters. This is done in one or both of two ways - by
1.4216 +telling it how important it is to keep the same filter for successive
1.4217 +rows, and by telling it the relative computational costs of the filters.
1.4218 +
1.4219 + double weights[3] = {1.5, 1.3, 1.1},
1.4220 + costs[PNG_FILTER_VALUE_LAST] =
1.4221 + {1.0, 1.3, 1.3, 1.5, 1.7};
1.4222 +
1.4223 + png_set_filter_heuristics(png_ptr,
1.4224 + PNG_FILTER_HEURISTIC_WEIGHTED, 3,
1.4225 + weights, costs);
1.4226 +
1.4227 +The weights are multiplying factors that indicate to libpng that the
1.4228 +row filter should be the same for successive rows unless another row filter
1.4229 +is that many times better than the previous filter. In the above example,
1.4230 +if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
1.4231 +"sum of absolute differences" 1.5 x 1.3 times higher than other filters
1.4232 +and still be chosen, while the NONE filter could have a sum 1.1 times
1.4233 +higher than other filters and still be chosen. Unspecified weights are
1.4234 +taken to be 1.0, and the specified weights should probably be declining
1.4235 +like those above in order to emphasize recent filters over older filters.
1.4236 +
1.4237 +The filter costs specify for each filter type a relative decoding cost
1.4238 +to be considered when selecting row filters. This means that filters
1.4239 +with higher costs are less likely to be chosen over filters with lower
1.4240 +costs, unless their "sum of absolute differences" is that much smaller.
1.4241 +The costs do not necessarily reflect the exact computational speeds of
1.4242 +the various filters, since this would unduly influence the final image
1.4243 +size.
1.4244 +
1.4245 +Note that the numbers above were invented purely for this example and
1.4246 +are given only to help explain the function usage. Little testing has
1.4247 +been done to find optimum values for either the costs or the weights.
1.4248 +
1.4249 +Removing unwanted object code
1.4250 +
1.4251 +There are a bunch of #define's in pngconf.h that control what parts of
1.4252 +libpng are compiled. All the defines end in _SUPPORTED. If you are
1.4253 +never going to use a capability, you can change the #define to #undef
1.4254 +before recompiling libpng and save yourself code and data space, or
1.4255 +you can turn off individual capabilities with defines that begin with
1.4256 +PNG_NO_.
1.4257 +
1.4258 +In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
1.4259 +
1.4260 +You can also turn all of the transforms and ancillary chunk capabilities
1.4261 +off en masse with compiler directives that define
1.4262 +PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
1.4263 +or all four,
1.4264 +along with directives to turn on any of the capabilities that you do
1.4265 +want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
1.4266 +transformations but still leave the library fully capable of reading
1.4267 +and writing PNG files with all known public chunks. Use of the
1.4268 +PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
1.4269 +that is incapable of reading or writing ancillary chunks. If you are
1.4270 +not using the progressive reading capability, you can turn that off
1.4271 +with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
1.4272 +capability, which you'll still have).
1.4273 +
1.4274 +All the reading and writing specific code are in separate files, so the
1.4275 +linker should only grab the files it needs. However, if you want to
1.4276 +make sure, or if you are building a stand alone library, all the
1.4277 +reading files start with "pngr" and all the writing files start with "pngw".
1.4278 +The files that don't match either (like png.c, pngtrans.c, etc.)
1.4279 +are used for both reading and writing, and always need to be included.
1.4280 +The progressive reader is in pngpread.c
1.4281 +
1.4282 +If you are creating or distributing a dynamically linked library (a .so
1.4283 +or DLL file), you should not remove or disable any parts of the library,
1.4284 +as this will cause applications linked with different versions of the
1.4285 +library to fail if they call functions not available in your library.
1.4286 +The size of the library itself should not be an issue, because only
1.4287 +those sections that are actually used will be loaded into memory.
1.4288 +
1.4289 +Requesting debug printout
1.4290 +
1.4291 +The macro definition PNG_DEBUG can be used to request debugging
1.4292 +printout. Set it to an integer value in the range 0 to 3. Higher
1.4293 +numbers result in increasing amounts of debugging information. The
1.4294 +information is printed to the "stderr" file, unless another file
1.4295 +name is specified in the PNG_DEBUG_FILE macro definition.
1.4296 +
1.4297 +When PNG_DEBUG > 0, the following functions (macros) become available:
1.4298 +
1.4299 + png_debug(level, message)
1.4300 + png_debug1(level, message, p1)
1.4301 + png_debug2(level, message, p1, p2)
1.4302 +
1.4303 +in which "level" is compared to PNG_DEBUG to decide whether to print
1.4304 +the message, "message" is the formatted string to be printed,
1.4305 +and p1 and p2 are parameters that are to be embedded in the string
1.4306 +according to printf-style formatting directives. For example,
1.4307 +
1.4308 + png_debug1(2, "foo=%d", foo);
1.4309 +
1.4310 +is expanded to
1.4311 +
1.4312 + if (PNG_DEBUG > 2)
1.4313 + fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
1.4314 +
1.4315 +When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
1.4316 +can still use PNG_DEBUG to control your own debugging:
1.4317 +
1.4318 + #ifdef PNG_DEBUG
1.4319 + fprintf(stderr, ...
1.4320 + #endif
1.4321 +
1.4322 +When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
1.4323 +having level = 0 will be printed. There aren't any such statements in
1.4324 +this version of libpng, but if you insert some they will be printed.
1.4325 +
1.4326 +Prepending a prefix to exported symbols
1.4327 +
1.4328 +Starting with libpng-1.6.0, you can configure libpng (when using the
1.4329 +"configure" script) to prefix all exported symbols by means of the
1.4330 +configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
1.4331 +string beginning with a letter and containing only uppercase
1.4332 +and lowercase letters, digits, and the underscore (i.e., a C language
1.4333 +identifier). This creates a set of macros in pnglibconf.h, so this is
1.4334 +transparent to applications; their function calls get transformed by
1.4335 +the macros to use the modified names.
1.4336 +
1.4337 +VII. MNG support
1.4338 +
1.4339 +The MNG specification (available at http://www.libpng.org/pub/mng) allows
1.4340 +certain extensions to PNG for PNG images that are embedded in MNG datastreams.
1.4341 +Libpng can support some of these extensions. To enable them, use the
1.4342 +png_permit_mng_features() function:
1.4343 +
1.4344 + feature_set = png_permit_mng_features(png_ptr, mask)
1.4345 +
1.4346 + mask is a png_uint_32 containing the bitwise OR of the
1.4347 + features you want to enable. These include
1.4348 + PNG_FLAG_MNG_EMPTY_PLTE
1.4349 + PNG_FLAG_MNG_FILTER_64
1.4350 + PNG_ALL_MNG_FEATURES
1.4351 +
1.4352 + feature_set is a png_uint_32 that is the bitwise AND of
1.4353 + your mask with the set of MNG features that is
1.4354 + supported by the version of libpng that you are using.
1.4355 +
1.4356 +It is an error to use this function when reading or writing a standalone
1.4357 +PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
1.4358 +in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
1.4359 +and the MHDR and MEND chunks. Libpng does not provide support for these
1.4360 +or any other MNG chunks; your application must provide its own support for
1.4361 +them. You may wish to consider using libmng (available at
1.4362 +http://www.libmng.com) instead.
1.4363 +
1.4364 +VIII. Changes to Libpng from version 0.88
1.4365 +
1.4366 +It should be noted that versions of libpng later than 0.96 are not
1.4367 +distributed by the original libpng author, Guy Schalnat, nor by
1.4368 +Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
1.4369 +distributed versions 0.89 through 0.96, but rather by another member
1.4370 +of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
1.4371 +still alive and well, but they have moved on to other things.
1.4372 +
1.4373 +The old libpng functions png_read_init(), png_write_init(),
1.4374 +png_info_init(), png_read_destroy(), and png_write_destroy() have been
1.4375 +moved to PNG_INTERNAL in version 0.95 to discourage their use. These
1.4376 +functions will be removed from libpng version 1.4.0.
1.4377 +
1.4378 +The preferred method of creating and initializing the libpng structures is
1.4379 +via the png_create_read_struct(), png_create_write_struct(), and
1.4380 +png_create_info_struct() because they isolate the size of the structures
1.4381 +from the application, allow version error checking, and also allow the
1.4382 +use of custom error handling routines during the initialization, which
1.4383 +the old functions do not. The functions png_read_destroy() and
1.4384 +png_write_destroy() do not actually free the memory that libpng
1.4385 +allocated for these structs, but just reset the data structures, so they
1.4386 +can be used instead of png_destroy_read_struct() and
1.4387 +png_destroy_write_struct() if you feel there is too much system overhead
1.4388 +allocating and freeing the png_struct for each image read.
1.4389 +
1.4390 +Setting the error callbacks via png_set_message_fn() before
1.4391 +png_read_init() as was suggested in libpng-0.88 is no longer supported
1.4392 +because this caused applications that do not use custom error functions
1.4393 +to fail if the png_ptr was not initialized to zero. It is still possible
1.4394 +to set the error callbacks AFTER png_read_init(), or to change them with
1.4395 +png_set_error_fn(), which is essentially the same function, but with a new
1.4396 +name to force compilation errors with applications that try to use the old
1.4397 +method.
1.4398 +
1.4399 +Support for the sCAL, iCCP, iTXt, and sPLT chunks was added at libpng-1.0.6;
1.4400 +however, iTXt support was not enabled by default.
1.4401 +
1.4402 +Starting with version 1.0.7, you can find out which version of the library
1.4403 +you are using at run-time:
1.4404 +
1.4405 + png_uint_32 libpng_vn = png_access_version_number();
1.4406 +
1.4407 +The number libpng_vn is constructed from the major version, minor
1.4408 +version with leading zero, and release number with leading zero,
1.4409 +(e.g., libpng_vn for version 1.0.7 is 10007).
1.4410 +
1.4411 +Note that this function does not take a png_ptr, so you can call it
1.4412 +before you've created one.
1.4413 +
1.4414 +You can also check which version of png.h you used when compiling your
1.4415 +application:
1.4416 +
1.4417 + png_uint_32 application_vn = PNG_LIBPNG_VER;
1.4418 +
1.4419 +IX. Changes to Libpng from version 1.0.x to 1.2.x
1.4420 +
1.4421 +Support for user memory management was enabled by default. To
1.4422 +accomplish this, the functions png_create_read_struct_2(),
1.4423 +png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
1.4424 +png_malloc_default(), and png_free_default() were added.
1.4425 +
1.4426 +Support for the iTXt chunk has been enabled by default as of
1.4427 +version 1.2.41.
1.4428 +
1.4429 +Support for certain MNG features was enabled.
1.4430 +
1.4431 +Support for numbered error messages was added. However, we never got
1.4432 +around to actually numbering the error messages. The function
1.4433 +png_set_strip_error_numbers() was added (Note: the prototype for this
1.4434 +function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
1.4435 +builds of libpng-1.2.15. It was restored in libpng-1.2.36).
1.4436 +
1.4437 +The png_malloc_warn() function was added at libpng-1.2.3. This issues
1.4438 +a png_warning and returns NULL instead of aborting when it fails to
1.4439 +acquire the requested memory allocation.
1.4440 +
1.4441 +Support for setting user limits on image width and height was enabled
1.4442 +by default. The functions png_set_user_limits(), png_get_user_width_max(),
1.4443 +and png_get_user_height_max() were added at libpng-1.2.6.
1.4444 +
1.4445 +The png_set_add_alpha() function was added at libpng-1.2.7.
1.4446 +
1.4447 +The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
1.4448 +Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
1.4449 +tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
1.4450 +deprecated.
1.4451 +
1.4452 +A number of macro definitions in support of runtime selection of
1.4453 +assembler code features (especially Intel MMX code support) were
1.4454 +added at libpng-1.2.0:
1.4455 +
1.4456 + PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
1.4457 + PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
1.4458 + PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
1.4459 + PNG_ASM_FLAG_MMX_READ_INTERLACE
1.4460 + PNG_ASM_FLAG_MMX_READ_FILTER_SUB
1.4461 + PNG_ASM_FLAG_MMX_READ_FILTER_UP
1.4462 + PNG_ASM_FLAG_MMX_READ_FILTER_AVG
1.4463 + PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
1.4464 + PNG_ASM_FLAGS_INITIALIZED
1.4465 + PNG_MMX_READ_FLAGS
1.4466 + PNG_MMX_FLAGS
1.4467 + PNG_MMX_WRITE_FLAGS
1.4468 + PNG_MMX_FLAGS
1.4469 +
1.4470 +We added the following functions in support of runtime
1.4471 +selection of assembler code features:
1.4472 +
1.4473 + png_get_mmx_flagmask()
1.4474 + png_set_mmx_thresholds()
1.4475 + png_get_asm_flags()
1.4476 + png_get_mmx_bitdepth_threshold()
1.4477 + png_get_mmx_rowbytes_threshold()
1.4478 + png_set_asm_flags()
1.4479 +
1.4480 +We replaced all of these functions with simple stubs in libpng-1.2.20,
1.4481 +when the Intel assembler code was removed due to a licensing issue.
1.4482 +
1.4483 +These macros are deprecated:
1.4484 +
1.4485 + PNG_READ_TRANSFORMS_NOT_SUPPORTED
1.4486 + PNG_PROGRESSIVE_READ_NOT_SUPPORTED
1.4487 + PNG_NO_SEQUENTIAL_READ_SUPPORTED
1.4488 + PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
1.4489 + PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
1.4490 + PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
1.4491 +
1.4492 +They have been replaced, respectively, by:
1.4493 +
1.4494 + PNG_NO_READ_TRANSFORMS
1.4495 + PNG_NO_PROGRESSIVE_READ
1.4496 + PNG_NO_SEQUENTIAL_READ
1.4497 + PNG_NO_WRITE_TRANSFORMS
1.4498 + PNG_NO_READ_ANCILLARY_CHUNKS
1.4499 + PNG_NO_WRITE_ANCILLARY_CHUNKS
1.4500 +
1.4501 +PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
1.4502 +deprecated since libpng-1.0.16 and libpng-1.2.6.
1.4503 +
1.4504 +The function
1.4505 + png_check_sig(sig, num)
1.4506 +was replaced with
1.4507 + !png_sig_cmp(sig, 0, num)
1.4508 +It has been deprecated since libpng-0.90.
1.4509 +
1.4510 +The function
1.4511 + png_set_gray_1_2_4_to_8()
1.4512 +which also expands tRNS to alpha was replaced with
1.4513 + png_set_expand_gray_1_2_4_to_8()
1.4514 +which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
1.4515 +
1.4516 +X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
1.4517 +
1.4518 +Private libpng prototypes and macro definitions were moved from
1.4519 +png.h and pngconf.h into a new pngpriv.h header file.
1.4520 +
1.4521 +Functions png_set_benign_errors(), png_benign_error(), and
1.4522 +png_chunk_benign_error() were added.
1.4523 +
1.4524 +Support for setting the maximum amount of memory that the application
1.4525 +will allocate for reading chunks was added, as a security measure.
1.4526 +The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
1.4527 +were added to the library.
1.4528 +
1.4529 +We implemented support for I/O states by adding png_ptr member io_state
1.4530 +and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
1.4531 +
1.4532 +We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
1.4533 +input transforms.
1.4534 +
1.4535 +Checking for and reporting of errors in the IHDR chunk is more thorough.
1.4536 +
1.4537 +Support for global arrays was removed, to improve thread safety.
1.4538 +
1.4539 +Some obsolete/deprecated macros and functions have been removed.
1.4540 +
1.4541 +Typecasted NULL definitions such as
1.4542 + #define png_voidp_NULL (png_voidp)NULL
1.4543 +were eliminated. If you used these in your application, just use
1.4544 +NULL instead.
1.4545 +
1.4546 +The png_struct and info_struct members "trans" and "trans_values" were
1.4547 +changed to "trans_alpha" and "trans_color", respectively.
1.4548 +
1.4549 +The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
1.4550 +were removed.
1.4551 +
1.4552 +The PNG_1_0_X and PNG_1_2_X macros were eliminated.
1.4553 +
1.4554 +The PNG_LEGACY_SUPPORTED macro was eliminated.
1.4555 +
1.4556 +Many WIN32_WCE #ifdefs were removed.
1.4557 +
1.4558 +The functions png_read_init(info_ptr), png_write_init(info_ptr),
1.4559 +png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
1.4560 +have been removed. They have been deprecated since libpng-0.95.
1.4561 +
1.4562 +The png_permit_empty_plte() was removed. It has been deprecated
1.4563 +since libpng-1.0.9. Use png_permit_mng_features() instead.
1.4564 +
1.4565 +We removed the obsolete stub functions png_get_mmx_flagmask(),
1.4566 +png_set_mmx_thresholds(), png_get_asm_flags(),
1.4567 +png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
1.4568 +png_set_asm_flags(), and png_mmx_supported()
1.4569 +
1.4570 +We removed the obsolete png_check_sig(), png_memcpy_check(), and
1.4571 +png_memset_check() functions. Instead use !png_sig_cmp(), memcpy(),
1.4572 +and memset(), respectively.
1.4573 +
1.4574 +The function png_set_gray_1_2_4_to_8() was removed. It has been
1.4575 +deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
1.4576 +png_set_expand_gray_1_2_4_to_8() because the former function also
1.4577 +expanded any tRNS chunk to an alpha channel.
1.4578 +
1.4579 +Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32
1.4580 +were added and are used by default instead of the corresponding
1.4581 +functions. Unfortunately,
1.4582 +from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
1.4583 +function) incorrectly returned a value of type png_uint_32.
1.4584 +
1.4585 +We changed the prototype for png_malloc() from
1.4586 + png_malloc(png_structp png_ptr, png_uint_32 size)
1.4587 +to
1.4588 + png_malloc(png_structp png_ptr, png_alloc_size_t size)
1.4589 +
1.4590 +This also applies to the prototype for the user replacement malloc_fn().
1.4591 +
1.4592 +The png_calloc() function was added and is used in place of
1.4593 +of "png_malloc(); memset();" except in the case in png_read_png()
1.4594 +where the array consists of pointers; in this case a "for" loop is used
1.4595 +after the png_malloc() to set the pointers to NULL, to give robust.
1.4596 +behavior in case the application runs out of memory part-way through
1.4597 +the process.
1.4598 +
1.4599 +We changed the prototypes of png_get_compression_buffer_size() and
1.4600 +png_set_compression_buffer_size() to work with png_size_t instead of
1.4601 +png_uint_32.
1.4602 +
1.4603 +Support for numbered error messages was removed by default, since we
1.4604 +never got around to actually numbering the error messages. The function
1.4605 +png_set_strip_error_numbers() was removed from the library by default.
1.4606 +
1.4607 +The png_zalloc() and png_zfree() functions are no longer exported.
1.4608 +The png_zalloc() function no longer zeroes out the memory that it
1.4609 +allocates. Applications that called png_zalloc(png_ptr, number, size)
1.4610 +can call png_calloc(png_ptr, number*size) instead, and can call
1.4611 +png_free() instead of png_zfree().
1.4612 +
1.4613 +Support for dithering was disabled by default in libpng-1.4.0, because
1.4614 +it has not been well tested and doesn't actually "dither".
1.4615 +The code was not
1.4616 +removed, however, and could be enabled by building libpng with
1.4617 +PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support
1.4618 +was re-enabled, but the function was renamed png_set_quantize() to
1.4619 +reflect more accurately what it actually does. At the same time,
1.4620 +the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
1.4621 +PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
1.4622 +was renamed to PNG_READ_QUANTIZE_SUPPORTED.
1.4623 +
1.4624 +We removed the trailing '.' from the warning and error messages.
1.4625 +
1.4626 +XI. Changes to Libpng from version 1.4.x to 1.5.x
1.4627 +
1.4628 +From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
1.4629 +function) incorrectly returned a value of type png_uint_32.
1.4630 +The incorrect macro was removed from libpng-1.4.5.
1.4631 +
1.4632 +Checking for invalid palette index on write was added at libpng
1.4633 +1.5.10. If a pixel contains an invalid (out-of-range) index libpng issues
1.4634 +a benign error. This is enabled by default because this condition is an
1.4635 +error according to the PNG specification, Clause 11.3.2, but the error can
1.4636 +be ignored in each png_ptr with
1.4637 +
1.4638 + png_set_check_for_invalid_index(png_ptr, allowed);
1.4639 +
1.4640 + allowed - one of
1.4641 + 0: disable benign error (accept the
1.4642 + invalid data without warning).
1.4643 + 1: enable benign error (treat the
1.4644 + invalid data as an error or a
1.4645 + warning).
1.4646 +
1.4647 +If the error is ignored, or if png_benign_error() treats it as a warning,
1.4648 +any invalid pixels are decoded as opaque black by the decoder and written
1.4649 +as-is by the encoder.
1.4650 +
1.4651 +Retrieving the maximum palette index found was added at libpng-1.5.15.
1.4652 +This statement must appear after png_read_png() or png_read_image() while
1.4653 +reading, and after png_write_png() or png_write_image() while writing.
1.4654 +
1.4655 + int max_palette = png_get_palette_max(png_ptr, info_ptr);
1.4656 +
1.4657 +This will return the maximum palette index found in the image, or "-1" if
1.4658 +the palette was not checked, or "0" if no palette was found. Note that this
1.4659 +does not account for any palette index used by ancillary chunks such as the
1.4660 +bKGD chunk; you must check those separately to determine the maximum
1.4661 +palette index actually used.
1.4662 +
1.4663 +A. Changes that affect users of libpng
1.4664 +
1.4665 +There are no substantial API changes between the non-deprecated parts of
1.4666 +the 1.4.5 API and the 1.5.0 API; however, the ability to directly access
1.4667 +members of the main libpng control structures, png_struct and png_info,
1.4668 +deprecated in earlier versions of libpng, has been completely removed from
1.4669 +libpng 1.5.
1.4670 +
1.4671 +We no longer include zlib.h in png.h. The include statement has been moved
1.4672 +to pngstruct.h, where it is not accessible by applications. Applications that
1.4673 +need access to information in zlib.h will need to add the '#include "zlib.h"'
1.4674 +directive. It does not matter whether this is placed prior to or after
1.4675 +the '"#include png.h"' directive.
1.4676 +
1.4677 +The png_sprintf(), png_strcpy(), and png_strncpy() macros are no longer used
1.4678 +and were removed.
1.4679 +
1.4680 +We moved the png_strlen(), png_memcpy(), png_memset(), and png_memcmp()
1.4681 +macros into a private header file (pngpriv.h) that is not accessible to
1.4682 +applications.
1.4683 +
1.4684 +In png_get_iCCP, the type of "profile" was changed from png_charpp
1.4685 +to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
1.4686 +
1.4687 +There are changes of form in png.h, including new and changed macros to
1.4688 +declare parts of the API. Some API functions with arguments that are
1.4689 +pointers to data not modified within the function have been corrected to
1.4690 +declare these arguments with PNG_CONST.
1.4691 +
1.4692 +Much of the internal use of C macros to control the library build has also
1.4693 +changed and some of this is visible in the exported header files, in
1.4694 +particular the use of macros to control data and API elements visible
1.4695 +during application compilation may require significant revision to
1.4696 +application code. (It is extremely rare for an application to do this.)
1.4697 +
1.4698 +Any program that compiled against libpng 1.4 and did not use deprecated
1.4699 +features or access internal library structures should compile and work
1.4700 +against libpng 1.5, except for the change in the prototype for
1.4701 +png_get_iCCP() and png_set_iCCP() API functions mentioned above.
1.4702 +
1.4703 +libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of
1.4704 +interlaced images. The macros return the number of rows and columns in
1.4705 +each pass and information that can be used to de-interlace and (if
1.4706 +absolutely necessary) interlace an image.
1.4707 +
1.4708 +libpng 1.5.0 adds an API png_longjmp(png_ptr, value). This API calls
1.4709 +the application-provided png_longjmp_ptr on the internal, but application
1.4710 +initialized, longjmp buffer. It is provided as a convenience to avoid
1.4711 +the need to use the png_jmpbuf macro, which had the unnecessary side
1.4712 +effect of resetting the internal png_longjmp_ptr value.
1.4713 +
1.4714 +libpng 1.5.0 includes a complete fixed point API. By default this is
1.4715 +present along with the corresponding floating point API. In general the
1.4716 +fixed point API is faster and smaller than the floating point one because
1.4717 +the PNG file format used fixed point, not floating point. This applies
1.4718 +even if the library uses floating point in internal calculations. A new
1.4719 +macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library
1.4720 +uses floating point arithmetic (the default) or fixed point arithmetic
1.4721 +internally for performance critical calculations such as gamma correction.
1.4722 +In some cases, the gamma calculations may produce slightly different
1.4723 +results. This has changed the results in png_rgb_to_gray and in alpha
1.4724 +composition (png_set_background for example). This applies even if the
1.4725 +original image was already linear (gamma == 1.0) and, therefore, it is
1.4726 +not necessary to linearize the image. This is because libpng has *not*
1.4727 +been changed to optimize that case correctly, yet.
1.4728 +
1.4729 +Fixed point support for the sCAL chunk comes with an important caveat;
1.4730 +the sCAL specification uses a decimal encoding of floating point values
1.4731 +and the accuracy of PNG fixed point values is insufficient for
1.4732 +representation of these values. Consequently a "string" API
1.4733 +(png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading
1.4734 +arbitrary sCAL chunks in the absence of either the floating point API or
1.4735 +internal floating point calculations. Starting with libpng-1.5.0, both
1.4736 +of these functions are present when PNG_sCAL_SUPPORTED is defined. Prior
1.4737 +to libpng-1.5.0, their presence also depended upon PNG_FIXED_POINT_SUPPORTED
1.4738 +being defined and PNG_FLOATING_POINT_SUPPORTED not being defined.
1.4739 +
1.4740 +Applications no longer need to include the optional distribution header
1.4741 +file pngusr.h or define the corresponding macros during application
1.4742 +build in order to see the correct variant of the libpng API. From 1.5.0
1.4743 +application code can check for the corresponding _SUPPORTED macro:
1.4744 +
1.4745 +#ifdef PNG_INCH_CONVERSIONS_SUPPORTED
1.4746 + /* code that uses the inch conversion APIs. */
1.4747 +#endif
1.4748 +
1.4749 +This macro will only be defined if the inch conversion functions have been
1.4750 +compiled into libpng. The full set of macros, and whether or not support
1.4751 +has been compiled in, are available in the header file pnglibconf.h.
1.4752 +This header file is specific to the libpng build. Notice that prior to
1.4753 +1.5.0 the _SUPPORTED macros would always have the default definition unless
1.4754 +reset by pngusr.h or by explicit settings on the compiler command line.
1.4755 +These settings may produce compiler warnings or errors in 1.5.0 because
1.4756 +of macro redefinition.
1.4757 +
1.4758 +Applications can now choose whether to use these macros or to call the
1.4759 +corresponding function by defining PNG_USE_READ_MACROS or
1.4760 +PNG_NO_USE_READ_MACROS before including png.h. Notice that this is
1.4761 +only supported from 1.5.0; defining PNG_NO_USE_READ_MACROS prior to 1.5.0
1.4762 +will lead to a link failure.
1.4763 +
1.4764 +Prior to libpng-1.5.4, the zlib compressor used the same set of parameters
1.4765 +when compressing the IDAT data and textual data such as zTXt and iCCP.
1.4766 +In libpng-1.5.4 we reinitialized the zlib stream for each type of data.
1.4767 +We added five png_set_text_*() functions for setting the parameters to
1.4768 +use with textual data.
1.4769 +
1.4770 +Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
1.4771 +option was off by default, and slightly inaccurate scaling occurred.
1.4772 +This option can no longer be turned off, and the choice of accurate
1.4773 +or inaccurate 16-to-8 scaling is by using the new png_set_scale_16_to_8()
1.4774 +API for accurate scaling or the old png_set_strip_16_to_8() API for simple
1.4775 +chopping. In libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
1.4776 +macro became PNG_READ_SCALE_16_TO_8_SUPPORTED, and the PNG_READ_16_TO_8
1.4777 +macro became PNG_READ_STRIP_16_TO_8_SUPPORTED, to enable the two
1.4778 +png_set_*_16_to_8() functions separately.
1.4779 +
1.4780 +Prior to libpng-1.5.4, the png_set_user_limits() function could only be
1.4781 +used to reduce the width and height limits from the value of
1.4782 +PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said
1.4783 +that it could be used to override them. Now this function will reduce or
1.4784 +increase the limits.
1.4785 +
1.4786 +Starting in libpng-1.5.10, the user limits can be set en masse with the
1.4787 +configuration option PNG_SAFE_LIMITS_SUPPORTED. If this option is enabled,
1.4788 +a set of "safe" limits is applied in pngpriv.h. These can be overridden by
1.4789 +application calls to png_set_user_limits(), png_set_user_chunk_cache_max(),
1.4790 +and/or png_set_user_malloc_max() that increase or decrease the limits. Also,
1.4791 +in libpng-1.5.10 the default width and height limits were increased
1.4792 +from 1,000,000 to 0x7ffffff (i.e., made unlimited). Therefore, the
1.4793 +limits are now
1.4794 + default safe
1.4795 + png_user_width_max 0x7fffffff 1,000,000
1.4796 + png_user_height_max 0x7fffffff 1,000,000
1.4797 + png_user_chunk_cache_max 0 (unlimited) 128
1.4798 + png_user_chunk_malloc_max 0 (unlimited) 8,000,000
1.4799 +
1.4800 +The png_set_option() function (and the "options" member of the png struct) was
1.4801 +added to libpng-1.5.15.
1.4802 +
1.4803 +B. Changes to the build and configuration of libpng
1.4804 +
1.4805 +Details of internal changes to the library code can be found in the CHANGES
1.4806 +file and in the GIT repository logs. These will be of no concern to the vast
1.4807 +majority of library users or builders; however, the few who configure libpng
1.4808 +to a non-default feature set may need to change how this is done.
1.4809 +
1.4810 +There should be no need for library builders to alter build scripts if
1.4811 +these use the distributed build support - configure or the makefiles -
1.4812 +however, users of the makefiles may care to update their build scripts
1.4813 +to build pnglibconf.h where the corresponding makefile does not do so.
1.4814 +
1.4815 +Building libpng with a non-default configuration has changed completely.
1.4816 +The old method using pngusr.h should still work correctly even though the
1.4817 +way pngusr.h is used in the build has been changed; however, library
1.4818 +builders will probably want to examine the changes to take advantage of
1.4819 +new capabilities and to simplify their build system.
1.4820 +
1.4821 +B.1 Specific changes to library configuration capabilities
1.4822 +
1.4823 +The library now supports a complete fixed point implementation and can
1.4824 +thus be used on systems that have no floating point support or very
1.4825 +limited or slow support. Previously gamma correction, an essential part
1.4826 +of complete PNG support, required reasonably fast floating point.
1.4827 +
1.4828 +As part of this the choice of internal implementation has been made
1.4829 +independent of the choice of fixed versus floating point APIs and all the
1.4830 +missing fixed point APIs have been implemented.
1.4831 +
1.4832 +The exact mechanism used to control attributes of API functions has
1.4833 +changed. A single set of operating system independent macro definitions
1.4834 +is used and operating system specific directives are defined in
1.4835 +pnglibconf.h
1.4836 +
1.4837 +As part of this the mechanism used to choose procedure call standards on
1.4838 +those systems that allow a choice has been changed. At present this only
1.4839 +affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
1.4840 +running on Intel processors. As before, PNGAPI is defined where required
1.4841 +to control the exported API functions; however, two new macros, PNGCBAPI
1.4842 +and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
1.4843 +(PNGCAPI) for functions that must match a C library prototype (currently
1.4844 +only png_longjmp_ptr, which must match the C longjmp function.) The new
1.4845 +approach is documented in pngconf.h
1.4846 +
1.4847 +Despite these changes, libpng 1.5.0 only supports the native C function
1.4848 +calling standard on those platforms tested so far (__cdecl on Microsoft
1.4849 +Windows). This is because the support requirements for alternative
1.4850 +calling conventions seem to no longer exist. Developers who find it
1.4851 +necessary to set PNG_API_RULE to 1 should advise the mailing list
1.4852 +(png-mng-implement) of this and library builders who use Openwatcom and
1.4853 +therefore set PNG_API_RULE to 2 should also contact the mailing list.
1.4854 +
1.4855 +A new test program, pngvalid, is provided in addition to pngtest.
1.4856 +pngvalid validates the arithmetic accuracy of the gamma correction
1.4857 +calculations and includes a number of validations of the file format.
1.4858 +A subset of the full range of tests is run when "make check" is done
1.4859 +(in the 'configure' build.) pngvalid also allows total allocated memory
1.4860 +usage to be evaluated and performs additional memory overwrite validation.
1.4861 +
1.4862 +Many changes to individual feature macros have been made. The following
1.4863 +are the changes most likely to be noticed by library builders who
1.4864 +configure libpng:
1.4865 +
1.4866 +1) All feature macros now have consistent naming:
1.4867 +
1.4868 +#define PNG_NO_feature turns the feature off
1.4869 +#define PNG_feature_SUPPORTED turns the feature on
1.4870 +
1.4871 +pnglibconf.h contains one line for each feature macro which is either:
1.4872 +
1.4873 +#define PNG_feature_SUPPORTED
1.4874 +
1.4875 +if the feature is supported or:
1.4876 +
1.4877 +/*#undef PNG_feature_SUPPORTED*/
1.4878 +
1.4879 +if it is not. Library code consistently checks for the 'SUPPORTED' macro.
1.4880 +It does not, and libpng applications should not, check for the 'NO' macro
1.4881 +which will not normally be defined even if the feature is not supported.
1.4882 +The 'NO' macros are only used internally for setting or not setting the
1.4883 +corresponding 'SUPPORTED' macros.
1.4884 +
1.4885 +Compatibility with the old names is provided as follows:
1.4886 +
1.4887 +PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED
1.4888 +
1.4889 +And the following definitions disable the corresponding feature:
1.4890 +
1.4891 +PNG_SETJMP_NOT_SUPPORTED disables SETJMP
1.4892 +PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS
1.4893 +PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV
1.4894 +PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS
1.4895 +PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS
1.4896 +PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS
1.4897 +
1.4898 +Library builders should remove use of the above, inconsistent, names.
1.4899 +
1.4900 +2) Warning and error message formatting was previously conditional on
1.4901 +the STDIO feature. The library has been changed to use the
1.4902 +CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled
1.4903 +the library no longer uses the printf(3) functions, even though the
1.4904 +default read/write implementations use (FILE) style stdio.h functions.
1.4905 +
1.4906 +3) Three feature macros now control the fixed/floating point decisions:
1.4907 +
1.4908 +PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs
1.4909 +
1.4910 +PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in
1.4911 +practice these are normally required internally anyway (because the PNG
1.4912 +file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT
1.4913 +merely stops the function from being exported.
1.4914 +
1.4915 +PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating
1.4916 +point implementation or the fixed point one. Typically the fixed point
1.4917 +implementation is larger and slower than the floating point implementation
1.4918 +on a system that supports floating point; however, it may be faster on a
1.4919 +system which lacks floating point hardware and therefore uses a software
1.4920 +emulation.
1.4921 +
1.4922 +4) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the
1.4923 +functions to read and write ints to be disabled independently of
1.4924 +PNG_USE_READ_MACROS, which allows libpng to be built with the functions
1.4925 +even though the default is to use the macros - this allows applications
1.4926 +to choose at app buildtime whether or not to use macros (previously
1.4927 +impossible because the functions weren't in the default build.)
1.4928 +
1.4929 +B.2 Changes to the configuration mechanism
1.4930 +
1.4931 +Prior to libpng-1.5.0 library builders who needed to configure libpng
1.4932 +had either to modify the exported pngconf.h header file to add system
1.4933 +specific configuration or had to write feature selection macros into
1.4934 +pngusr.h and cause this to be included into pngconf.h by defining
1.4935 +PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
1.4936 +application built without PNG_USER_CONFIG defined would see the
1.4937 +unmodified, default, libpng API and thus would probably fail to link.
1.4938 +
1.4939 +These mechanisms still work in the configure build and in any makefile
1.4940 +build that builds pnglibconf.h, although the feature selection macros
1.4941 +have changed somewhat as described above. In 1.5.0, however, pngusr.h is
1.4942 +processed only once, when the exported header file pnglibconf.h is built.
1.4943 +pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the
1.4944 +build of pnglibconf.h and it is never included in an application build.
1.4945 +
1.4946 +The rarely used alternative of adding a list of feature macros to the
1.4947 +CFLAGS setting in the build also still works; however, the macros will be
1.4948 +copied to pnglibconf.h and this may produce macro redefinition warnings
1.4949 +when the individual C files are compiled.
1.4950 +
1.4951 +All configuration now only works if pnglibconf.h is built from
1.4952 +scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan
1.4953 +(the original author of awk) maintains C source code of that awk and this
1.4954 +and all known later implementations (often called by subtly different
1.4955 +names - nawk and gawk for example) are adequate to build pnglibconf.h.
1.4956 +The Sun Microsystems (now Oracle) program 'awk' is an earlier version
1.4957 +and does not work; this may also apply to other systems that have a
1.4958 +functioning awk called 'nawk'.
1.4959 +
1.4960 +Configuration options are now documented in scripts/pnglibconf.dfa. This
1.4961 +file also includes dependency information that ensures a configuration is
1.4962 +consistent; that is, if a feature is switched off dependent features are
1.4963 +also removed. As a recommended alternative to using feature macros in
1.4964 +pngusr.h a system builder may also define equivalent options in pngusr.dfa
1.4965 +(or, indeed, any file) and add that to the configuration by setting
1.4966 +DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate
1.4967 +how to do this, and a case where pngusr.h is still required.
1.4968 +
1.4969 +XII. Changes to Libpng from version 1.5.x to 1.6.x
1.4970 +
1.4971 +A "simplified API" has been added (see documentation in png.h and a simple
1.4972 +example in contrib/examples/pngtopng.c). The new publicly visible API
1.4973 +includes the following:
1.4974 +
1.4975 + macros:
1.4976 + PNG_FORMAT_*
1.4977 + PNG_IMAGE_*
1.4978 + structures:
1.4979 + png_control
1.4980 + png_image
1.4981 + read functions
1.4982 + png_image_begin_read_from_file()
1.4983 + png_image_begin_read_from_stdio()
1.4984 + png_image_begin_read_from_memory()
1.4985 + png_image_finish_read()
1.4986 + png_image_free()
1.4987 + write functions
1.4988 + png_image_write_to_file()
1.4989 + png_image_write_to_stdio()
1.4990 +
1.4991 +Starting with libpng-1.6.0, you can configure libpng to prefix all exported
1.4992 +symbols, using the PNG_PREFIX macro.
1.4993 +
1.4994 +We no longer include string.h in png.h. The include statement has been moved
1.4995 +to pngpriv.h, where it is not accessible by applications. Applications that
1.4996 +need access to information in string.h must add an '#include <string.h>'
1.4997 +directive. It does not matter whether this is placed prior to or after
1.4998 +the '#include "png.h"' directive.
1.4999 +
1.5000 +The following API are now DEPRECATED:
1.5001 + png_info_init_3()
1.5002 + png_convert_to_rfc1123() which has been replaced
1.5003 + with png_convert_to_rfc1123_buffer()
1.5004 + png_data_freer()
1.5005 + png_malloc_default()
1.5006 + png_free_default()
1.5007 + png_reset_zstream()
1.5008 +
1.5009 +The following have been removed:
1.5010 + png_get_io_chunk_name(), which has been replaced
1.5011 + with png_get_io_chunk_type(). The new
1.5012 + function returns a 32-bit integer instead of
1.5013 + a string.
1.5014 + The png_sizeof(), png_strlen(), png_memcpy(), png_memcmp(), and
1.5015 + png_memset() macros are no longer used in the libpng sources and
1.5016 + have been removed. These had already been made invisible to applications
1.5017 + (i.e., defined in the private pngpriv.h header file) since libpng-1.5.0.
1.5018 +
1.5019 +The signatures of many exported functions were changed, such that
1.5020 + png_structp became png_structrp or png_const_structrp
1.5021 + png_infop became png_inforp or png_const_inforp
1.5022 +where "rp" indicates a "restricted pointer".
1.5023 +
1.5024 +Error detection in some chunks has improved; in particular the iCCP chunk
1.5025 +reader now does pretty complete validation of the basic format. Some bad
1.5026 +profiles that were previously accepted are now accepted with a warning or
1.5027 +rejected, depending upon the png_set_benign_errors() setting, in particular the
1.5028 +very old broken Microsoft/HP 3144-byte sRGB profile. The PNG spec requirement
1.5029 +that only grayscale profiles may appear in images with color type 0 or 4 and
1.5030 +that even if the image only contains gray pixels, only RGB profiles may appear
1.5031 +in images with color type 2, 3, or 6, is now enforced. The sRGB chunk
1.5032 +is allowed to appear in images with any color type.
1.5033 +
1.5034 +Prior to libpng-1.6.0 a warning would be issued if the iTXt chunk contained
1.5035 +an empty language field or an empty translated keyword. Both of these
1.5036 +are allowed by the PNG specification, so these warnings are no longer issued.
1.5037 +
1.5038 +The library now issues an error if the application attempts to set a
1.5039 +transform after it calls png_read_update_info() or if it attempts to call
1.5040 +both png_read_update_info() and png_start_read_image() or to call either
1.5041 +of them more than once.
1.5042 +
1.5043 +The default condition for benign_errors is now to treat benign errors as
1.5044 +warnings while reading and as errors while writing.
1.5045 +
1.5046 +The library now issues a warning if both background processing and RGB to
1.5047 +gray are used when gamma correction happens. As with previous versions of
1.5048 +the library the results are numerically very incorrect in this case.
1.5049 +
1.5050 +There are some minor arithmetic changes in some transforms such as
1.5051 +png_set_background(), that might be detected by certain regression tests.
1.5052 +
1.5053 +Unknown chunk handling has been improved internally, without any API change.
1.5054 +This adds more correct option control of the unknown handling, corrects
1.5055 +a pre-existing bug where the per-chunk 'keep' setting is ignored, and makes
1.5056 +it possible to skip IDAT chunks in the sequential reader.
1.5057 +
1.5058 +The machine-generated configure files are no longer included in branches
1.5059 +libpng16 and later of the GIT repository. They continue to be included
1.5060 +in the tarball releases, however.
1.5061 +
1.5062 +Libpng-1.6.0 through 1.6.2 used the CMF bytes at the beginning of the IDAT
1.5063 +stream to set the size of the sliding window for reading instead of using the
1.5064 +default 32-kbyte sliding window size. It was discovered that there are
1.5065 +hundreds of PNG files in the wild that have incorrect CMF bytes that caused
1.5066 +libpng to issue a "too far back" error and reject the file. Libpng-1.6.3 and
1.5067 +later calculate their own safe CMF from the image dimensions, provide a way
1.5068 +to revert to the libpng-1.5.x behavior (ignoring the CMF bytes and using a
1.5069 +32-kbyte sliding window), by using
1.5070 +
1.5071 + png_set_option(png_ptr, PNG_MAXIMUM_INFLATE_WINDOW,
1.5072 + PNG_OPTION_ON);
1.5073 +
1.5074 +and provide a tool (contrib/tools/pngfix) for optimizing the CMF bytes
1.5075 +correctly.
1.5076 +
1.5077 +Libpng-1.6.0 and libpng-1.6.1 wrote uncompressed iTXt chunks with the wrong
1.5078 +length, which resulted in PNG files that cannot be read beyond the bad iTXt
1.5079 +chunk. This error was fixed in libpng-1.6.3, and a tool (called
1.5080 +contrib/tools/png-fix-itxt) has been added to the libpng distribution.
1.5081 +
1.5082 +XIII. Detecting libpng
1.5083 +
1.5084 +The png_get_io_ptr() function has been present since libpng-0.88, has never
1.5085 +changed, and is unaffected by conditional compilation macros. It is the
1.5086 +best choice for use in configure scripts for detecting the presence of any
1.5087 +libpng version since 0.88. In an autoconf "configure.in" you could use
1.5088 +
1.5089 + AC_CHECK_LIB(png, png_get_io_ptr, ...
1.5090 +
1.5091 +XV. Source code repository
1.5092 +
1.5093 +Since about February 2009, version 1.2.34, libpng has been under "git" source
1.5094 +control. The git repository was built from old libpng-x.y.z.tar.gz files
1.5095 +going back to version 0.70. You can access the git repository (read only)
1.5096 +at
1.5097 +
1.5098 + git://git.code.sf.net/p/libpng/code
1.5099 +
1.5100 +or you can browse it with a web browser by selecting the "code" button at
1.5101 +
1.5102 + https://sourceforge.net/projects/libpng
1.5103 +
1.5104 +Patches can be sent to glennrp at users.sourceforge.net or to
1.5105 +png-mng-implement at lists.sourceforge.net or you can upload them to
1.5106 +the libpng bug tracker at
1.5107 +
1.5108 + http://libpng.sourceforge.net
1.5109 +
1.5110 +We also accept patches built from the tar or zip distributions, and
1.5111 +simple verbal discriptions of bug fixes, reported either to the
1.5112 +SourceForge bug tracker, to the png-mng-implement at lists.sf.net
1.5113 +mailing list, or directly to glennrp.
1.5114 +
1.5115 +XV. Coding style
1.5116 +
1.5117 +Our coding style is similar to the "Allman" style, with curly
1.5118 +braces on separate lines:
1.5119 +
1.5120 + if (condition)
1.5121 + {
1.5122 + action;
1.5123 + }
1.5124 +
1.5125 + else if (another condition)
1.5126 + {
1.5127 + another action;
1.5128 + }
1.5129 +
1.5130 +The braces can be omitted from simple one-line actions:
1.5131 +
1.5132 + if (condition)
1.5133 + return (0);
1.5134 +
1.5135 +We use 3-space indentation, except for continued statements which
1.5136 +are usually indented the same as the first line of the statement
1.5137 +plus four more spaces.
1.5138 +
1.5139 +For macro definitions we use 2-space indentation, always leaving the "#"
1.5140 +in the first column.
1.5141 +
1.5142 + #ifndef PNG_NO_FEATURE
1.5143 + # ifndef PNG_FEATURE_SUPPORTED
1.5144 + # define PNG_FEATURE_SUPPORTED
1.5145 + # endif
1.5146 + #endif
1.5147 +
1.5148 +Comments appear with the leading "/*" at the same indentation as
1.5149 +the statement that follows the comment:
1.5150 +
1.5151 + /* Single-line comment */
1.5152 + statement;
1.5153 +
1.5154 + /* This is a multiple-line
1.5155 + * comment.
1.5156 + */
1.5157 + statement;
1.5158 +
1.5159 +Very short comments can be placed after the end of the statement
1.5160 +to which they pertain:
1.5161 +
1.5162 + statement; /* comment */
1.5163 +
1.5164 +We don't use C++ style ("//") comments. We have, however,
1.5165 +used them in the past in some now-abandoned MMX assembler
1.5166 +code.
1.5167 +
1.5168 +Functions and their curly braces are not indented, and
1.5169 +exported functions are marked with PNGAPI:
1.5170 +
1.5171 + /* This is a public function that is visible to
1.5172 + * application programmers. It does thus-and-so.
1.5173 + */
1.5174 + void PNGAPI
1.5175 + png_exported_function(png_ptr, png_info, foo)
1.5176 + {
1.5177 + body;
1.5178 + }
1.5179 +
1.5180 +The prototypes for all exported functions appear in png.h,
1.5181 +above the comment that says
1.5182 +
1.5183 + /* Maintainer: Put new public prototypes here ... */
1.5184 +
1.5185 +We mark all non-exported functions with "/* PRIVATE */"":
1.5186 +
1.5187 + void /* PRIVATE */
1.5188 + png_non_exported_function(png_ptr, png_info, foo)
1.5189 + {
1.5190 + body;
1.5191 + }
1.5192 +
1.5193 +The prototypes for non-exported functions (except for those in
1.5194 +pngtest) appear in
1.5195 +pngpriv.h
1.5196 +above the comment that says
1.5197 +
1.5198 + /* Maintainer: Put new private prototypes here ^ */
1.5199 +
1.5200 +We put a space after the "sizeof" operator and we omit the
1.5201 +optional parentheses around its argument when the argument
1.5202 +is an expression, not a type name, and we always enclose the
1.5203 +sizeof operator, with its argument, in parentheses:
1.5204 +
1.5205 + (sizeof (png_uint_32))
1.5206 + (sizeof array)
1.5207 +
1.5208 +Prior to libpng-1.6.0 we used a "png_sizeof()" macro, formatted as
1.5209 +though it were a function.
1.5210 +
1.5211 +To avoid polluting the global namespace, the names of all exported
1.5212 +functions and variables begin with "png_", and all publicly visible C
1.5213 +preprocessor macros begin with "PNG". We request that applications that
1.5214 +use libpng *not* begin any of their own symbols with either of these strings.
1.5215 +
1.5216 +We put a space after each comma and after each semicolon
1.5217 +in "for" statements, and we put spaces before and after each
1.5218 +C binary operator and after "for" or "while", and before
1.5219 +"?". We don't put a space between a typecast and the expression
1.5220 +being cast, nor do we put one between a function name and the
1.5221 +left parenthesis that follows it:
1.5222 +
1.5223 + for (i = 2; i > 0; --i)
1.5224 + y[i] = a(x) + (int)b;
1.5225 +
1.5226 +We prefer #ifdef and #ifndef to #if defined() and #if !defined()
1.5227 +when there is only one macro being tested. We always use parentheses
1.5228 +with "defined".
1.5229 +
1.5230 +We prefer to express integers that are used as bit masks in hex format,
1.5231 +with an even number of lower-case hex digits (e.g., 0x00, 0xff, 0x0100).
1.5232 +
1.5233 +We prefer to use underscores in variable names rather than camelCase, except
1.5234 +for a few type names that we inherit from zlib.h.
1.5235 +
1.5236 +We do not use the TAB character for indentation in the C sources.
1.5237 +
1.5238 +Lines do not exceed 80 characters.
1.5239 +
1.5240 +Other rules can be inferred by inspecting the libpng source.
1.5241 +
1.5242 +XVI. Y2K Compliance in libpng
1.5243 +
1.5244 +February 6, 2014
1.5245 +
1.5246 +Since the PNG Development group is an ad-hoc body, we can't make
1.5247 +an official declaration.
1.5248 +
1.5249 +This is your unofficial assurance that libpng from version 0.71 and
1.5250 +upward through 1.6.9 are Y2K compliant. It is my belief that earlier
1.5251 +versions were also Y2K compliant.
1.5252 +
1.5253 +Libpng only has two year fields. One is a 2-byte unsigned integer
1.5254 +that will hold years up to 65535. The other, which is deprecated,
1.5255 +holds the date in text format, and will hold years up to 9999.
1.5256 +
1.5257 +The integer is
1.5258 + "png_uint_16 year" in png_time_struct.
1.5259 +
1.5260 +The string is
1.5261 + "char time_buffer[29]" in png_struct. This is no longer used
1.5262 +in libpng-1.6.x and will be removed from libpng-1.7.0.
1.5263 +
1.5264 +There are seven time-related functions:
1.5265 +
1.5266 + png_convert_to_rfc_1123() in png.c
1.5267 + (formerly png_convert_to_rfc_1152() in error)
1.5268 + png_convert_from_struct_tm() in pngwrite.c, called
1.5269 + in pngwrite.c
1.5270 + png_convert_from_time_t() in pngwrite.c
1.5271 + png_get_tIME() in pngget.c
1.5272 + png_handle_tIME() in pngrutil.c, called in pngread.c
1.5273 + png_set_tIME() in pngset.c
1.5274 + png_write_tIME() in pngwutil.c, called in pngwrite.c
1.5275 +
1.5276 +All appear to handle dates properly in a Y2K environment. The
1.5277 +png_convert_from_time_t() function calls gmtime() to convert from system
1.5278 +clock time, which returns (year - 1900), which we properly convert to
1.5279 +the full 4-digit year. There is a possibility that applications using
1.5280 +libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
1.5281 +function, or that they are incorrectly passing only a 2-digit year
1.5282 +instead of "year - 1900" into the png_convert_from_struct_tm() function,
1.5283 +but this is not under our control. The libpng documentation has always
1.5284 +stated that it works with 4-digit years, and the APIs have been
1.5285 +documented as such.
1.5286 +
1.5287 +The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
1.5288 +integer to hold the year, and can hold years as large as 65535.
1.5289 +
1.5290 +zlib, upon which libpng depends, is also Y2K compliant. It contains
1.5291 +no date-related code.
1.5292 +
1.5293 +
1.5294 + Glenn Randers-Pehrson
1.5295 + libpng maintainer
1.5296 + PNG Development Group
