VirtualBox

source: vbox/trunk/src/libs/libpng-1.2.54/libpng-1.2.54.txt@ 78229

Last change on this file since 78229 was 58796, checked in by vboxsync, 9 years ago

libpng 1.2.54 unmodified

  • Property svn:eol-style set to native
File size: 131.7 KB
Line 
1libpng.txt - A description on how to use and modify libpng
2
3 libpng version 1.2.54 - November 12, 2015
4 Updated and distributed by Glenn Randers-Pehrson
5 <glennrp at users.sourceforge.net>
6 Copyright (c) 1998-2014 Glenn Randers-Pehrson
7
8 This document is released under the libpng license.
9 For conditions of distribution and use, see the disclaimer
10 and license in png.h
11
12 Based on:
13
14 libpng versions 0.97, January 1998, through 1.2.54 - November 12, 2015
15 Updated and distributed by Glenn Randers-Pehrson
16 Copyright (c) 1998-2014 Glenn Randers-Pehrson
17
18 libpng 1.0 beta 6 version 0.96 May 28, 1997
19 Updated and distributed by Andreas Dilger
20 Copyright (c) 1996, 1997 Andreas Dilger
21
22 libpng 1.0 beta 2 - version 0.88 January 26, 1996
23 For conditions of distribution and use, see copyright
24 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
25 Schalnat, Group 42, Inc.
26
27 Updated/rewritten per request in the libpng FAQ
28 Copyright (c) 1995, 1996 Frank J. T. Wojcik
29 December 18, 1995 & January 20, 1996
30
31I. Introduction
32
33This file describes how to use and modify the PNG reference library
34(known as libpng) for your own use. There are five sections to this
35file: introduction, structures, reading, writing, and modification and
36configuration notes for various special platforms. In addition to this
37file, example.c is a good starting point for using the library, as
38it is heavily commented and should include everything most people
39will need. We assume that libpng is already installed; see the
40INSTALL file for instructions on how to install libpng.
41
42For examples of libpng usage, see the files "example.c", "pngtest.c",
43and the files in the "contrib" directory, all of which are included in
44the libpng distribution.
45
46Libpng was written as a companion to the PNG specification, as a way
47of reducing the amount of time and effort it takes to support the PNG
48file format in application programs.
49
50The PNG specification (second edition), November 2003, is available as
51a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
52<http://www.w3.org/TR/2003/REC-PNG-20031110/
53The W3C and ISO documents have identical technical content.
54
55The PNG-1.2 specification is available at
56<http://png-mng.sourceforge.net/pub/png/spec/1.2/>.
57It is technically equivalent
58to the PNG specification (second edition) but has some additional material.
59
60The PNG-1.0 specification is available as RFC 2083
61<http://png-mng.sourceforge.net/pub/png/spec/1.0/> and as a
62W3C Recommendation <http://www.w3.org/TR/REC-png-961001>.
63
64Some additional chunks are described in the special-purpose public chunks
65documents at <http://www.libpng.org/pub/png/spec/register/>
66
67Other information
68about PNG, and the latest version of libpng, can be found at the PNG home
69page, <http://www.libpng.org/pub/png/>.
70
71Most users will not have to modify the library significantly; advanced
72users may want to modify it more. All attempts were made to make it as
73complete as possible, while keeping the code easy to understand.
74Currently, this library only supports C. Support for other languages
75is being considered.
76
77Libpng has been designed to handle multiple sessions at one time,
78to be easily modifiable, to be portable to the vast majority of
79machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
80to use. The ultimate goal of libpng is to promote the acceptance of
81the PNG file format in whatever way possible. While there is still
82work to be done (see the TODO file), libpng should cover the
83majority of the needs of its users.
84
85Libpng uses zlib for its compression and decompression of PNG files.
86Further information about zlib, and the latest version of zlib, can
87be found at the zlib home page, <http://zlib.net/>.
88The zlib compression utility is a general purpose utility that is
89useful for more than PNG files, and can be used without libpng.
90See the documentation delivered with zlib for more details.
91You can usually find the source files for the zlib utility wherever you
92find the libpng source files.
93
94Libpng is thread safe, provided the threads are using different
95instances of the structures. Each thread should have its own
96png_struct and png_info instances, and thus its own image.
97Libpng does not protect itself against two threads using the
98same instance of a structure.
99
100II. Structures
101
102There are two main structures that are important to libpng, png_struct
103and png_info. The first, png_struct, is an internal structure that
104will not, for the most part, be used by a user except as the first
105variable passed to every libpng function call.
106
107The png_info structure is designed to provide information about the
108PNG file. At one time, the fields of png_info were intended to be
109directly accessible to the user. However, this tended to cause problems
110with applications using dynamically loaded libraries, and as a result
111a set of interface functions for png_info (the png_get_*() and png_set_*()
112functions) was developed. The fields of png_info are still available for
113older applications, but it is suggested that applications use the new
114interfaces if at all possible.
115
116Applications that do make direct access to the members of png_struct (except
117for png_ptr->jmpbuf) must be recompiled whenever the library is updated,
118and applications that make direct access to the members of png_info must
119be recompiled if they were compiled or loaded with libpng version 1.0.6,
120in which the members were in a different order. In version 1.0.7, the
121members of the png_info structure reverted to the old order, as they were
122in versions 0.97c through 1.0.5. Starting with version 2.0.0, both
123structures are going to be hidden, and the contents of the structures will
124only be accessible through the png_get/png_set functions.
125
126The png.h header file is an invaluable reference for programming with libpng.
127And while I'm on the topic, make sure you include the libpng header file:
128
129#include <png.h>
130
131III. Reading
132
133We'll now walk you through the possible functions to call when reading
134in a PNG file sequentially, briefly explaining the syntax and purpose
135of each one. See example.c and png.h for more detail. While
136progressive reading is covered in the next section, you will still
137need some of the functions discussed in this section to read a PNG
138file.
139
140Setup
141
142You will want to do the I/O initialization(*) before you get into libpng,
143so if it doesn't work, you don't have much to undo. Of course, you
144will also want to insure that you are, in fact, dealing with a PNG
145file. Libpng provides a simple check to see if a file is a PNG file.
146To use it, pass in the first 1 to 8 bytes of the file to the function
147png_sig_cmp(), and it will return 0 (false) if the bytes match the
148corresponding bytes of the PNG signature, or nonzero (true) otherwise.
149Of course, the more bytes you pass in, the greater the accuracy of the
150prediction.
151
152If you are intending to keep the file pointer open for use in libpng,
153you must ensure you don't read more than 8 bytes from the beginning
154of the file, and you also have to make a call to png_set_sig_bytes()
155with the number of bytes you read from the beginning. Libpng will
156then only check the bytes (if any) that your program didn't read.
157
158(*): If you are not using the standard I/O functions, you will need
159to replace them with custom functions. See the discussion under
160Customizing libpng.
161
162
163 FILE *fp = fopen(file_name, "rb");
164 if (!fp)
165 {
166 return (ERROR);
167 }
168 fread(header, 1, number, fp);
169 is_png = !png_sig_cmp(header, 0, number);
170 if (!is_png)
171 {
172 return (NOT_PNG);
173 }
174
175
176Next, png_struct and png_info need to be allocated and initialized. In
177order to ensure that the size of these structures is correct even with a
178dynamically linked libpng, there are functions to initialize and
179allocate the structures. We also pass the library version, optional
180pointers to error handling functions, and a pointer to a data struct for
181use by the error functions, if necessary (the pointer and functions can
182be NULL if the default error handlers are to be used). See the section
183on Changes to Libpng below regarding the old initialization functions.
184The structure allocation functions quietly return NULL if they fail to
185create the structure, so your application should check for that.
186
187 png_structp png_ptr = png_create_read_struct
188 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
189 user_error_fn, user_warning_fn);
190 if (!png_ptr)
191 return (ERROR);
192
193 png_infop info_ptr = png_create_info_struct(png_ptr);
194 if (!info_ptr)
195 {
196 png_destroy_read_struct(&png_ptr,
197 (png_infopp)NULL, (png_infopp)NULL);
198 return (ERROR);
199 }
200
201 png_infop end_info = png_create_info_struct(png_ptr);
202 if (!end_info)
203 {
204 png_destroy_read_struct(&png_ptr, &info_ptr,
205 (png_infopp)NULL);
206 return (ERROR);
207 }
208
209If you want to use your own memory allocation routines,
210define PNG_USER_MEM_SUPPORTED and use
211png_create_read_struct_2() instead of png_create_read_struct():
212
213 png_structp png_ptr = png_create_read_struct_2
214 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
215 user_error_fn, user_warning_fn, (png_voidp)
216 user_mem_ptr, user_malloc_fn, user_free_fn);
217
218The error handling routines passed to png_create_read_struct()
219and the memory alloc/free routines passed to png_create_struct_2()
220are only necessary if you are not using the libpng supplied error
221handling and memory alloc/free functions.
222
223When libpng encounters an error, it expects to longjmp back
224to your routine. Therefore, you will need to call setjmp and pass
225your png_jmpbuf(png_ptr). If you read the file from different
226routines, you will need to update the jmpbuf field every time you enter
227a new routine that will call a png_*() function.
228
229See your documentation of setjmp/longjmp for your compiler for more
230information on setjmp/longjmp. See the discussion on libpng error
231handling in the Customizing Libpng section below for more information
232on the libpng error handling. If an error occurs, and libpng longjmp's
233back to your setjmp, you will want to call png_destroy_read_struct() to
234free any memory.
235
236 if (setjmp(png_jmpbuf(png_ptr)))
237 {
238 png_destroy_read_struct(&png_ptr, &info_ptr,
239 &end_info);
240 fclose(fp);
241 return (ERROR);
242 }
243
244If you would rather avoid the complexity of setjmp/longjmp issues,
245you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
246errors will result in a call to PNG_ABORT() which defaults to abort().
247
248Now you need to set up the input code. The default for libpng is to
249use the C function fread(). If you use this, you will need to pass a
250valid FILE * in the function png_init_io(). Be sure that the file is
251opened in binary mode. If you wish to handle reading data in another
252way, you need not call the png_init_io() function, but you must then
253implement the libpng I/O methods discussed in the Customizing Libpng
254section below.
255
256 png_init_io(png_ptr, fp);
257
258If you had previously opened the file and read any of the signature from
259the beginning in order to see if this was a PNG file, you need to let
260libpng know that there are some bytes missing from the start of the file.
261
262 png_set_sig_bytes(png_ptr, number);
263
264Setting up callback code
265
266You can set up a callback function to handle any unknown chunks in the
267input stream. You must supply the function
268
269 read_chunk_callback(png_ptr ptr,
270 png_unknown_chunkp chunk);
271 {
272 /* The unknown chunk structure contains your
273 chunk data, along with similar data for any other
274 unknown chunks: */
275
276 png_byte name[5];
277 png_byte *data;
278 png_size_t size;
279
280 /* Note that libpng has already taken care of
281 the CRC handling */
282
283 /* put your code here. Search for your chunk in the
284 unknown chunk structure, process it, and return one
285 of the following: */
286
287 return (-n); /* chunk had an error */
288 return (0); /* did not recognize */
289 return (n); /* success */
290 }
291
292(You can give your function another name that you like instead of
293"read_chunk_callback")
294
295To inform libpng about your function, use
296
297 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
298 read_chunk_callback);
299
300This names not only the callback function, but also a user pointer that
301you can retrieve with
302
303 png_get_user_chunk_ptr(png_ptr);
304
305If you call the png_set_read_user_chunk_fn() function, then all unknown
306chunks will be saved when read, in case your callback function will need
307one or more of them. This behavior can be changed with the
308png_set_keep_unknown_chunks() function, described below.
309
310At this point, you can set up a callback function that will be
311called after each row has been read, which you can use to control
312a progress meter or the like. It's demonstrated in pngtest.c.
313You must supply a function
314
315 void read_row_callback(png_ptr ptr, png_uint_32 row,
316 int pass);
317 {
318 /* put your code here */
319 }
320
321(You can give it another name that you like instead of "read_row_callback")
322
323To inform libpng about your function, use
324
325 png_set_read_status_fn(png_ptr, read_row_callback);
326
327Unknown-chunk handling
328
329Now you get to set the way the library processes unknown chunks in the
330input PNG stream. Both known and unknown chunks will be read. Normal
331behavior is that known chunks will be parsed into information in
332various info_ptr members while unknown chunks will be discarded. This
333behavior can be wasteful if your application will never use some known
334chunk types. To change this, you can call:
335
336 png_set_keep_unknown_chunks(png_ptr, keep,
337 chunk_list, num_chunks);
338 keep - 0: default unknown chunk handling
339 1: ignore; do not keep
340 2: keep only if safe-to-copy
341 3: keep even if unsafe-to-copy
342 You can use these definitions:
343 PNG_HANDLE_CHUNK_AS_DEFAULT 0
344 PNG_HANDLE_CHUNK_NEVER 1
345 PNG_HANDLE_CHUNK_IF_SAFE 2
346 PNG_HANDLE_CHUNK_ALWAYS 3
347 chunk_list - list of chunks affected (a byte string,
348 five bytes per chunk, NULL or '\0' if
349 num_chunks is 0)
350 num_chunks - number of chunks affected; if 0, all
351 unknown chunks are affected. If nonzero,
352 only the chunks in the list are affected
353
354Unknown chunks declared in this way will be saved as raw data onto a
355list of png_unknown_chunk structures. If a chunk that is normally
356known to libpng is named in the list, it will be handled as unknown,
357according to the "keep" directive. If a chunk is named in successive
358instances of png_set_keep_unknown_chunks(), the final instance will
359take precedence. The IHDR and IEND chunks should not be named in
360chunk_list; if they are, libpng will process them normally anyway.
361
362Here is an example of the usage of png_set_keep_unknown_chunks(),
363where the private "vpAg" chunk will later be processed by a user chunk
364callback function:
365
366 png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'};
367
368 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
369 png_byte unused_chunks[]=
370 {
371 104, 73, 83, 84, (png_byte) '\0', /* hIST */
372 105, 84, 88, 116, (png_byte) '\0', /* iTXt */
373 112, 67, 65, 76, (png_byte) '\0', /* pCAL */
374 115, 67, 65, 76, (png_byte) '\0', /* sCAL */
375 115, 80, 76, 84, (png_byte) '\0', /* sPLT */
376 116, 73, 77, 69, (png_byte) '\0', /* tIME */
377 };
378 #endif
379
380 ...
381
382 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
383 /* ignore all unknown chunks: */
384 png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
385 /* except for vpAg: */
386 png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
387 /* also ignore unused known chunks: */
388 png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
389 (int)sizeof(unused_chunks)/5);
390 #endif
391
392User limits
393
394The PNG specification allows the width and height of an image to be as
395large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
396Since very few applications really need to process such large images,
397we have imposed an arbitrary 1-million limit on rows and columns.
398Larger images will be rejected immediately with a png_error() call. If
399you wish to override this limit, you can use
400
401 png_set_user_limits(png_ptr, width_max, height_max);
402
403to set your own limits, or use width_max = height_max = 0x7fffffffL
404to allow all valid dimensions (libpng may reject some very large images
405anyway because of potential buffer overflow conditions).
406
407You should put this statement after you create the PNG structure and
408before calling png_read_info(), png_read_png(), or png_process_data().
409If you need to retrieve the limits that are being applied, use
410
411 width_max = png_get_user_width_max(png_ptr);
412 height_max = png_get_user_height_max(png_ptr);
413
414The PNG specification sets no limit on the number of ancillary chunks
415allowed in a PNG datastream. You can impose a limit on the total number
416of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
417
418 png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
419
420where 0x7fffffffL means unlimited. You can retrieve this limit with
421
422 chunk_cache_max = png_get_chunk_cache_max(png_ptr);
423
424This limit also applies to the number of buffers that can be allocated
425by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
426
427The high-level read interface
428
429At this point there are two ways to proceed; through the high-level
430read interface, or through a sequence of low-level read operations.
431You can use the high-level interface if (a) you are willing to read
432the entire image into memory, and (b) the input transformations
433you want to do are limited to the following set:
434
435 PNG_TRANSFORM_IDENTITY No transformation
436 PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
437 8 bits
438 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
439 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
440 samples to bytes
441 PNG_TRANSFORM_PACKSWAP Change order of packed
442 pixels to LSB first
443 PNG_TRANSFORM_EXPAND Perform set_expand()
444 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
445 PNG_TRANSFORM_SHIFT Normalize pixels to the
446 sBIT depth
447 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
448 to BGRA
449 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
450 to AG
451 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
452 to transparency
453 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
454 PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
455 to RGB (or GA to RGBA)
456
457(This excludes setting a background color, doing gamma transformation,
458dithering, and setting filler.) If this is the case, simply do this:
459
460 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
461
462where png_transforms is an integer containing the bitwise OR of some
463set of transformation flags. This call is equivalent to png_read_info(),
464followed the set of transformations indicated by the transform mask,
465then png_read_image(), and finally png_read_end().
466
467(The final parameter of this call is not yet used. Someday it might point
468to transformation parameters required by some future input transform.)
469
470You must use png_transforms and not call any png_set_transform() functions
471when you use png_read_png().
472
473After you have called png_read_png(), you can retrieve the image data
474with
475
476 row_pointers = png_get_rows(png_ptr, info_ptr);
477
478where row_pointers is an array of pointers to the pixel data for each row:
479
480 png_bytep row_pointers[height];
481
482If you know your image size and pixel size ahead of time, you can allocate
483row_pointers prior to calling png_read_png() with
484
485 if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
486 png_error (png_ptr,
487 "Image is too tall to process in memory");
488 if (width > PNG_UINT_32_MAX/pixel_size)
489 png_error (png_ptr,
490 "Image is too wide to process in memory");
491 row_pointers = png_malloc(png_ptr,
492 height*png_sizeof(png_bytep));
493 for (int i=0; i<height, i++)
494 row_pointers[i]=NULL; /* security precaution */
495 for (int i=0; i<height, i++)
496 row_pointers[i]=png_malloc(png_ptr,
497 width*pixel_size);
498 png_set_rows(png_ptr, info_ptr, &row_pointers);
499
500Alternatively you could allocate your image in one big block and define
501row_pointers[i] to point into the proper places in your block.
502
503If you use png_set_rows(), the application is responsible for freeing
504row_pointers (and row_pointers[i], if they were separately allocated).
505
506If you don't allocate row_pointers ahead of time, png_read_png() will
507do it, and it'll be free'ed when you call png_destroy_*().
508
509The low-level read interface
510
511If you are going the low-level route, you are now ready to read all
512the file information up to the actual image data. You do this with a
513call to png_read_info().
514
515 png_read_info(png_ptr, info_ptr);
516
517This will process all chunks up to but not including the image data.
518
519Querying the info structure
520
521Functions are used to get the information from the info_ptr once it
522has been read. Note that these fields may not be completely filled
523in until png_read_end() has read the chunk data following the image.
524
525 png_get_IHDR(png_ptr, info_ptr, &width, &height,
526 &bit_depth, &color_type, &interlace_type,
527 &compression_type, &filter_method);
528
529 width - holds the width of the image
530 in pixels (up to 2^31).
531 height - holds the height of the image
532 in pixels (up to 2^31).
533 bit_depth - holds the bit depth of one of the
534 image channels. (valid values are
535 1, 2, 4, 8, 16 and depend also on
536 the color_type. See also
537 significant bits (sBIT) below).
538 color_type - describes which color/alpha channels
539 are present.
540 PNG_COLOR_TYPE_GRAY
541 (bit depths 1, 2, 4, 8, 16)
542 PNG_COLOR_TYPE_GRAY_ALPHA
543 (bit depths 8, 16)
544 PNG_COLOR_TYPE_PALETTE
545 (bit depths 1, 2, 4, 8)
546 PNG_COLOR_TYPE_RGB
547 (bit_depths 8, 16)
548 PNG_COLOR_TYPE_RGB_ALPHA
549 (bit_depths 8, 16)
550
551 PNG_COLOR_MASK_PALETTE
552 PNG_COLOR_MASK_COLOR
553 PNG_COLOR_MASK_ALPHA
554
555 filter_method - (must be PNG_FILTER_TYPE_BASE
556 for PNG 1.0, and can also be
557 PNG_INTRAPIXEL_DIFFERENCING if
558 the PNG datastream is embedded in
559 a MNG-1.0 datastream)
560 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
561 for PNG 1.0)
562 interlace_type - (PNG_INTERLACE_NONE or
563 PNG_INTERLACE_ADAM7)
564
565 Any or all of interlace_type, compression_type, or
566 filter_method can be NULL if you are
567 not interested in their values.
568
569 Note that png_get_IHDR() returns 32-bit data into
570 the application's width and height variables.
571 This is an unsafe situation if these are 16-bit
572 variables. In such situations, the
573 png_get_image_width() and png_get_image_height()
574 functions described below are safer.
575
576 width = png_get_image_width(png_ptr,
577 info_ptr);
578 height = png_get_image_height(png_ptr,
579 info_ptr);
580 bit_depth = png_get_bit_depth(png_ptr,
581 info_ptr);
582 color_type = png_get_color_type(png_ptr,
583 info_ptr);
584 filter_method = png_get_filter_type(png_ptr,
585 info_ptr);
586 compression_type = png_get_compression_type(png_ptr,
587 info_ptr);
588 interlace_type = png_get_interlace_type(png_ptr,
589 info_ptr);
590
591 channels = png_get_channels(png_ptr, info_ptr);
592 channels - number of channels of info for the
593 color type (valid values are 1 (GRAY,
594 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
595 4 (RGB_ALPHA or RGB + filler byte))
596 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
597 rowbytes - number of bytes needed to hold a row
598
599 signature = png_get_signature(png_ptr, info_ptr);
600 signature - holds the signature read from the
601 file (if any). The data is kept in
602 the same offset it would be if the
603 whole signature were read (i.e. if an
604 application had already read in 4
605 bytes of signature before starting
606 libpng, the remaining 4 bytes would
607 be in signature[4] through signature[7]
608 (see png_set_sig_bytes())).
609
610These are also important, but their validity depends on whether the chunk
611has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
612png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
613data has been read, or zero if it is missing. The parameters to the
614png_get_<chunk> are set directly if they are simple data types, or a
615pointer into the info_ptr is returned for any complex types.
616
617 png_get_PLTE(png_ptr, info_ptr, &palette,
618 &num_palette);
619 palette - the palette for the file
620 (array of png_color)
621 num_palette - number of entries in the palette
622
623 png_get_gAMA(png_ptr, info_ptr, &gamma);
624 gamma - the gamma the file is written
625 at (PNG_INFO_gAMA)
626
627 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
628 srgb_intent - the rendering intent (PNG_INFO_sRGB)
629 The presence of the sRGB chunk
630 means that the pixel data is in the
631 sRGB color space. This chunk also
632 implies specific values of gAMA and
633 cHRM.
634
635 png_get_iCCP(png_ptr, info_ptr, &name,
636 &compression_type, &profile, &proflen);
637 name - The profile name.
638 compression - The compression type; always
639 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
640 You may give NULL to this argument to
641 ignore it.
642 profile - International Color Consortium color
643 profile data. May contain NULs.
644 proflen - length of profile data in bytes.
645
646 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
647 sig_bit - the number of significant bits for
648 (PNG_INFO_sBIT) each of the gray,
649 red, green, and blue channels,
650 whichever are appropriate for the
651 given color type (png_color_16)
652
653 png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
654 &trans_values);
655 trans - array of transparent
656 entries for palette (PNG_INFO_tRNS)
657 trans_values - graylevel or color sample values of
658 the single transparent color for
659 non-paletted images (PNG_INFO_tRNS)
660 num_trans - number of transparent entries
661 (PNG_INFO_tRNS)
662
663 png_get_hIST(png_ptr, info_ptr, &hist);
664 (PNG_INFO_hIST)
665 hist - histogram of palette (array of
666 png_uint_16)
667
668 png_get_tIME(png_ptr, info_ptr, &mod_time);
669 mod_time - time image was last modified
670 (PNG_VALID_tIME)
671
672 png_get_bKGD(png_ptr, info_ptr, &background);
673 background - background color (PNG_VALID_bKGD)
674 valid 16-bit red, green and blue
675 values, regardless of color_type
676
677 num_comments = png_get_text(png_ptr, info_ptr,
678 &text_ptr, &num_text);
679 num_comments - number of comments
680 text_ptr - array of png_text holding image
681 comments
682 text_ptr[i].compression - type of compression used
683 on "text" PNG_TEXT_COMPRESSION_NONE
684 PNG_TEXT_COMPRESSION_zTXt
685 PNG_ITXT_COMPRESSION_NONE
686 PNG_ITXT_COMPRESSION_zTXt
687 text_ptr[i].key - keyword for comment. Must contain
688 1-79 characters.
689 text_ptr[i].text - text comments for current
690 keyword. Can be empty.
691 text_ptr[i].text_length - length of text string,
692 after decompression, 0 for iTXt
693 text_ptr[i].itxt_length - length of itxt string,
694 after decompression, 0 for tEXt/zTXt
695 text_ptr[i].lang - language of comment (empty
696 string for unknown).
697 text_ptr[i].lang_key - keyword in UTF-8
698 (empty string for unknown).
699 Note that the itxt_length, lang, and lang_key
700 members of the text_ptr structure only exist
701 when the library is built with iTXt chunk support.
702
703 num_text - number of comments (same as
704 num_comments; you can put NULL here
705 to avoid the duplication)
706 Note while png_set_text() will accept text, language,
707 and translated keywords that can be NULL pointers, the
708 structure returned by png_get_text will always contain
709 regular zero-terminated C strings. They might be
710 empty strings but they will never be NULL pointers.
711
712 num_spalettes = png_get_sPLT(png_ptr, info_ptr,
713 &palette_ptr);
714 palette_ptr - array of palette structures holding
715 contents of one or more sPLT chunks
716 read.
717 num_spalettes - number of sPLT chunks read.
718
719 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
720 &unit_type);
721 offset_x - positive offset from the left edge
722 of the screen
723 offset_y - positive offset from the top edge
724 of the screen
725 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
726
727 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
728 &unit_type);
729 res_x - pixels/unit physical resolution in
730 x direction
731 res_y - pixels/unit physical resolution in
732 x direction
733 unit_type - PNG_RESOLUTION_UNKNOWN,
734 PNG_RESOLUTION_METER
735
736 png_get_sCAL(png_ptr, info_ptr, &unit, &width,
737 &height)
738 unit - physical scale units (an integer)
739 width - width of a pixel in physical scale units
740 height - height of a pixel in physical scale units
741 (width and height are doubles)
742
743 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
744 &height)
745 unit - physical scale units (an integer)
746 width - width of a pixel in physical scale units
747 height - height of a pixel in physical scale units
748 (width and height are strings like "2.54")
749
750 num_unknown_chunks = png_get_unknown_chunks(png_ptr,
751 info_ptr, &unknowns)
752 unknowns - array of png_unknown_chunk
753 structures holding unknown chunks
754 unknowns[i].name - name of unknown chunk
755 unknowns[i].data - data of unknown chunk
756 unknowns[i].size - size of unknown chunk's data
757 unknowns[i].location - position of chunk in file
758
759 The value of "i" corresponds to the order in which the
760 chunks were read from the PNG file or inserted with the
761 png_set_unknown_chunks() function.
762
763The data from the pHYs chunk can be retrieved in several convenient
764forms:
765
766 res_x = png_get_x_pixels_per_meter(png_ptr,
767 info_ptr)
768 res_y = png_get_y_pixels_per_meter(png_ptr,
769 info_ptr)
770 res_x_and_y = png_get_pixels_per_meter(png_ptr,
771 info_ptr)
772 res_x = png_get_x_pixels_per_inch(png_ptr,
773 info_ptr)
774 res_y = png_get_y_pixels_per_inch(png_ptr,
775 info_ptr)
776 res_x_and_y = png_get_pixels_per_inch(png_ptr,
777 info_ptr)
778 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
779 info_ptr)
780
781 (Each of these returns 0 [signifying "unknown"] if
782 the data is not present or if res_x is 0;
783 res_x_and_y is 0 if res_x != res_y)
784
785The data from the oFFs chunk can be retrieved in several convenient
786forms:
787
788 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
789 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
790 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
791 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
792
793 (Each of these returns 0 [signifying "unknown" if both
794 x and y are 0] if the data is not present or if the
795 chunk is present but the unit is the pixel)
796
797For more information, see the png_info definition in png.h and the
798PNG specification for chunk contents. Be careful with trusting
799rowbytes, as some of the transformations could increase the space
800needed to hold a row (expand, filler, gray_to_rgb, etc.).
801See png_read_update_info(), below.
802
803A quick word about text_ptr and num_text. PNG stores comments in
804keyword/text pairs, one pair per chunk, with no limit on the number
805of text chunks, and a 2^31 byte limit on their size. While there are
806suggested keywords, there is no requirement to restrict the use to these
807strings. It is strongly suggested that keywords and text be sensible
808to humans (that's the point), so don't use abbreviations. Non-printing
809symbols are not allowed. See the PNG specification for more details.
810There is also no requirement to have text after the keyword.
811
812Keywords should be limited to 79 Latin-1 characters without leading or
813trailing spaces, but non-consecutive spaces are allowed within the
814keyword. It is possible to have the same keyword any number of times.
815The text_ptr is an array of png_text structures, each holding a
816pointer to a language string, a pointer to a keyword and a pointer to
817a text string. The text string, language code, and translated
818keyword may be empty or NULL pointers. The keyword/text
819pairs are put into the array in the order that they are received.
820However, some or all of the text chunks may be after the image, so, to
821make sure you have read all the text chunks, don't mess with these
822until after you read the stuff after the image. This will be
823mentioned again below in the discussion that goes with png_read_end().
824
825Input transformations
826
827After you've read the header information, you can set up the library
828to handle any special transformations of the image data. The various
829ways to transform the data will be described in the order that they
830should occur. This is important, as some of these change the color
831type and/or bit depth of the data, and some others only work on
832certain color types and bit depths. Even though each transformation
833checks to see if it has data that it can do something with, you should
834make sure to only enable a transformation if it will be valid for the
835data. For example, don't swap red and blue on grayscale data.
836
837The colors used for the background and transparency values should be
838supplied in the same format/depth as the current image data. They
839are stored in the same format/depth as the image data in a bKGD or tRNS
840chunk, so this is what libpng expects for this data. The colors are
841transformed to keep in sync with the image data when an application
842calls the png_read_update_info() routine (see below).
843
844Data will be decoded into the supplied row buffers packed into bytes
845unless the library has been told to transform it into another format.
846For example, 4 bit/pixel paletted or grayscale data will be returned
8472 pixels/byte with the leftmost pixel in the high-order bits of the
848byte, unless png_set_packing() is called. 8-bit RGB data will be stored
849in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
850is called to insert filler bytes, either before or after each RGB triplet.
85116-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
852byte of the color value first, unless png_set_strip_16() is called to
853transform it to regular RGB RGB triplets, or png_set_filler() or
854png_set_add alpha() is called to insert filler bytes, either before or
855after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
856be modified with
857png_set_filler(), png_set_add_alpha(), or png_set_strip_16().
858
859The following code transforms grayscale images of less than 8 to 8 bits,
860changes paletted images to RGB, and adds a full alpha channel if there is
861transparency information in a tRNS chunk. This is most useful on
862grayscale images with bit depths of 2 or 4 or if there is a multiple-image
863viewing application that wishes to treat all images in the same way.
864
865 if (color_type == PNG_COLOR_TYPE_PALETTE)
866 png_set_palette_to_rgb(png_ptr);
867
868 if (color_type == PNG_COLOR_TYPE_GRAY &&
869 bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
870
871 if (png_get_valid(png_ptr, info_ptr,
872 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
873
874These three functions are actually aliases for png_set_expand(), added
875in libpng version 1.0.4, with the function names expanded to improve code
876readability. In some future version they may actually do different
877things.
878
879As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
880added. It expands the sample depth without changing tRNS to alpha.
881
882As of libpng version 1.2.54, not all possible expansions are supported.
883
884In the following table, the 01 means grayscale with depth<8, 31 means
885indexed with depth<8, other numerals represent the color type, "T" means
886the tRNS chunk is present, A means an alpha channel is present, and O
887means tRNS or alpha is present but all pixels in the image are opaque.
888
889 FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
890 TO
891 01 -
892 31 -
893 0 1 -
894 0T -
895 0O -
896 2 GX -
897 2T -
898 2O -
899 3 1 -
900 3T -
901 3O -
902 4A T -
903 4O -
904 6A GX TX TX -
905 6O GX TX -
906
907Within the matrix,
908 "-" means the transformation is not supported.
909 "X" means the transformation is obtained by png_set_expand().
910 "1" means the transformation is obtained by
911 png_set_expand_gray_1_2_4_to_8
912 "G" means the transformation is obtained by
913 png_set_gray_to_rgb().
914 "P" means the transformation is obtained by
915 png_set_expand_palette_to_rgb().
916 "T" means the transformation is obtained by
917 png_set_tRNS_to_alpha().
918
919PNG can have files with 16 bits per channel. If you only can handle
9208 bits per channel, this will strip the pixels down to 8 bit.
921
922 if (bit_depth == 16)
923 png_set_strip_16(png_ptr);
924
925If, for some reason, you don't need the alpha channel on an image,
926and you want to remove it rather than combining it with the background
927(but the image author certainly had in mind that you *would* combine
928it with the background, so that's what you should probably do):
929
930 if (color_type & PNG_COLOR_MASK_ALPHA)
931 png_set_strip_alpha(png_ptr);
932
933In PNG files, the alpha channel in an image
934is the level of opacity. If you need the alpha channel in an image to
935be the level of transparency instead of opacity, you can invert the
936alpha channel (or the tRNS chunk data) after it's read, so that 0 is
937fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
938images) is fully transparent, with
939
940 png_set_invert_alpha(png_ptr);
941
942The PNG format only supports pixels with postmultiplied alpha.
943If you want to replace the pixels, after reading them, with pixels
944that have premultiplied color samples, you can do this with
945
946 png_set_premultiply_alpha(png_ptr);
947
948If you do this, any input with a tRNS chunk will be expanded to
949have an alpha channel.
950
951PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
952they can, resulting in, for example, 8 pixels per byte for 1 bit
953files. This code expands to 1 pixel per byte without changing the
954values of the pixels:
955
956 if (bit_depth < 8)
957 png_set_packing(png_ptr);
958
959PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
960stored in a PNG image have been "scaled" or "shifted" up to the next
961higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
962to 8 bits/sample in the range [0, 255]). However, it is also possible
963to convert the PNG pixel data back to the original bit depth of the
964image. This call reduces the pixels back down to the original bit depth:
965
966 png_color_8p sig_bit;
967
968 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
969 png_set_shift(png_ptr, sig_bit);
970
971PNG files store 3-color pixels in red, green, blue order. This code
972changes the storage of the pixels to blue, green, red:
973
974 if (color_type == PNG_COLOR_TYPE_RGB ||
975 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
976 png_set_bgr(png_ptr);
977
978PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
979into 4 or 8 bytes for windowing systems that need them in this format:
980
981 if (color_type == PNG_COLOR_TYPE_RGB)
982 png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
983
984where "filler" is the 8 or 16-bit number to fill with, and the location is
985either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
986you want the filler before the RGB or after. This transformation
987does not affect images that already have full alpha channels. To add an
988opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
989will generate RGBA pixels.
990
991Note that png_set_filler() does not change the color type. If you want
992to do that, you can add a true alpha channel with
993
994 if (color_type == PNG_COLOR_TYPE_RGB ||
995 color_type == PNG_COLOR_TYPE_GRAY)
996 png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
997
998where "filler" contains the alpha value to assign to each pixel.
999This function was added in libpng-1.2.7.
1000
1001If you are reading an image with an alpha channel, and you need the
1002data as ARGB instead of the normal PNG format RGBA:
1003
1004 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1005 png_set_swap_alpha(png_ptr);
1006
1007For some uses, you may want a grayscale image to be represented as
1008RGB. This code will do that conversion:
1009
1010 if (color_type == PNG_COLOR_TYPE_GRAY ||
1011 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1012 png_set_gray_to_rgb(png_ptr);
1013
1014Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
1015with alpha.
1016
1017 if (color_type == PNG_COLOR_TYPE_RGB ||
1018 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1019 png_set_rgb_to_gray_fixed(png_ptr, error_action,
1020 int red_weight, int green_weight);
1021
1022 error_action = 1: silently do the conversion
1023 error_action = 2: issue a warning if the original
1024 image has any pixel where
1025 red != green or red != blue
1026 error_action = 3: issue an error and abort the
1027 conversion if the original
1028 image has any pixel where
1029 red != green or red != blue
1030
1031 red_weight: weight of red component times 100000
1032 green_weight: weight of green component times 100000
1033 If either weight is negative, default
1034 weights (21268, 71514) are used.
1035
1036If you have set error_action = 1 or 2, you can
1037later check whether the image really was gray, after processing
1038the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1039It will return a png_byte that is zero if the image was gray or
10401 if there were any non-gray pixels. bKGD and sBIT data
1041will be silently converted to grayscale, using the green channel
1042data, regardless of the error_action setting.
1043
1044With red_weight+green_weight<=100000,
1045the normalized graylevel is computed:
1046
1047 int rw = red_weight * 65536;
1048 int gw = green_weight * 65536;
1049 int bw = 65536 - (rw + gw);
1050 gray = (rw*red + gw*green + bw*blue)/65536;
1051
1052The default values come from the PNG file cHRM chunk if present; otherwise, the
1053defaults correspond to the ITU-R recommendation 709, and also the sRGB color
1054space, as recommended in the Charles Poynton's Colour FAQ,
1055Copyright (c) 2006-11-28 Charles Poynton, in section 9:
1056
1057<http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9>
1058
1059 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1060
1061Libpng approximates this with
1062
1063 Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
1064
1065which can be expressed with integers as
1066
1067 Y = (6969 * R + 23434 * G + 2365 * B)/32768
1068
1069The calculation is done in a linear colorspace, if the image gamma
1070is known.
1071
1072If you have a grayscale and you are using png_set_expand_depth(),
1073png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to
1074a higher bit-depth, you must either supply the background color as a gray
1075value at the original file bit-depth (need_expand = 1) or else supply the
1076background color as an RGB triplet at the final, expanded bit depth
1077(need_expand = 0). Similarly, if you are reading a paletted image, you
1078must either supply the background color as a palette index (need_expand = 1)
1079or as an RGB triplet that may or may not be in the palette (need_expand = 0).
1080
1081 png_color_16 my_background;
1082 png_color_16p image_background;
1083
1084 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1085 png_set_background(png_ptr, image_background,
1086 PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
1087 else
1088 png_set_background(png_ptr, &my_background,
1089 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
1090
1091The png_set_background() function tells libpng to composite images
1092with alpha or simple transparency against the supplied background
1093color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
1094you may use this color, or supply another color more suitable for
1095the current display (e.g., the background color from a web page). You
1096need to tell libpng whether the color is in the gamma space of the
1097display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
1098(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
1099that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
1100know why anyone would use this, but it's here).
1101
1102To properly display PNG images on any kind of system, the application needs
1103to know what the display gamma is. Ideally, the user will know this, and
1104the application will allow them to set it. One method of allowing the user
1105to set the display gamma separately for each system is to check for a
1106SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be
1107correctly set.
1108
1109Note that display_gamma is the overall gamma correction required to produce
1110pleasing results, which depends on the lighting conditions in the surrounding
1111environment. In a dim or brightly lit room, no compensation other than
1112the physical gamma exponent of the monitor is needed, while in a dark room
1113a slightly smaller exponent is better.
1114
1115 double gamma, screen_gamma;
1116
1117 if (/* We have a user-defined screen
1118 gamma value */)
1119 {
1120 screen_gamma = user_defined_screen_gamma;
1121 }
1122 /* One way that applications can share the same
1123 screen gamma value */
1124 else if ((gamma_str = getenv("SCREEN_GAMMA"))
1125 != NULL)
1126 {
1127 screen_gamma = (double)atof(gamma_str);
1128 }
1129 /* If we don't have another value */
1130 else
1131 {
1132 screen_gamma = 2.2; /* A good guess for a
1133 PC monitor in a bright office or a dim room */
1134 screen_gamma = 2.0; /* A good guess for a
1135 PC monitor in a dark room */
1136 screen_gamma = 1.7 or 1.0; /* A good
1137 guess for Mac systems */
1138 }
1139
1140The png_set_gamma() function handles gamma transformations of the data.
1141Pass both the file gamma and the current screen_gamma. If the file does
1142not have a gamma value, you can pass one anyway if you have an idea what
1143it is (usually 0.45455 is a good guess for GIF images on PCs). Note
1144that file gammas are inverted from screen gammas. See the discussions
1145on gamma in the PNG specification for an excellent description of what
1146gamma is, and why all applications should support it. It is strongly
1147recommended that PNG viewers support gamma correction.
1148
1149 if (png_get_gAMA(png_ptr, info_ptr, &gamma))
1150 png_set_gamma(png_ptr, screen_gamma, gamma);
1151 else
1152 png_set_gamma(png_ptr, screen_gamma, 0.45455);
1153
1154If you need to reduce an RGB file to a paletted file, or if a paletted
1155file has more entries then will fit on your screen, png_set_dither()
1156will do that. Note that this is a simple match dither that merely
1157finds the closest color available. This should work fairly well with
1158optimized palettes, and fairly badly with linear color cubes. If you
1159pass a palette that is larger then maximum_colors, the file will
1160reduce the number of colors in the palette so it will fit into
1161maximum_colors. If there is a histogram, it will use it to make
1162more intelligent choices when reducing the palette. If there is no
1163histogram, it may not do as good a job.
1164
1165 if (color_type & PNG_COLOR_MASK_COLOR)
1166 {
1167 if (png_get_valid(png_ptr, info_ptr,
1168 PNG_INFO_PLTE))
1169 {
1170 png_uint_16p histogram = NULL;
1171
1172 png_get_hIST(png_ptr, info_ptr,
1173 &histogram);
1174 png_set_dither(png_ptr, palette, num_palette,
1175 max_screen_colors, histogram, 1);
1176 }
1177 else
1178 {
1179 png_color std_color_cube[MAX_SCREEN_COLORS] =
1180 { ... colors ... };
1181
1182 png_set_dither(png_ptr, std_color_cube,
1183 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1184 NULL,0);
1185 }
1186 }
1187
1188PNG files describe monochrome as black being zero and white being one.
1189The following code will reverse this (make black be one and white be
1190zero):
1191
1192 if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
1193 png_set_invert_mono(png_ptr);
1194
1195This function can also be used to invert grayscale and gray-alpha images:
1196
1197 if (color_type == PNG_COLOR_TYPE_GRAY ||
1198 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1199 png_set_invert_mono(png_ptr);
1200
1201PNG files store 16 bit pixels in network byte order (big-endian,
1202ie. most significant bits first). This code changes the storage to the
1203other way (little-endian, i.e. least significant bits first, the
1204way PCs store them):
1205
1206 if (bit_depth == 16)
1207 png_set_swap(png_ptr);
1208
1209If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1210need to change the order the pixels are packed into bytes, you can use:
1211
1212 if (bit_depth < 8)
1213 png_set_packswap(png_ptr);
1214
1215Finally, you can write your own transformation function if none of
1216the existing ones meets your needs. This is done by setting a callback
1217with
1218
1219 png_set_read_user_transform_fn(png_ptr,
1220 read_transform_fn);
1221
1222You must supply the function
1223
1224 void read_transform_fn(png_ptr ptr, row_info_ptr
1225 row_info, png_bytep data)
1226
1227See pngtest.c for a working example. Your function will be called
1228after all of the other transformations have been processed.
1229
1230You can also set up a pointer to a user structure for use by your
1231callback function, and you can inform libpng that your transform
1232function will change the number of channels or bit depth with the
1233function
1234
1235 png_set_user_transform_info(png_ptr, user_ptr,
1236 user_depth, user_channels);
1237
1238The user's application, not libpng, is responsible for allocating and
1239freeing any memory required for the user structure.
1240
1241You can retrieve the pointer via the function
1242png_get_user_transform_ptr(). For example:
1243
1244 voidp read_user_transform_ptr =
1245 png_get_user_transform_ptr(png_ptr);
1246
1247The last thing to handle is interlacing; this is covered in detail below,
1248but you must call the function here if you want libpng to handle expansion
1249of the interlaced image.
1250
1251 number_of_passes = png_set_interlace_handling(png_ptr);
1252
1253After setting the transformations, libpng can update your png_info
1254structure to reflect any transformations you've requested with this
1255call. This is most useful to update the info structure's rowbytes
1256field so you can use it to allocate your image memory. This function
1257will also update your palette with the correct screen_gamma and
1258background if these have been given with the calls above.
1259
1260 png_read_update_info(png_ptr, info_ptr);
1261
1262After you call png_read_update_info(), you can allocate any
1263memory you need to hold the image. The row data is simply
1264raw byte data for all forms of images. As the actual allocation
1265varies among applications, no example will be given. If you
1266are allocating one large chunk, you will need to build an
1267array of pointers to each row, as it will be needed for some
1268of the functions below.
1269
1270Reading image data
1271
1272After you've allocated memory, you can read the image data.
1273The simplest way to do this is in one function call. If you are
1274allocating enough memory to hold the whole image, you can just
1275call png_read_image() and libpng will read in all the image data
1276and put it in the memory area supplied. You will need to pass in
1277an array of pointers to each row.
1278
1279This function automatically handles interlacing, so you don't need
1280to call png_set_interlace_handling() or call this function multiple
1281times, or any of that other stuff necessary with png_read_rows().
1282
1283 png_read_image(png_ptr, row_pointers);
1284
1285where row_pointers is:
1286
1287 png_bytep row_pointers[height];
1288
1289You can point to void or char or whatever you use for pixels.
1290
1291If you don't want to read in the whole image at once, you can
1292use png_read_rows() instead. If there is no interlacing (check
1293interlace_type == PNG_INTERLACE_NONE), this is simple:
1294
1295 png_read_rows(png_ptr, row_pointers, NULL,
1296 number_of_rows);
1297
1298where row_pointers is the same as in the png_read_image() call.
1299
1300If you are doing this just one row at a time, you can do this with
1301a single row_pointer instead of an array of row_pointers:
1302
1303 png_bytep row_pointer = row;
1304 png_read_row(png_ptr, row_pointer, NULL);
1305
1306If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
1307get somewhat harder. The only current (PNG Specification version 1.2)
1308interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
1309is a somewhat complicated 2D interlace scheme, known as Adam7, that
1310breaks down an image into seven smaller images of varying size, based
1311on an 8x8 grid.
1312
1313libpng can fill out those images or it can give them to you "as is".
1314If you want them filled out, there are two ways to do that. The one
1315mentioned in the PNG specification is to expand each pixel to cover
1316those pixels that have not been read yet (the "rectangle" method).
1317This results in a blocky image for the first pass, which gradually
1318smooths out as more pixels are read. The other method is the "sparkle"
1319method, where pixels are drawn only in their final locations, with the
1320rest of the image remaining whatever colors they were initialized to
1321before the start of the read. The first method usually looks better,
1322but tends to be slower, as there are more pixels to put in the rows.
1323
1324If you don't want libpng to handle the interlacing details, just call
1325png_read_rows() seven times to read in all seven images. Each of the
1326images is a valid image by itself, or they can all be combined on an
13278x8 grid to form a single image (although if you intend to combine them
1328you would be far better off using the libpng interlace handling).
1329
1330The first pass will return an image 1/8 as wide as the entire image
1331(every 8th column starting in column 0) and 1/8 as high as the original
1332(every 8th row starting in row 0), the second will be 1/8 as wide
1333(starting in column 4) and 1/8 as high (also starting in row 0). The
1334third pass will be 1/4 as wide (every 4th pixel starting in column 0) and
13351/8 as high (every 8th row starting in row 4), and the fourth pass will
1336be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,
1337and every 4th row starting in row 0). The fifth pass will return an
1338image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),
1339while the sixth pass will be 1/2 as wide and 1/2 as high as the original
1340(starting in column 1 and row 0). The seventh and final pass will be as
1341wide as the original, and 1/2 as high, containing all of the odd
1342numbered scanlines. Phew!
1343
1344If you want libpng to expand the images, call this before calling
1345png_start_read_image() or png_read_update_info():
1346
1347 if (interlace_type == PNG_INTERLACE_ADAM7)
1348 number_of_passes
1349 = png_set_interlace_handling(png_ptr);
1350
1351This will return the number of passes needed. Currently, this
1352is seven, but may change if another interlace type is added.
1353This function can be called even if the file is not interlaced,
1354where it will return one pass.
1355
1356If you are not going to display the image after each pass, but are
1357going to wait until the entire image is read in, use the sparkle
1358effect. This effect is faster and the end result of either method
1359is exactly the same. If you are planning on displaying the image
1360after each pass, the "rectangle" effect is generally considered the
1361better looking one.
1362
1363If you only want the "sparkle" effect, just call png_read_rows() as
1364normal, with the third parameter NULL. Make sure you make pass over
1365the image number_of_passes times, and you don't change the data in the
1366rows between calls. You can change the locations of the data, just
1367not the data. Each pass only writes the pixels appropriate for that
1368pass, and assumes the data from previous passes is still valid.
1369
1370 png_read_rows(png_ptr, row_pointers, NULL,
1371 number_of_rows);
1372
1373If you only want the first effect (the rectangles), do the same as
1374before except pass the row buffer in the third parameter, and leave
1375the second parameter NULL.
1376
1377 png_read_rows(png_ptr, NULL, row_pointers,
1378 number_of_rows);
1379
1380Finishing a sequential read
1381
1382After you are finished reading the image through the
1383low-level interface, you can finish reading the file. If you are
1384interested in comments or time, which may be stored either before or
1385after the image data, you should pass the separate png_info struct if
1386you want to keep the comments from before and after the image
1387separate. If you are not interested, you can pass NULL.
1388
1389 png_read_end(png_ptr, end_info);
1390
1391When you are done, you can free all memory allocated by libpng like this:
1392
1393 png_destroy_read_struct(&png_ptr, &info_ptr,
1394 &end_info);
1395
1396It is also possible to individually free the info_ptr members that
1397point to libpng-allocated storage with the following function:
1398
1399 png_free_data(png_ptr, info_ptr, mask, seq)
1400 mask - identifies data to be freed, a mask
1401 containing the bitwise OR of one or
1402 more of
1403 PNG_FREE_PLTE, PNG_FREE_TRNS,
1404 PNG_FREE_HIST, PNG_FREE_ICCP,
1405 PNG_FREE_PCAL, PNG_FREE_ROWS,
1406 PNG_FREE_SCAL, PNG_FREE_SPLT,
1407 PNG_FREE_TEXT, PNG_FREE_UNKN,
1408 or simply PNG_FREE_ALL
1409 seq - sequence number of item to be freed
1410 (-1 for all items)
1411
1412This function may be safely called when the relevant storage has
1413already been freed, or has not yet been allocated, or was allocated
1414by the user and not by libpng, and will in those cases do nothing.
1415The "seq" parameter is ignored if only one item of the selected data
1416type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
1417are allowed for the data type identified in the mask, such as text or
1418sPLT, only the n'th item in the structure is freed, where n is "seq".
1419
1420The default behavior is only to free data that was allocated internally
1421by libpng. This can be changed, so that libpng will not free the data,
1422or so that it will free data that was allocated by the user with png_malloc()
1423or png_zalloc() and passed in via a png_set_*() function, with
1424
1425 png_data_freer(png_ptr, info_ptr, freer, mask)
1426 mask - which data elements are affected
1427 same choices as in png_free_data()
1428 freer - one of
1429 PNG_DESTROY_WILL_FREE_DATA
1430 PNG_SET_WILL_FREE_DATA
1431 PNG_USER_WILL_FREE_DATA
1432
1433This function only affects data that has already been allocated.
1434You can call this function after reading the PNG data but before calling
1435any png_set_*() functions, to control whether the user or the png_set_*()
1436function is responsible for freeing any existing data that might be present,
1437and again after the png_set_*() functions to control whether the user
1438or png_destroy_*() is supposed to free the data. When the user assumes
1439responsibility for libpng-allocated data, the application must use
1440png_free() to free it, and when the user transfers responsibility to libpng
1441for data that the user has allocated, the user must have used png_malloc()
1442or png_zalloc() to allocate it.
1443
1444If you allocated your row_pointers in a single block, as suggested above in
1445the description of the high level read interface, you must not transfer
1446responsibility for freeing it to the png_set_rows or png_read_destroy function,
1447because they would also try to free the individual row_pointers[i].
1448
1449If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
1450separately, do not transfer responsibility for freeing text_ptr to libpng,
1451because when libpng fills a png_text structure it combines these members with
1452the key member, and png_free_data() will free only text_ptr.key. Similarly,
1453if you transfer responsibility for free'ing text_ptr from libpng to your
1454application, your application must not separately free those members.
1455
1456The png_free_data() function will turn off the "valid" flag for anything
1457it frees. If you need to turn the flag off for a chunk that was freed by
1458your application instead of by libpng, you can use
1459
1460 png_set_invalid(png_ptr, info_ptr, mask);
1461 mask - identifies the chunks to be made invalid,
1462 containing the bitwise OR of one or
1463 more of
1464 PNG_INFO_gAMA, PNG_INFO_sBIT,
1465 PNG_INFO_cHRM, PNG_INFO_PLTE,
1466 PNG_INFO_tRNS, PNG_INFO_bKGD,
1467 PNG_INFO_hIST, PNG_INFO_pHYs,
1468 PNG_INFO_oFFs, PNG_INFO_tIME,
1469 PNG_INFO_pCAL, PNG_INFO_sRGB,
1470 PNG_INFO_iCCP, PNG_INFO_sPLT,
1471 PNG_INFO_sCAL, PNG_INFO_IDAT
1472
1473For a more compact example of reading a PNG image, see the file example.c.
1474
1475Reading PNG files progressively
1476
1477The progressive reader is slightly different then the non-progressive
1478reader. Instead of calling png_read_info(), png_read_rows(), and
1479png_read_end(), you make one call to png_process_data(), which calls
1480callbacks when it has the info, a row, or the end of the image. You
1481set up these callbacks with png_set_progressive_read_fn(). You don't
1482have to worry about the input/output functions of libpng, as you are
1483giving the library the data directly in png_process_data(). I will
1484assume that you have read the section on reading PNG files above,
1485so I will only highlight the differences (although I will show
1486all of the code).
1487
1488png_structp png_ptr;
1489png_infop info_ptr;
1490
1491 /* An example code fragment of how you would
1492 initialize the progressive reader in your
1493 application. */
1494 int
1495 initialize_png_reader()
1496 {
1497 png_ptr = png_create_read_struct
1498 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1499 user_error_fn, user_warning_fn);
1500 if (!png_ptr)
1501 return (ERROR);
1502 info_ptr = png_create_info_struct(png_ptr);
1503 if (!info_ptr)
1504 {
1505 png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
1506 (png_infopp)NULL);
1507 return (ERROR);
1508 }
1509
1510 if (setjmp(png_jmpbuf(png_ptr)))
1511 {
1512 png_destroy_read_struct(&png_ptr, &info_ptr,
1513 (png_infopp)NULL);
1514 return (ERROR);
1515 }
1516
1517 /* This one's new. You can provide functions
1518 to be called when the header info is valid,
1519 when each row is completed, and when the image
1520 is finished. If you aren't using all functions,
1521 you can specify NULL parameters. Even when all
1522 three functions are NULL, you need to call
1523 png_set_progressive_read_fn(). You can use
1524 any struct as the user_ptr (cast to a void pointer
1525 for the function call), and retrieve the pointer
1526 from inside the callbacks using the function
1527
1528 png_get_progressive_ptr(png_ptr);
1529
1530 which will return a void pointer, which you have
1531 to cast appropriately.
1532 */
1533 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
1534 info_callback, row_callback, end_callback);
1535
1536 return 0;
1537 }
1538
1539 /* A code fragment that you call as you receive blocks
1540 of data */
1541 int
1542 process_data(png_bytep buffer, png_uint_32 length)
1543 {
1544 if (setjmp(png_jmpbuf(png_ptr)))
1545 {
1546 png_destroy_read_struct(&png_ptr, &info_ptr,
1547 (png_infopp)NULL);
1548 return (ERROR);
1549 }
1550
1551 /* This one's new also. Simply give it a chunk
1552 of data from the file stream (in order, of
1553 course). On machines with segmented memory
1554 models machines, don't give it any more than
1555 64K. The library seems to run fine with sizes
1556 of 4K. Although you can give it much less if
1557 necessary (I assume you can give it chunks of
1558 1 byte, I haven't tried less then 256 bytes
1559 yet). When this function returns, you may
1560 want to display any rows that were generated
1561 in the row callback if you don't already do
1562 so there.
1563 */
1564 png_process_data(png_ptr, info_ptr, buffer, length);
1565 return 0;
1566 }
1567
1568 /* This function is called (as set by
1569 png_set_progressive_read_fn() above) when enough data
1570 has been supplied so all of the header has been
1571 read.
1572 */
1573 void
1574 info_callback(png_structp png_ptr, png_infop info)
1575 {
1576 /* Do any setup here, including setting any of
1577 the transformations mentioned in the Reading
1578 PNG files section. For now, you _must_ call
1579 either png_start_read_image() or
1580 png_read_update_info() after all the
1581 transformations are set (even if you don't set
1582 any). You may start getting rows before
1583 png_process_data() returns, so this is your
1584 last chance to prepare for that.
1585 */
1586 }
1587
1588 /* This function is called when each row of image
1589 data is complete */
1590 void
1591 row_callback(png_structp png_ptr, png_bytep new_row,
1592 png_uint_32 row_num, int pass)
1593 {
1594 /* If the image is interlaced, and you turned
1595 on the interlace handler, this function will
1596 be called for every row in every pass. Some
1597 of these rows will not be changed from the
1598 previous pass. When the row is not changed,
1599 the new_row variable will be NULL. The rows
1600 and passes are called in order, so you don't
1601 really need the row_num and pass, but I'm
1602 supplying them because it may make your life
1603 easier.
1604
1605 For the non-NULL rows of interlaced images,
1606 you must call png_progressive_combine_row()
1607 passing in the row and the old row. You can
1608 call this function for NULL rows (it will just
1609 return) and for non-interlaced images (it just
1610 does the memcpy for you) if it will make the
1611 code easier. Thus, you can just do this for
1612 all cases:
1613 */
1614
1615 png_progressive_combine_row(png_ptr, old_row,
1616 new_row);
1617
1618 /* where old_row is what was displayed for
1619 previously for the row. Note that the first
1620 pass (pass == 0, really) will completely cover
1621 the old row, so the rows do not have to be
1622 initialized. After the first pass (and only
1623 for interlaced images), you will have to pass
1624 the current row, and the function will combine
1625 the old row and the new row.
1626 */
1627 }
1628
1629 void
1630 end_callback(png_structp png_ptr, png_infop info)
1631 {
1632 /* This function is called after the whole image
1633 has been read, including any chunks after the
1634 image (up to and including the IEND). You
1635 will usually have the same info chunk as you
1636 had in the header, although some data may have
1637 been added to the comments and time fields.
1638
1639 Most people won't do much here, perhaps setting
1640 a flag that marks the image as finished.
1641 */
1642 }
1643
1644
1645
1646IV. Writing
1647
1648Much of this is very similar to reading. However, everything of
1649importance is repeated here, so you won't have to constantly look
1650back up in the reading section to understand writing.
1651
1652Setup
1653
1654You will want to do the I/O initialization before you get into libpng,
1655so if it doesn't work, you don't have anything to undo. If you are not
1656using the standard I/O functions, you will need to replace them with
1657custom writing functions. See the discussion under Customizing libpng.
1658
1659 FILE *fp = fopen(file_name, "wb");
1660 if (!fp)
1661 {
1662 return (ERROR);
1663 }
1664
1665Next, png_struct and png_info need to be allocated and initialized.
1666As these can be both relatively large, you may not want to store these
1667on the stack, unless you have stack space to spare. Of course, you
1668will want to check if they return NULL. If you are also reading,
1669you won't want to name your read structure and your write structure
1670both "png_ptr"; you can call them anything you like, such as
1671"read_ptr" and "write_ptr". Look at pngtest.c, for example.
1672
1673 png_structp png_ptr = png_create_write_struct
1674 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1675 user_error_fn, user_warning_fn);
1676 if (!png_ptr)
1677 return (ERROR);
1678
1679 png_infop info_ptr = png_create_info_struct(png_ptr);
1680 if (!info_ptr)
1681 {
1682 png_destroy_write_struct(&png_ptr,
1683 (png_infopp)NULL);
1684 return (ERROR);
1685 }
1686
1687If you want to use your own memory allocation routines,
1688define PNG_USER_MEM_SUPPORTED and use
1689png_create_write_struct_2() instead of png_create_write_struct():
1690
1691 png_structp png_ptr = png_create_write_struct_2
1692 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1693 user_error_fn, user_warning_fn, (png_voidp)
1694 user_mem_ptr, user_malloc_fn, user_free_fn);
1695
1696After you have these structures, you will need to set up the
1697error handling. When libpng encounters an error, it expects to
1698longjmp() back to your routine. Therefore, you will need to call
1699setjmp() and pass the png_jmpbuf(png_ptr). If you
1700write the file from different routines, you will need to update
1701the png_jmpbuf(png_ptr) every time you enter a new routine that will
1702call a png_*() function. See your documentation of setjmp/longjmp
1703for your compiler for more information on setjmp/longjmp. See
1704the discussion on libpng error handling in the Customizing Libpng
1705section below for more information on the libpng error handling.
1706
1707 if (setjmp(png_jmpbuf(png_ptr)))
1708 {
1709 png_destroy_write_struct(&png_ptr, &info_ptr);
1710 fclose(fp);
1711 return (ERROR);
1712 }
1713 ...
1714 return;
1715
1716If you would rather avoid the complexity of setjmp/longjmp issues,
1717you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
1718errors will result in a call to PNG_ABORT() which defaults to abort().
1719
1720Now you need to set up the output code. The default for libpng is to
1721use the C function fwrite(). If you use this, you will need to pass a
1722valid FILE * in the function png_init_io(). Be sure that the file is
1723opened in binary mode. Again, if you wish to handle writing data in
1724another way, see the discussion on libpng I/O handling in the Customizing
1725Libpng section below.
1726
1727 png_init_io(png_ptr, fp);
1728
1729If you are embedding your PNG into a datastream such as MNG, and don't
1730want libpng to write the 8-byte signature, or if you have already
1731written the signature in your application, use
1732
1733 png_set_sig_bytes(png_ptr, 8);
1734
1735to inform libpng that it should not write a signature.
1736
1737Write callbacks
1738
1739At this point, you can set up a callback function that will be
1740called after each row has been written, which you can use to control
1741a progress meter or the like. It's demonstrated in pngtest.c.
1742You must supply a function
1743
1744 void write_row_callback(png_ptr, png_uint_32 row,
1745 int pass);
1746 {
1747 /* put your code here */
1748 }
1749
1750(You can give it another name that you like instead of "write_row_callback")
1751
1752To inform libpng about your function, use
1753
1754 png_set_write_status_fn(png_ptr, write_row_callback);
1755
1756You now have the option of modifying how the compression library will
1757run. The following functions are mainly for testing, but may be useful
1758in some cases, like if you need to write PNG files extremely fast and
1759are willing to give up some compression, or if you want to get the
1760maximum possible compression at the expense of slower writing. If you
1761have no special needs in this area, let the library do what it wants by
1762not calling this function at all, as it has been tuned to deliver a good
1763speed/compression ratio. The second parameter to png_set_filter() is
1764the filter method, for which the only valid values are 0 (as of the
1765July 1999 PNG specification, version 1.2) or 64 (if you are writing
1766a PNG datastream that is to be embedded in a MNG datastream). The third
1767parameter is a flag that indicates which filter type(s) are to be tested
1768for each scanline. See the PNG specification for details on the specific
1769filter types.
1770
1771
1772 /* turn on or off filtering, and/or choose
1773 specific filters. You can use either a single
1774 PNG_FILTER_VALUE_NAME or the bitwise OR of one
1775 or more PNG_FILTER_NAME masks. */
1776 png_set_filter(png_ptr, 0,
1777 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
1778 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
1779 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
1780 PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |
1781 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
1782 PNG_ALL_FILTERS);
1783
1784If an application
1785wants to start and stop using particular filters during compression,
1786it should start out with all of the filters (to ensure that the previous
1787row of pixels will be stored in case it's needed later), and then add
1788and remove them after the start of compression.
1789
1790If you are writing a PNG datastream that is to be embedded in a MNG
1791datastream, the second parameter can be either 0 or 64.
1792
1793The png_set_compression_*() functions interface to the zlib compression
1794library, and should mostly be ignored unless you really know what you are
1795doing. The only generally useful call is png_set_compression_level()
1796which changes how much time zlib spends on trying to compress the image
1797data. See the Compression Library (zlib.h and algorithm.txt, distributed
1798with zlib) for details on the compression levels.
1799
1800 /* set the zlib compression level */
1801 png_set_compression_level(png_ptr,
1802 Z_BEST_COMPRESSION);
1803
1804 /* set other zlib parameters */
1805 png_set_compression_mem_level(png_ptr, 8);
1806 png_set_compression_strategy(png_ptr,
1807 Z_DEFAULT_STRATEGY);
1808 png_set_compression_window_bits(png_ptr, 15);
1809 png_set_compression_method(png_ptr, 8);
1810 png_set_compression_buffer_size(png_ptr, 8192)
1811
1812extern PNG_EXPORT(void,png_set_zbuf_size)
1813
1814Setting the contents of info for output
1815
1816You now need to fill in the png_info structure with all the data you
1817wish to write before the actual image. Note that the only thing you
1818are allowed to write after the image is the text chunks and the time
1819chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
1820the latest PNG specification for more information on that. If you
1821wish to write them before the image, fill them in now, and flag that
1822data as being valid. If you want to wait until after the data, don't
1823fill them until png_write_end(). For all the fields in png_info and
1824their data types, see png.h. For explanations of what the fields
1825contain, see the PNG specification.
1826
1827Some of the more important parts of the png_info are:
1828
1829 png_set_IHDR(png_ptr, info_ptr, width, height,
1830 bit_depth, color_type, interlace_type,
1831 compression_type, filter_method)
1832 width - holds the width of the image
1833 in pixels (up to 2^31).
1834 height - holds the height of the image
1835 in pixels (up to 2^31).
1836 bit_depth - holds the bit depth of one of the
1837 image channels.
1838 (valid values are 1, 2, 4, 8, 16
1839 and depend also on the
1840 color_type. See also significant
1841 bits (sBIT) below).
1842 color_type - describes which color/alpha
1843 channels are present.
1844 PNG_COLOR_TYPE_GRAY
1845 (bit depths 1, 2, 4, 8, 16)
1846 PNG_COLOR_TYPE_GRAY_ALPHA
1847 (bit depths 8, 16)
1848 PNG_COLOR_TYPE_PALETTE
1849 (bit depths 1, 2, 4, 8)
1850 PNG_COLOR_TYPE_RGB
1851 (bit_depths 8, 16)
1852 PNG_COLOR_TYPE_RGB_ALPHA
1853 (bit_depths 8, 16)
1854
1855 PNG_COLOR_MASK_PALETTE
1856 PNG_COLOR_MASK_COLOR
1857 PNG_COLOR_MASK_ALPHA
1858
1859 interlace_type - PNG_INTERLACE_NONE or
1860 PNG_INTERLACE_ADAM7
1861 compression_type - (must be
1862 PNG_COMPRESSION_TYPE_DEFAULT)
1863 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
1864 or, if you are writing a PNG to
1865 be embedded in a MNG datastream,
1866 can also be
1867 PNG_INTRAPIXEL_DIFFERENCING)
1868
1869If you call png_set_IHDR(), the call must appear before any of the
1870other png_set_*() functions, because they might require access to some of
1871the IHDR settings. The remaining png_set_*() functions can be called
1872in any order.
1873
1874If you wish, you can reset the compression_type, interlace_type, or
1875filter_method later by calling png_set_IHDR() again; if you do this, the
1876width, height, bit_depth, and color_type must be the same in each call.
1877
1878 png_set_PLTE(png_ptr, info_ptr, palette,
1879 num_palette);
1880 palette - the palette for the file
1881 (array of png_color)
1882 num_palette - number of entries in the palette
1883
1884 png_set_gAMA(png_ptr, info_ptr, gamma);
1885 gamma - the gamma the image was created
1886 at (PNG_INFO_gAMA)
1887
1888 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
1889 srgb_intent - the rendering intent
1890 (PNG_INFO_sRGB) The presence of
1891 the sRGB chunk means that the pixel
1892 data is in the sRGB color space.
1893 This chunk also implies specific
1894 values of gAMA and cHRM. Rendering
1895 intent is the CSS-1 property that
1896 has been defined by the International
1897 Color Consortium
1898 (http://www.color.org).
1899 It can be one of
1900 PNG_sRGB_INTENT_SATURATION,
1901 PNG_sRGB_INTENT_PERCEPTUAL,
1902 PNG_sRGB_INTENT_ABSOLUTE, or
1903 PNG_sRGB_INTENT_RELATIVE.
1904
1905
1906 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
1907 srgb_intent);
1908 srgb_intent - the rendering intent
1909 (PNG_INFO_sRGB) The presence of the
1910 sRGB chunk means that the pixel
1911 data is in the sRGB color space.
1912 This function also causes gAMA and
1913 cHRM chunks with the specific values
1914 that are consistent with sRGB to be
1915 written.
1916
1917 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
1918 profile, proflen);
1919 name - The profile name.
1920 compression - The compression type; always
1921 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1922 You may give NULL to this argument to
1923 ignore it.
1924 profile - International Color Consortium color
1925 profile data. May contain NULs.
1926 proflen - length of profile data in bytes.
1927
1928 png_set_sBIT(png_ptr, info_ptr, sig_bit);
1929 sig_bit - the number of significant bits for
1930 (PNG_INFO_sBIT) each of the gray, red,
1931 green, and blue channels, whichever are
1932 appropriate for the given color type
1933 (png_color_16)
1934
1935 png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
1936 trans_values);
1937 trans - array of transparent
1938 entries for palette (PNG_INFO_tRNS)
1939 trans_values - graylevel or color sample values
1940 (in order red, green, blue) of the
1941 single transparent color for
1942 non-paletted images (PNG_INFO_tRNS)
1943 num_trans - number of transparent entries
1944 (PNG_INFO_tRNS)
1945
1946 png_set_hIST(png_ptr, info_ptr, hist);
1947 (PNG_INFO_hIST)
1948 hist - histogram of palette (array of
1949 png_uint_16)
1950
1951 png_set_tIME(png_ptr, info_ptr, mod_time);
1952 mod_time - time image was last modified
1953 (PNG_VALID_tIME)
1954
1955 png_set_bKGD(png_ptr, info_ptr, background);
1956 background - background color (PNG_VALID_bKGD)
1957
1958 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
1959 text_ptr - array of png_text holding image
1960 comments
1961 text_ptr[i].compression - type of compression used
1962 on "text" PNG_TEXT_COMPRESSION_NONE
1963 PNG_TEXT_COMPRESSION_zTXt
1964 PNG_ITXT_COMPRESSION_NONE
1965 PNG_ITXT_COMPRESSION_zTXt
1966 text_ptr[i].key - keyword for comment. Must contain
1967 1-79 characters.
1968 text_ptr[i].text - text comments for current
1969 keyword. Can be NULL or empty.
1970 text_ptr[i].text_length - length of text string,
1971 after decompression, 0 for iTXt
1972 text_ptr[i].itxt_length - length of itxt string,
1973 after decompression, 0 for tEXt/zTXt
1974 text_ptr[i].lang - language of comment (NULL or
1975 empty for unknown).
1976 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
1977 or empty for unknown).
1978 Note that the itxt_length, lang, and lang_key
1979 members of the text_ptr structure only exist
1980 when the library is built with iTXt chunk support.
1981
1982 num_text - number of comments
1983
1984 png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
1985 num_spalettes);
1986 palette_ptr - array of png_sPLT_struct structures
1987 to be added to the list of palettes
1988 in the info structure.
1989 num_spalettes - number of palette structures to be
1990 added.
1991
1992 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
1993 unit_type);
1994 offset_x - positive offset from the left
1995 edge of the screen
1996 offset_y - positive offset from the top
1997 edge of the screen
1998 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1999
2000 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2001 unit_type);
2002 res_x - pixels/unit physical resolution
2003 in x direction
2004 res_y - pixels/unit physical resolution
2005 in y direction
2006 unit_type - PNG_RESOLUTION_UNKNOWN,
2007 PNG_RESOLUTION_METER
2008
2009 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
2010 unit - physical scale units (an integer)
2011 width - width of a pixel in physical scale units
2012 height - height of a pixel in physical scale units
2013 (width and height are doubles)
2014
2015 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2016 unit - physical scale units (an integer)
2017 width - width of a pixel in physical scale units
2018 height - height of a pixel in physical scale units
2019 (width and height are strings like "2.54")
2020
2021 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
2022 num_unknowns)
2023 unknowns - array of png_unknown_chunk
2024 structures holding unknown chunks
2025 unknowns[i].name - name of unknown chunk
2026 unknowns[i].data - data of unknown chunk
2027 unknowns[i].size - size of unknown chunk's data
2028 unknowns[i].location - position to write chunk in file
2029 0: do not write chunk
2030 PNG_HAVE_IHDR: before PLTE
2031 PNG_HAVE_PLTE: before IDAT
2032 PNG_AFTER_IDAT: after IDAT
2033
2034The "location" member is set automatically according to
2035what part of the output file has already been written.
2036You can change its value after calling png_set_unknown_chunks()
2037as demonstrated in pngtest.c. Within each of the "locations",
2038the chunks are sequenced according to their position in the
2039structure (that is, the value of "i", which is the order in which
2040the chunk was either read from the input file or defined with
2041png_set_unknown_chunks).
2042
2043A quick word about text and num_text. text is an array of png_text
2044structures. num_text is the number of valid structures in the array.
2045Each png_text structure holds a language code, a keyword, a text value,
2046and a compression type.
2047
2048The compression types have the same valid numbers as the compression
2049types of the image data. Currently, the only valid number is zero.
2050However, you can store text either compressed or uncompressed, unlike
2051images, which always have to be compressed. So if you don't want the
2052text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
2053Because tEXt and zTXt chunks don't have a language field, if you
2054specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
2055any language code or translated keyword will not be written out.
2056
2057Until text gets around 1000 bytes, it is not worth compressing it.
2058After the text has been written out to the file, the compression type
2059is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
2060so that it isn't written out again at the end (in case you are calling
2061png_write_end() with the same struct.
2062
2063The keywords that are given in the PNG Specification are:
2064
2065 Title Short (one line) title or
2066 caption for image
2067 Author Name of image's creator
2068 Description Description of image (possibly long)
2069 Copyright Copyright notice
2070 Creation Time Time of original image creation
2071 (usually RFC 1123 format, see below)
2072 Software Software used to create the image
2073 Disclaimer Legal disclaimer
2074 Warning Warning of nature of content
2075 Source Device used to create the image
2076 Comment Miscellaneous comment; conversion
2077 from other image format
2078
2079The keyword-text pairs work like this. Keywords should be short
2080simple descriptions of what the comment is about. Some typical
2081keywords are found in the PNG specification, as is some recommendations
2082on keywords. You can repeat keywords in a file. You can even write
2083some text before the image and some after. For example, you may want
2084to put a description of the image before the image, but leave the
2085disclaimer until after, so viewers working over modem connections
2086don't have to wait for the disclaimer to go over the modem before
2087they start seeing the image. Finally, keywords should be full
2088words, not abbreviations. Keywords and text are in the ISO 8859-1
2089(Latin-1) character set (a superset of regular ASCII) and can not
2090contain NUL characters, and should not contain control or other
2091unprintable characters. To make the comments widely readable, stick
2092with basic ASCII, and avoid machine specific character set extensions
2093like the IBM-PC character set. The keyword must be present, but
2094you can leave off the text string on non-compressed pairs.
2095Compressed pairs must have a text string, as only the text string
2096is compressed anyway, so the compression would be meaningless.
2097
2098PNG supports modification time via the png_time structure. Two
2099conversion routines are provided, png_convert_from_time_t() for
2100time_t and png_convert_from_struct_tm() for struct tm. The
2101time_t routine uses gmtime(). You don't have to use either of
2102these, but if you wish to fill in the png_time structure directly,
2103you should provide the time in universal time (GMT) if possible
2104instead of your local time. Note that the year number is the full
2105year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
2106that months start with 1.
2107
2108If you want to store the time of the original image creation, you should
2109use a plain tEXt chunk with the "Creation Time" keyword. This is
2110necessary because the "creation time" of a PNG image is somewhat vague,
2111depending on whether you mean the PNG file, the time the image was
2112created in a non-PNG format, a still photo from which the image was
2113scanned, or possibly the subject matter itself. In order to facilitate
2114machine-readable dates, it is recommended that the "Creation Time"
2115tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
2116although this isn't a requirement. Unlike the tIME chunk, the
2117"Creation Time" tEXt chunk is not expected to be automatically changed
2118by the software. To facilitate the use of RFC 1123 dates, a function
2119png_convert_to_rfc1123(png_timep) is provided to convert from PNG
2120time to an RFC 1123 format string.
2121
2122Writing unknown chunks
2123
2124You can use the png_set_unknown_chunks function to queue up chunks
2125for writing. You give it a chunk name, raw data, and a size; that's
2126all there is to it. The chunks will be written by the next following
2127png_write_info_before_PLTE, png_write_info, or png_write_end function.
2128Any chunks previously read into the info structure's unknown-chunk
2129list will also be written out in a sequence that satisfies the PNG
2130specification's ordering rules.
2131
2132The high-level write interface
2133
2134At this point there are two ways to proceed; through the high-level
2135write interface, or through a sequence of low-level write operations.
2136You can use the high-level interface if your image data is present
2137in the info structure. All defined output
2138transformations are permitted, enabled by the following masks.
2139
2140 PNG_TRANSFORM_IDENTITY No transformation
2141 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
2142 PNG_TRANSFORM_PACKSWAP Change order of packed
2143 pixels to LSB first
2144 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
2145 PNG_TRANSFORM_SHIFT Normalize pixels to the
2146 sBIT depth
2147 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
2148 to BGRA
2149 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
2150 to AG
2151 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
2152 to transparency
2153 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
2154 PNG_TRANSFORM_STRIP_FILLER Strip out filler
2155 bytes (deprecated).
2156 PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
2157 filler bytes
2158 PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing
2159 filler bytes
2160
2161If you have valid image data in the info structure (you can use
2162png_set_rows() to put image data in the info structure), simply do this:
2163
2164 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
2165
2166where png_transforms is an integer containing the bitwise OR of some set of
2167transformation flags. This call is equivalent to png_write_info(),
2168followed the set of transformations indicated by the transform mask,
2169then png_write_image(), and finally png_write_end().
2170
2171(The final parameter of this call is not yet used. Someday it might point
2172to transformation parameters required by some future output transform.)
2173
2174You must use png_transforms and not call any png_set_transform() functions
2175when you use png_write_png().
2176
2177The low-level write interface
2178
2179If you are going the low-level route instead, you are now ready to
2180write all the file information up to the actual image data. You do
2181this with a call to png_write_info().
2182
2183 png_write_info(png_ptr, info_ptr);
2184
2185Note that there is one transformation you may need to do before
2186png_write_info(). In PNG files, the alpha channel in an image is the
2187level of opacity. If your data is supplied as a level of transparency,
2188you can invert the alpha channel before you write it, so that 0 is
2189fully transparent and 255 (in 8-bit or paletted images) or 65535
2190(in 16-bit images) is fully opaque, with
2191
2192 png_set_invert_alpha(png_ptr);
2193
2194This must appear before png_write_info() instead of later with the
2195other transformations because in the case of paletted images the tRNS
2196chunk data has to be inverted before the tRNS chunk is written. If
2197your image is not a paletted image, the tRNS data (which in such cases
2198represents a single color to be rendered as transparent) won't need to
2199be changed, and you can safely do this transformation after your
2200png_write_info() call.
2201
2202If you need to write a private chunk that you want to appear before
2203the PLTE chunk when PLTE is present, you can write the PNG info in
2204two steps, and insert code to write your own chunk between them:
2205
2206 png_write_info_before_PLTE(png_ptr, info_ptr);
2207 png_set_unknown_chunks(png_ptr, info_ptr, ...);
2208 png_write_info(png_ptr, info_ptr);
2209
2210After you've written the file information, you can set up the library
2211to handle any special transformations of the image data. The various
2212ways to transform the data will be described in the order that they
2213should occur. This is important, as some of these change the color
2214type and/or bit depth of the data, and some others only work on
2215certain color types and bit depths. Even though each transformation
2216checks to see if it has data that it can do something with, you should
2217make sure to only enable a transformation if it will be valid for the
2218data. For example, don't swap red and blue on grayscale data.
2219
2220PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
2221the library to strip input data that has 4 or 8 bytes per pixel down
2222to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
2223bytes per pixel).
2224
2225 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
2226
2227where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
2228PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
2229is stored XRGB or RGBX.
2230
2231PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
2232they can, resulting in, for example, 8 pixels per byte for 1 bit files.
2233If the data is supplied at 1 pixel per byte, use this code, which will
2234correctly pack the pixels into a single byte:
2235
2236 png_set_packing(png_ptr);
2237
2238PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
2239data is of another bit depth, you can write an sBIT chunk into the
2240file so that decoders can recover the original data if desired.
2241
2242 /* Set the true bit depth of the image data */
2243 if (color_type & PNG_COLOR_MASK_COLOR)
2244 {
2245 sig_bit.red = true_bit_depth;
2246 sig_bit.green = true_bit_depth;
2247 sig_bit.blue = true_bit_depth;
2248 }
2249 else
2250 {
2251 sig_bit.gray = true_bit_depth;
2252 }
2253 if (color_type & PNG_COLOR_MASK_ALPHA)
2254 {
2255 sig_bit.alpha = true_bit_depth;
2256 }
2257
2258 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
2259
2260If the data is stored in the row buffer in a bit depth other than
2261one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
2262this will scale the values to appear to be the correct bit depth as
2263is required by PNG.
2264
2265 png_set_shift(png_ptr, &sig_bit);
2266
2267PNG files store 16 bit pixels in network byte order (big-endian,
2268ie. most significant bits first). This code would be used if they are
2269supplied the other way (little-endian, i.e. least significant bits
2270first, the way PCs store them):
2271
2272 if (bit_depth > 8)
2273 png_set_swap(png_ptr);
2274
2275If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2276need to change the order the pixels are packed into bytes, you can use:
2277
2278 if (bit_depth < 8)
2279 png_set_packswap(png_ptr);
2280
2281PNG files store 3 color pixels in red, green, blue order. This code
2282would be used if they are supplied as blue, green, red:
2283
2284 png_set_bgr(png_ptr);
2285
2286PNG files describe monochrome as black being zero and white being
2287one. This code would be used if the pixels are supplied with this reversed
2288(black being one and white being zero):
2289
2290 png_set_invert_mono(png_ptr);
2291
2292Finally, you can write your own transformation function if none of
2293the existing ones meets your needs. This is done by setting a callback
2294with
2295
2296 png_set_write_user_transform_fn(png_ptr,
2297 write_transform_fn);
2298
2299You must supply the function
2300
2301 void write_transform_fn(png_ptr ptr, row_info_ptr
2302 row_info, png_bytep data)
2303
2304See pngtest.c for a working example. Your function will be called
2305before any of the other transformations are processed.
2306
2307You can also set up a pointer to a user structure for use by your
2308callback function.
2309
2310 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
2311
2312The user_channels and user_depth parameters of this function are ignored
2313when writing; you can set them to zero as shown.
2314
2315You can retrieve the pointer via the function png_get_user_transform_ptr().
2316For example:
2317
2318 voidp write_user_transform_ptr =
2319 png_get_user_transform_ptr(png_ptr);
2320
2321It is possible to have libpng flush any pending output, either manually,
2322or automatically after a certain number of lines have been written. To
2323flush the output stream a single time call:
2324
2325 png_write_flush(png_ptr);
2326
2327and to have libpng flush the output stream periodically after a certain
2328number of scanlines have been written, call:
2329
2330 png_set_flush(png_ptr, nrows);
2331
2332Note that the distance between rows is from the last time png_write_flush()
2333was called, or the first row of the image if it has never been called.
2334So if you write 50 lines, and then png_set_flush 25, it will flush the
2335output on the next scanline, and every 25 lines thereafter, unless
2336png_write_flush() is called before 25 more lines have been written.
2337If nrows is too small (less than about 10 lines for a 640 pixel wide
2338RGB image) the image compression may decrease noticeably (although this
2339may be acceptable for real-time applications). Infrequent flushing will
2340only degrade the compression performance by a few percent over images
2341that do not use flushing.
2342
2343Writing the image data
2344
2345That's it for the transformations. Now you can write the image data.
2346The simplest way to do this is in one function call. If you have the
2347whole image in memory, you can just call png_write_image() and libpng
2348will write the image. You will need to pass in an array of pointers to
2349each row. This function automatically handles interlacing, so you don't
2350need to call png_set_interlace_handling() or call this function multiple
2351times, or any of that other stuff necessary with png_write_rows().
2352
2353 png_write_image(png_ptr, row_pointers);
2354
2355where row_pointers is:
2356
2357 png_byte *row_pointers[height];
2358
2359You can point to void or char or whatever you use for pixels.
2360
2361If you don't want to write the whole image at once, you can
2362use png_write_rows() instead. If the file is not interlaced,
2363this is simple:
2364
2365 png_write_rows(png_ptr, row_pointers,
2366 number_of_rows);
2367
2368row_pointers is the same as in the png_write_image() call.
2369
2370If you are just writing one row at a time, you can do this with
2371a single row_pointer instead of an array of row_pointers:
2372
2373 png_bytep row_pointer = row;
2374
2375 png_write_row(png_ptr, row_pointer);
2376
2377When the file is interlaced, things can get a good deal more complicated.
2378The only currently (as of the PNG Specification version 1.2, dated July
23791999) defined interlacing scheme for PNG files is the "Adam7" interlace
2380scheme, that breaks down an image into seven smaller images of varying
2381size. libpng will build these images for you, or you can do them
2382yourself. If you want to build them yourself, see the PNG specification
2383for details of which pixels to write when.
2384
2385If you don't want libpng to handle the interlacing details, just
2386use png_set_interlace_handling() and call png_write_rows() the
2387correct number of times to write all seven sub-images.
2388
2389If you want libpng to build the sub-images, call this before you start
2390writing any rows:
2391
2392 number_of_passes =
2393 png_set_interlace_handling(png_ptr);
2394
2395This will return the number of passes needed. Currently, this is seven,
2396but may change if another interlace type is added.
2397
2398Then write the complete image number_of_passes times.
2399
2400 png_write_rows(png_ptr, row_pointers,
2401 number_of_rows);
2402
2403As some of these rows are not used, and thus return immediately, you may
2404want to read about interlacing in the PNG specification, and only update
2405the rows that are actually used.
2406
2407Finishing a sequential write
2408
2409After you are finished writing the image, you should finish writing
2410the file. If you are interested in writing comments or time, you should
2411pass an appropriately filled png_info pointer. If you are not interested,
2412you can pass NULL.
2413
2414 png_write_end(png_ptr, info_ptr);
2415
2416When you are done, you can free all memory used by libpng like this:
2417
2418 png_destroy_write_struct(&png_ptr, &info_ptr);
2419
2420It is also possible to individually free the info_ptr members that
2421point to libpng-allocated storage with the following function:
2422
2423 png_free_data(png_ptr, info_ptr, mask, seq)
2424 mask - identifies data to be freed, a mask
2425 containing the bitwise OR of one or
2426 more of
2427 PNG_FREE_PLTE, PNG_FREE_TRNS,
2428 PNG_FREE_HIST, PNG_FREE_ICCP,
2429 PNG_FREE_PCAL, PNG_FREE_ROWS,
2430 PNG_FREE_SCAL, PNG_FREE_SPLT,
2431 PNG_FREE_TEXT, PNG_FREE_UNKN,
2432 or simply PNG_FREE_ALL
2433 seq - sequence number of item to be freed
2434 (-1 for all items)
2435
2436This function may be safely called when the relevant storage has
2437already been freed, or has not yet been allocated, or was allocated
2438by the user and not by libpng, and will in those cases do nothing.
2439The "seq" parameter is ignored if only one item of the selected data
2440type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
2441are allowed for the data type identified in the mask, such as text or
2442sPLT, only the n'th item in the structure is freed, where n is "seq".
2443
2444If you allocated data such as a palette that you passed in to libpng
2445with png_set_*, you must not free it until just before the call to
2446png_destroy_write_struct().
2447
2448The default behavior is only to free data that was allocated internally
2449by libpng. This can be changed, so that libpng will not free the data,
2450or so that it will free data that was allocated by the user with png_malloc()
2451or png_zalloc() and passed in via a png_set_*() function, with
2452
2453 png_data_freer(png_ptr, info_ptr, freer, mask)
2454 mask - which data elements are affected
2455 same choices as in png_free_data()
2456 freer - one of
2457 PNG_DESTROY_WILL_FREE_DATA
2458 PNG_SET_WILL_FREE_DATA
2459 PNG_USER_WILL_FREE_DATA
2460
2461For example, to transfer responsibility for some data from a read structure
2462to a write structure, you could use
2463
2464 png_data_freer(read_ptr, read_info_ptr,
2465 PNG_USER_WILL_FREE_DATA,
2466 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2467 png_data_freer(write_ptr, write_info_ptr,
2468 PNG_DESTROY_WILL_FREE_DATA,
2469 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2470
2471thereby briefly reassigning responsibility for freeing to the user but
2472immediately afterwards reassigning it once more to the write_destroy
2473function. Having done this, it would then be safe to destroy the read
2474structure and continue to use the PLTE, tRNS, and hIST data in the write
2475structure.
2476
2477This function only affects data that has already been allocated.
2478You can call this function before calling after the png_set_*() functions
2479to control whether the user or png_destroy_*() is supposed to free the data.
2480When the user assumes responsibility for libpng-allocated data, the
2481application must use
2482png_free() to free it, and when the user transfers responsibility to libpng
2483for data that the user has allocated, the user must have used png_malloc()
2484or png_zalloc() to allocate it.
2485
2486If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
2487separately, do not transfer responsibility for freeing text_ptr to libpng,
2488because when libpng fills a png_text structure it combines these members with
2489the key member, and png_free_data() will free only text_ptr.key. Similarly,
2490if you transfer responsibility for free'ing text_ptr from libpng to your
2491application, your application must not separately free those members.
2492For a more compact example of writing a PNG image, see the file example.c.
2493
2494V. Modifying/Customizing libpng:
2495
2496There are two issues here. The first is changing how libpng does
2497standard things like memory allocation, input/output, and error handling.
2498The second deals with more complicated things like adding new chunks,
2499adding new transformations, and generally changing how libpng works.
2500Both of those are compile-time issues; that is, they are generally
2501determined at the time the code is written, and there is rarely a need
2502to provide the user with a means of changing them.
2503
2504Memory allocation, input/output, and error handling
2505
2506All of the memory allocation, input/output, and error handling in libpng
2507goes through callbacks that are user-settable. The default routines are
2508in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
2509these functions, call the appropriate png_set_*_fn() function.
2510
2511Memory allocation is done through the functions png_malloc(), png_calloc(),
2512and png_free(). These currently just call the standard C functions.
2513png_calloc() calls png_malloc() and then png_memset() to clear the newly
2514allocated memory to zero. If your pointers can't access more then 64K
2515at a time, you will want to set MAXSEG_64K in zlib.h. Since it is
2516unlikely that the method of handling memory allocation on a platform
2517will change between applications, these functions must be modified in
2518the library at compile time. If you prefer to use a different method
2519of allocating and freeing data, you can use png_create_read_struct_2() or
2520png_create_write_struct_2() to register your own functions as described
2521above. These functions also provide a void pointer that can be retrieved
2522via
2523
2524 mem_ptr=png_get_mem_ptr(png_ptr);
2525
2526Your replacement memory functions must have prototypes as follows:
2527
2528 png_voidp malloc_fn(png_structp png_ptr,
2529 png_size_t size);
2530 void free_fn(png_structp png_ptr, png_voidp ptr);
2531
2532Your malloc_fn() must return NULL in case of failure. The png_malloc()
2533function will normally call png_error() if it receives a NULL from the
2534system memory allocator or from your replacement malloc_fn().
2535
2536Your free_fn() will never be called with a NULL ptr, since libpng's
2537png_free() checks for NULL before calling free_fn().
2538
2539Input/Output in libpng is done through png_read() and png_write(),
2540which currently just call fread() and fwrite(). The FILE * is stored in
2541png_struct and is initialized via png_init_io(). If you wish to change
2542the method of I/O, the library supplies callbacks that you can set
2543through the function png_set_read_fn() and png_set_write_fn() at run
2544time, instead of calling the png_init_io() function. These functions
2545also provide a void pointer that can be retrieved via the function
2546png_get_io_ptr(). For example:
2547
2548 png_set_read_fn(png_structp read_ptr,
2549 voidp read_io_ptr, png_rw_ptr read_data_fn)
2550
2551 png_set_write_fn(png_structp write_ptr,
2552 voidp write_io_ptr, png_rw_ptr write_data_fn,
2553 png_flush_ptr output_flush_fn);
2554
2555 voidp read_io_ptr = png_get_io_ptr(read_ptr);
2556 voidp write_io_ptr = png_get_io_ptr(write_ptr);
2557
2558The replacement I/O functions must have prototypes as follows:
2559
2560 void user_read_data(png_structp png_ptr,
2561 png_bytep data, png_size_t length);
2562 void user_write_data(png_structp png_ptr,
2563 png_bytep data, png_size_t length);
2564 void user_flush_data(png_structp png_ptr);
2565
2566The user_read_data() function is responsible for detecting and
2567handling end-of-data errors.
2568
2569Supplying NULL for the read, write, or flush functions sets them back
2570to using the default C stream functions, which expect the io_ptr to
2571point to a standard *FILE structure. It is probably a mistake
2572to use NULL for one of write_data_fn and output_flush_fn but not both
2573of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
2574It is an error to read from a write stream, and vice versa.
2575
2576Error handling in libpng is done through png_error() and png_warning().
2577Errors handled through png_error() are fatal, meaning that png_error()
2578should never return to its caller. Currently, this is handled via
2579setjmp() and longjmp() (unless you have compiled libpng with
2580PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
2581but you could change this to do things like exit() if you should wish.
2582
2583On non-fatal errors, png_warning() is called
2584to print a warning message, and then control returns to the calling code.
2585By default png_error() and png_warning() print a message on stderr via
2586fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
2587(because you don't want the messages) or PNG_NO_STDIO defined (because
2588fprintf() isn't available). If you wish to change the behavior of the error
2589functions, you will need to set up your own message callbacks. These
2590functions are normally supplied at the time that the png_struct is created.
2591It is also possible to redirect errors and warnings to your own replacement
2592functions after png_create_*_struct() has been called by calling:
2593
2594 png_set_error_fn(png_structp png_ptr,
2595 png_voidp error_ptr, png_error_ptr error_fn,
2596 png_error_ptr warning_fn);
2597
2598 png_voidp error_ptr = png_get_error_ptr(png_ptr);
2599
2600If NULL is supplied for either error_fn or warning_fn, then the libpng
2601default function will be used, calling fprintf() and/or longjmp() if a
2602problem is encountered. The replacement error functions should have
2603parameters as follows:
2604
2605 void user_error_fn(png_structp png_ptr,
2606 png_const_charp error_msg);
2607 void user_warning_fn(png_structp png_ptr,
2608 png_const_charp warning_msg);
2609
2610The motivation behind using setjmp() and longjmp() is the C++ throw and
2611catch exception handling methods. This makes the code much easier to write,
2612as there is no need to check every return code of every function call.
2613However, there are some uncertainties about the status of local variables
2614after a longjmp, so the user may want to be careful about doing anything
2615after setjmp returns non-zero besides returning itself. Consult your
2616compiler documentation for more details. For an alternative approach, you
2617may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
2618
2619Custom chunks
2620
2621If you need to read or write custom chunks, you may need to get deeper
2622into the libpng code. The library now has mechanisms for storing
2623and writing chunks of unknown type; you can even declare callbacks
2624for custom chunks. However, this may not be good enough if the
2625library code itself needs to know about interactions between your
2626chunk and existing `intrinsic' chunks.
2627
2628If you need to write a new intrinsic chunk, first read the PNG
2629specification. Acquire a first level of understanding of how it works.
2630Pay particular attention to the sections that describe chunk names,
2631and look at how other chunks were designed, so you can do things
2632similarly. Second, check out the sections of libpng that read and
2633write chunks. Try to find a chunk that is similar to yours and use
2634it as a template. More details can be found in the comments inside
2635the code. It is best to handle unknown chunks in a generic method,
2636via callback functions, instead of by modifying libpng functions.
2637
2638If you wish to write your own transformation for the data, look through
2639the part of the code that does the transformations, and check out some of
2640the simpler ones to get an idea of how they work. Try to find a similar
2641transformation to the one you want to add and copy off of it. More details
2642can be found in the comments inside the code itself.
2643
2644Configuring for 16 bit platforms
2645
2646You will want to look into zconf.h to tell zlib (and thus libpng) that
2647it cannot allocate more then 64K at a time. Even if you can, the memory
2648won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
2649
2650Configuring for DOS
2651
2652For DOS users who only have access to the lower 640K, you will
2653have to limit zlib's memory usage via a png_set_compression_mem_level()
2654call. See zlib.h or zconf.h in the zlib library for more information.
2655
2656Configuring for Medium Model
2657
2658Libpng's support for medium model has been tested on most of the popular
2659compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
2660defined, and FAR gets defined to far in pngconf.h, and you should be
2661all set. Everything in the library (except for zlib's structure) is
2662expecting far data. You must use the typedefs with the p or pp on
2663the end for pointers (or at least look at them and be careful). Make
2664note that the rows of data are defined as png_bytepp, which is an
2665unsigned char far * far *.
2666
2667Configuring for gui/windowing platforms:
2668
2669You will need to write new error and warning functions that use the GUI
2670interface, as described previously, and set them to be the error and
2671warning functions at the time that png_create_*_struct() is called,
2672in order to have them available during the structure initialization.
2673They can be changed later via png_set_error_fn(). On some compilers,
2674you may also have to change the memory allocators (png_malloc, etc.).
2675
2676Configuring for compiler xxx:
2677
2678All includes for libpng are in pngconf.h. If you need to add, change
2679or delete an include, this is the place to do it.
2680The includes that are not needed outside libpng are protected by the
2681PNG_INTERNAL definition, which is only defined for those routines inside
2682libpng itself. The files in libpng proper only include png.h, which
2683includes pngconf.h.
2684
2685Configuring zlib:
2686
2687There are special functions to configure the compression. Perhaps the
2688most useful one changes the compression level, which currently uses
2689input compression values in the range 0 - 9. The library normally
2690uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
2691have shown that for a large majority of images, compression values in
2692the range 3-6 compress nearly as well as higher levels, and do so much
2693faster. For online applications it may be desirable to have maximum speed
2694(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
2695specify no compression (Z_NO_COMPRESSION = 0), but this would create
2696files larger than just storing the raw bitmap. You can specify the
2697compression level by calling:
2698
2699 png_set_compression_level(png_ptr, level);
2700
2701Another useful one is to reduce the memory level used by the library.
2702The memory level defaults to 8, but it can be lowered if you are
2703short on memory (running DOS, for example, where you only have 640K).
2704Note that the memory level does have an effect on compression; among
2705other things, lower levels will result in sections of incompressible
2706data being emitted in smaller stored blocks, with a correspondingly
2707larger relative overhead of up to 15% in the worst case.
2708
2709 png_set_compression_mem_level(png_ptr, level);
2710
2711The other functions are for configuring zlib. They are not recommended
2712for normal use and may result in writing an invalid PNG file. See
2713zlib.h for more information on what these mean.
2714
2715 png_set_compression_strategy(png_ptr,
2716 strategy);
2717 png_set_compression_window_bits(png_ptr,
2718 window_bits);
2719 png_set_compression_method(png_ptr, method);
2720 png_set_compression_buffer_size(png_ptr, size);
2721
2722Controlling row filtering
2723
2724If you want to control whether libpng uses filtering or not, which
2725filters are used, and how it goes about picking row filters, you
2726can call one of these functions. The selection and configuration
2727of row filters can have a significant impact on the size and
2728encoding speed and a somewhat lesser impact on the decoding speed
2729of an image. Filtering is enabled by default for RGB and grayscale
2730images (with and without alpha), but not for paletted images nor
2731for any images with bit depths less than 8 bits/pixel.
2732
2733The 'method' parameter sets the main filtering method, which is
2734currently only '0' in the PNG 1.2 specification. The 'filters'
2735parameter sets which filter(s), if any, should be used for each
2736scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
2737to turn filtering on and off, respectively.
2738
2739Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
2740PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
2741ORed together with '|' to specify one or more filters to use.
2742These filters are described in more detail in the PNG specification.
2743If you intend to change the filter type during the course of writing
2744the image, you should start with flags set for all of the filters
2745you intend to use so that libpng can initialize its internal
2746structures appropriately for all of the filter types. (Note that this
2747means the first row must always be adaptively filtered, because libpng
2748currently does not allocate the filter buffers until png_write_row()
2749is called for the first time.)
2750
2751 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
2752 PNG_FILTER_UP | PNG_FILTER_AVG |
2753 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
2754
2755 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
2756 filters);
2757 The second parameter can also be
2758 PNG_INTRAPIXEL_DIFFERENCING if you are
2759 writing a PNG to be embedded in a MNG
2760 datastream. This parameter must be the
2761 same as the value of filter_method used
2762 in png_set_IHDR().
2763
2764Removing unwanted object code
2765
2766There are a bunch of #define's in pngconf.h that control what parts of
2767libpng are compiled. All the defines end in _SUPPORTED. If you are
2768never going to use a capability, you can change the #define to #undef
2769before recompiling libpng and save yourself code and data space, or
2770you can turn off individual capabilities with defines that begin with
2771PNG_NO_.
2772
2773You can also turn all of the transforms and ancillary chunk capabilities
2774off en masse with compiler directives that define
2775PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
2776or all four,
2777along with directives to turn on any of the capabilities that you do
2778want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
2779transformations but still leave the library fully capable of reading
2780and writing PNG files with all known public chunks. Use of the
2781PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
2782that is incapable of reading or writing ancillary chunks. If you are
2783not using the progressive reading capability, you can turn that off
2784with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
2785capability, which you'll still have).
2786
2787All the reading and writing specific code are in separate files, so the
2788linker should only grab the files it needs. However, if you want to
2789make sure, or if you are building a stand alone library, all the
2790reading files start with pngr and all the writing files start with
2791pngw. The files that don't match either (like png.c, pngtrans.c, etc.)
2792are used for both reading and writing, and always need to be included.
2793The progressive reader is in pngpread.c
2794
2795If you are creating or distributing a dynamically linked library (a .so
2796or DLL file), you should not remove or disable any parts of the library,
2797as this will cause applications linked with different versions of the
2798library to fail if they call functions not available in your library.
2799The size of the library itself should not be an issue, because only
2800those sections that are actually used will be loaded into memory.
2801
2802Requesting debug printout
2803
2804The macro definition PNG_DEBUG can be used to request debugging
2805printout. Set it to an integer value in the range 0 to 3. Higher
2806numbers result in increasing amounts of debugging information. The
2807information is printed to the "stderr" file, unless another file
2808name is specified in the PNG_DEBUG_FILE macro definition.
2809
2810When PNG_DEBUG > 0, the following functions (macros) become available:
2811
2812 png_debug(level, message)
2813 png_debug1(level, message, p1)
2814 png_debug2(level, message, p1, p2)
2815
2816in which "level" is compared to PNG_DEBUG to decide whether to print
2817the message, "message" is the formatted string to be printed,
2818and p1 and p2 are parameters that are to be embedded in the string
2819according to printf-style formatting directives. For example,
2820
2821 png_debug1(2, "foo=%d", foo);
2822
2823is expanded to
2824
2825 if(PNG_DEBUG > 2)
2826 fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
2827
2828When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
2829can still use PNG_DEBUG to control your own debugging:
2830
2831 #ifdef PNG_DEBUG
2832 fprintf(stderr, ...
2833 #endif
2834
2835When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
2836having level = 0 will be printed. There aren't any such statements in
2837this version of libpng, but if you insert some they will be printed.
2838
2839VI. MNG support
2840
2841The MNG specification (available at http://www.libpng.org/pub/mng) allows
2842certain extensions to PNG for PNG images that are embedded in MNG datastreams.
2843Libpng can support some of these extensions. To enable them, use the
2844png_permit_mng_features() function:
2845
2846 feature_set = png_permit_mng_features(png_ptr, mask)
2847 mask is a png_uint_32 containing the bitwise OR of the
2848 features you want to enable. These include
2849 PNG_FLAG_MNG_EMPTY_PLTE
2850 PNG_FLAG_MNG_FILTER_64
2851 PNG_ALL_MNG_FEATURES
2852 feature_set is a png_uint_32 that is the bitwise AND of
2853 your mask with the set of MNG features that is
2854 supported by the version of libpng that you are using.
2855
2856It is an error to use this function when reading or writing a standalone
2857PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
2858in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
2859and the MHDR and MEND chunks. Libpng does not provide support for these
2860or any other MNG chunks; your application must provide its own support for
2861them. You may wish to consider using libmng (available at
2862http://www.libmng.com) instead.
2863
2864VII. Changes to Libpng from version 0.88
2865
2866It should be noted that versions of libpng later than 0.96 are not
2867distributed by the original libpng author, Guy Schalnat, nor by
2868Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
2869distributed versions 0.89 through 0.96, but rather by another member
2870of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
2871still alive and well, but they have moved on to other things.
2872
2873The old libpng functions png_read_init(), png_write_init(),
2874png_info_init(), png_read_destroy(), and png_write_destroy() have been
2875moved to PNG_INTERNAL in version 0.95 to discourage their use. These
2876functions will be removed from libpng version 2.0.0.
2877
2878The preferred method of creating and initializing the libpng structures is
2879via the png_create_read_struct(), png_create_write_struct(), and
2880png_create_info_struct() because they isolate the size of the structures
2881from the application, allow version error checking, and also allow the
2882use of custom error handling routines during the initialization, which
2883the old functions do not. The functions png_read_destroy() and
2884png_write_destroy() do not actually free the memory that libpng
2885allocated for these structs, but just reset the data structures, so they
2886can be used instead of png_destroy_read_struct() and
2887png_destroy_write_struct() if you feel there is too much system overhead
2888allocating and freeing the png_struct for each image read.
2889
2890Setting the error callbacks via png_set_message_fn() before
2891png_read_init() as was suggested in libpng-0.88 is no longer supported
2892because this caused applications that do not use custom error functions
2893to fail if the png_ptr was not initialized to zero. It is still possible
2894to set the error callbacks AFTER png_read_init(), or to change them with
2895png_set_error_fn(), which is essentially the same function, but with a new
2896name to force compilation errors with applications that try to use the old
2897method.
2898
2899Support for the sCAL, iCCP, iTXt, and sPLT chunks was added at libpng-1.0.6;
2900however, iTXt support was not enabled by default.
2901
2902Starting with version 1.0.7, you can find out which version of the library
2903you are using at run-time:
2904
2905 png_uint_32 libpng_vn = png_access_version_number();
2906
2907The number libpng_vn is constructed from the major version, minor
2908version with leading zero, and release number with leading zero,
2909(e.g., libpng_vn for version 1.0.7 is 10007).
2910
2911You can also check which version of png.h you used when compiling your
2912application:
2913
2914 png_uint_32 application_vn = PNG_LIBPNG_VER;
2915
2916VIII. Changes to Libpng from version 1.0.x to 1.2.x
2917
2918Support for user memory management was enabled by default. To
2919accomplish this, the functions png_create_read_struct_2(),
2920png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
2921png_malloc_default(), and png_free_default() were added.
2922
2923Support for the iTXt chunk has been enabled by default as of
2924version 1.2.41.
2925
2926Support for certain MNG features was enabled.
2927
2928Support for numbered error messages was added. However, we never got
2929around to actually numbering the error messages. The function
2930png_set_strip_error_numbers() was added (Note: the prototype for this
2931function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
2932builds of libpng-1.2.15. It was restored in libpng-1.2.36).
2933
2934The png_malloc_warn() function was added at libpng-1.2.3. This issues
2935a png_warning and returns NULL instead of aborting when it fails to
2936acquire the requested memory allocation.
2937
2938Support for setting user limits on image width and height was enabled
2939by default. The functions png_set_user_limits(), png_get_user_width_max(),
2940and png_get_user_height_max() were added at libpng-1.2.6.
2941
2942The png_set_add_alpha() function was added at libpng-1.2.7.
2943
2944The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
2945Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
2946tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
2947deprecated.
2948
2949A number of macro definitions in support of runtime selection of
2950assembler code features (especially Intel MMX code support) were
2951added at libpng-1.2.0:
2952
2953 PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
2954 PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
2955 PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
2956 PNG_ASM_FLAG_MMX_READ_INTERLACE
2957 PNG_ASM_FLAG_MMX_READ_FILTER_SUB
2958 PNG_ASM_FLAG_MMX_READ_FILTER_UP
2959 PNG_ASM_FLAG_MMX_READ_FILTER_AVG
2960 PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
2961 PNG_ASM_FLAGS_INITIALIZED
2962 PNG_MMX_READ_FLAGS
2963 PNG_MMX_FLAGS
2964 PNG_MMX_WRITE_FLAGS
2965 PNG_MMX_FLAGS
2966
2967We added the following functions in support of runtime
2968selection of assembler code features:
2969
2970 png_get_mmx_flagmask()
2971 png_set_mmx_thresholds()
2972 png_get_asm_flags()
2973 png_get_mmx_bitdepth_threshold()
2974 png_get_mmx_rowbytes_threshold()
2975 png_set_asm_flags()
2976
2977We replaced all of these functions with simple stubs in libpng-1.2.20,
2978when the Intel assembler code was removed due to a licensing issue.
2979
2980These macros are deprecated:
2981
2982 PNG_READ_TRANSFORMS_NOT_SUPPORTED
2983 PNG_PROGRESSIVE_READ_NOT_SUPPORTED
2984 PNG_NO_SEQUENTIAL_READ_SUPPORTED
2985 PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
2986 PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
2987 PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
2988
2989They have been replaced, respectively, by:
2990
2991 PNG_NO_READ_TRANSFORMS
2992 PNG_NO_PROGRESSIVE_READ
2993 PNG_NO_SEQUENTIAL_READ
2994 PNG_NO_WRITE_TRANSFORMS
2995 PNG_NO_READ_ANCILLARY_CHUNKS
2996 PNG_NO_WRITE_ANCILLARY_CHUNKS
2997
2998PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
2999deprecated since libpng-1.0.16 and libpng-1.2.6.
3000
3001The function
3002 png_check_sig(sig, num)
3003was replaced with
3004 !png_sig_cmp(sig, 0, num)
3005It has been deprecated since libpng-0.90.
3006
3007The function
3008 png_set_gray_1_2_4_to_8()
3009which also expands tRNS to alpha was replaced with
3010 png_set_expand_gray_1_2_4_to_8()
3011which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
3012
3013IX. (Omitted)
3014
3015
3016Starting with libpng-1.2.54, attempting to set an over-length
3017PLTE chunk is an error. Previously this requirement of the PNG specification
3018was not enforced, and the palette was always limited to 256 entries.
3019An over-length PLTE chunk found in an input PNG is silently truncated.
3020
3021X. Detecting libpng
3022
3023The png_get_io_ptr() function has been present since libpng-0.88, has never
3024changed, and is unaffected by conditional compilation macros. It is the
3025best choice for use in configure scripts for detecting the presence of any
3026libpng version since 0.88. In an autoconf "configure.in" you could use
3027
3028 AC_CHECK_LIB(png, png_get_io_ptr, ...
3029
3030XI. Source code repository
3031
3032Since about February 2009, version 1.2.34, libpng has been under "git" source
3033control. The git repository was built from old libpng-x.y.z.tar.gz files
3034going back to version 0.70. You can access the git repository (read only)
3035at
3036
3037 git://git.code.sf.net/p/libpng/code
3038
3039or you can browse it with a web browser by selecting the "code" button at
3040
3041 https://sourceforge.net/projects/libpng/
3042
3043Patches can be sent to glennrp at users.sourceforge.net or to
3044png-mng-implement at lists.sourceforge.net or you can upload them to
3045the libpng bug tracker at
3046
3047 http://libpng.sourceforge.net
3048
3049XII. Coding style
3050
3051Our coding style is similar to the "Allman" style
3052(See http://en.wikipedia.org/wiki/Indent_style#Allman_style), with curly
3053braces on separate lines:
3054
3055 if (condition)
3056 {
3057 action;
3058 }
3059
3060 else if (another condition)
3061 {
3062 another action;
3063 }
3064
3065The braces can be omitted from simple one-line actions:
3066
3067 if (condition)
3068 return (0);
3069
3070We use 3-space indentation, except for continued statements which
3071are usually indented the same as the first line of the statement
3072plus four more spaces.
3073
3074For macro definitions we use 2-space indentation, always leaving the "#"
3075in the first column.
3076
3077 #ifndef PNG_NO_FEATURE
3078 # ifndef PNG_FEATURE_SUPPORTED
3079 # define PNG_FEATURE_SUPPORTED
3080 # endif
3081 #endif
3082
3083Comments appear with the leading "/*" at the same indentation as
3084the statement that follows the comment:
3085
3086 /* Single-line comment */
3087 statement;
3088
3089 /* Multiple-line
3090 * comment
3091 */
3092 statement;
3093
3094Very short comments can be placed at the end of the statement
3095to which they pertain:
3096
3097 statement; /* comment */
3098
3099We don't use C++ style ("//") comments. We have, however,
3100used them in the past in some now-abandoned MMX assembler
3101code.
3102
3103Functions and their curly braces are not indented, and
3104exported functions are marked with PNGAPI:
3105
3106 /* This is a public function that is visible to
3107 * application programers. It does thus-and-so.
3108 */
3109 void PNGAPI
3110 png_exported_function(png_ptr, png_info, foo)
3111 {
3112 body;
3113 }
3114
3115The prototypes for all exported functions appear in png.h,
3116above the comment that says
3117
3118 /* Maintainer: Put new public prototypes here ... */
3119
3120We mark all non-exported functions with "/* PRIVATE */"":
3121
3122 void /* PRIVATE */
3123 png_non_exported_function(png_ptr, png_info, foo)
3124 {
3125 body;
3126 }
3127
3128The prototypes for non-exported functions (except for those in
3129pngtest) appear in
3130the PNG_INTERNAL section of png.h
3131above the comment that says
3132
3133 /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
3134
3135The names of all exported functions and variables begin
3136with "png_", and all publicly visible C preprocessor
3137macros begin with "PNG".
3138
3139We put a space after each comma and after each semicolon
3140in "for" statments, and we put spaces before and after each
3141C binary operator and after "for" or "while". We don't
3142put a space between a typecast and the expression being
3143cast, nor do we put one between a function name and the
3144left parenthesis that follows it:
3145
3146 for (i = 2; i > 0; --i)
3147 y[i] = a(x) + (int)b;
3148
3149We prefer #ifdef and #ifndef to #if defined() and if !defined()
3150when there is only one macro being tested.
3151
3152We do not use the TAB character for indentation in the C sources.
3153
3154Lines do not exceed 80 characters.
3155
3156Other rules can be inferred by inspecting the libpng source.
3157
3158XIII. Y2K Compliance in libpng
3159
3160Since the PNG Development group is an ad-hoc body, we can't make
3161an official declaration.
3162
3163This is your unofficial assurance that libpng from version 0.71 and
3164upward through 1.2.54 are Y2K compliant. It is my belief that earlier
3165versions were also Y2K compliant.
3166
3167Libpng only has three year fields. One is a 2-byte unsigned integer that
3168will hold years up to 65535. The other two hold the date in text
3169format, and will hold years up to 9999.
3170
3171The integer is
3172 "png_uint_16 year" in png_time_struct.
3173
3174The strings are
3175 "png_charp time_buffer" in png_struct and
3176 "near_time_buffer", which is a local character string in png.c.
3177
3178There are seven time-related functions:
3179
3180 png_convert_to_rfc_1123() in png.c
3181 (formerly png_convert_to_rfc_1152() in error)
3182 png_convert_from_struct_tm() in pngwrite.c, called
3183 in pngwrite.c
3184 png_convert_from_time_t() in pngwrite.c
3185 png_get_tIME() in pngget.c
3186 png_handle_tIME() in pngrutil.c, called in pngread.c
3187 png_set_tIME() in pngset.c
3188 png_write_tIME() in pngwutil.c, called in pngwrite.c
3189
3190All appear to handle dates properly in a Y2K environment. The
3191png_convert_from_time_t() function calls gmtime() to convert from system
3192clock time, which returns (year - 1900), which we properly convert to
3193the full 4-digit year. There is a possibility that applications using
3194libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
3195function, or that they are incorrectly passing only a 2-digit year
3196instead of "year - 1900" into the png_convert_from_struct_tm() function,
3197but this is not under our control. The libpng documentation has always
3198stated that it works with 4-digit years, and the APIs have been
3199documented as such.
3200
3201The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
3202integer to hold the year, and can hold years as large as 65535.
3203
3204zlib, upon which libpng depends, is also Y2K compliant. It contains
3205no date-related code.
3206
3207
3208 Glenn Randers-Pehrson
3209 libpng maintainer
3210 PNG Development Group
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette