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