]> git.saurik.com Git - wxWidgets.git/blame_incremental - src/png/libpng.3
cleaned up the checkbox creation code (~70 lines of code became 3)
[wxWidgets.git] / src / png / libpng.3
... / ...
CommitLineData
1.TH LIBPNG 3 "January 14, 1999"
2.SH NAME
3libpng \- Portable Network Graphics (PNG) Reference Library 1.0.3 - January 14, 1999
4.SH SYNOPSIS
5
6#include <png.h>
7
8int png_check_sig (png_bytep sig, int num);
9
10void png_chunk_error (png_structp png_ptr, png_const_charp
11error);
12
13void png_chunk_warning (png_structp png_ptr, png_const_charp
14message);
15
16void png_convert_from_struct_tm (png_timep ptime, struct tm FAR
17* ttime);
18
19void png_convert_from_time_t (png_timep ptime, time_t ttime);
20
21png_charp png_convert_to_rfc1123 (png_structp png_ptr,
22png_timep ptime);
23
24png_infop png_create_info_struct (png_structp png_ptr);
25
26png_structp png_create_read_struct (png_const_charp
27user_png_ver, voidp error_ptr, png_error_ptr error_fn,
28png_error_ptr warn_fn);
29
30png_structp png_create_read_struct_2(png_const_charp user_png_ver,
31png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr
32warn_fn, png_voidp mem_ptr, png_malloc_ptr malloc_fn,
33png_free_ptr free_fn)
34
35png_structp png_create_write_struct (png_const_charp
36user_png_ver, voidp error_ptr, png_error_ptr error_fn,
37png_error_ptr warn_fn);
38
39png_structp png_create_write_struct_2(png_const_charp
40user_png_ver, png_voidp error_ptr, png_error_ptr error_fn,
41png_error_ptr warn_fn, png_voidp mem_ptr,
42png_malloc_ptr malloc_fn, png_free_ptr free_fn)
43
44int png_debug(int level, png_const_charp message)
45
46int png_debug1(int level, png_const_charp message, p1)
47
48int png_debug2(int level, png_const_charp message, p1, p2)
49
50void png_destroy_info_struct (png_structp png_ptr, png_infopp
51info_ptr_ptr);
52
53void png_destroy_read_struct (png_structpp png_ptr_ptr,
54png_infopp info_ptr_ptr, png_infopp end_info_ptr_ptr);
55
56void png_destroy_write_struct (png_structpp png_ptr_ptr,
57png_infopp info_ptr_ptr);
58
59void png_error (png_structp png_ptr, png_const_charp error);
60
61void png_free (png_structp png_ptr, png_voidp ptr);
62
63void png_free_default(png_structp png_ptr, png_voidp ptr)
64
65png_byte png_get_bit_depth (png_structp png_ptr, png_infop
66info_ptr);
67
68png_uint_32 png_get_bKGD (png_structp png_ptr, png_infop
69info_ptr, png_color_16p *background);
70
71png_byte png_get_channels (png_structp png_ptr, png_infop
72info_ptr);
73
74png_uint_32 png_get_cHRM (png_structp png_ptr, png_infop
75info_ptr, double *white_x, double *white_y, double *red_x,
76double *red_y, double *green_x, double *green_y, double
77*blue_x, double *blue_y);
78
79png_byte png_get_color_type (png_structp png_ptr, png_infop
80info_ptr);
81
82png_byte png_get_compression_type (png_structp png_ptr,
83png_infop info_ptr);
84
85png_byte png_get_copyright (png_structp png_ptr);
86
87png_voidp png_get_error_ptr (png_structp png_ptr);
88
89png_byte png_get_filter_type (png_structp png_ptr, png_infop
90info_ptr);
91
92png_uint_32 png_get_gAMA (png_structp png_ptr, png_infop
93info_ptr, double *file_gamma);
94
95png_byte png_get_header_version (png_structp png_ptr);
96
97png_uint_32 png_get_hIST (png_structp png_ptr, png_infop
98info_ptr, png_uint_16p *hist);
99
100png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop
101info_ptr, png_uint_32 *width, png_uint_32 *height, int
102*bit_depth, int *color_type, int *interlace_type, int
103*compression_type, int *filter_type);
104
105png_uint_32 png_get_image_height (png_structp png_ptr,
106png_infop info_ptr);
107
108png_uint_32 png_get_image_width (png_structp png_ptr, png_infop
109info_ptr);
110
111png_byte png_get_interlace_type (png_structp png_ptr, png_infop
112info_ptr);
113
114png_voidp png_get_io_ptr (png_structp png_ptr);
115
116png_voidp png_get_mem_ptr(png_structp png_ptr)
117
118png_uint_32 png_get_oFFs (png_structp png_ptr, png_infop
119info_ptr, png_uint_32 *offset_x, png_uint_32 *offset_y, int
120*unit_type);
121
122png_uint_32 png_get_pCAL (png_structp png_ptr, png_infop
123info_ptr, png_charp *purpose, png_int_32 *X0, png_int_32 *X1,
124int *type, int *nparams, png_charp *units, png_charpp *params);
125
126png_uint_32 png_get_pHYs (png_structp png_ptr, png_infop
127info_ptr, png_uint_32 *res_x, png_uint_32 *res_y, int
128*unit_type);
129
130float png_get_pixel_aspect_ratio (png_structp png_ptr,
131png_infop info_ptr);
132
133png_uint_32 png_get_pixels_per_meter (png_structp png_ptr,
134png_infop info_ptr);
135
136png_voidp png_get_progressive_ptr (png_structp png_ptr);
137
138png_uint_32 png_get_PLTE (png_structp png_ptr, png_infop
139info_ptr, png_colorp *palette, int *num_palette);
140
141png_byte png_get_rgb_to_gray_status (png_structp png_ptr)
142
143png_uint_32 png_get_rowbytes (png_structp png_ptr, png_infop
144info_ptr);
145
146png_uint_32 png_get_sBIT (png_structp png_ptr, png_infop
147info_ptr, png_color_8p *sig_bit);
148
149png_bytep png_get_signature (png_structp png_ptr, png_infop
150info_ptr);
151
152png_uint_32 png_get_sRGB (png_structp png_ptr, png_infop
153info_ptr, int *intent);
154
155png_uint_32 png_get_text (png_structp png_ptr, png_infop
156info_ptr, png_textp *text_ptr, int *num_text);
157
158png_uint_32 png_get_tIME (png_structp png_ptr, png_infop
159info_ptr, png_timep *mod_time);
160
161png_uint_32 png_get_tRNS (png_structp png_ptr, png_infop
162info_ptr, png_bytep *trans, int *num_trans, png_color_16p
163*trans_values);
164
165png_uint_32 png_get_valid (png_structp png_ptr, png_infop
166info_ptr, png_uint_32 flag);
167
168png_uint_32 png_get_x_offset_microns (png_structp png_ptr,
169png_infop info_ptr);
170
171png_uint_32 png_get_x_offset_pixels (png_structp png_ptr,
172png_infop info_ptr);
173
174png_uint_32 png_get_x_pixels_per_meter (png_structp png_ptr,
175png_infop info_ptr);
176
177png_uint_32 png_get_y_offset_microns (png_structp png_ptr,
178png_infop info_ptr);
179
180png_uint_32 png_get_y_offset_pixels (png_structp png_ptr,
181png_infop info_ptr);
182
183png_uint_32 png_get_y_pixels_per_meter (png_structp png_ptr,
184png_infop info_ptr);
185
186void png_info_init (png_infop info_ptr);
187
188void png_init_io (png_structp png_ptr, FILE *fp);
189
190png_voidp png_malloc (png_structp png_ptr, png_uint_32 size);
191
192png_voidp png_malloc_default(png_structp png_ptr,
193png_uint_32 size)
194
195voidp png_memcpy (png_voidp s1, png_voidp s2, png_size_t size);
196
197png_voidp png_memcpy_check (png_structp png_ptr, png_voidp s1,
198png_voidp s2, png_uint_32 size);
199
200voidp png_memset (png_voidp s1, int value, png_size_t size);
201
202png_voidp png_memset_check (png_structp png_ptr, png_voidp
203s1, int value, png_uint_32 size);
204
205void png_process_data (png_structp png_ptr, png_infop info_ptr,
206png_bytep buffer, png_size_t buffer_size);
207
208void png_progressive_combine_row (png_structp png_ptr,
209png_bytep old_row, png_bytep new_row);
210
211void png_read_destroy (png_structp png_ptr, png_infop info_ptr,
212png_infop end_info_ptr);
213
214void png_read_end (png_structp png_ptr, png_infop info_ptr);
215
216void png_read_image (png_structp png_ptr, png_bytepp image);
217
218void png_read_info (png_structp png_ptr, png_infop info_ptr);
219
220void png_read_row (png_structp png_ptr, png_bytep row,
221png_bytep display_row);
222
223void png_read_rows (png_structp png_ptr, png_bytepp row,
224png_bytepp display_row, png_uint_32 num_rows);
225
226void png_read_update_info (png_structp png_ptr, png_infop
227info_ptr);
228
229void png_set_background (png_structp png_ptr, png_color_16p
230background_color, int background_gamma_code, int need_expand,
231double background_gamma);
232
233void png_set_bgr (png_structp png_ptr);
234
235void png_set_bKGD (png_structp png_ptr, png_infop info_ptr,
236png_color_16p background);
237
238void png_set_cHRM (png_structp png_ptr, png_infop info_ptr,
239double white_x, double white_y, double red_x, double red_y,
240double green_x, double green_y, double blue_x, double blue_y);
241
242void png_set_compression_level (png_structp png_ptr, int
243level);
244
245void png_set_compression_mem_level (png_structp png_ptr, int
246mem_level);
247
248void png_set_compression_method (png_structp png_ptr, int
249method);
250
251void png_set_compression_strategy (png_structp png_ptr, int
252strategy);
253
254void png_set_compression_window_bits (png_structp png_ptr, int
255window_bits);
256
257void png_set_crc_action (png_structp png_ptr, int crit_action,
258int ancil_action);
259
260void png_set_dither (png_structp png_ptr, png_colorp palette,
261int num_palette, int maximum_colors, png_uint_16p histogram,
262int full_dither);
263
264void png_set_error_fn (png_structp png_ptr, png_voidp
265error_ptr, png_error_ptr error_fn, png_error_ptr warning_fn);
266
267void png_set_expand (png_structp png_ptr);
268
269void png_set_filler (png_structp png_ptr, png_uint_32 filler,
270int flags);
271
272void png_set_filter (png_structp png_ptr, int method, int
273filters);
274
275void png_set_filter_heuristics (png_structp png_ptr, int
276heuristic_method, int num_weights, png_doublep filter_weights,
277png_doublep filter_costs);
278
279void png_set_flush (png_structp png_ptr, int nrows);
280
281void png_set_gamma (png_structp png_ptr, double screen_gamma,
282double default_file_gamma);
283
284void png_set_gAMA (png_structp png_ptr, png_infop info_ptr,
285double file_gamma);
286
287void png_set_gray_to_rgb (png_structp png_ptr);
288
289void png_set_hIST (png_structp png_ptr, png_infop info_ptr,
290png_uint_16p hist);
291
292int png_set_interlace_handling (png_structp png_ptr);
293
294void png_set_invert_alpha (png_structp png_ptr);
295
296void png_set_invert_mono (png_structp png_ptr);
297
298void png_set_IHDR (png_structp png_ptr, png_infop info_ptr,
299png_uint_32 width, png_uint_32 height, int bit_depth, int
300color_type, int interlace_type, int compression_type, int
301filter_type);
302
303void png_set_mem_fn(png_structp png_ptr, png_voidp mem_ptr,
304png_malloc_ptr malloc_fn, png_free_ptr free_fn)
305
306void png_set_oFFs (png_structp png_ptr, png_infop info_ptr,
307png_uint_32 offset_x, png_uint_32 offset_y, int unit_type);
308
309void png_set_packing (png_structp png_ptr);
310
311void png_set_packswap (png_structp png_ptr);
312
313void png_set_pCAL (png_structp png_ptr, png_infop info_ptr,
314png_charp purpose, png_int_32 X0, png_int_32 X1, int type, int
315nparams, png_charp units, png_charpp params);
316
317void png_set_pHYs (png_structp png_ptr, png_infop info_ptr,
318png_uint_32 res_x, png_uint_32 res_y, int unit_type);
319
320void png_set_progressive_read_fn (png_structp png_ptr,
321png_voidp progressive_ptr, png_progressive_info_ptr info_fn,
322png_progressive_row_ptr row_fn, png_progressive_end_ptr
323end_fn);
324
325void png_set_PLTE (png_structp png_ptr, png_infop info_ptr,
326png_colorp palette, int num_palette);
327
328void png_set_read_fn (png_structp png_ptr, png_voidp io_ptr,
329png_rw_ptr read_data_fn);
330
331void png_set_read_status_fn (png_structp png_ptr, png_read_status_ptr
332read_row_fn);
333
334void png_set_read_user_transform_fn (png_structp png_ptr,
335png_user_transform_ptr read_user_transform_fn);
336
337void png_set_rgb_to_gray (png_structp png_ptr, int error_action);
338
339void png_set_sBIT (png_structp png_ptr, png_infop info_ptr,
340png_color_8p sig_bit);
341
342void png_set_shift (png_structp png_ptr, png_color_8p
343true_bits);
344
345void png_set_sig_bytes (png_structp png_ptr, int num_bytes);
346
347void png_set_sRGB (png_structp png_ptr, png_infop info_ptr, int
348intent);
349
350void png_set_sRGB_gAMA_and_cHRM (png_structp png_ptr, png_infop
351info_ptr, int intent);
352
353void png_set_strip_16 (png_structp png_ptr);
354
355void png_set_strip_alpha (png_structp png_ptr);
356
357void png_set_swap (png_structp png_ptr);
358
359void png_set_swap_alpha (png_structp png_ptr);
360
361void png_set_text (png_structp png_ptr, png_infop info_ptr,
362png_textp text_ptr, int num_text);
363
364void png_set_tIME (png_structp png_ptr, png_infop info_ptr,
365png_timep mod_time);
366
367void png_set_tRNS (png_structp png_ptr, png_infop info_ptr,
368png_bytep trans, int num_trans, png_color_16p trans_values);
369
370void png_set_write_fn (png_structp png_ptr, png_voidp io_ptr,
371png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn);
372
373void png_set_write_status_fn (png_structp png_ptr, png_write_status_ptr
374write_row_fn);
375
376void png_set_write_user_transform_fn (png_structp png_ptr,
377png_user_transform_ptr write_user_transform_fn);
378
379int png_sig_cmp (png_bytep sig, png_size_t start, png_size_t
380num_to_check);
381
382void png_start_read_image (png_structp png_ptr);
383
384void png_warning (png_structp png_ptr, png_const_charp
385message);
386
387void png_write_chunk (png_structp png_ptr, png_bytep
388chunk_name, png_bytep data, png_size_t length);
389
390void png_write_chunk_data (png_structp png_ptr, png_bytep data,
391png_size_t length);
392
393void png_write_chunk_end (png_structp png_ptr);
394
395void png_write_chunk_start (png_structp png_ptr, png_bytep
396chunk_name, png_uint_32 length);
397
398void png_write_destroy (png_structp png_ptr);
399
400void png_write_destroy_info (png_infop info_ptr);
401
402void png_write_end (png_structp png_ptr, png_infop info_ptr);
403
404void png_write_flush (png_structp png_ptr);
405
406void png_write_image (png_structp png_ptr, png_bytepp image);
407
408void png_write_info (png_structp png_ptr, png_infop info_ptr);
409
410void png_write_row (png_structp png_ptr, png_bytep row);
411
412void png_write_rows (png_structp png_ptr, png_bytepp row,
413png_uint_32 num_rows);
414
415.SH DESCRIPTION
416The
417.I libpng
418library supports encoding, decoding, and various manipulations of
419the Portable Network Graphics (PNG) format image files. It uses the
420.IR zlib(3)
421compression library.
422Following is a copy of the libpng.txt file that accompanies libpng.
423.SH LIBPNG.TXT
424libpng.txt - A description on how to use and modify libpng
425
426 libpng version 1.0.3 - January 14, 1999
427 Updated and distributed by Glenn Randers-Pehrson
428 <randeg@alumni.rpi.edu>
429 Copyright (c) 1998, 1999 Glenn Randers-Pehrson
430 For conditions of distribution and use, see copyright
431 notice in png.h.
432
433 based on:
434
435 libpng 1.0 beta 6 version 0.96 May 28, 1997
436 Updated and distributed by Andreas Dilger
437 Copyright (c) 1996, 1997 Andreas Dilger
438
439 libpng 1.0 beta 2 - version 0.88 January 26, 1996
440 For conditions of distribution and use, see copyright
441 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
442 Schalnat, Group 42, Inc.
443
444 Updated/rewritten per request in the libpng FAQ
445 Copyright (c) 1995 Frank J. T. Wojcik
446 December 18, 1995 && January 20, 1996
447
448.SH I. Introduction
449
450This file describes how to use and modify the PNG reference library
451(known as libpng) for your own use. There are five sections to this
452file: introduction, structures, reading, writing, and modification and
453configuration notes for various special platforms. In addition to this
454file, example.c is a good starting point for using the library, as
455it is heavily commented and should include everything most people
456will need. We assume that libpng is already installed; see the
457INSTALL file for instructions on how to install libpng.
458
459Libpng was written as a companion to the PNG specification, as a way
460of reducing the amount of time and effort it takes to support the PNG
461file format in application programs. The PNG specification is available
462as RFC 2083 <ftp://ftp.uu.net/graphics/png/documents/> and as a
463W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some
464additional chunks are described in the special-purpose public chunks
465documents at <ftp://ftp.uu.net/graphics/png/documents/>. Other information
466about PNG, and the latest version of libpng, can be found at the PNG home
467page, <http://www.cdrom.com/pub/png/>.
468
469Most users will not have to modify the library significantly; advanced
470users may want to modify it more. All attempts were made to make it as
471complete as possible, while keeping the code easy to understand.
472Currently, this library only supports C. Support for other languages
473is being considered.
474
475Libpng has been designed to handle multiple sessions at one time,
476to be easily modifiable, to be portable to the vast majority of
477machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
478to use. The ultimate goal of libpng is to promote the acceptance of
479the PNG file format in whatever way possible. While there is still
480work to be done (see the TODO file), libpng should cover the
481majority of the needs of its users.
482
483Libpng uses zlib for its compression and decompression of PNG files.
484Further information about zlib, and the latest version of zlib, can
485be found at the zlib home page, <http://www.cdrom.com/pub/infozip/zlib/>.
486The zlib compression utility is a general purpose utility that is
487useful for more than PNG files, and can be used without libpng.
488See the documentation delivered with zlib for more details.
489You can usually find the source files for the zlib utility wherever you
490find the libpng source files.
491
492Libpng is thread safe, provided the threads are using different
493instances of the structures. Each thread should have its own
494png_struct and png_info instances, and thus its own image.
495Libpng does not protect itself against two threads using the
496same instance of a structure.
497
498
499.SH II. Structures
500
501There are two main structures that are important to libpng, png_struct
502and png_info. The first, png_struct, is an internal structure that
503will not, for the most part, be used by a user except as the first
504variable passed to every libpng function call.
505
506The png_info structure is designed to provide information about the
507PNG file. At one time, the fields of png_info were intended to be
508directly accessible to the user. However, this tended to cause problems
509with applications using dynamically loaded libraries, and as a result
510a set of interface functions for png_info was developed. The fields
511of png_info are still available for older applications, but it is
512suggested that applications use the new interfaces if at all possible.
513
514The png.h header file is an invaluable reference for programming with libpng.
515And while I'm on the topic, make sure you include the libpng header file:
516
517#include <png.h>
518
519.SH III. Reading
520
521Reading PNG files:
522
523We'll now walk you through the possible functions to call when reading
524in a PNG file, briefly explaining the syntax and purpose of each one.
525See example.c and png.h for more detail. While Progressive reading
526is covered in the next section, you will still need some of the
527functions discussed in this section to read a PNG file.
528
529You will want to do the I/O initialization(*) before you get into libpng,
530so if it doesn't work, you don't have much to undo. Of course, you
531will also want to insure that you are, in fact, dealing with a PNG
532file. Libpng provides a simple check to see if a file is a PNG file.
533To use it, pass in the first 1 to 8 bytes of the file, and it will
534return true or false (1 or 0) depending on whether the bytes could be
535part of a PNG file. Of course, the more bytes you pass in, the
536greater the accuracy of the prediction.
537
538If you are intending to keep the file pointer open for use in libpng,
539you must ensure you don't read more than 8 bytes from the beginning
540of the file, and you also have to make a call to png_set_sig_bytes_read()
541with the number of bytes you read from the beginning. Libpng will
542then only check the bytes (if any) that your program didn't read.
543
544(*): If you are not using the standard I/O functions, you will need
545to replace them with custom functions. See the discussion under
546Customizing libpng.
547
548
549 FILE *fp = fopen(file_name, "rb");
550 if (!fp)
551 {
552 return;
553 }
554 fread(header, 1, number, fp);
555 is_png = !png_sig_cmp(header, 0, number);
556 if (!is_png)
557 {
558 return;
559 }
560
561
562Next, png_struct and png_info need to be allocated and initialized. In
563order to ensure that the size of these structures is correct even with a
564dynamically linked libpng, there are functions to initialize and
565allocate the structures. We also pass the library version, optional
566pointers to error handling functions, and a pointer to a data struct for
567use by the error functions, if necessary (the pointer and functions can
568be NULL if the default error handlers are to be used). See the section
569on Changes to Libpng below regarding the old initialization functions.
570
571 png_structp png_ptr = png_create_read_struct
572 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
573 user_error_fn, user_warning_fn);
574 if (!png_ptr)
575 return;
576
577 png_infop info_ptr = png_create_info_struct(png_ptr);
578 if (!info_ptr)
579 {
580 png_destroy_read_struct(&png_ptr,
581 (png_infopp)NULL, (png_infopp)NULL);
582 return;
583 }
584
585 png_infop end_info = png_create_info_struct(png_ptr);
586 if (!end_info)
587 {
588 png_destroy_read_struct(&png_ptr, &info_ptr,
589 (png_infopp)NULL);
590 return;
591 }
592
593If you want to use your own memory allocation routines,
594define PNG_USER_MEM_SUPPORTED and use
595png_create_read_struct_2() instead of png_create_read_struct():
596
597 png_structp png_ptr = png_create_read_struct_2
598 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
599 user_error_fn, user_warning_fn, (png_voidp)
600 user_mem_ptr, user_malloc_fn, user_free_fn);
601
602The error handling routines passed to png_create_read_struct()
603and the memory alloc/free routines passed to png_create_struct_2()
604are only necessary if you are not using the libpng supplied error
605handling and memory alloc/free functions.
606
607When libpng encounters an error, it expects to longjmp back
608to your routine. Therefore, you will need to call setjmp and pass
609your png_ptr->jmpbuf. If you read the file from different
610routines, you will need to update the jmpbuf field every time you enter
611a new routine that will call a png_ function.
612
613See your documentation of setjmp/longjmp for your compiler for more
614handling in the Customizing Libpng section below for more information on
615the libpng error handling. If an error occurs, and libpng longjmp's
616back to your setjmp, you will want to call png_destroy_read_struct() to
617free any memory.
618
619 if (setjmp(png_ptr->jmpbuf))
620 {
621 png_destroy_read_struct(&png_ptr, &info_ptr,
622 &end_info);
623 fclose(fp);
624 return;
625 }
626
627Now you need to set up the input code. The default for libpng is to
628use the C function fread(). If you use this, you will need to pass a
629valid FILE * in the function png_init_io(). Be sure that the file is
630opened in binary mode. If you wish to handle reading data in another
631way, you need not call the png_init_io() function, but you must then
632implement the libpng I/O methods discussed in the Customizing Libpng
633section below.
634
635 png_init_io(png_ptr, fp);
636
637If you had previously opened the file and read any of the signature from
638the beginning in order to see if this was a PNG file, you need to let
639libpng know that there are some bytes missing from the start of the file.
640
641 png_set_sig_bytes(png_ptr, number);
642
643At this point, you can set up a callback function that will be
644called after each row has been read, which you can use to control
645a progress meter or the like. It's demonstrated in pngtest.c.
646You must supply a function
647
648 void read_row_callback(png_ptr, png_uint_32 row, int pass);
649 {
650 /* put your code here */
651 }
652
653(You can give it another name that you like instead of "read_row_callback")
654
655To inform libpng about your function, use
656
657 png_set_read_status_fn(png_ptr, read_row_callback);
658
659In PNG files, the alpha channel in an image is the level of opacity.
660If you need the alpha channel in an image to be the level of transparency
661instead of opacity, you can invert the alpha channel (or the tRNS chunk
662data) after it's read, so that 0 is fully opaque and 255 (in 8-bit or
663paletted images) or 65535 (in 16-bit images) is fully transparent, with
664
665 png_set_invert_alpha(png_ptr);
666
667This has to appear here rather than later with the other transformations
668because the tRNS chunk data must be modified in the case of paletted images.
669If your image is not a paletted image, the tRNS data (which in such cases
670represents a single color to be rendered as transparent) won't be changed.
671
672Finally, you can write your own transformation function if none of
673the existing ones meets your needs. This is done by setting a callback
674with
675
676 png_set_read_user_transform_fn(png_ptr,
677 read_transform_fn);
678
679You must supply the function
680
681 void read_transform_fn(png_ptr ptr, row_info_ptr
682 row_info, png_bytep data)
683
684See pngtest.c for a working example. Your function will be called
685after all of the other transformations have been processed.
686
687You are now ready to read all the file information up to the actual
688image data. You do this with a call to png_read_info().
689
690 png_read_info(png_ptr, info_ptr);
691
692Functions are used to get the information from the info_ptr:
693
694 png_get_IHDR(png_ptr, info_ptr, &width, &height,
695 &bit_depth, &color_type, &interlace_type,
696 &compression_type, &filter_type);
697
698 width - holds the width of the image
699 in pixels (up to 2^31).
700 height - holds the height of the image
701 in pixels (up to 2^31).
702 bit_depth - holds the bit depth of one of the
703 image channels. (valid values are
704 1, 2, 4, 8, 16 and depend also on
705 the color_type. See also
706 significant bits (sBIT) below).
707 color_type - describes which color/alpha channels
708 are present.
709 PNG_COLOR_TYPE_GRAY
710 (bit depths 1, 2, 4, 8, 16)
711 PNG_COLOR_TYPE_GRAY_ALPHA
712 (bit depths 8, 16)
713 PNG_COLOR_TYPE_PALETTE
714 (bit depths 1, 2, 4, 8)
715 PNG_COLOR_TYPE_RGB
716 (bit_depths 8, 16)
717 PNG_COLOR_TYPE_RGB_ALPHA
718 (bit_depths 8, 16)
719
720 PNG_COLOR_MASK_PALETTE
721 PNG_COLOR_MASK_COLOR
722 PNG_COLOR_MASK_ALPHA
723
724 filter_type - (must be PNG_FILTER_TYPE_BASE
725 for PNG 1.0)
726 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
727 for PNG 1.0)
728 interlace_type - (PNG_INTERLACE_NONE or
729 PNG_INTERLACE_ADAM7)
730 Any or all of interlace_type, compression_type, of
731 filter_type can be
732 NULL if you are not interested in their values.
733
734 channels = png_get_channels(png_ptr, info_ptr);
735 channels - number of channels of info for the
736 color type (valid values are 1 (GRAY,
737 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
738 4 (RGB_ALPHA or RGB + filler byte))
739 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
740 rowbytes - number of bytes needed to hold a row
741
742 signature = png_get_signature(png_ptr, info_ptr);
743 signature - holds the signature read from the
744 file (if any). The data is kept in
745 the same offset it would be if the
746 whole signature were read (i.e. if an
747 application had already read in 4
748 bytes of signature before starting
749 libpng, the remaining 4 bytes would
750 be in signature[4] through signature[7]
751 (see png_set_sig_bytes())).
752
753
754 width = png_get_image_width(png_ptr,
755 info_ptr);
756 height = png_get_image_height(png_ptr,
757 info_ptr);
758 bit_depth = png_get_bit_depth(png_ptr,
759 info_ptr);
760 color_type = png_get_color_type(png_ptr,
761 info_ptr);
762 filter_type = png_get_filter_type(png_ptr,
763 info_ptr);
764 compression_type = png_get_compression_type(png_ptr,
765 info_ptr);
766 interlace_type = png_get_interlace_type(png_ptr,
767 info_ptr);
768
769
770These are also important, but their validity depends on whether the chunk
771has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
772png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
773data has been read, or zero if it is missing. The parameters to the
774png_get_<chunk> are set directly if they are simple data types, or a pointer
775into the info_ptr is returned for any complex types.
776
777 png_get_PLTE(png_ptr, info_ptr, &palette,
778 &num_palette);
779 palette - the palette for the file
780 (array of png_color)
781 num_palette - number of entries in the palette
782
783 png_get_gAMA(png_ptr, info_ptr, &gamma);
784 gamma - the gamma the file is written
785 at (PNG_INFO_gAMA)
786
787 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
788 srgb_intent - the rendering intent (PNG_INFO_sRGB)
789 The presence of the sRGB chunk
790 means that the pixel data is in the
791 sRGB color space. This chunk also
792 implies specific values of gAMA and
793 cHRM.
794
795 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
796 sig_bit - the number of significant bits for
797 (PNG_INFO_sBIT) each of the gray,
798 red, green, and blue channels,
799 whichever are appropriate for the
800 given color type (png_color_16)
801
802 png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
803 &trans_values);
804 trans - array of transparent entries for
805 palette (PNG_INFO_tRNS)
806 trans_values - transparent pixel for non-paletted
807 images (PNG_INFO_tRNS)
808 num_trans - number of transparent entries
809 (PNG_INFO_tRNS)
810
811 png_get_hIST(png_ptr, info_ptr, &hist);
812 (PNG_INFO_hIST)
813 hist - histogram of palette (array of
814 png_color_16)
815
816 png_get_tIME(png_ptr, info_ptr, &mod_time);
817 mod_time - time image was last modified
818 (PNG_VALID_tIME)
819
820 png_get_bKGD(png_ptr, info_ptr, &background);
821 background - background color (PNG_VALID_bKGD)
822
823 num_text = png_get_text(png_ptr, info_ptr, &text_ptr);
824 text_ptr - array of png_text holding image
825 comments
826 text_ptr[i]->key - keyword for comment.
827 text_ptr[i]->text - text comments for current
828 keyword.
829 text_ptr[i]->compression - type of compression used
830 on "text" PNG_TEXT_COMPRESSION_NONE
831 or PNG_TEXT_COMPRESSION_zTXt
832 num_text - number of comments
833
834 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
835 &unit_type);
836 offset_x - positive offset from the left edge
837 of the screen
838 offset_y - positive offset from the top edge
839 of the screen
840 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
841
842 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
843 &unit_type);
844 res_x - pixels/unit physical resolution in
845 x direction
846 res_y - pixels/unit physical resolution in
847 x direction
848 unit_type - PNG_RESOLUTION_UNKNOWN,
849 PNG_RESOLUTION_METER
850
851The data from the pHYs chunk can be retrieved in several convenient
852forms:
853
854 res_x = png_get_x_pixels_per_meter(png_ptr,
855 info_ptr)
856 res_y = png_get_y_pixels_per_meter(png_ptr,
857 info_ptr)
858 res_x_and_y = png_get_pixels_per_meter(png_ptr,
859 info_ptr)
860 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
861 info_ptr)
862
863 (Each of these returns 0 [signifying "unknown"] if
864 the data is not present or if res_x is 0;
865 res_x_and_y is 0 if res_x != res_y)
866
867For more information, see the png_info definition in png.h and the
868PNG specification for chunk contents. Be careful with trusting
869rowbytes, as some of the transformations could increase the space
870needed to hold a row (expand, filler, gray_to_rgb, etc.).
871See png_read_update_info(), below.
872
873A quick word about text_ptr and num_text. PNG stores comments in
874keyword/text pairs, one pair per chunk, with no limit on the number
875of text chunks, and a 2^31 byte limit on their size. While there are
876suggested keywords, there is no requirement to restrict the use to these
877strings. It is strongly suggested that keywords and text be sensible
878to humans (that's the point), so don't use abbreviations. Non-printing
879symbols are not allowed. See the PNG specification for more details.
880There is also no requirement to have text after the keyword.
881
882Keywords should be limited to 79 Latin-1 characters without leading or
883trailing spaces, but non-consecutive spaces are allowed within the
884keyword. It is possible to have the same keyword any number of times.
885The text_ptr is an array of png_text structures, each holding pointer
886to a keyword and a pointer to a text string. Only the text string may
887be null. The keyword/text pairs are put into the array in the order
888that they are received. However, some or all of the text chunks may be
889after the image, so, to make sure you have read all the text chunks,
890don't mess with these until after you read the stuff after the image.
891This will be mentioned again below in the discussion that goes with
892png_read_end().
893
894After you've read the header information, you can set up the library
895to handle any special transformations of the image data. The various
896ways to transform the data will be described in the order that they
897should occur. This is important, as some of these change the color
898type and/or bit depth of the data, and some others only work on
899certain color types and bit depths. Even though each transformation
900checks to see if it has data that it can do something with, you should
901make sure to only enable a transformation if it will be valid for the
902data. For example, don't swap red and blue on grayscale data.
903
904The colors used for the background and transparency values should be
905supplied in the same format/depth as the current image data. They
906are stored in the same format/depth as the image data in a bKGD or tRNS
907chunk, so this is what libpng expects for this data. The colors are
908transformed to keep in sync with the image data when an application
909calls the png_read_update_info() routine (see below).
910
911Data will be decoded into the supplied row buffers packed into bytes
912unless the library has been told to transform it into another format.
913For example, 4 bit/pixel paletted or grayscale data will be returned
9142 pixels/byte with the leftmost pixel in the high-order bits of the
915byte, unless png_set_packing() is called. 8-bit RGB data will be stored
916in RGB RGB RGB format unless png_set_filler() is called to insert filler
917bytes, either before or after each RGB triplet. 16-bit RGB data will
918be returned RRGGBB RRGGBB, with the most significant byte of the color
919value first, unless png_set_strip_16() is called to transform it to
920regular RGB RGB triplets, or png_set_filler() is called to insert
921filler bytes, either before or after each RRGGBB triplet. Similarly,
9228-bit or 16-bit grayscale data can be modified with png_set_filler()
923or png_set_strip_16().
924
925The following code transforms grayscale images of less than 8 to 8 bits,
926changes paletted images to RGB, and adds a full alpha channel if there is
927transparency information in a tRNS chunk. This is most useful on
928grayscale images with bit depths of 2 or 4 or if there is a multiple-image
929viewing application that wishes to treat all images in the same way.
930
931 if (color_type == PNG_COLOR_TYPE_PALETTE &&
932 bit_depth <= 8) png_set_expand(png_ptr);
933
934 if (color_type == PNG_COLOR_TYPE_GRAY &&
935 bit_depth < 8) png_set_expand(png_ptr);
936
937 if (png_get_valid(png_ptr, info_ptr,
938 PNG_INFO_tRNS)) png_set_expand(png_ptr);
939
940PNG can have files with 16 bits per channel. If you only can handle
9418 bits per channel, this will strip the pixels down to 8 bit.
942
943 if (bit_depth == 16)
944 png_set_strip_16(png_ptr);
945
946The png_set_background() function tells libpng to composite images
947with alpha or simple transparency against the supplied background
948color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
949you may use this color, or supply another color more suitable for
950the current display (e.g., the background color from a web page). You
951need to tell libpng whether the color is in the gamma space of the
952display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
953(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
954that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
955know why anyone would use this, but it's here).
956
957If, for some reason, you don't need the alpha channel on an image,
958and you want to remove it rather than combining it with the background
959(but the image author certainly had in mind that you *would* combine
960it with the background, so that's what you should probably do):
961
962 if (color_type & PNG_COLOR_MASK_ALPHA)
963 png_set_strip_alpha(png_ptr);
964
965PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
966they can, resulting in, for example, 8 pixels per byte for 1 bit
967files. This code expands to 1 pixel per byte without changing the
968values of the pixels:
969
970 if (bit_depth < 8)
971 png_set_packing(png_ptr);
972
973PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
974stored in a PNG image have been "scaled" or "shifted" up to the next
975higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
9768 bits/sample in the range [0, 255]). However, it is also possible to
977convert the PNG pixel data back to the original bit depth of the image.
978This call reduces the pixels back down to the original bit depth:
979
980 png_color_16p sig_bit;
981
982 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
983 png_set_shift(png_ptr, sig_bit);
984
985PNG files store 3-color pixels in red, green, blue order. This code
986changes the storage of the pixels to blue, green, red:
987
988 if (color_type == PNG_COLOR_TYPE_RGB ||
989 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
990 png_set_bgr(png_ptr);
991
992PNG files store RGB pixels packed into 3 bytes. This code expands them
993into 4 bytes for windowing systems that need them in this format:
994
995 if (bit_depth == 8 && color_type ==
996 PNG_COLOR_TYPE_RGB) png_set_filler(png_ptr,
997 filler, PNG_FILLER_BEFORE);
998
999where "filler" is the 8 or 16-bit number to fill with, and the location is
1000either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1001you want the filler before the RGB or after. This transformation
1002does not affect images that already have full alpha channels.
1003
1004If you are reading an image with an alpha channel, and you need the
1005data as ARGB instead of the normal PNG format RGBA:
1006
1007 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1008 png_set_swap_alpha(png_ptr);
1009
1010For some uses, you may want a grayscale image to be represented as
1011RGB. This code will do that conversion:
1012
1013 if (color_type == PNG_COLOR_TYPE_GRAY ||
1014 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1015 png_set_gray_to_rgb(png_ptr);
1016
1017Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
1018with alpha. This is intended for conversion of images that really are
1019gray (red == green == blue), so the function simply strips out the red
1020and blue channels, leaving the green channel in the gray position.
1021
1022 if (color_type == PNG_COLOR_TYPE_RGB ||
1023 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1024 png_set_rgb_to_gray(png_ptr, error_action,
1025 float red_weight, float green_weight);
1026
1027 error_action = 1: silently do the conversion
1028 error_action = 2: issue a warning if the original
1029 image has any pixel where
1030 red != green or red != blue
1031 error_action = 3: issue an error and abort the
1032 conversion if the original
1033 image has any pixel where
1034 red != green or red != blue
1035
1036 red_weight: weight of red component
1037 (NULL -> default 54/256)
1038 green_weight: weight of green component
1039 (NULL -> default 183/256)
1040
1041If you have set error_action = 1 or 2, you can
1042later check whether the image really was gray, after processing
1043the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1044It will return a png_byte that is zero if the image was gray or
10451 if there were any non-gray pixels. bKGD and sBIT data
1046will be silently converted to grayscale, using the green channel
1047data, regardless of the error_action setting.
1048
1049With 0.0<=red_weight+green_weight<=1.0,
1050the normalized graylevel is computed:
1051
1052 int rw = red_weight * 256;
1053 int gw = green_weight * 256;
1054 int bw = 256 - (rw + gw);
1055 gray = (rw*red + gw*green + bw*blue)/256;
1056
1057The default values approximate those recommended in the Charles
1058Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
1059Copyright (c) 1998-01-04 Charles Poynton poynton@inforamp.net
1060
1061 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1062
1063Libpng approximates this with
1064
1065 Y = 0.211 * R + 0.715 * G + 0.074 * B
1066
1067which can be expressed with integers as
1068
1069 Y = (54 * R + 183 * G + 19 * B)/256
1070
1071The calculation is done in a linear colorspace, if the image gamma
1072is known.
1073
1074If you have a grayscale and you are using png_set_expand() to change to
1075a higher bit-depth, you must either supply the background color as a gray
1076value at the original file bit-depth (need_expand = 1) or else supply the
1077background color as an RGB triplet at the final, expanded bit depth
1078(need_expand = 0). Similarly, if you are reading a paletted image, you
1079must either supply the background color as a palette index (need_expand = 1)
1080or as an RGB triplet that may or may not be in the palette (need_expand = 0).
1081
1082 png_color_16 my_background;
1083 png_color_16p image_background;
1084
1085 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1086 png_set_background(png_ptr, image_background,
1087 PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
1088 else
1089 png_set_background(png_ptr, &my_background,
1090 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
1091
1092To properly display PNG images on any kind of system, the application needs
1093to know what the display gamma is. Ideally, the user will know this, and
1094the application will allow them to set it. One method of allowing the user
1095to set the display gamma separately for each system is to check for the
1096DISPLAY_GAMMA and VIEWING_GAMMA environment variables or for a SCREEN_GAMMA
1097environment variable, which will hopefully be correctly set.
1098
1099Note that display_gamma is the gamma of your display, while screen_gamma is
1100the overall gamma correction required to produce pleasing results,
1101which depends on the lighting conditions in the surrounding environment.
1102Screen_gamma is display_gamma/viewing_gamma, where viewing_gamma is
1103the amount of additional gamma correction needed to compensate for
1104a (viewing_gamma=1.25) environment. In a dim or brightly lit room, no
1105compensation other than the display_gamma is needed (viewing_gamma=1.0).
1106
1107 if (/* We have a user-defined screen
1108 gamma value */)
1109 {
1110 screen_gamma = user_defined_screen_gamma;
1111 }
1112 /* One way that applications can share the same
1113 screen gamma value */
1114 else if ((gamma_str = getenv("SCREEN_GAMMA"))
1115 != NULL)
1116 {
1117 screen_gamma = atof(gamma_str);
1118 }
1119 /* If we don't have another value */
1120 else
1121 {
1122 screen_gamma = 2.2; /* A good guess for a
1123 PC monitor in a bright office or a dim room */
1124 screen_gamma = 2.0; /* A good guess for a
1125 PC monitor in a dark room */
1126 screen_gamma = 1.7 or 1.0; /* A good
1127 guess for Mac systems */
1128 }
1129
1130The png_set_gamma() function handles gamma transformations of the data.
1131Pass both the file gamma and the current screen_gamma. If the file does
1132not have a gamma value, you can pass one anyway if you have an idea what
1133it is (usually 0.45455 is a good guess for GIF images on PCs). Note
1134that file gammas are inverted from screen gammas. See the discussions
1135on gamma in the PNG specification for an excellent description of what
1136gamma is, and why all applications should support it. It is strongly
1137recommended that PNG viewers support gamma correction.
1138
1139 if (png_get_gAMA(png_ptr, info_ptr, &gamma))
1140 png_set_gamma(png_ptr, screen_gamma, gamma);
1141 else
1142 png_set_gamma(png_ptr, screen_gamma, 0.45455);
1143
1144If you need to reduce an RGB file to a paletted file, or if a paletted
1145file has more entries then will fit on your screen, png_set_dither()
1146will do that. Note that this is a simple match dither that merely
1147finds the closest color available. This should work fairly well with
1148optimized palettes, and fairly badly with linear color cubes. If you
1149pass a palette that is larger then maximum_colors, the file will
1150reduce the number of colors in the palette so it will fit into
1151maximum_colors. If there is a histogram, it will use it to make
1152more intelligent choices when reducing the palette. If there is no
1153histogram, it may not do as good a job.
1154
1155 if (color_type & PNG_COLOR_MASK_COLOR)
1156 {
1157 if (png_get_valid(png_ptr, info_ptr,
1158 PNG_INFO_PLTE))
1159 {
1160 png_color_16p histogram;
1161
1162 png_get_hIST(png_ptr, info_ptr,
1163 &histogram);
1164 png_set_dither(png_ptr, palette, num_palette,
1165 max_screen_colors, histogram, 1);
1166 }
1167 else
1168 {
1169 png_color std_color_cube[MAX_SCREEN_COLORS] =
1170 { ... colors ... };
1171
1172 png_set_dither(png_ptr, std_color_cube,
1173 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1174 NULL,0);
1175 }
1176 }
1177
1178PNG files describe monochrome as black being zero and white being one.
1179The following code will reverse this (make black be one and white be
1180zero):
1181
1182 if (bit_depth == 1 && color_type == PNG_COLOR_GRAY)
1183 png_set_invert_mono(png_ptr);
1184
1185PNG files store 16 bit pixels in network byte order (big-endian,
1186ie. most significant bits first). This code changes the storage to the
1187other way (little-endian, i.e. least significant bits first, the
1188way PCs store them):
1189
1190 if (bit_depth == 16)
1191 png_set_swap(png_ptr);
1192
1193If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1194need to change the order the pixels are packed into bytes, you can use:
1195
1196 if (bit_depth < 8)
1197 png_set_packswap(png_ptr);
1198
1199The last thing to handle is interlacing; this is covered in detail below,
1200but you must call the function here if you want libpng to handle expansion
1201of the interlaced image.
1202
1203 number_of_passes = png_set_interlace_handling(png_ptr);
1204
1205After setting the transformations, libpng can update your png_info
1206structure to reflect any transformations you've requested with this
1207call. This is most useful to update the info structure's rowbytes
1208field so you can use it to allocate your image memory. This function
1209will also update your palette with the correct screen_gamma and
1210background if these have been given with the calls above.
1211
1212 png_read_update_info(png_ptr, info_ptr);
1213
1214After you call png_read_update_info(), you can allocate any
1215memory you need to hold the image. The row data is simply
1216raw byte data for all forms of images. As the actual allocation
1217varies among applications, no example will be given. If you
1218are allocating one large chunk, you will need to build an
1219array of pointers to each row, as it will be needed for some
1220of the functions below.
1221
1222After you've allocated memory, you can read the image data.
1223The simplest way to do this is in one function call. If you are
1224allocating enough memory to hold the whole image, you can just
1225call png_read_image() and libpng will read in all the image data
1226and put it in the memory area supplied. You will need to pass in
1227an array of pointers to each row.
1228
1229This function automatically handles interlacing, so you don't need
1230to call png_set_interlace_handling() or call this function multiple
1231times, or any of that other stuff necessary with png_read_rows().
1232
1233 png_read_image(png_ptr, row_pointers);
1234
1235where row_pointers is:
1236
1237 png_bytep row_pointers[height];
1238
1239You can point to void or char or whatever you use for pixels.
1240
1241If you don't want to read in the whole image at once, you can
1242use png_read_rows() instead. If there is no interlacing (check
1243interlace_type == PNG_INTERLACE_NONE), this is simple:
1244
1245 png_read_rows(png_ptr, row_pointers, NULL,
1246 number_of_rows);
1247
1248where row_pointers is the same as in the png_read_image() call.
1249
1250If you are doing this just one row at a time, you can do this with
1251row_pointers:
1252
1253 png_bytep row_pointers = row;
1254 png_read_row(png_ptr, &row_pointers, NULL);
1255
1256If the file is interlaced (info_ptr->interlace_type != 0), things get
1257somewhat harder. The only current (PNG Specification version 1.0)
1258interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
1259is a somewhat complicated 2D interlace scheme, known as Adam7, that
1260breaks down an image into seven smaller images of varying size, based
1261on an 8x8 grid.
1262
1263libpng can fill out those images or it can give them to you "as is".
1264If you want them filled out, there are two ways to do that. The one
1265mentioned in the PNG specification is to expand each pixel to cover
1266those pixels that have not been read yet (the "rectangle" method).
1267This results in a blocky image for the first pass, which gradually
1268smooths out as more pixels are read. The other method is the "sparkle"
1269method, where pixels are drawn only in their final locations, with the
1270rest of the image remaining whatever colors they were initialized to
1271before the start of the read. The first method usually looks better,
1272but tends to be slower, as there are more pixels to put in the rows.
1273
1274If you don't want libpng to handle the interlacing details, just call
1275png_read_rows() seven times to read in all seven images. Each of the
1276images is a valid image by itself, or they can all be combined on an
12778x8 grid to form a single image (although if you intend to combine them
1278you would be far better off using the libpng interlace handling).
1279
1280The first pass will return an image 1/8 as wide as the entire image
1281(every 8th column starting in column 0) and 1/8 as high as the original
1282(every 8th row starting in row 0), the second will be 1/8 as wide
1283(starting in column 4) and 1/8 as high (also starting in row 0). The
1284third pass will be 1/4 as wide (every 4th pixel starting in column 0) and
12851/8 as high (every 8th row starting in row 4), and the fourth pass will
1286be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,
1287and every 4th row starting in row 0). The fifth pass will return an
1288image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),
1289while the sixth pass will be 1/2 as wide and 1/2 as high as the original
1290(starting in column 1 and row 0). The seventh and final pass will be as
1291wide as the original, and 1/2 as high, containing all of the odd
1292numbered scanlines. Phew!
1293
1294If you want libpng to expand the images, call this before calling
1295png_start_read_image() or png_read_update_info():
1296
1297 if (interlace_type == PNG_INTERLACE_ADAM7)
1298 number_of_passes
1299 = png_set_interlace_handling(png_ptr);
1300
1301This will return the number of passes needed. Currently, this
1302is seven, but may change if another interlace type is added.
1303This function can be called even if the file is not interlaced,
1304where it will return one pass.
1305
1306If you are not going to display the image after each pass, but are
1307going to wait until the entire image is read in, use the sparkle
1308effect. This effect is faster and the end result of either method
1309is exactly the same. If you are planning on displaying the image
1310after each pass, the "rectangle" effect is generally considered the
1311better looking one.
1312
1313If you only want the "sparkle" effect, just call png_read_rows() as
1314normal, with the third parameter NULL. Make sure you make pass over
1315the image number_of_passes times, and you don't change the data in the
1316rows between calls. You can change the locations of the data, just
1317not the data. Each pass only writes the pixels appropriate for that
1318pass, and assumes the data from previous passes is still valid.
1319
1320 png_read_rows(png_ptr, row_pointers, NULL,
1321 number_of_rows);
1322
1323If you only want the first effect (the rectangles), do the same as
1324before except pass the row buffer in the third parameter, and leave
1325the second parameter NULL.
1326
1327 png_read_rows(png_ptr, NULL, row_pointers,
1328 number_of_rows);
1329
1330After you are finished reading the image, you can finish reading
1331the file. If you are interested in comments or time, which may be
1332stored either before or after the image data, you should pass the
1333separate png_info struct if you want to keep the comments from
1334before and after the image separate. If you are not interested, you
1335can pass NULL.
1336
1337 png_read_end(png_ptr, end_info);
1338
1339When you are done, you can free all memory allocated by libpng like this:
1340
1341 png_destroy_read_struct(&png_ptr, &info_ptr,
1342 &end_info);
1343
1344For a more compact example of reading a PNG image, see the file example.c.
1345
1346
1347Reading PNG files progressively:
1348
1349The progressive reader is slightly different then the non-progressive
1350reader. Instead of calling png_read_info(), png_read_rows(), and
1351png_read_end(), you make one call to png_process_data(), which calls
1352callbacks when it has the info, a row, or the end of the image. You
1353set up these callbacks with png_set_progressive_read_fn(). You don't
1354have to worry about the input/output functions of libpng, as you are
1355giving the library the data directly in png_process_data(). I will
1356assume that you have read the section on reading PNG files above,
1357so I will only highlight the differences (although I will show
1358all of the code).
1359
1360png_structp png_ptr;
1361png_infop info_ptr;
1362
1363 /* An example code fragment of how you would
1364 initialize the progressive reader in your
1365 application. */
1366 int
1367 initialize_png_reader()
1368 {
1369 png_ptr = png_create_read_struct
1370 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1371 user_error_fn, user_warning_fn);
1372 if (!png_ptr)
1373 return -1;
1374 info_ptr = png_create_info_struct(png_ptr);
1375 if (!info_ptr)
1376 {
1377 png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
1378 (png_infopp)NULL);
1379 return -1;
1380 }
1381
1382 if (setjmp(png_ptr->jmpbuf))
1383 {
1384 png_destroy_read_struct(&png_ptr, &info_ptr,
1385 (png_infopp)NULL);
1386 return -1;
1387 }
1388
1389 /* This one's new. You can provide functions
1390 to be called when the header info is valid,
1391 when each row is completed, and when the image
1392 is finished. If you aren't using all functions,
1393 you can specify NULL parameters. Even when all
1394 three functions are NULL, you need to call
1395 png_set_progressive_read_fn(). You can use
1396 any struct as the user_ptr (cast to a void pointer
1397 for the function call), and retrieve the pointer
1398 from inside the callbacks using the function
1399
1400 png_get_progressive_ptr(png_ptr);
1401
1402 which will return a void pointer, which you have
1403 to cast appropriately.
1404 */
1405 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
1406 info_callback, row_callback, end_callback);
1407
1408 return 0;
1409 }
1410
1411 /* A code fragment that you call as you receive blocks
1412 of data */
1413 int
1414 process_data(png_bytep buffer, png_uint_32 length)
1415 {
1416 if (setjmp(png_ptr->jmpbuf))
1417 {
1418 png_destroy_read_struct(&png_ptr, &info_ptr,
1419 (png_infopp)NULL);
1420 return -1;
1421 }
1422
1423 /* This one's new also. Simply give it a chunk
1424 of data from the file stream (in order, of
1425 course). On machines with segmented memory
1426 models machines, don't give it any more than
1427 64K. The library seems to run fine with sizes
1428 of 4K. Although you can give it much less if
1429 necessary (I assume you can give it chunks of
1430 1 byte, I haven't tried less then 256 bytes
1431 yet). When this function returns, you may
1432 want to display any rows that were generated
1433 in the row callback if you don't already do
1434 so there.
1435 */
1436 png_process_data(png_ptr, info_ptr, buffer, length);
1437 return 0;
1438 }
1439
1440 /* This function is called (as set by
1441 png_set_progressive_read_fn() above) when enough data
1442 has been supplied so all of the header has been
1443 read.
1444 */
1445 void
1446 info_callback(png_structp png_ptr, png_infop info)
1447 {
1448 /* Do any setup here, including setting any of
1449 the transformations mentioned in the Reading
1450 PNG files section. For now, you _must_ call
1451 either png_start_read_image() or
1452 png_read_update_info() after all the
1453 transformations are set (even if you don't set
1454 any). You may start getting rows before
1455 png_process_data() returns, so this is your
1456 last chance to prepare for that.
1457 */
1458 }
1459
1460 /* This function is called when each row of image
1461 data is complete */
1462 void
1463 row_callback(png_structp png_ptr, png_bytep new_row,
1464 png_uint_32 row_num, int pass)
1465 {
1466 /* If the image is interlaced, and you turned
1467 on the interlace handler, this function will
1468 be called for every row in every pass. Some
1469 of these rows will not be changed from the
1470 previous pass. When the row is not changed,
1471 the new_row variable will be NULL. The rows
1472 and passes are called in order, so you don't
1473 really need the row_num and pass, but I'm
1474 supplying them because it may make your life
1475 easier.
1476
1477 For the non-NULL rows of interlaced images,
1478 you must call png_progressive_combine_row()
1479 passing in the row and the old row. You can
1480 call this function for NULL rows (it will just
1481 return) and for non-interlaced images (it just
1482 does the memcpy for you) if it will make the
1483 code easier. Thus, you can just do this for
1484 all cases:
1485 */
1486
1487 png_progressive_combine_row(png_ptr, old_row,
1488 new_row);
1489
1490 /* where old_row is what was displayed for
1491 previously for the row. Note that the first
1492 pass (pass == 0, really) will completely cover
1493 the old row, so the rows do not have to be
1494 initialized. After the first pass (and only
1495 for interlaced images), you will have to pass
1496 the current row, and the function will combine
1497 the old row and the new row.
1498 */
1499 }
1500
1501 void
1502 end_callback(png_structp png_ptr, png_infop info)
1503 {
1504 /* This function is called after the whole image
1505 has been read, including any chunks after the
1506 image (up to and including the IEND). You
1507 will usually have the same info chunk as you
1508 had in the header, although some data may have
1509 been added to the comments and time fields.
1510
1511 Most people won't do much here, perhaps setting
1512 a flag that marks the image as finished.
1513 */
1514 }
1515
1516
1517
1518.SH IV. Writing
1519
1520Much of this is very similar to reading. However, everything of
1521importance is repeated here, so you won't have to constantly look
1522back up in the reading section to understand writing.
1523
1524You will want to do the I/O initialization before you get into libpng,
1525so if it doesn't work, you don't have anything to undo. If you are not
1526using the standard I/O functions, you will need to replace them with
1527custom writing functions. See the discussion under Customizing libpng.
1528
1529 FILE *fp = fopen(file_name, "wb");
1530 if (!fp)
1531 {
1532 return;
1533 }
1534
1535Next, png_struct and png_info need to be allocated and initialized.
1536As these can be both relatively large, you may not want to store these
1537on the stack, unless you have stack space to spare. Of course, you
1538will want to check if they return NULL. If you are also reading,
1539you won't want to name your read structure and your write structure
1540both "png_ptr"; you can call them anything you like, such as
1541"read_ptr" and "write_ptr". Look at pngtest.c, for example.
1542
1543 png_structp png_ptr = png_create_write_struct
1544 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1545 user_error_fn, user_warning_fn);
1546 if (!png_ptr)
1547 return;
1548
1549 png_infop info_ptr = png_create_info_struct(png_ptr);
1550 if (!info_ptr)
1551 {
1552 png_destroy_write_struct(&png_ptr,
1553 (png_infopp)NULL);
1554 return;
1555 }
1556
1557If you want to use your own memory allocation routines,
1558define PNG_USER_MEM_SUPPORTED and use
1559png_create_write_struct_2() instead of png_create_read_struct():
1560
1561 png_structp png_ptr = png_create_write_struct_2
1562 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1563 user_error_fn, user_warning_fn, (png_voidp)
1564 user_mem_ptr, user_malloc_fn, user_free_fn);
1565
1566After you have these structures, you will need to set up the
1567error handling. When libpng encounters an error, it expects to
1568longjmp() back to your routine. Therefore, you will need to call
1569setjmp() and pass the png_ptr->jmpbuf. If you
1570write the file from different routines, you will need to update
1571the jmpbuf field every time you enter a new routine that will
1572call a png_ function. See your documentation of setjmp/longjmp
1573for your compiler for more information on setjmp/longjmp. See
1574the discussion on libpng error handling in the Customizing Libpng
1575section below for more information on the libpng error handling.
1576
1577 if (setjmp(png_ptr->jmpbuf))
1578 {
1579 png_destroy_write_struct(&png_ptr, &info_ptr);
1580 fclose(fp);
1581 return;
1582 }
1583 ...
1584 return;
1585
1586Now you need to set up the output code. The default for libpng is to
1587use the C function fwrite(). If you use this, you will need to pass a
1588valid FILE * in the function png_init_io(). Be sure that the file is
1589opened in binary mode. Again, if you wish to handle writing data in
1590another way, see the discussion on libpng I/O handling in the Customizing
1591Libpng section below.
1592
1593 png_init_io(png_ptr, fp);
1594
1595At this point, you can set up a callback function that will be
1596called after each row has been written, which you can use to control
1597a progress meter or the like. It's demonstrated in pngtest.c.
1598You must supply a function
1599
1600 void write_row_callback(png_ptr, png_uint_32 row, int pass);
1601 {
1602 /* put your code here */
1603 }
1604
1605(You can give it another name that you like instead of "write_row_callback")
1606
1607To inform libpng about your function, use
1608
1609 png_set_write_status_fn(png_ptr, write_row_callback);
1610
1611You now have the option of modifying how the compression library will
1612run. The following functions are mainly for testing, but may be useful
1613in some cases, like if you need to write PNG files extremely fast and
1614are willing to give up some compression, or if you want to get the
1615maximum possible compression at the expense of slower writing. If you
1616have no special needs in this area, let the library do what it wants by
1617not calling this function at all, as it has been tuned to deliver a good
1618speed/compression ratio. The second parameter to png_set_filter() is
1619the filter method, for which the only valid value is '0' (as of the
1620October 1996 PNG specification, version 1.0). The third parameter is a
1621flag that indicates which filter type(s) are to be tested for each
1622scanline. See the Compression Library for details on the specific filter
1623types.
1624
1625
1626 /* turn on or off filtering, and/or choose
1627 specific filters */
1628 png_set_filter(png_ptr, 0,
1629 PNG_FILTER_NONE | PNG_FILTER_SUB |
1630 PNG_FILTER_PAETH);
1631
1632The png_set_compression_???() functions interface to the zlib compression
1633library, and should mostly be ignored unless you really know what you are
1634doing. The only generally useful call is png_set_compression_level()
1635which changes how much time zlib spends on trying to compress the image
1636data. See the Compression Library for details on the compression levels.
1637
1638 /* set the zlib compression level */
1639 png_set_compression_level(png_ptr,
1640 Z_BEST_COMPRESSION);
1641
1642 /* set other zlib parameters */
1643 png_set_compression_mem_level(png_ptr, 8);
1644 png_set_compression_strategy(png_ptr,
1645 Z_DEFAULT_STRATEGY);
1646 png_set_compression_window_bits(png_ptr, 15);
1647 png_set_compression_method(png_ptr, 8);
1648
1649You now need to fill in the png_info structure with all the data you
1650wish to write before the actual image. Note that the only thing you
1651are allowed to write after the image is the text chunks and the time
1652chunk (as of PNG Specification 1.0, anyway). See png_write_end() and
1653the latest PNG specification for more information on that. If you
1654wish to write them before the image, fill them in now, and flag that
1655data as being valid. If you want to wait until after the data, don't
1656fill them until png_write_end(). For all the fields in png_info and
1657their data types, see png.h. For explanations of what the fields
1658contain, see the PNG specification.
1659
1660Some of the more important parts of the png_info are:
1661
1662 png_set_IHDR(png_ptr, info_ptr, width, height,
1663 bit_depth, color_type, interlace_type,
1664 compression_type, filter_type)
1665 width - holds the width of the image
1666 in pixels (up to 2^31).
1667 height - holds the height of the image
1668 in pixels (up to 2^31).
1669 bit_depth - holds the bit depth of one of the
1670 image channels.
1671 (valid values are 1, 2, 4, 8, 16
1672 and depend also on the
1673 color_type. See also significant
1674 bits (sBIT) below).
1675 color_type - describes which color/alpha
1676 channels are present.
1677 PNG_COLOR_TYPE_GRAY
1678 (bit depths 1, 2, 4, 8, 16)
1679 PNG_COLOR_TYPE_GRAY_ALPHA
1680 (bit depths 8, 16)
1681 PNG_COLOR_TYPE_PALETTE
1682 (bit depths 1, 2, 4, 8)
1683 PNG_COLOR_TYPE_RGB
1684 (bit_depths 8, 16)
1685 PNG_COLOR_TYPE_RGB_ALPHA
1686 (bit_depths 8, 16)
1687
1688 PNG_COLOR_MASK_PALETTE
1689 PNG_COLOR_MASK_COLOR
1690 PNG_COLOR_MASK_ALPHA
1691
1692 interlace_type - PNG_INTERLACE_NONE or
1693 PNG_INTERLACE_ADAM7
1694 compression_type - (must be
1695 PNG_COMPRESSION_TYPE_DEFAULT)
1696 filter_type - (must be PNG_FILTER_TYPE_DEFAULT)
1697
1698 png_set_PLTE(png_ptr, info_ptr, palette,
1699 num_palette);
1700 palette - the palette for the file
1701 (array of png_color)
1702 num_palette - number of entries in the palette
1703
1704 png_set_gAMA(png_ptr, info_ptr, gamma);
1705 gamma - the gamma the image was created
1706 at (PNG_INFO_gAMA)
1707
1708 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
1709 srgb_intent - the rendering intent
1710 (PNG_INFO_sRGB) The presence of
1711 the sRGB chunk means that the pixel
1712 data is in the sRGB color space.
1713 This chunk also implies specific
1714 values of gAMA and cHRM. Rendering
1715 intent is the CSS-1 property that
1716 has been defined by the International
1717 Color Consortium
1718 (http://www.color.org).
1719 It can be one of
1720 PNG_SRGB_INTENT_SATURATION,
1721 PNG_SRGB_INTENT_PERCEPTUAL,
1722 PNG_SRGB_INTENT_ABSOLUTE, or
1723 PNG_SRGB_INTENT_RELATIVE.
1724
1725
1726 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
1727 srgb_intent);
1728 srgb_intent - the rendering intent
1729 (PNG_INFO_sRGB) The presence of the
1730 sRGB chunk means that the pixel
1731 data is in the sRGB color space.
1732 This function also causes gAMA and
1733 cHRM chunks with the specific values
1734 that are consistent with sRGB to be
1735 written.
1736
1737 png_set_sBIT(png_ptr, info_ptr, sig_bit);
1738 sig_bit - the number of significant bits for
1739 (PNG_INFO_sBIT) each of the gray, red,
1740 green, and blue channels, whichever are
1741 appropriate for the given color type
1742 (png_color_16)
1743
1744 png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
1745 trans_values);
1746 trans - array of transparent entries for
1747 palette (PNG_INFO_tRNS)
1748 trans_values - transparent pixel for non-paletted
1749 images (PNG_INFO_tRNS)
1750 num_trans - number of transparent entries
1751 (PNG_INFO_tRNS)
1752
1753 png_set_hIST(png_ptr, info_ptr, hist);
1754 (PNG_INFO_hIST)
1755 hist - histogram of palette (array of
1756 png_color_16)
1757
1758 png_set_tIME(png_ptr, info_ptr, mod_time);
1759 mod_time - time image was last modified
1760 (PNG_VALID_tIME)
1761
1762 png_set_bKGD(png_ptr, info_ptr, background);
1763 background - background color (PNG_VALID_bKGD)
1764
1765 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
1766 text_ptr - array of png_text holding image
1767 comments
1768 text_ptr[i]->key - keyword for comment.
1769 text_ptr[i]->text - text comments for current
1770 keyword.
1771 text_ptr[i]->compression - type of compression used
1772 on "text" PNG_TEXT_COMPRESSION_NONE or
1773 PNG_TEXT_COMPRESSION_zTXt
1774 num_text - number of comments in text_ptr
1775
1776 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
1777 unit_type);
1778 offset_x - positive offset from the left
1779 edge of the screen
1780 offset_y - positive offset from the top
1781 edge of the screen
1782 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1783
1784 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
1785 unit_type);
1786 res_x - pixels/unit physical resolution
1787 in x direction
1788 res_y - pixels/unit physical resolution
1789 in y direction
1790 unit_type - PNG_RESOLUTION_UNKNOWN,
1791 PNG_RESOLUTION_METER
1792
1793In PNG files, the alpha channel in an image is the level of opacity.
1794If your data is supplied as a level of transparency, you can invert the
1795alpha channel before you write it, so that 0 is fully transparent and 255
1796(in 8-bit or paletted images) or 65535 (in 16-bit images) is fully opaque,
1797with
1798
1799 png_set_invert_alpha(png_ptr);
1800
1801This must appear here instead of later with the other transformations
1802because in the case of paletted images the tRNS chunk data has to
1803be inverted before the tRNS chunk is written. If your image is not a
1804paletted image, the tRNS data (which in such cases represents a single
1805color to be rendered as transparent) won't be changed.
1806
1807A quick word about text and num_text. text is an array of png_text
1808structures. num_text is the number of valid structures in the array.
1809If you want, you can use max_text to hold the size of the array, but
1810libpng ignores it for writing (it does use it for reading). Each
1811png_text structure holds a keyword-text value, and a compression type.
1812The compression types have the same valid numbers as the compression
1813types of the image data. Currently, the only valid number is zero.
1814However, you can store text either compressed or uncompressed, unlike
1815images, which always have to be compressed. So if you don't want the
1816text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
1817Until text gets around 1000 bytes, it is not worth compressing it.
1818After the text has been written out to the file, the compression type
1819is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
1820so that it isn't written out again at the end (in case you are calling
1821png_write_end() with the same struct.
1822
1823The keywords that are given in the PNG Specification are:
1824
1825 Title Short (one line) title or
1826 caption for image
1827 Author Name of image's creator
1828 Description Description of image (possibly long)
1829 Copyright Copyright notice
1830 Creation Time Time of original image creation
1831 (usually RFC 1123 format, see below)
1832 Software Software used to create the image
1833 Disclaimer Legal disclaimer
1834 Warning Warning of nature of content
1835 Source Device used to create the image
1836 Comment Miscellaneous comment; conversion
1837 from other image format
1838
1839The keyword-text pairs work like this. Keywords should be short
1840simple descriptions of what the comment is about. Some typical
1841keywords are found in the PNG specification, as is some recommendations
1842on keywords. You can repeat keywords in a file. You can even write
1843some text before the image and some after. For example, you may want
1844to put a description of the image before the image, but leave the
1845disclaimer until after, so viewers working over modem connections
1846don't have to wait for the disclaimer to go over the modem before
1847they start seeing the image. Finally, keywords should be full
1848words, not abbreviations. Keywords and text are in the ISO 8859-1
1849(Latin-1) character set (a superset of regular ASCII) and can not
1850contain NUL characters, and should not contain control or other
1851unprintable characters. To make the comments widely readable, stick
1852with basic ASCII, and avoid machine specific character set extensions
1853like the IBM-PC character set. The keyword must be present, but
1854you can leave off the text string on non-compressed pairs.
1855Compressed pairs must have a text string, as only the text string
1856is compressed anyway, so the compression would be meaningless.
1857
1858PNG supports modification time via the png_time structure. Two
1859conversion routines are proved, png_convert_from_time_t() for
1860time_t and png_convert_from_struct_tm() for struct tm. The
1861time_t routine uses gmtime(). You don't have to use either of
1862these, but if you wish to fill in the png_time structure directly,
1863you should provide the time in universal time (GMT) if possible
1864instead of your local time. Note that the year number is the full
1865year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
1866that months start with 1.
1867
1868If you want to store the time of the original image creation, you should
1869use a plain tEXt chunk with the "Creation Time" keyword. This is
1870necessary because the "creation time" of a PNG image is somewhat vague,
1871depending on whether you mean the PNG file, the time the image was
1872created in a non-PNG format, a still photo from which the image was
1873scanned, or possibly the subject matter itself. In order to facilitate
1874machine-readable dates, it is recommended that the "Creation Time"
1875tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
1876although this isn't a requirement. Unlike the tIME chunk, the
1877"Creation Time" tEXt chunk is not expected to be automatically changed
1878by the software. To facilitate the use of RFC 1123 dates, a function
1879png_convert_to_rfc1123(png_timep) is provided to convert from PNG
1880time to an RFC 1123 format string.
1881
1882You are now ready to write all the file information up to the actual
1883image data. You do this with a call to png_write_info().
1884
1885 png_write_info(png_ptr, info_ptr);
1886
1887After you've written the file information, you can set up the library
1888to handle any special transformations of the image data. The various
1889ways to transform the data will be described in the order that they
1890should occur. This is important, as some of these change the color
1891type and/or bit depth of the data, and some others only work on
1892certain color types and bit depths. Even though each transformation
1893checks to see if it has data that it can do something with, you should
1894make sure to only enable a transformation if it will be valid for the
1895data. For example, don't swap red and blue on grayscale data.
1896
1897PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
1898the library to expand the input data to 4 or 8 bytes per pixel
1899(or expand 1 or 2-byte grayscale data to 2 or 4 bytes per pixel).
1900
1901 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
1902
1903where the 0 is the value that will be put in the 4th byte, and the
1904location is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending
1905upon whether the filler byte is stored XRGB or RGBX.
1906
1907PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1908they can, resulting in, for example, 8 pixels per byte for 1 bit files.
1909If the data is supplied at 1 pixel per byte, use this code, which will
1910correctly pack the pixels into a single byte:
1911
1912 png_set_packing(png_ptr);
1913
1914PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
1915data is of another bit depth, you can write an sBIT chunk into the
1916file so that decoders can get the original data if desired.
1917
1918 /* Set the true bit depth of the image data */
1919 if (color_type & PNG_COLOR_MASK_COLOR)
1920 {
1921 sig_bit.red = true_bit_depth;
1922 sig_bit.green = true_bit_depth;
1923 sig_bit.blue = true_bit_depth;
1924 }
1925 else
1926 {
1927 sig_bit.gray = true_bit_depth;
1928 }
1929 if (color_type & PNG_COLOR_MASK_ALPHA)
1930 {
1931 sig_bit.alpha = true_bit_depth;
1932 }
1933
1934 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
1935
1936If the data is stored in the row buffer in a bit depth other than
1937one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
1938this will scale the values to appear to be the correct bit depth as
1939is required by PNG.
1940
1941 png_set_shift(png_ptr, &sig_bit);
1942
1943PNG files store 16 bit pixels in network byte order (big-endian,
1944ie. most significant bits first). This code would be used if they are
1945supplied the other way (little-endian, i.e. least significant bits
1946first, the way PCs store them):
1947
1948 if (bit_depth > 8)
1949 png_set_swap(png_ptr);
1950
1951If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1952need to change the order the pixels are packed into bytes, you can use:
1953
1954 if (bit_depth < 8)
1955 png_set_packswap(png_ptr);
1956
1957PNG files store 3 color pixels in red, green, blue order. This code
1958would be used if they are supplied as blue, green, red:
1959
1960 png_set_bgr(png_ptr);
1961
1962PNG files describe monochrome as black being zero and white being
1963one. This code would be used if the pixels are supplied with this reversed
1964(black being one and white being zero):
1965
1966 png_set_invert_mono(png_ptr);
1967
1968Finally, you can write your own transformation function if none of
1969the existing ones meets your needs. This is done by setting a callback
1970with
1971
1972 png_set_write_user_transform_fn(png_ptr,
1973 write_transform_fn);
1974
1975You must supply the function
1976
1977 void write_transform_fn(png_ptr ptr, row_info_ptr
1978 row_info, png_bytep data)
1979
1980See pngtest.c for a working example. Your function will be called
1981before any of the other transformations have been processed.
1982
1983It is possible to have libpng flush any pending output, either manually,
1984or automatically after a certain number of lines have been written. To
1985flush the output stream a single time call:
1986
1987 png_write_flush(png_ptr);
1988
1989and to have libpng flush the output stream periodically after a certain
1990number of scanlines have been written, call:
1991
1992 png_set_flush(png_ptr, nrows);
1993
1994Note that the distance between rows is from the last time png_write_flush()
1995was called, or the first row of the image if it has never been called.
1996So if you write 50 lines, and then png_set_flush 25, it will flush the
1997output on the next scanline, and every 25 lines thereafter, unless
1998png_write_flush() is called before 25 more lines have been written.
1999If nrows is too small (less than about 10 lines for a 640 pixel wide
2000RGB image) the image compression may decrease noticeably (although this
2001may be acceptable for real-time applications). Infrequent flushing will
2002only degrade the compression performance by a few percent over images
2003that do not use flushing.
2004
2005That's it for the transformations. Now you can write the image data.
2006The simplest way to do this is in one function call. If have the
2007whole image in memory, you can just call png_write_image() and libpng
2008will write the image. You will need to pass in an array of pointers to
2009each row. This function automatically handles interlacing, so you don't
2010need to call png_set_interlace_handling() or call this function multiple
2011times, or any of that other stuff necessary with png_write_rows().
2012
2013 png_write_image(png_ptr, row_pointers);
2014
2015where row_pointers is:
2016
2017 png_byte *row_pointers[height];
2018
2019You can point to void or char or whatever you use for pixels.
2020
2021If you don't want to write the whole image at once, you can
2022use png_write_rows() instead. If the file is not interlaced,
2023this is simple:
2024
2025 png_write_rows(png_ptr, row_pointers,
2026 number_of_rows);
2027
2028row_pointers is the same as in the png_write_image() call.
2029
2030If you are just writing one row at a time, you can do this with
2031row_pointers:
2032
2033 png_bytep row_pointer = row;
2034
2035 png_write_row(png_ptr, &row_pointer);
2036
2037When the file is interlaced, things can get a good deal more
2038complicated. The only currently (as of February 1998 -- PNG Specification
2039version 1.0, dated October 1996) defined interlacing scheme for PNG files
2040is the "Adam7" interlace scheme, that breaks down an
2041image into seven smaller images of varying size. libpng will build
2042these images for you, or you can do them yourself. If you want to
2043build them yourself, see the PNG specification for details of which
2044pixels to write when.
2045
2046If you don't want libpng to handle the interlacing details, just
2047use png_set_interlace_handling() and call png_write_rows() the
2048correct number of times to write all seven sub-images.
2049
2050If you want libpng to build the sub-images, call this before you start
2051writing any rows:
2052
2053 number_of_passes =
2054 png_set_interlace_handling(png_ptr);
2055
2056This will return the number of passes needed. Currently, this
2057is seven, but may change if another interlace type is added.
2058
2059Then write the complete image number_of_passes times.
2060
2061 png_write_rows(png_ptr, row_pointers,
2062 number_of_rows);
2063
2064As some of these rows are not used, and thus return immediately,
2065you may want to read about interlacing in the PNG specification,
2066and only update the rows that are actually used.
2067
2068After you are finished writing the image, you should finish writing
2069the file. If you are interested in writing comments or time, you should
2070pass an appropriately filled png_info pointer. If you are not interested,
2071you can pass NULL.
2072
2073 png_write_end(png_ptr, info_ptr);
2074
2075When you are done, you can free all memory used by libpng like this:
2076
2077 png_destroy_write_struct(&png_ptr, &info_ptr);
2078
2079You must free any data you allocated for info_ptr, such as comments,
2080palette, or histogram, before the call to png_destroy_write_struct();
2081
2082For a more compact example of writing a PNG image, see the file example.c.
2083
2084
2085.SH V. Modifying/Customizing libpng:
2086
2087There are two issues here. The first is changing how libpng does
2088standard things like memory allocation, input/output, and error handling.
2089The second deals with more complicated things like adding new chunks,
2090adding new transformations, and generally changing how libpng works.
2091
2092All of the memory allocation, input/output, and error handling in libpng
2093goes through callbacks that are user settable. The default routines are
2094in pngmem.c, pngrio.c, pngwio.c, and pngerror.c respectively. To change
2095these functions, call the appropriate png_set_???_fn() function.
2096
2097Memory allocation is done through the functions png_large_malloc(),
2098png_malloc(), png_realloc(), png_large_free(), and png_free(). These
2099currently just call the standard C functions. The large functions must
2100handle exactly 64K, but they don't have to handle more than that. If
2101your pointers can't access more then 64K at a time, you will want to set
2102MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling
2103memory allocation on a platform will change between applications, these
2104functions must be modified in the library at compile time.
2105
2106Input/Output in libpng is done through png_read() and png_write(),
2107which currently just call fread() and fwrite(). The FILE * is stored in
2108png_struct and is initialized via png_init_io(). If you wish to change
2109the method of I/O, the library supplies callbacks that you can set
2110through the function png_set_read_fn() and png_set_write_fn() at run
2111time, instead of calling the png_init_io() function. These functions
2112also provide a void pointer that can be retrieved via the function
2113png_get_io_ptr(). For example:
2114
2115 png_set_read_fn(png_structp read_ptr,
2116 voidp read_io_ptr, png_rw_ptr read_data_fn)
2117
2118 png_set_write_fn(png_structp write_ptr,
2119 voidp write_io_ptr, png_rw_ptr write_data_fn,
2120 png_flush_ptr output_flush_fn);
2121
2122 voidp read_io_ptr = png_get_io_ptr(read_ptr);
2123 voidp write_io_ptr = png_get_io_ptr(write_ptr);
2124
2125The replacement I/O functions should have prototypes as follows:
2126
2127 void user_read_data(png_structp png_ptr,
2128 png_bytep data, png_uint_32 length);
2129 void user_write_data(png_structp png_ptr,
2130 png_bytep data, png_uint_32 length);
2131 void user_flush_data(png_structp png_ptr);
2132
2133Supplying NULL for the read, write, or flush functions sets them back
2134to using the default C stream functions. It is an error to read from
2135a write stream, and vice versa.
2136
2137Error handling in libpng is done through png_error() and png_warning().
2138Errors handled through png_error() are fatal, meaning that png_error()
2139should never return to its caller. Currently, this is handled via
2140setjmp() and longjmp(), but you could change this to do things like
2141exit() if you should wish. On non-fatal errors, png_warning() is called
2142to print a warning message, and then control returns to the calling code.
2143By default png_error() and png_warning() print a message on stderr via
2144fprintf() unless the library is compiled with PNG_NO_STDIO defined. If
2145you wish to change the behavior of the error functions, you will need to
2146set up your own message callbacks. These functions are normally supplied
2147at the time that the png_struct is created. It is also possible to change
2148these functions after png_create_???_struct() has been called by calling:
2149
2150 png_set_error_fn(png_structp png_ptr,
2151 png_voidp error_ptr, png_error_ptr error_fn,
2152 png_error_ptr warning_fn);
2153
2154 png_voidp error_ptr = png_get_error_ptr(png_ptr);
2155
2156If NULL is supplied for either error_fn or warning_fn, then the libpng
2157default function will be used, calling fprintf() and/or longjmp() if a
2158problem is encountered. The replacement error functions should have
2159parameters as follows:
2160
2161 void user_error_fn(png_structp png_ptr,
2162 png_const_charp error_msg);
2163 void user_warning_fn(png_structp png_ptr,
2164 png_const_charp warning_msg);
2165
2166The motivation behind using setjmp() and longjmp() is the C++ throw and
2167catch exception handling methods. This makes the code much easier to write,
2168as there is no need to check every return code of every function call.
2169However, there are some uncertainties about the status of local variables
2170after a longjmp, so the user may want to be careful about doing anything after
2171setjmp returns non-zero besides returning itself. Consult your compiler
2172documentation for more details.
2173
2174If you need to read or write custom chunks, you will need to get deeper
2175into the libpng code, as a mechanism has not yet been supplied for user
2176callbacks with custom chunks. First, read the PNG specification, and have
2177a first level of understanding of how it works. Pay particular attention
2178to the sections that describe chunk names, and look at how other chunks
2179were designed, so you can do things similarly. Second, check out the
2180sections of libpng that read and write chunks. Try to find a chunk that
2181is similar to yours and copy off of it. More details can be found in the
2182comments inside the code. A way of handling unknown chunks in a generic
2183method, potentially via callback functions, would be best.
2184
2185If you wish to write your own transformation for the data, look through
2186the part of the code that does the transformations, and check out some of
2187the simpler ones to get an idea of how they work. Try to find a similar
2188transformation to the one you want to add and copy off of it. More details
2189can be found in the comments inside the code itself.
2190
2191Configuring for 16 bit platforms:
2192
2193You may need to change the png_large_malloc() and png_large_free()
2194routines in pngmem.c, as these are required to allocate 64K, although
2195there is already support for many of the common DOS compilers. Also,
2196you will want to look into zconf.h to tell zlib (and thus libpng) that
2197it cannot allocate more then 64K at a time. Even if you can, the memory
2198won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
2199
2200Configuring for DOS:
2201
2202For DOS users who only have access to the lower 640K, you will
2203have to limit zlib's memory usage via a png_set_compression_mem_level()
2204call. See zlib.h or zconf.h in the zlib library for more information.
2205
2206Configuring for Medium Model:
2207
2208Libpng's support for medium model has been tested on most of the popular
2209compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
2210defined, and FAR gets defined to far in pngconf.h, and you should be
2211all set. Everything in the library (except for zlib's structure) is
2212expecting far data. You must use the typedefs with the p or pp on
2213the end for pointers (or at least look at them and be careful). Make
2214note that the row's of data are defined as png_bytepp, which is an
2215unsigned char far * far *.
2216
2217Configuring for gui/windowing platforms:
2218
2219You will need to write new error and warning functions that use the GUI
2220interface, as described previously, and set them to be the error and
2221warning functions at the time that png_create_???_struct() is called,
2222in order to have them available during the structure initialization.
2223They can be changed later via png_set_error_fn(). On some compilers,
2224you may also have to change the memory allocators (png_malloc, etc.).
2225
2226Configuring for compiler xxx:
2227
2228All includes for libpng are in pngconf.h. If you need to add/change/delete
2229an include, this is the place to do it. The includes that are not
2230needed outside libpng are protected by the PNG_INTERNAL definition,
2231which is only defined for those routines inside libpng itself. The
2232files in libpng proper only include png.h, which includes pngconf.h.
2233
2234Configuring zlib:
2235
2236There are special functions to configure the compression. Perhaps the
2237most useful one changes the compression level, which currently uses
2238input compression values in the range 0 - 9. The library normally
2239uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
2240have shown that for a large majority of images, compression values in
2241the range 3-6 compress nearly as well as higher levels, and do so much
2242faster. For online applications it may be desirable to have maximum speed
2243(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
2244specify no compression (Z_NO_COMPRESSION = 0), but this would create
2245files larger than just storing the raw bitmap. You can specify the
2246compression level by calling:
2247
2248 png_set_compression_level(png_ptr, level);
2249
2250Another useful one is to reduce the memory level used by the library.
2251The memory level defaults to 8, but it can be lowered if you are
2252short on memory (running DOS, for example, where you only have 640K).
2253
2254 png_set_compression_mem_level(png_ptr, level);
2255
2256The other functions are for configuring zlib. They are not recommended
2257for normal use and may result in writing an invalid PNG file. See
2258zlib.h for more information on what these mean.
2259
2260 png_set_compression_strategy(png_ptr,
2261 strategy);
2262 png_set_compression_window_bits(png_ptr,
2263 window_bits);
2264 png_set_compression_method(png_ptr, method);
2265
2266Controlling row filtering:
2267
2268If you want to control whether libpng uses filtering or not, which
2269filters are used, and how it goes about picking row filters, you
2270can call one of these functions. The selection and configuration
2271of row filters can have a significant impact on the size and
2272encoding speed and a somewhat lesser impact on the decoding speed
2273of an image. Filtering is enabled by default for RGB and grayscale
2274images (with and without alpha), but not for paletted images nor
2275for any images with bit depths less than 8 bits/pixel.
2276
2277The 'method' parameter sets the main filtering method, which is
2278currently only '0' in the PNG 1.0 specification. The 'filters'
2279parameter sets which filter(s), if any, should be used for each
2280scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
2281to turn filtering on and off, respectively.
2282
2283Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
2284PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
2285ORed together '|' to specify one or more filters to use. These
2286filters are described in more detail in the PNG specification. If
2287you intend to change the filter type during the course of writing
2288the image, you should start with flags set for all of the filters
2289you intend to use so that libpng can initialize its internal
2290structures appropriately for all of the filter types.
2291
2292 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
2293 | PNG_FILTER_UP;
2294 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
2295 filters);
2296
2297It is also possible to influence how libpng chooses from among the
2298available filters. This is done in two ways - by telling it how
2299important it is to keep the same filter for successive rows, and
2300by telling it the relative computational costs of the filters.
2301
2302 double weights[3] = {1.5, 1.3, 1.1},
2303 costs[PNG_FILTER_VALUE_LAST] =
2304 {1.0, 1.3, 1.3, 1.5, 1.7};
2305
2306 png_set_filter_selection(png_ptr,
2307 PNG_FILTER_SELECTION_WEIGHTED, 3,
2308 weights, costs);
2309
2310The weights are multiplying factors that indicate to libpng that the
2311row filter should be the same for successive rows unless another row filter
2312is that many times better than the previous filter. In the above example,
2313if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
2314"sum of absolute differences" 1.5 x 1.3 times higher than other filters
2315and still be chosen, while the NONE filter could have a sum 1.1 times
2316higher than other filters and still be chosen. Unspecified weights are
2317taken to be 1.0, and the specified weights should probably be declining
2318like those above in order to emphasize recent filters over older filters.
2319
2320The filter costs specify for each filter type a relative decoding cost
2321to be considered when selecting row filters. This means that filters
2322with higher costs are less likely to be chosen over filters with lower
2323costs, unless their "sum of absolute differences" is that much smaller.
2324The costs do not necessarily reflect the exact computational speeds of
2325the various filters, since this would unduly influence the final image
2326size.
2327
2328Note that the numbers above were invented purely for this example and
2329are given only to help explain the function usage. Little testing has
2330been done to find optimum values for either the costs or the weights.
2331
2332Removing unwanted object code:
2333
2334There are a bunch of #define's in pngconf.h that control what parts of
2335libpng are compiled. All the defines end in _SUPPORTED. If you are
2336never going to use a capability, you can change the #define to #undef
2337before recompiling libpng and save yourself code and data space, or
2338you can turn off individual capabilities with defines that begin with
2339PNG_NO_.
2340
2341You can also turn all of the transforms and ancillary chunk capabilities
2342off en masse with compiler directives that define
2343PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
2344or all four,
2345along with directives to turn on any of the capabilities that you do
2346want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable
2347the extra transformations but still leave the library fully capable of reading
2348and writing PNG files with all known public chunks [except for sPLT].
2349Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive
2350produces a library that is incapable of reading or writing ancillary chunks.
2351If you are not using the progressive reading capability, you can
2352turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse
2353this with the INTERLACING capability, which you'll still have).
2354
2355All the reading and writing specific code are in separate files, so the
2356linker should only grab the files it needs. However, if you want to
2357make sure, or if you are building a stand alone library, all the
2358reading files start with pngr and all the writing files start with
2359pngw. The files that don't match either (like png.c, pngtrans.c, etc.)
2360are used for both reading and writing, and always need to be included.
2361The progressive reader is in pngpread.c
2362
2363If you are creating or distributing a dynamically linked library (a .so
2364or DLL file), you should not remove or disable any parts of the library,
2365as this will cause applications linked with different versions of the
2366library to fail if they call functions not available in your library.
2367The size of the library itself should not be an issue, because only
2368those sections that are actually used will be loaded into memory.
2369
2370Requesting debug printout:
2371
2372The macro definition PNG_DEBUG can be used to request debugging
2373printout. Set it to an integer value in the range 0 to 3. Higher
2374numbers result in increasing amounts of debugging information. The
2375information is printed to the "stderr" file, unless another file
2376name is specified in the PNG_DEBUG_FILE macro definition.
2377
2378When PNG_DEBUG > 0, the following functions (macros) become available:
2379
2380 png_debug(level, message)
2381 png_debug1(level, message, p1)
2382 png_debug2(level, message, p1, p2)
2383
2384in which "level" is compared to PNG_DEBUG to decide whether to print
2385the message, "message" is the formatted string to be printed,
2386and p1 and p2 are parameters that are to be embedded in the string
2387according to printf-style formatting directives. For example,
2388
2389 png_debug1(2, "foo=%d\n", foo);
2390
2391is expanded to
2392
2393 if(PNG_DEBUG > 2)
2394 fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
2395
2396When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
2397can still use PNG_DEBUG to control your own debugging:
2398
2399 #ifdef PNG_DEBUG
2400 fprintf(stderr, ...
2401 #endif
2402
2403When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
2404having level = 0 will be printed. There aren't any such statements in
2405this version of libpng, but if you insert some they will be printed.
2406
2407.SH VI. Changes to Libpng from version 0.88
2408
2409It should be noted that versions of libpng later than 0.96 are not
2410distributed by the original libpng author, Guy Schalnat, nor by
2411Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
2412distributed versions 0.89 through 0.96, but rather by another member
2413of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
2414still alive and well, but they have moved on to other things.
2415
2416The old libpng functions png_read_init(), png_write_init(),
2417png_info_init(), png_read_destroy(), and png_write_destory() have been
2418moved to PNG_INTERNAL in version 0.95 to discourage their use. The
2419preferred method of creating and initializing the libpng structures is
2420via the png_create_read_struct(), png_create_write_struct(), and
2421png_create_info_struct() because they isolate the size of the structures
2422from the application, allow version error checking, and also allow the
2423use of custom error handling routines during the initialization, which
2424the old functions do not. The functions png_read_destroy() and
2425png_write_destroy() do not actually free the memory that libpng
2426allocated for these structs, but just reset the data structures, so they
2427can be used instead of png_destroy_read_struct() and
2428png_destroy_write_struct() if you feel there is too much system overhead
2429allocating and freeing the png_struct for each image read.
2430
2431Setting the error callbacks via png_set_message_fn() before
2432png_read_init() as was suggested in libpng-0.88 is no longer supported
2433because this caused applications that do not use custom error functions
2434to fail if the png_ptr was not initialized to zero. It is still possible
2435to set the error callbacks AFTER png_read_init(), or to change them with
2436png_set_error_fn(), which is essentially the same function, but with a
2437new name to force compilation errors with applications that try to use
2438the old method.
2439
2440.SH VII. Y2K Compliance in libpng
2441
2442January 13, 1999
2443
2444Since the PNG Development group is an ad-hoc body, we can't make
2445an official declaration.
2446
2447This is your unofficial assurance that libpng from version 0.81 and
2448upward are Y2K compliant. It is my belief that earlier versions were
2449also Y2K compliant.
2450
2451Libpng only has three year fields. One is a 2-byte unsigned integer that
2452will hold years up to 65535. The other two hold the date in text
2453format, and will hold years up to 9999.
2454
2455The integer is
2456 "png_uint_16 year" in png_time_struct.
2457
2458The strings are
2459 "png_charp time_buffer" in png_struct and
2460 "near_time_buffer", which is a local character string in png.c.
2461
2462There are seven time-related functions:
2463
2464 png_convert_to_rfc_1123() in png.c
2465 (formerly png_convert_to_rfc_1152() in error)
2466 png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c
2467 png_convert_from_time_t() in pngwrite.c
2468 png_get_tIME() in pngget.c
2469 png_handle_tIME() in pngrutil.c, called in pngread.c
2470 png_set_tIME() in pngset.c
2471 png_write_tIME() in pngwutil.c, called in pngwrite.c
2472
2473All appear to handle dates properly in a Y2K environment. The
2474png_convert_from_time_t() function calls gmtime() to convert from system
2475clock time, which returns (year - 1900), which we properly convert to
2476the full 4-digit year. There is a possibility that applications using
2477libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
2478function, or incorrectly passing only a 2-digit year instead of
2479"year - 1900" into the png_convert_from_struct_tm() function, but this
2480is not under our control. The libpng documentation has always stated
2481that it works with 4-digit years, and the APIs have been documented as
2482such.
2483
2484The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
2485integer to hold the year, and can hold years as large as 65535.
2486
2487
2488 Glenn Randers-Pehrson
2489 libpng maintainer
2490 PNG Development Group
2491
2492.SH NOTE
2493
2494Note about libpng version numbers:
2495
2496Due to various miscommunications, unforeseen code incompatibilities
2497and occasional factors outside the authors' control, version numbering
2498on the library has not always been consistent and straightforward.
2499The following table summarizes matters since version 0.89c, which was
2500the first widely used release:
2501
2502 source png.h png.h shared-lib
2503 version string int version
2504 ------- ------ ------ ----------
2505 0.89c 0.89 89 1.0.89
2506 0.90 0.90 90 0.90 [should be 2.0.90]
2507 0.95 0.95 95 0.95 [should be 2.0.95]
2508 0.96 0.96 96 0.96 [should be 2.0.96]
2509 0.97b 1.00.97 97 1.0.1 [should be 2.0.97]
2510 0.97c 0.97 97 2.0.97
2511 0.98 0.98 98 2.0.98
2512 0.99 0.99 98 2.0.99
2513 0.99a-m 0.99 99 2.0.99
2514 1.00 1.00 100 2.1.0 [int should be 10000]
2515 1.0.0 1.0.0 100 2.1.0 [int should be 10000]
2516 1.0.1 1.0.1 10001 2.1.0
2517
2518Henceforth the source version will match the shared-library
2519minor and patch numbers; the shared-library major version number will be
2520used for changes in backward compatibility, as it is intended.
2521The PNG_PNGLIB_VER macro, which is not used within libpng but
2522is available for applications, is an unsigned integer of the form
2523xyyzz corresponding to the source version x.y.z (leading zeros in y and z).
2524
2525.SH "SEE ALSO"
2526libpngpf(3), png(5)
2527.LP
2528.IR libpng :
2529.IP
2530ftp://ftp.uu.net/graphics/png
2531http://www.cdrom.com/pub/png
2532
2533.LP
2534.IR zlib :
2535.IP
2536(generally) at the same location as
2537.I libpng
2538or at
2539.br
2540ftp://ftp.uu.net/pub/archiving/zip/zlib
2541.br
2542http://www.cdrom.com/pub/infozip/zlib
2543
2544.LP
2545.IR PNG specification: RFC 2083
2546.IP
2547(generally) at the same location as
2548.I libpng
2549or at
2550.br
2551ftp://ds.internic.net/rfc/rfc2083.txt
2552.br
2553or (as a W3C Recommendation) at
2554.br
2555http://www.w3.org/TR/REC-png.html
2556
2557.LP
2558In the case of any inconsistency between the PNG specification
2559and this library, the specification takes precedence.
2560
2561.SH AUTHORS
2562This man page: Glenn Randers-Pehrson
2563<randeg@alumni.rpi.edu>
2564
2565Contributing Authors: John Bowler, Kevin Bracey, Sam Bushell, Andreas Dilger,
2566Magnus Holmgren, Tom Lane, Dave Martindale, Glenn Randers-Pehrson,
2567Greg Roelofs, Guy Eric Schalnat, Paul Schmidt, Tom Tanner, Willem van
2568Schaik, Tim Wegner.
2569<png-implement@dworkin.wustl.edu>
2570
2571The contributing authors would like to thank all those who helped
2572with testing, bug fixes, and patience. This wouldn't have been
2573possible without all of you.
2574
2575Thanks to Frank J. T. Wojcik for helping with the documentation.
2576
2577Libpng version 1.0.3 - January 14, 1999:
2578Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
2579Currently maintained by Glenn Randers-Pehrson (randeg@alumni.rpi.edu).
2580
2581Supported by the PNG development group
2582.br
2583(png-implement@dworkin.wustl.edu).
2584
2585.SH COPYRIGHT NOTICE:
2586
2587Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
2588Copyright (c) 1996, 1997 Andreas Dilger
2589Copyright (c) 1998, 1999 Glenn Randers-Pehrson
2590
2591The PNG Reference Library (libpng) is supplied "AS IS". The Contributing
2592Authors and Group 42, Inc. disclaim all warranties, expressed or implied,
2593including, without limitation, the warranties of merchantability and of
2594fitness for any purpose. The Contributing Authors and Group 42, Inc.
2595assume no liability for direct, indirect, incidental, special, exemplary,
2596or consequential damages, which may result from the use of the PNG
2597Reference Library, even if advised of the possibility of such damage.
2598
2599Permission is hereby granted to use, copy, modify, and distribute this
2600source code, or portions hereof, for any purpose, without fee, subject
2601to the following restrictions:
2602
2603 1. The origin of this source code must not be
2604 misrepresented.
2605
2606 2. Altered versions must be plainly marked as such
2607 and must not be misrepresented as being the
2608 original source.
2609
2610 3. This Copyright notice may not be removed or
2611 altered from any source or altered source
2612 distribution.
2613
2614The Contributing Authors and Group 42, Inc. specifically permit, without
2615fee, and encourage the use of this source code as a component to
2616supporting the PNG file format in commercial products. If you use this
2617source code in a product, acknowledgment is not required but would be
2618appreciated.
2619
2620.\" end of man page
2621