1LIBPNG(3) Library Functions Manual LIBPNG(3)
2
6 libpng - Portable Network Graphics (PNG) Reference Library 1.2.29
7
9 #include <png.h>
10 png_uint_32 png_access_version_number (void);
12 int png_check_sig (png_bytep sig, int num);
14 void png_chunk_error (png_structp png_ptr, png_const_charp error);
16 void png_chunk_warning (png_structp png_ptr, png_const_charp message);
18 void png_convert_from_struct_tm (png_timep ptime, struct tm FAR *
20 ttime);
21 void png_convert_from_time_t (png_timep ptime, time_t ttime);
23 png_charp png_convert_to_rfc1123 (png_structp png_ptr, png_timep
25 ptime);
26 png_infop png_create_info_struct (png_structp png_ptr);
28 png_structp png_create_read_struct (png_const_charp user_png_ver,
30 png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn);
31 png_structp png_create_read_struct_2(png_const_charp user_png_ver,
33 png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn,
34 png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);
35 png_structp png_create_write_struct (png_const_charp user_png_ver,
37 png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn);
38 png_structp png_create_write_struct_2(png_const_charp user_png_ver,
40 png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn,
41 png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);
42 int png_debug(int level, png_const_charp message);
44 int png_debug1(int level, png_const_charp message, p1);
46 int png_debug2(int level, png_const_charp message, p1, p2);
48 void png_destroy_info_struct (png_structp png_ptr, png_infopp
50 info_ptr_ptr);
51 void png_destroy_read_struct (png_structpp png_ptr_ptr, png_infopp
53 info_ptr_ptr, png_infopp end_info_ptr_ptr);
54 void png_destroy_write_struct (png_structpp png_ptr_ptr, png_infopp
56 info_ptr_ptr);
57 void png_error (png_structp png_ptr, png_const_charp error);
59 void png_free (png_structp png_ptr, png_voidp ptr);
61 void png_free_chunk_list (png_structp png_ptr);
63 void png_free_default(png_structp png_ptr, png_voidp ptr);
65 void png_free_data (png_structp png_ptr, png_infop info_ptr, int num);
67 png_byte png_get_bit_depth (png_structp png_ptr, png_infop info_ptr);
69 png_uint_32 png_get_bKGD (png_structp png_ptr, png_infop info_ptr,
71 png_color_16p *background);
72 png_byte png_get_channels (png_structp png_ptr, png_infop info_ptr);
74 png_uint_32 png_get_cHRM (png_structp png_ptr, png_infop info_ptr, dou‐
76 ble *white_x, double *white_y, double *red_x, double *red_y, double
77 *green_x, double *green_y, double *blue_x, double *blue_y);
78 png_uint_32 png_get_cHRM_fixed (png_structp png_ptr, png_infop
80 info_ptr, png_uint_32 *white_x, png_uint_32 *white_y, png_uint_32
81 *red_x, png_uint_32 *red_y, png_uint_32 *green_x, png_uint_32 *green_y,
82 png_uint_32 *blue_x, png_uint_32 *blue_y);
83 png_byte png_get_color_type (png_structp png_ptr, png_infop info_ptr);
85 png_byte png_get_compression_type (png_structp png_ptr, png_infop
87 info_ptr);
88 png_byte png_get_copyright (png_structp png_ptr);
90 png_voidp png_get_error_ptr (png_structp png_ptr);
92 png_byte png_get_filter_type (png_structp png_ptr, png_infop info_ptr);
94 png_uint_32 png_get_gAMA (png_structp png_ptr, png_infop info_ptr, dou‐
96 ble *file_gamma);
97 png_uint_32 png_get_gAMA_fixed (png_structp png_ptr, png_infop
99 info_ptr, png_uint_32 *int_file_gamma);
100 png_byte png_get_header_ver (png_structp png_ptr);
102 png_byte png_get_header_version (png_structp png_ptr);
104 png_uint_32 png_get_hIST (png_structp png_ptr, png_infop info_ptr,
106 png_uint_16p *hist);
107 png_uint_32 png_get_iCCP (png_structp png_ptr, png_infop info_ptr,
109 png_charpp name, int *compression_type, png_charpp profile, png_uint_32
110 *proflen);
111 png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop info_ptr,
113 png_uint_32 *width, png_uint_32 *height, int *bit_depth, int
114 *color_type, int *interlace_type, int *compression_type, int *fil‐
115 ter_type);
116 png_uint_32 png_get_image_height (png_structp png_ptr, png_infop
118 info_ptr);
119 png_uint_32 png_get_image_width (png_structp png_ptr, png_infop
121 info_ptr);
122 #if !defined(PNG_1_0_X) png_int_32 png_get_int_32 (png_bytep buf);
124 #endif
125 png_byte png_get_interlace_type (png_structp png_ptr, png_infop
127 info_ptr);
128 png_voidp png_get_io_ptr (png_structp png_ptr);
130 png_byte png_get_libpng_ver (png_structp png_ptr);
132 png_voidp png_get_mem_ptr(png_structp png_ptr);
134 png_uint_32 png_get_oFFs (png_structp png_ptr, png_infop info_ptr,
136 png_uint_32 *offset_x, png_uint_32 *offset_y, int *unit_type);
137 png_uint_32 png_get_pCAL (png_structp png_ptr, png_infop info_ptr,
139 png_charp *purpose, png_int_32 *X0, png_int_32 *X1, int *type, int
140 *nparams, png_charp *units, png_charpp *params);
141 png_uint_32 png_get_pHYs (png_structp png_ptr, png_infop info_ptr,
143 png_uint_32 *res_x, png_uint_32 *res_y, int *unit_type);
144 float png_get_pixel_aspect_ratio (png_structp png_ptr, png_infop
146 info_ptr);
147 png_uint_32 png_get_pixels_per_meter (png_structp png_ptr, png_infop
149 info_ptr);
150 png_voidp png_get_progressive_ptr (png_structp png_ptr);
152 png_uint_32 png_get_PLTE (png_structp png_ptr, png_infop info_ptr,
154 png_colorp *palette, int *num_palette);
155 png_byte png_get_rgb_to_gray_status (png_structp png_ptr) png_uint_32
157 png_get_rowbytes (png_structp png_ptr, png_infop info_ptr);
158 png_bytepp png_get_rows (png_structp png_ptr, png_infop info_ptr);
160 png_uint_32 png_get_sBIT (png_structp png_ptr, png_infop info_ptr,
162 png_color_8p *sig_bit);
163 png_bytep png_get_signature (png_structp png_ptr, png_infop info_ptr);
165 png_uint_32 png_get_sPLT (png_structp png_ptr, png_infop info_ptr,
167 png_spalette_p *splt_ptr);
168 png_uint_32 png_get_sRGB (png_structp png_ptr, png_infop info_ptr, int
170 *intent);
171 png_uint_32 png_get_text (png_structp png_ptr, png_infop info_ptr,
173 png_textp *text_ptr, int *num_text);
174 png_uint_32 png_get_tIME (png_structp png_ptr, png_infop info_ptr,
176 png_timep *mod_time);
177 png_uint_32 png_get_tRNS (png_structp png_ptr, png_infop info_ptr,
179 png_bytep *trans, int *num_trans, png_color_16p *trans_values);
180 #if !defined(PNG_1_0_X) png_uint_16 png_get_uint_16 (png_bytep buf);
182 png_uint_32 png_get_uint_31 (png_bytep buf);
184 png_uint_32 png_get_uint_32 (png_bytep buf); #endif
186 png_uint_32 png_get_unknown_chunks (png_structp png_ptr, png_infop
188 info_ptr, png_unknown_chunkpp unknowns);
189 png_voidp png_get_user_chunk_ptr (png_structp png_ptr);
191 png_uint_32 png_get_user_height_max( png_structp png_ptr);
193 png_voidp png_get_user_transform_ptr (png_structp png_ptr);
195 png_uint_32 png_get_user_width_max (png_structp png_ptr);
197 png_uint_32 png_get_valid (png_structp png_ptr, png_infop info_ptr,
199 png_uint_32 flag);
200 png_int_32 png_get_x_offset_microns (png_structp png_ptr, png_infop
202 info_ptr);
203 png_int_32 png_get_x_offset_pixels (png_structp png_ptr, png_infop
205 info_ptr);
206 png_uint_32 png_get_x_pixels_per_meter (png_structp png_ptr, png_infop
208 info_ptr);
209 png_int_32 png_get_y_offset_microns (png_structp png_ptr, png_infop
211 info_ptr);
212 png_int_32 png_get_y_offset_pixels (png_structp png_ptr, png_infop
214 info_ptr);
215 png_uint_32 png_get_y_pixels_per_meter (png_structp png_ptr, png_infop
217 info_ptr);
218 png_uint_32 png_get_compression_buffer_size (png_structp png_ptr);
220 int png_handle_as_unknown (png_structp png_ptr, png_bytep chunk_name);
222 void png_init_io (png_structp png_ptr, FILE *fp);
224 DEPRECATED: void png_info_init (png_infop info_ptr);
226 DEPRECATED: void png_info_init_2 (png_infopp ptr_ptr, png_size_t
228 png_info_struct_size);
229 png_voidp png_malloc (png_structp png_ptr, png_uint_32 size);
231 png_voidp png_malloc_default(png_structp png_ptr, png_uint_32 size);
233 voidp png_memcpy (png_voidp s1, png_voidp s2, png_size_t size);
235 png_voidp png_memcpy_check (png_structp png_ptr, png_voidp s1,
237 png_voidp s2, png_uint_32 size);
238 voidp png_memset (png_voidp s1, int value, png_size_t size);
240 png_voidp png_memset_check (png_structp png_ptr, png_voidp s1, int
242 value, png_uint_32 size);
243 DEPRECATED: void png_permit_empty_plte (png_structp png_ptr, int
245 empty_plte_permitted);
246 void png_process_data (png_structp png_ptr, png_infop info_ptr,
248 png_bytep buffer, png_size_t buffer_size);
249 void png_progressive_combine_row (png_structp png_ptr, png_bytep
251 old_row, png_bytep new_row);
252 void png_read_destroy (png_structp png_ptr, png_infop info_ptr,
254 png_infop end_info_ptr);
255 void png_read_end (png_structp png_ptr, png_infop info_ptr);
257 void png_read_image (png_structp png_ptr, png_bytepp image);
259 DEPRECATED: void png_read_init (png_structp png_ptr);
261 DEPRECATED: void png_read_init_2 (png_structpp ptr_ptr, png_const_charp
263 user_png_ver, png_size_t png_struct_size, png_size_t png_info_size);
264 void png_read_info (png_structp png_ptr, png_infop info_ptr);
266 void png_read_png (png_structp png_ptr, png_infop info_ptr, int trans‐
268 forms, png_voidp params);
269 void png_read_row (png_structp png_ptr, png_bytep row, png_bytep dis‐
271 play_row);
272 void png_read_rows (png_structp png_ptr, png_bytepp row, png_bytepp
274 display_row, png_uint_32 num_rows);
275 void png_read_update_info (png_structp png_ptr, png_infop info_ptr);
277 #if !defined(PNG_1_0_X) png_save_int_32 (png_bytep buf, png_int_32 i);
279 void png_save_uint_16 (png_bytep buf, unsigned int i);
281 void png_save_uint_32 (png_bytep buf, png_uint_32 i);
283 void png_set_add_alpha (png_structp png_ptr, png_uint_32 filler, int
285 flags); #endif
286 void png_set_background (png_structp png_ptr, png_color_16p back‐
288 ground_color, int background_gamma_code, int need_expand, double back‐
289 ground_gamma);
290 void png_set_bgr (png_structp png_ptr);
292 void png_set_bKGD (png_structp png_ptr, png_infop info_ptr,
294 png_color_16p background);
295 void png_set_cHRM (png_structp png_ptr, png_infop info_ptr, double
297 white_x, double white_y, double red_x, double red_y, double green_x,
298 double green_y, double blue_x, double blue_y);
299 void png_set_cHRM_fixed (png_structp png_ptr, png_infop info_ptr,
301 png_uint_32 white_x, png_uint_32 white_y, png_uint_32 red_x,
302 png_uint_32 red_y, png_uint_32 green_x, png_uint_32 green_y,
303 png_uint_32 blue_x, png_uint_32 blue_y);
304 void png_set_compression_level (png_structp png_ptr, int level);
306 void png_set_compression_mem_level (png_structp png_ptr, int
308 mem_level);
309 void png_set_compression_method (png_structp png_ptr, int method);
311 void png_set_compression_strategy (png_structp png_ptr, int strategy);
313 void png_set_compression_window_bits (png_structp png_ptr, int win‐
315 dow_bits);
316 void png_set_crc_action (png_structp png_ptr, int crit_action, int
318 ancil_action);
319 void png_set_dither (png_structp png_ptr, png_colorp palette, int
321 num_palette, int maximum_colors, png_uint_16p histogram, int
322 full_dither);
323 void png_set_error_fn (png_structp png_ptr, png_voidp error_ptr,
325 png_error_ptr error_fn, png_error_ptr warning_fn);
326 void png_set_expand (png_structp png_ptr);
328 void png_set_expand_gray_1_2_4_to_8(png_structp png_ptr);
330 void png_set_filler (png_structp png_ptr, png_uint_32 filler, int
332 flags);
333 void png_set_filter (png_structp png_ptr, int method, int filters);
335 void png_set_filter_heuristics (png_structp png_ptr, int heuris‐
337 tic_method, int num_weights, png_doublep filter_weights, png_doublep
338 filter_costs);
339 void png_set_flush (png_structp png_ptr, int nrows);
341 void png_set_gamma (png_structp png_ptr, double screen_gamma, double
343 default_file_gamma);
344 void png_set_gAMA (png_structp png_ptr, png_infop info_ptr, double
346 file_gamma);
347 void png_set_gAMA_fixed (png_structp png_ptr, png_infop info_ptr,
349 png_uint_32 file_gamma);
350 void png_set_gray_1_2_4_to_8(png_structp png_ptr);
352 void png_set_gray_to_rgb (png_structp png_ptr);
354 void png_set_hIST (png_structp png_ptr, png_infop info_ptr,
356 png_uint_16p hist);
357 void png_set_iCCP (png_structp png_ptr, png_infop info_ptr, png_charp
359 name, int compression_type, png_charp profile, png_uint_32 proflen);
360 int png_set_interlace_handling (png_structp png_ptr);
362 void png_set_invalid (png_structp png_ptr, png_infop info_ptr, int
364 mask);
365 void png_set_invert_alpha (png_structp png_ptr);
367 void png_set_invert_mono (png_structp png_ptr);
369 void png_set_IHDR (png_structp png_ptr, png_infop info_ptr, png_uint_32
371 width, png_uint_32 height, int bit_depth, int color_type, int inter‐
372 lace_type, int compression_type, int filter_type);
373 void png_set_keep_unknown_chunks (png_structp png_ptr, int keep,
375 png_bytep chunk_list, int num_chunks);
376 void png_set_mem_fn(png_structp png_ptr, png_voidp mem_ptr, png_mal‐
378 loc_ptr malloc_fn, png_free_ptr free_fn);
379 void png_set_oFFs (png_structp png_ptr, png_infop info_ptr, png_uint_32
381 offset_x, png_uint_32 offset_y, int unit_type);
382 void png_set_packing (png_structp png_ptr);
384 void png_set_packswap (png_structp png_ptr);
386 void png_set_palette_to_rgb(png_structp png_ptr);
388 void png_set_pCAL (png_structp png_ptr, png_infop info_ptr, png_charp
390 purpose, png_int_32 X0, png_int_32 X1, int type, int nparams, png_charp
391 units, png_charpp params);
392 void png_set_pHYs (png_structp png_ptr, png_infop info_ptr, png_uint_32
394 res_x, png_uint_32 res_y, int unit_type);
395 void png_set_progressive_read_fn (png_structp png_ptr, png_voidp pro‐
397 gressive_ptr, png_progressive_info_ptr info_fn, png_progressive_row_ptr
398 row_fn, png_progressive_end_ptr end_fn);
399 void png_set_PLTE (png_structp png_ptr, png_infop info_ptr, png_colorp
401 palette, int num_palette);
402 void png_set_read_fn (png_structp png_ptr, png_voidp io_ptr, png_rw_ptr
404 read_data_fn);
405 void png_set_read_status_fn (png_structp png_ptr, png_read_status_ptr
407 read_row_fn);
408 void png_set_read_user_transform_fn (png_structp png_ptr,
410 png_user_transform_ptr read_user_transform_fn);
411 void png_set_rgb_to_gray (png_structp png_ptr, int error_action, double
413 red, double green);
414 void png_set_rgb_to_gray_fixed (png_structp png_ptr, int error_action
416 png_fixed_point red, png_fixed_point green);
417 void png_set_rows (png_structp png_ptr, png_infop info_ptr, png_bytepp
419 row_pointers);
420 void png_set_sBIT (png_structp png_ptr, png_infop info_ptr,
422 png_color_8p sig_bit);
423 void png_set_sCAL (png_structp png_ptr, png_infop info_ptr, png_charp
425 unit, double width, double height);
426 void png_set_shift (png_structp png_ptr, png_color_8p true_bits);
428 void png_set_sig_bytes (png_structp png_ptr, int num_bytes);
430 void png_set_sPLT (png_structp png_ptr, png_infop info_ptr,
432 png_spalette_p splt_ptr, int num_spalettes);
433 void png_set_sRGB (png_structp png_ptr, png_infop info_ptr, int
435 intent);
436 void png_set_sRGB_gAMA_and_cHRM (png_structp png_ptr, png_infop
438 info_ptr, int intent);
439 void png_set_strip_16 (png_structp png_ptr);
441 void png_set_strip_alpha (png_structp png_ptr);
443 void png_set_swap (png_structp png_ptr);
445 void png_set_swap_alpha (png_structp png_ptr);
447 void png_set_text (png_structp png_ptr, png_infop info_ptr, png_textp
449 text_ptr, int num_text);
450 void png_set_tIME (png_structp png_ptr, png_infop info_ptr, png_timep
452 mod_time);
453 void png_set_tRNS (png_structp png_ptr, png_infop info_ptr, png_bytep
455 trans, int num_trans, png_color_16p trans_values);
456 void png_set_tRNS_to_alpha(png_structp png_ptr);
458 png_uint_32 png_set_unknown_chunks (png_structp png_ptr, png_infop
460 info_ptr, png_unknown_chunkp unknowns, int num, int location);
461 void png_set_unknown_chunk_location(png_structp png_ptr, png_infop
463 info_ptr, int chunk, int location);
464 void png_set_read_user_chunk_fn (png_structp png_ptr, png_voidp
466 user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn);
467 void png_set_user_limits (png_structp png_ptr, png_uint_32
469 user_width_max, png_uint_32 user_height_max);
470 void png_set_user_transform_info (png_structp png_ptr, png_voidp
472 user_transform_ptr, int user_transform_depth, int user_transform_chan‐
473 nels);
474 void png_set_write_fn (png_structp png_ptr, png_voidp io_ptr,
476 png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn);
477 void png_set_write_status_fn (png_structp png_ptr, png_write_status_ptr
479 write_row_fn);
480 void png_set_write_user_transform_fn (png_structp png_ptr,
482 png_user_transform_ptr write_user_transform_fn);
483 void png_set_compression_buffer_size(png_structp png_ptr, png_uint_32
485 size);
486 int png_sig_cmp (png_bytep sig, png_size_t start, png_size_t
488 num_to_check);
489 void png_start_read_image (png_structp png_ptr);
491 void png_warning (png_structp png_ptr, png_const_charp message);
493 void png_write_chunk (png_structp png_ptr, png_bytep chunk_name,
495 png_bytep data, png_size_t length);
496 void png_write_chunk_data (png_structp png_ptr, png_bytep data,
498 png_size_t length);
499 void png_write_chunk_end (png_structp png_ptr);
501 void png_write_chunk_start (png_structp png_ptr, png_bytep chunk_name,
503 png_uint_32 length);
504 void png_write_destroy (png_structp png_ptr);
506 void png_write_end (png_structp png_ptr, png_infop info_ptr);
508 void png_write_flush (png_structp png_ptr);
510 void png_write_image (png_structp png_ptr, png_bytepp image);
512 DEPRECATED: void png_write_init (png_structp png_ptr);
514 DEPRECATED: void png_write_init_2 (png_structpp ptr_ptr,
516 png_const_charp user_png_ver, png_size_t png_struct_size, png_size_t
517 png_info_size);
518 void png_write_info (png_structp png_ptr, png_infop info_ptr);
520 void png_write_info_before_PLTE (png_structp png_ptr, png_infop
522 info_ptr);
523 void png_write_png (png_structp png_ptr, png_infop info_ptr, int trans‐
525 forms, png_voidp params);
526 void png_write_row (png_structp png_ptr, png_bytep row);
528 void png_write_rows (png_structp png_ptr, png_bytepp row, png_uint_32
530 num_rows);
531 voidpf png_zalloc (voidpf png_ptr, uInt items, uInt size);
533 void png_zfree (voidpf png_ptr, voidpf ptr);
535
538 The libpng library supports encoding, decoding, and various manipula‐
539 tions of the Portable Network Graphics (PNG) format image files. It
540 uses the zlib(3) compression library. Following is a copy of the
541 libpng.txt file that accompanies libpng.
542
544 libpng.txt - A description on how to use and modify libpng
545 libpng version 1.2.29 - May 8, 2008
547 Updated and distributed by Glenn Randers-Pehrson
548 <glennrp at users.sourceforge.net>
549 Copyright (c) 1998-2008 Glenn Randers-Pehrson
550 For conditions of distribution and use, see copyright
551 notice in png.h.
552 Based on:
554 libpng versions 0.97, January 1998, through 1.2.29 - May 8, 2008
556 Updated and distributed by Glenn Randers-Pehrson
557 Copyright (c) 1998-2008 Glenn Randers-Pehrson
558 libpng 1.0 beta 6 version 0.96 May 28, 1997
560 Updated and distributed by Andreas Dilger
561 Copyright (c) 1996, 1997 Andreas Dilger
562 libpng 1.0 beta 2 - version 0.88 January 26, 1996
564 For conditions of distribution and use, see copyright
565 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
566 Schalnat, Group 42, Inc.
567 Updated/rewritten per request in the libpng FAQ
569 Copyright (c) 1995, 1996 Frank J. T. Wojcik
570 December 18, 1995 & January 20, 1996
571
574 This file describes how to use and modify the PNG reference library
575 (known as libpng) for your own use. There are five sections to this
576 file: introduction, structures, reading, writing, and modification and
577 configuration notes for various special platforms. In addition to this
578 file, example.c is a good starting point for using the library, as it
579 is heavily commented and should include everything most people will
580 need. We assume that libpng is already installed; see the INSTALL file
581 for instructions on how to install libpng.
582 For examples of libpng usage, see the files "example.c", "pngtest.c",
584 and the files in the "contrib" directory, all of which are included in
585 the libpng distribution.
586 Libpng was written as a companion to the PNG specification, as a way of
588 reducing the amount of time and effort it takes to support the PNG file
589 format in application programs.
590 The PNG specification (second edition), November 2003, is available as
592 a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
593 <http://www.w3.org/TR/2003/REC-PNG-20031110/ The W3C and ISO documents
594 have identical technical content.
595 The PNG-1.2 specification is available at
597 <http://www.libpng.org/pub/png/documents/>. It is technically equiva‐
598 lent to the PNG specification (second edition) but has some additional
599 material.
600 The PNG-1.0 specification is available as RFC 2083
602 <http://www.libpng.org/pub/png/documents/> and as a W3C Recommendation
603 <http://www.w3.org/TR/REC.png.html>.
604 Some additional chunks are described in the special-purpose public
606 chunks documents at <http://www.libpng.org/pub/png/documents/>.
607 Other information about PNG, and the latest version of libpng, can be
609 found at the PNG home page, <http://www.libpng.org/pub/png/>.
610 Most users will not have to modify the library significantly; advanced
612 users may want to modify it more. All attempts were made to make it as
613 complete as possible, while keeping the code easy to understand. Cur‐
614 rently, this library only supports C. Support for other languages is
615 being considered.
616 Libpng has been designed to handle multiple sessions at one time, to be
618 easily modifiable, to be portable to the vast majority of machines
619 (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy to use.
620 The ultimate goal of libpng is to promote the acceptance of the PNG
621 file format in whatever way possible. While there is still work to be
622 done (see the TODO file), libpng should cover the majority of the needs
623 of its users.
624 Libpng uses zlib for its compression and decompression of PNG files.
626 Further information about zlib, and the latest version of zlib, can be
627 found at the zlib home page, <http://www.info-
628 zip.org/pub/infozip/zlib/>. The zlib compression utility is a general
629 purpose utility that is useful for more than PNG files, and can be used
630 without libpng. See the documentation delivered with zlib for more
631 details. You can usually find the source files for the zlib utility
632 wherever you find the libpng source files.
633 Libpng is thread safe, provided the threads are using different
635 instances of the structures. Each thread should have its own
636 png_struct and png_info instances, and thus its own image. Libpng does
637 not protect itself against two threads using the same instance of a
638 structure.
639
642 There are two main structures that are important to libpng, png_struct
643 and png_info. The first, png_struct, is an internal structure that
644 will not, for the most part, be used by a user except as the first
645 variable passed to every libpng function call.
646 The png_info structure is designed to provide information about the PNG
648 file. At one time, the fields of png_info were intended to be directly
649 accessible to the user. However, this tended to cause problems with
650 applications using dynamically loaded libraries, and as a result a set
651 of interface functions for png_info (the png_get_*() and png_set_*()
652 functions) was developed. The fields of png_info are still available
653 for older applications, but it is suggested that applications use the
654 new interfaces if at all possible.
655 Applications that do make direct access to the members of png_struct
657 (except for png_ptr->jmpbuf) must be recompiled whenever the library is
658 updated, and applications that make direct access to the members of
659 png_info must be recompiled if they were compiled or loaded with libpng
660 version 1.0.6, in which the members were in a different order. In ver‐
661 sion 1.0.7, the members of the png_info structure reverted to the old
662 order, as they were in versions 0.97c through 1.0.5. Starting with
663 version 2.0.0, both structures are going to be hidden, and the contents
664 of the structures will only be accessible through the png_get/png_set
665 functions.
666 The png.h header file is an invaluable reference for programming with
668 libpng. And while I'm on the topic, make sure you include the libpng
669 header file:
670 #include <png.h>
672
675 We'll now walk you through the possible functions to call when reading
676 in a PNG file sequentially, briefly explaining the syntax and purpose
677 of each one. See example.c and png.h for more detail. While progres‐
678 sive reading is covered in the next section, you will still need some
679 of the functions discussed in this section to read a PNG file.
680 Setup
683 You will want to do the I/O initialization(*) before you get into
684 libpng, so if it doesn't work, you don't have much to undo. Of course,
685 you will also want to insure that you are, in fact, dealing with a PNG
686 file. Libpng provides a simple check to see if a file is a PNG file.
687 To use it, pass in the first 1 to 8 bytes of the file to the function
688 png_sig_cmp(), and it will return 0 if the bytes match the correspond‐
689 ing bytes of the PNG signature, or nonzero otherwise. Of course, the
690 more bytes you pass in, the greater the accuracy of the prediction.
691 If you are intending to keep the file pointer open for use in libpng,
693 you must ensure you don't read more than 8 bytes from the beginning of
694 the file, and you also have to make a call to png_set_sig_bytes_read()
695 with the number of bytes you read from the beginning. Libpng will then
696 only check the bytes (if any) that your program didn't read.
697 (*): If you are not using the standard I/O functions, you will need to
699 replace them with custom functions. See the discussion under Customiz‐
700 ing libpng.
701 FILE *fp = fopen(file_name, "rb");
704 if (!fp)
705 {
706 return (ERROR);
707 }
708 fread(header, 1, number, fp);
709 is_png = !png_sig_cmp(header, 0, number);
710 if (!is_png)
711 {
712 return (NOT_PNG);
713 }
714 Next, png_struct and png_info need to be allocated and initialized. In
717 order to ensure that the size of these structures is correct even with
718 a dynamically linked libpng, there are functions to initialize and
719 allocate the structures. We also pass the library version, optional
720 pointers to error handling functions, and a pointer to a data struct
721 for use by the error functions, if necessary (the pointer and functions
722 can be NULL if the default error handlers are to be used). See the
723 section on Changes to Libpng below regarding the old initialization
724 functions. The structure allocation functions quietly return NULL if
725 they fail to create the structure, so your application should check for
726 that.
727 png_structp png_ptr = png_create_read_struct
729 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
730 user_error_fn, user_warning_fn);
731 if (!png_ptr)
732 return (ERROR);
733 png_infop info_ptr = png_create_info_struct(png_ptr);
735 if (!info_ptr)
736 {
737 png_destroy_read_struct(&png_ptr,
738 (png_infopp)NULL, (png_infopp)NULL);
739 return (ERROR);
740 }
741 png_infop end_info = png_create_info_struct(png_ptr);
743 if (!end_info)
744 {
745 png_destroy_read_struct(&png_ptr, &info_ptr,
746 (png_infopp)NULL);
747 return (ERROR);
748 }
749 If you want to use your own memory allocation routines, define
751 PNG_USER_MEM_SUPPORTED and use png_create_read_struct_2() instead of
752 png_create_read_struct():
753 png_structp png_ptr = png_create_read_struct_2
755 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
756 user_error_fn, user_warning_fn, (png_voidp)
757 user_mem_ptr, user_malloc_fn, user_free_fn);
758 The error handling routines passed to png_create_read_struct() and the
760 memory alloc/free routines passed to png_create_struct_2() are only
761 necessary if you are not using the libpng supplied error handling and
762 memory alloc/free functions.
763 When libpng encounters an error, it expects to longjmp back to your
765 routine. Therefore, you will need to call setjmp and pass your
766 png_jmpbuf(png_ptr). If you read the file from different routines, you
767 will need to update the jmpbuf field every time you enter a new routine
768 that will call a png_*() function.
769 See your documentation of setjmp/longjmp for your compiler for more
771 information on setjmp/longjmp. See the discussion on libpng error han‐
772 dling in the Customizing Libpng section below for more information on
773 the libpng error handling. If an error occurs, and libpng longjmp's
774 back to your setjmp, you will want to call png_destroy_read_struct() to
775 free any memory.
776 if (setjmp(png_jmpbuf(png_ptr)))
778 {
779 png_destroy_read_struct(&png_ptr, &info_ptr,
780 &end_info);
781 fclose(fp);
782 return (ERROR);
783 }
784 If you would rather avoid the complexity of setjmp/longjmp issues, you
786 can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case errors
787 will result in a call to PNG_ABORT() which defaults to abort().
788 Now you need to set up the input code. The default for libpng is to
790 use the C function fread(). If you use this, you will need to pass a
791 valid FILE * in the function png_init_io(). Be sure that the file is
792 opened in binary mode. If you wish to handle reading data in another
793 way, you need not call the png_init_io() function, but you must then
794 implement the libpng I/O methods discussed in the Customizing Libpng
795 section below.
796 png_init_io(png_ptr, fp);
798 If you had previously opened the file and read any of the signature
800 from the beginning in order to see if this was a PNG file, you need to
801 let libpng know that there are some bytes missing from the start of the
802 file.
803 png_set_sig_bytes(png_ptr, number);
805 Setting up callback code
808 You can set up a callback function to handle any unknown chunks in the
809 input stream. You must supply the function
810 read_chunk_callback(png_ptr ptr,
812 png_unknown_chunkp chunk);
813 {
814 /* The unknown chunk structure contains your
815 chunk data, along with similar data for any other
816 unknown chunks: */
817 png_byte name[5];
819 png_byte *data;
820 png_size_t size;
821 /* Note that libpng has already taken care of
823 the CRC handling */
824 /* put your code here. Search for your chunk in the
826 unknown chunk structure, process it, and return one
827 of the following: */
828 return (-n); /* chunk had an error */
830 return (0); /* did not recognize */
831 return (n); /* success */
832 }
833 (You can give your function another name that you like instead of
835 "read_chunk_callback")
836 To inform libpng about your function, use
838 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
840 read_chunk_callback);
841 This names not only the callback function, but also a user pointer that
843 you can retrieve with
844 png_get_user_chunk_ptr(png_ptr);
846 If you call the png_set_read_user_chunk_fn() function, then all unknown
848 chunks will be saved when read, in case your callback function will
849 need one or more of them. This behavior can be changed with the
850 png_set_keep_unknown_chunks() function, described below.
851 At this point, you can set up a callback function that will be called
853 after each row has been read, which you can use to control a progress
854 meter or the like. It's demonstrated in pngtest.c. You must supply a
855 function
856 void read_row_callback(png_ptr ptr, png_uint_32 row,
858 int pass);
859 {
860 /* put your code here */
861 }
862 (You can give it another name that you like instead of "read_row_call‐
864 back")
865 To inform libpng about your function, use
867 png_set_read_status_fn(png_ptr, read_row_callback);
869 Width and height limits
872 The PNG specification allows the width and height of an image to be as
873 large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
874 Since very few applications really need to process such large images,
875 we have imposed an arbitrary 1-million limit on rows and columns.
876 Larger images will be rejected immediately with a png_error() call. If
877 you wish to override this limit, you can use
878 png_set_user_limits(png_ptr, width_max, height_max);
880 to set your own limits, or use width_max = height_max = 0x7fffffffL to
882 allow all valid dimensions (libpng may reject some very large images
883 anyway because of potential buffer overflow conditions).
884 You should put this statement after you create the PNG structure and
886 before calling png_read_info(), png_read_png(), or png_process_data().
887 If you need to retrieve the limits that are being applied, use
888 width_max = png_get_user_width_max(png_ptr);
890 height_max = png_get_user_height_max(png_ptr);
891 Unknown-chunk handling
894 Now you get to set the way the library processes unknown chunks in the
895 input PNG stream. Both known and unknown chunks will be read. Normal
896 behavior is that known chunks will be parsed into information in vari‐
897 ous info_ptr members while unknown chunks will be discarded. To change
898 this, you can call:
899 png_set_keep_unknown_chunks(png_ptr, keep,
901 chunk_list, num_chunks);
902 keep - 0: default unknown chunk handling
903 1: ignore; do not keep
904 2: keep only if safe-to-copy
905 3: keep even if unsafe-to-copy
906 You can use these definitions:
907 PNG_HANDLE_CHUNK_AS_DEFAULT 0
908 PNG_HANDLE_CHUNK_NEVER 1
909 PNG_HANDLE_CHUNK_IF_SAFE 2
910 PNG_HANDLE_CHUNK_ALWAYS 3
911 chunk_list - list of chunks affected (a byte string,
912 five bytes per chunk, NULL or ' ' if
913 num_chunks is 0)
914 num_chunks - number of chunks affected; if 0, all
915 unknown chunks are affected. If nonzero,
916 only the chunks in the list are affected
917 Unknown chunks declared in this way will be saved as raw data onto a
919 list of png_unknown_chunk structures. If a chunk that is normally
920 known to libpng is named in the list, it will be handled as unknown,
921 according to the "keep" directive. If a chunk is named in successive
922 instances of png_set_keep_unknown_chunks(), the final instance will
923 take precedence. The IHDR and IEND chunks should not be named in
924 chunk_list; if they are, libpng will process them normally anyway.
925 Here is an example of the usage of png_set_keep_unknown_chunks(), where
927 the private "vpAg" chunk will later be processed by a user chunk call‐
928 back function:
929 png_byte vpAg[5]={118, 112, 65, 103, (png_byte) ' '};
931 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
933 png_byte unused_chunks[]=
934 {
935 104, 73, 83, 84, (png_byte) ' ', /* hIST */
936 105, 84, 88, 116, (png_byte) ' ', /* iTXt */
937 112, 67, 65, 76, (png_byte) ' ', /* pCAL */
938 115, 67, 65, 76, (png_byte) ' ', /* sCAL */
939 115, 80, 76, 84, (png_byte) ' ', /* sPLT */
940 116, 73, 77, 69, (png_byte) ' ', /* tIME */
941 };
942 #endif
943 ...
945 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
947 /* ignore all unknown chunks: */
948 png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
949 /* except for vpAg: */
950 png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
951 /* also ignore unused known chunks: */
952 png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
953 (int)sizeof(unused_chunks)/5);
954 #endif
955 The high-level read interface
959 At this point there are two ways to proceed; through the high-level
960 read interface, or through a sequence of low-level read operations.
961 You can use the high-level interface if (a) you are willing to read the
962 entire image into memory, and (b) the input transformations you want to
963 do are limited to the following set:
964 PNG_TRANSFORM_IDENTITY No transformation
966 PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
967 8 bits
968 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
969 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
970 samples to bytes
971 PNG_TRANSFORM_PACKSWAP Change order of packed
972 pixels to LSB first
973 PNG_TRANSFORM_EXPAND Perform set_expand()
974 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
975 PNG_TRANSFORM_SHIFT Normalize pixels to the
976 sBIT depth
977 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
978 to BGRA
979 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
980 to AG
981 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
982 to transparency
983 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
984 (This excludes setting a background color, doing gamma transformation,
986 dithering, and setting filler.) If this is the case, simply do this:
987 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
989 where png_transforms is an integer containing the bitwise OR of some
991 set of transformation flags. This call is equivalent to
992 png_read_info(), followed the set of transformations indicated by the
993 transform mask, then png_read_image(), and finally png_read_end().
994 (The final parameter of this call is not yet used. Someday it might
996 point to transformation parameters required by some future input trans‐
997 form.)
998 You must use png_transforms and not call any png_set_transform() func‐
1000 tions when you use png_read_png().
1001 After you have called png_read_png(), you can retrieve the image data
1003 with
1004 row_pointers = png_get_rows(png_ptr, info_ptr);
1006 where row_pointers is an array of pointers to the pixel data for each
1008 row:
1009 png_bytep row_pointers[height];
1011 If you know your image size and pixel size ahead of time, you can allo‐
1013 cate row_pointers prior to calling png_read_png() with
1014 if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
1016 png_error (png_ptr,
1017 "Image is too tall to process in memory");
1018 if (width > PNG_UINT_32_MAX/pixel_size)
1019 png_error (png_ptr,
1020 "Image is too wide to process in memory");
1021 row_pointers = png_malloc(png_ptr,
1022 height*png_sizeof(png_bytep));
1023 for (int i=0; i<height, i++)
1024 row_pointers[i]=png_malloc(png_ptr,
1025 width*pixel_size);
1026 png_set_rows(png_ptr, info_ptr, &row_pointers);
1027 Alternatively you could allocate your image in one big block and define
1029 row_pointers[i] to point into the proper places in your block.
1030 If you use png_set_rows(), the application is responsible for freeing
1032 row_pointers (and row_pointers[i], if they were separately allocated).
1033 If you don't allocate row_pointers ahead of time, png_read_png() will
1035 do it, and it'll be free'ed when you call png_destroy_*().
1036 The low-level read interface
1039 If you are going the low-level route, you are now ready to read all the
1040 file information up to the actual image data. You do this with a call
1041 to png_read_info().
1042 png_read_info(png_ptr, info_ptr);
1044 This will process all chunks up to but not including the image data.
1046 Querying the info structure
1049 Functions are used to get the information from the info_ptr once it has
1050 been read. Note that these fields may not be completely filled in
1051 until png_read_end() has read the chunk data following the image.
1052 png_get_IHDR(png_ptr, info_ptr, &width, &height,
1054 &bit_depth, &color_type, &interlace_type,
1055 &compression_type, &filter_method);
1056 width - holds the width of the image
1058 in pixels (up to 2^31).
1059 height - holds the height of the image
1060 in pixels (up to 2^31).
1061 bit_depth - holds the bit depth of one of the
1062 image channels. (valid values are
1063 1, 2, 4, 8, 16 and depend also on
1064 the color_type. See also
1065 significant bits (sBIT) below).
1066 color_type - describes which color/alpha channels
1067 are present.
1068 PNG_COLOR_TYPE_GRAY
1069 (bit depths 1, 2, 4, 8, 16)
1070 PNG_COLOR_TYPE_GRAY_ALPHA
1071 (bit depths 8, 16)
1072 PNG_COLOR_TYPE_PALETTE
1073 (bit depths 1, 2, 4, 8)
1074 PNG_COLOR_TYPE_RGB
1075 (bit_depths 8, 16)
1076 PNG_COLOR_TYPE_RGB_ALPHA
1077 (bit_depths 8, 16)
1078 PNG_COLOR_MASK_PALETTE
1080 PNG_COLOR_MASK_COLOR
1081 PNG_COLOR_MASK_ALPHA
1082 filter_method - (must be PNG_FILTER_TYPE_BASE
1084 for PNG 1.0, and can also be
1085 PNG_INTRAPIXEL_DIFFERENCING if
1086 the PNG datastream is embedded in
1087 a MNG-1.0 datastream)
1088 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1089 for PNG 1.0)
1090 interlace_type - (PNG_INTERLACE_NONE or
1091 PNG_INTERLACE_ADAM7)
1092 Any or all of interlace_type, compression_type, of
1093 filter_method can be NULL if you are
1094 not interested in their values.
1095 channels = png_get_channels(png_ptr, info_ptr);
1097 channels - number of channels of info for the
1098 color type (valid values are 1 (GRAY,
1099 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1100 4 (RGB_ALPHA or RGB + filler byte))
1101 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1102 rowbytes - number of bytes needed to hold a row
1103 signature = png_get_signature(png_ptr, info_ptr);
1105 signature - holds the signature read from the
1106 file (if any). The data is kept in
1107 the same offset it would be if the
1108 whole signature were read (i.e. if an
1109 application had already read in 4
1110 bytes of signature before starting
1111 libpng, the remaining 4 bytes would
1112 be in signature[4] through signature[7]
1113 (see png_set_sig_bytes())).
1114 width = png_get_image_width(png_ptr,
1117 info_ptr);
1118 height = png_get_image_height(png_ptr,
1119 info_ptr);
1120 bit_depth = png_get_bit_depth(png_ptr,
1121 info_ptr);
1122 color_type = png_get_color_type(png_ptr,
1123 info_ptr);
1124 filter_method = png_get_filter_type(png_ptr,
1125 info_ptr);
1126 compression_type = png_get_compression_type(png_ptr,
1127 info_ptr);
1128 interlace_type = png_get_interlace_type(png_ptr,
1129 info_ptr);
1130 These are also important, but their validity depends on whether the
1133 chunk has been read. The png_get_valid(png_ptr, info_ptr,
1134 PNG_INFO_<chunk>) and png_get_<chunk>(png_ptr, info_ptr, ...) functions
1135 return non-zero if the data has been read, or zero if it is missing.
1136 The parameters to the png_get_<chunk> are set directly if they are sim‐
1137 ple data types, or a pointer into the info_ptr is returned for any com‐
1138 plex types.
1139 png_get_PLTE(png_ptr, info_ptr, &palette,
1141 &num_palette);
1142 palette - the palette for the file
1143 (array of png_color)
1144 num_palette - number of entries in the palette
1145 png_get_gAMA(png_ptr, info_ptr, &gamma);
1147 gamma - the gamma the file is written
1148 at (PNG_INFO_gAMA)
1149 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1151 srgb_intent - the rendering intent (PNG_INFO_sRGB)
1152 The presence of the sRGB chunk
1153 means that the pixel data is in the
1154 sRGB color space. This chunk also
1155 implies specific values of gAMA and
1156 cHRM.
1157 png_get_iCCP(png_ptr, info_ptr, &name,
1159 &compression_type, &profile, &proflen);
1160 name - The profile name.
1161 compression - The compression type; always
1162 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1163 You may give NULL to this argument to
1164 ignore it.
1165 profile - International Color Consortium color
1166 profile data. May contain NULs.
1167 proflen - length of profile data in bytes.
1168 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1170 sig_bit - the number of significant bits for
1171 (PNG_INFO_sBIT) each of the gray,
1172 red, green, and blue channels,
1173 whichever are appropriate for the
1174 given color type (png_color_16)
1175 png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
1177 &trans_values);
1178 trans - array of transparent entries for
1179 palette (PNG_INFO_tRNS)
1180 trans_values - graylevel or color sample values of
1181 the single transparent color for
1182 non-paletted images (PNG_INFO_tRNS)
1183 num_trans - number of transparent entries
1184 (PNG_INFO_tRNS)
1185 png_get_hIST(png_ptr, info_ptr, &hist);
1187 (PNG_INFO_hIST)
1188 hist - histogram of palette (array of
1189 png_uint_16)
1190 png_get_tIME(png_ptr, info_ptr, &mod_time);
1192 mod_time - time image was last modified
1193 (PNG_VALID_tIME)
1194 png_get_bKGD(png_ptr, info_ptr, &background);
1196 background - background color (PNG_VALID_bKGD)
1197 valid 16-bit red, green and blue
1198 values, regardless of color_type
1199 num_comments = png_get_text(png_ptr, info_ptr,
1201 &text_ptr, &num_text);
1202 num_comments - number of comments
1203 text_ptr - array of png_text holding image
1204 comments
1205 text_ptr[i].compression - type of compression used
1206 on "text" PNG_TEXT_COMPRESSION_NONE
1207 PNG_TEXT_COMPRESSION_zTXt
1208 PNG_ITXT_COMPRESSION_NONE
1209 PNG_ITXT_COMPRESSION_zTXt
1210 text_ptr[i].key - keyword for comment. Must contain
1211 1-79 characters.
1212 text_ptr[i].text - text comments for current
1213 keyword. Can be empty.
1214 text_ptr[i].text_length - length of text string,
1215 after decompression, 0 for iTXt
1216 text_ptr[i].itxt_length - length of itxt string,
1217 after decompression, 0 for tEXt/zTXt
1218 text_ptr[i].lang - language of comment (empty
1219 string for unknown).
1220 text_ptr[i].lang_key - keyword in UTF-8
1221 (empty string for unknown).
1222 num_text - number of comments (same as
1223 num_comments; you can put NULL here
1224 to avoid the duplication)
1225 Note while png_set_text() will accept text, language,
1226 and translated keywords that can be NULL pointers, the
1227 structure returned by png_get_text will always contain
1228 regular zero-terminated C strings. They might be
1229 empty strings but they will never be NULL pointers.
1230 num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1232 &palette_ptr);
1233 palette_ptr - array of palette structures holding
1234 contents of one or more sPLT chunks
1235 read.
1236 num_spalettes - number of sPLT chunks read.
1237 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
1239 &unit_type);
1240 offset_x - positive offset from the left edge
1241 of the screen
1242 offset_y - positive offset from the top edge
1243 of the screen
1244 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1245 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
1247 &unit_type);
1248 res_x - pixels/unit physical resolution in
1249 x direction
1250 res_y - pixels/unit physical resolution in
1251 x direction
1252 unit_type - PNG_RESOLUTION_UNKNOWN,
1253 PNG_RESOLUTION_METER
1254 png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1256 &height)
1257 unit - physical scale units (an integer)
1258 width - width of a pixel in physical scale units
1259 height - height of a pixel in physical scale units
1260 (width and height are doubles)
1261 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1263 &height)
1264 unit - physical scale units (an integer)
1265 width - width of a pixel in physical scale units
1266 height - height of a pixel in physical scale units
1267 (width and height are strings like "2.54")
1268 num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1270 info_ptr, &unknowns)
1271 unknowns - array of png_unknown_chunk
1272 structures holding unknown chunks
1273 unknowns[i].name - name of unknown chunk
1274 unknowns[i].data - data of unknown chunk
1275 unknowns[i].size - size of unknown chunk's data
1276 unknowns[i].location - position of chunk in file
1277 The value of "i" corresponds to the order in which the
1279 chunks were read from the PNG file or inserted with the
1280 png_set_unknown_chunks() function.
1281 The data from the pHYs chunk can be retrieved in several convenient
1283 forms:
1284 res_x = png_get_x_pixels_per_meter(png_ptr,
1286 info_ptr)
1287 res_y = png_get_y_pixels_per_meter(png_ptr,
1288 info_ptr)
1289 res_x_and_y = png_get_pixels_per_meter(png_ptr,
1290 info_ptr)
1291 res_x = png_get_x_pixels_per_inch(png_ptr,
1292 info_ptr)
1293 res_y = png_get_y_pixels_per_inch(png_ptr,
1294 info_ptr)
1295 res_x_and_y = png_get_pixels_per_inch(png_ptr,
1296 info_ptr)
1297 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
1298 info_ptr)
1299 (Each of these returns 0 [signifying "unknown"] if
1301 the data is not present or if res_x is 0;
1302 res_x_and_y is 0 if res_x != res_y)
1303 The data from the oFFs chunk can be retrieved in several convenient
1305 forms:
1306 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1308 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1309 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1310 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1311 (Each of these returns 0 [signifying "unknown" if both
1313 x and y are 0] if the data is not present or if the
1314 chunk is present but the unit is the pixel)
1315 For more information, see the png_info definition in png.h and the PNG
1317 specification for chunk contents. Be careful with trusting rowbytes,
1318 as some of the transformations could increase the space needed to hold
1319 a row (expand, filler, gray_to_rgb, etc.). See png_read_update_info(),
1320 below.
1321 A quick word about text_ptr and num_text. PNG stores comments in key‐
1323 word/text pairs, one pair per chunk, with no limit on the number of
1324 text chunks, and a 2^31 byte limit on their size. While there are sug‐
1325 gested keywords, there is no requirement to restrict the use to these
1326 strings. It is strongly suggested that keywords and text be sensible
1327 to humans (that's the point), so don't use abbreviations. Non-printing
1328 symbols are not allowed. See the PNG specification for more details.
1329 There is also no requirement to have text after the keyword.
1330 Keywords should be limited to 79 Latin-1 characters without leading or
1332 trailing spaces, but non-consecutive spaces are allowed within the key‐
1333 word. It is possible to have the same keyword any number of times.
1334 The text_ptr is an array of png_text structures, each holding a pointer
1335 to a language string, a pointer to a keyword and a pointer to a text
1336 string. The text string, language code, and translated keyword may be
1337 empty or NULL pointers. The keyword/text pairs are put into the array
1338 in the order that they are received. However, some or all of the text
1339 chunks may be after the image, so, to make sure you have read all the
1340 text chunks, don't mess with these until after you read the stuff after
1341 the image. This will be mentioned again below in the discussion that
1342 goes with png_read_end().
1343 Input transformations
1346 After you've read the header information, you can set up the library to
1347 handle any special transformations of the image data. The various ways
1348 to transform the data will be described in the order that they should
1349 occur. This is important, as some of these change the color type
1350 and/or bit depth of the data, and some others only work on certain
1351 color types and bit depths. Even though each transformation checks to
1352 see if it has data that it can do something with, you should make sure
1353 to only enable a transformation if it will be valid for the data. For
1354 example, don't swap red and blue on grayscale data.
1355 The colors used for the background and transparency values should be
1357 supplied in the same format/depth as the current image data. They are
1358 stored in the same format/depth as the image data in a bKGD or tRNS
1359 chunk, so this is what libpng expects for this data. The colors are
1360 transformed to keep in sync with the image data when an application
1361 calls the png_read_update_info() routine (see below).
1362 Data will be decoded into the supplied row buffers packed into bytes
1364 unless the library has been told to transform it into another format.
1365 For example, 4 bit/pixel paletted or grayscale data will be returned 2
1366 pixels/byte with the leftmost pixel in the high-order bits of the byte,
1367 unless png_set_packing() is called. 8-bit RGB data will be stored in
1368 RGB RGB RGB format unless png_set_filler() or png_set_add_alpha() is
1369 called to insert filler bytes, either before or after each RGB triplet.
1370 16-bit RGB data will be returned RRGGBB RRGGBB, with the most signifi‐
1371 cant byte of the color value first, unless png_set_strip_16() is called
1372 to transform it to regular RGB RGB triplets, or png_set_filler() or
1373 png_set_add alpha() is called to insert filler bytes, either before or
1374 after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data
1375 can be modified with png_set_filler(), png_set_add_alpha(), or
1376 png_set_strip_16().
1377 The following code transforms grayscale images of less than 8 to 8
1379 bits, changes paletted images to RGB, and adds a full alpha channel if
1380 there is transparency information in a tRNS chunk. This is most useful
1381 on grayscale images with bit depths of 2 or 4 or if there is a multi‐
1382 ple-image viewing application that wishes to treat all images in the
1383 same way.
1384 if (color_type == PNG_COLOR_TYPE_PALETTE)
1386 png_set_palette_to_rgb(png_ptr);
1387 if (color_type == PNG_COLOR_TYPE_GRAY &&
1389 bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
1390 if (png_get_valid(png_ptr, info_ptr,
1392 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1393 These three functions are actually aliases for png_set_expand(), added
1395 in libpng version 1.0.4, with the function names expanded to improve
1396 code readability. In some future version they may actually do differ‐
1397 ent things.
1398 As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was added.
1400 It expands the sample depth without changing tRNS to alpha. At the
1401 same time, png_set_gray_1_2_4_to_8() was deprecated, and it will be
1402 removed from a future version.
1403 PNG can have files with 16 bits per channel. If you only can handle 8
1406 bits per channel, this will strip the pixels down to 8 bit.
1407 if (bit_depth == 16)
1409 png_set_strip_16(png_ptr);
1410 If, for some reason, you don't need the alpha channel on an image, and
1412 you want to remove it rather than combining it with the background (but
1413 the image author certainly had in mind that you *would* combine it with
1414 the background, so that's what you should probably do):
1415 if (color_type & PNG_COLOR_MASK_ALPHA)
1417 png_set_strip_alpha(png_ptr);
1418 In PNG files, the alpha channel in an image is the level of opacity.
1420 If you need the alpha channel in an image to be the level of trans‐
1421 parency instead of opacity, you can invert the alpha channel (or the
1422 tRNS chunk data) after it's read, so that 0 is fully opaque and 255 (in
1423 8-bit or paletted images) or 65535 (in 16-bit images) is fully trans‐
1424 parent, with
1425 png_set_invert_alpha(png_ptr);
1427 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1429 they can, resulting in, for example, 8 pixels per byte for 1 bit files.
1430 This code expands to 1 pixel per byte without changing the values of
1431 the pixels:
1432 if (bit_depth < 8)
1434 png_set_packing(png_ptr);
1435 PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
1437 stored in a PNG image have been "scaled" or "shifted" up to the next
1438 higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
1439 to 8 bits/sample in the range [0, 255]). However, it is also possible
1440 to convert the PNG pixel data back to the original bit depth of the
1441 image. This call reduces the pixels back down to the original bit
1442 depth:
1443 png_color_8p sig_bit;
1445 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1447 png_set_shift(png_ptr, sig_bit);
1448 PNG files store 3-color pixels in red, green, blue order. This code
1450 changes the storage of the pixels to blue, green, red:
1451 if (color_type == PNG_COLOR_TYPE_RGB ||
1453 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1454 png_set_bgr(png_ptr);
1455 PNG files store RGB pixels packed into 3 or 6 bytes. This code expands
1457 them into 4 or 8 bytes for windowing systems that need them in this
1458 format:
1459 if (color_type == PNG_COLOR_TYPE_RGB)
1461 png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
1462 where "filler" is the 8 or 16-bit number to fill with, and the location
1464 is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1465 you want the filler before the RGB or after. This transformation does
1466 not affect images that already have full alpha channels. To add an
1467 opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER
1468 which will generate RGBA pixels.
1469 Note that png_set_filler() does not change the color type. If you want
1471 to do that, you can add a true alpha channel with
1472 if (color_type == PNG_COLOR_TYPE_RGB ||
1474 color_type == PNG_COLOR_TYPE_GRAY)
1475 png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1476 where "filler" contains the alpha value to assign to each pixel. This
1478 function was added in libpng-1.2.7.
1479 If you are reading an image with an alpha channel, and you need the
1481 data as ARGB instead of the normal PNG format RGBA:
1482 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1484 png_set_swap_alpha(png_ptr);
1485 For some uses, you may want a grayscale image to be represented as RGB.
1487 This code will do that conversion:
1488 if (color_type == PNG_COLOR_TYPE_GRAY ||
1490 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1491 png_set_gray_to_rgb(png_ptr);
1492 Conversely, you can convert an RGB or RGBA image to grayscale or
1494 grayscale with alpha.
1495 if (color_type == PNG_COLOR_TYPE_RGB ||
1497 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1498 png_set_rgb_to_gray_fixed(png_ptr, error_action,
1499 int red_weight, int green_weight);
1500 error_action = 1: silently do the conversion
1502 error_action = 2: issue a warning if the original
1503 image has any pixel where
1504 red != green or red != blue
1505 error_action = 3: issue an error and abort the
1506 conversion if the original
1507 image has any pixel where
1508 red != green or red != blue
1509 red_weight: weight of red component times 100000
1511 green_weight: weight of green component times 100000
1512 If either weight is negative, default
1513 weights (21268, 71514) are used.
1514 If you have set error_action = 1 or 2, you can later check whether the
1516 image really was gray, after processing the image rows, with the
1517 png_get_rgb_to_gray_status(png_ptr) function. It will return a
1518 png_byte that is zero if the image was gray or 1 if there were any non-
1519 gray pixels. bKGD and sBIT data will be silently converted to
1520 grayscale, using the green channel data, regardless of the error_action
1521 setting.
1522 With red_weight+green_weight<=100000, the normalized graylevel is com‐
1524 puted:
1525 int rw = red_weight * 65536;
1527 int gw = green_weight * 65536;
1528 int bw = 65536 - (rw + gw);
1529 gray = (rw*red + gw*green + bw*blue)/65536;
1530 The default values approximate those recommended in the Charles Poyn‐
1532 ton's Color FAQ, <http://www.inforamp.net/~poynton/> Copyright (c)
1533 1998-01-04 Charles Poynton <poynton at inforamp.net>
1534 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1536 Libpng approximates this with
1538 Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
1540 which can be expressed with integers as
1542 Y = (6969 * R + 23434 * G + 2365 * B)/32768
1544 The calculation is done in a linear colorspace, if the image gamma is
1546 known.
1547 If you have a grayscale and you are using png_set_expand_depth(),
1549 png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to a
1550 higher bit-depth, you must either supply the background color as a gray
1551 value at the original file bit-depth (need_expand = 1) or else supply
1552 the background color as an RGB triplet at the final, expanded bit depth
1553 (need_expand = 0). Similarly, if you are reading a paletted image, you
1554 must either supply the background color as a palette index (need_expand
1555 = 1) or as an RGB triplet that may or may not be in the palette
1556 (need_expand = 0).
1557 png_color_16 my_background;
1559 png_color_16p image_background;
1560 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1562 png_set_background(png_ptr, image_background,
1563 PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
1564 else
1565 png_set_background(png_ptr, &my_background,
1566 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
1567 The png_set_background() function tells libpng to composite images with
1569 alpha or simple transparency against the supplied background color. If
1570 the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), you may use
1571 this color, or supply another color more suitable for the current dis‐
1572 play (e.g., the background color from a web page). You need to tell
1573 libpng whether the color is in the gamma space of the display
1574 (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
1575 (PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one that
1576 is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't know
1577 why anyone would use this, but it's here).
1578 To properly display PNG images on any kind of system, the application
1580 needs to know what the display gamma is. Ideally, the user will know
1581 this, and the application will allow them to set it. One method of
1582 allowing the user to set the display gamma separately for each system
1583 is to check for a SCREEN_GAMMA or DISPLAY_GAMMA environment variable,
1584 which will hopefully be correctly set.
1585 Note that display_gamma is the overall gamma correction required to
1587 produce pleasing results, which depends on the lighting conditions in
1588 the surrounding environment. In a dim or brightly lit room, no compen‐
1589 sation other than the physical gamma exponent of the monitor is needed,
1590 while in a dark room a slightly smaller exponent is better.
1591 double gamma, screen_gamma;
1593 if (/* We have a user-defined screen
1595 gamma value */)
1596 {
1597 screen_gamma = user_defined_screen_gamma;
1598 }
1599 /* One way that applications can share the same
1600 screen gamma value */
1601 else if ((gamma_str = getenv("SCREEN_GAMMA"))
1602 != NULL)
1603 {
1604 screen_gamma = (double)atof(gamma_str);
1605 }
1606 /* If we don't have another value */
1607 else
1608 {
1609 screen_gamma = 2.2; /* A good guess for a
1610 PC monitor in a bright office or a dim room */
1611 screen_gamma = 2.0; /* A good guess for a
1612 PC monitor in a dark room */
1613 screen_gamma = 1.7 or 1.0; /* A good
1614 guess for Mac systems */
1615 }
1616 The png_set_gamma() function handles gamma transformations of the data.
1618 Pass both the file gamma and the current screen_gamma. If the file
1619 does not have a gamma value, you can pass one anyway if you have an
1620 idea what it is (usually 0.45455 is a good guess for GIF images on
1621 PCs). Note that file gammas are inverted from screen gammas. See the
1622 discussions on gamma in the PNG specification for an excellent descrip‐
1623 tion of what gamma is, and why all applications should support it. It
1624 is strongly recommended that PNG viewers support gamma correction.
1625 if (png_get_gAMA(png_ptr, info_ptr, &gamma))
1627 png_set_gamma(png_ptr, screen_gamma, gamma);
1628 else
1629 png_set_gamma(png_ptr, screen_gamma, 0.45455);
1630 If you need to reduce an RGB file to a paletted file, or if a paletted
1632 file has more entries then will fit on your screen, png_set_dither()
1633 will do that. Note that this is a simple match dither that merely
1634 finds the closest color available. This should work fairly well with
1635 optimized palettes, and fairly badly with linear color cubes. If you
1636 pass a palette that is larger then maximum_colors, the file will reduce
1637 the number of colors in the palette so it will fit into maximum_colors.
1638 If there is a histogram, it will use it to make more intelligent
1639 choices when reducing the palette. If there is no histogram, it may
1640 not do as good a job.
1641 if (color_type & PNG_COLOR_MASK_COLOR)
1643 {
1644 if (png_get_valid(png_ptr, info_ptr,
1645 PNG_INFO_PLTE))
1646 {
1647 png_uint_16p histogram = NULL;
1648 png_get_hIST(png_ptr, info_ptr,
1650 &histogram);
1651 png_set_dither(png_ptr, palette, num_palette,
1652 max_screen_colors, histogram, 1);
1653 }
1654 else
1655 {
1656 png_color std_color_cube[MAX_SCREEN_COLORS] =
1657 { ... colors ... };
1658 png_set_dither(png_ptr, std_color_cube,
1660 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1661 NULL,0);
1662 }
1663 }
1664 PNG files describe monochrome as black being zero and white being one.
1666 The following code will reverse this (make black be one and white be
1667 zero):
1668 if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
1670 png_set_invert_mono(png_ptr);
1671 This function can also be used to invert grayscale and gray-alpha
1673 images:
1674 if (color_type == PNG_COLOR_TYPE_GRAY ||
1676 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1677 png_set_invert_mono(png_ptr);
1678 PNG files store 16 bit pixels in network byte order (big-endian, ie.
1680 most significant bits first). This code changes the storage to the
1681 other way (little-endian, i.e. least significant bits first, the way
1682 PCs store them):
1683 if (bit_depth == 16)
1685 png_set_swap(png_ptr);
1686 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1688 need to change the order the pixels are packed into bytes, you can use:
1689 if (bit_depth < 8)
1691 png_set_packswap(png_ptr);
1692 Finally, you can write your own transformation function if none of the
1694 existing ones meets your needs. This is done by setting a callback
1695 with
1696 png_set_read_user_transform_fn(png_ptr,
1698 read_transform_fn);
1699 You must supply the function
1701 void read_transform_fn(png_ptr ptr, row_info_ptr
1703 row_info, png_bytep data)
1704 See pngtest.c for a working example. Your function will be called
1706 after all of the other transformations have been processed.
1707 You can also set up a pointer to a user structure for use by your call‐
1709 back function, and you can inform libpng that your transform function
1710 will change the number of channels or bit depth with the function
1711 png_set_user_transform_info(png_ptr, user_ptr,
1713 user_depth, user_channels);
1714 The user's application, not libpng, is responsible for allocating and
1716 freeing any memory required for the user structure.
1717 You can retrieve the pointer via the function png_get_user_trans‐
1719 form_ptr(). For example:
1720 voidp read_user_transform_ptr =
1722 png_get_user_transform_ptr(png_ptr);
1723 The last thing to handle is interlacing; this is covered in detail
1725 below, but you must call the function here if you want libpng to handle
1726 expansion of the interlaced image.
1727 number_of_passes = png_set_interlace_handling(png_ptr);
1729 After setting the transformations, libpng can update your png_info
1731 structure to reflect any transformations you've requested with this
1732 call. This is most useful to update the info structure's rowbytes
1733 field so you can use it to allocate your image memory. This function
1734 will also update your palette with the correct screen_gamma and back‐
1735 ground if these have been given with the calls above.
1736 png_read_update_info(png_ptr, info_ptr);
1738 After you call png_read_update_info(), you can allocate any memory you
1740 need to hold the image. The row data is simply raw byte data for all
1741 forms of images. As the actual allocation varies among applications,
1742 no example will be given. If you are allocating one large chunk, you
1743 will need to build an array of pointers to each row, as it will be
1744 needed for some of the functions below.
1745 Reading image data
1748 After you've allocated memory, you can read the image data. The sim‐
1749 plest way to do this is in one function call. If you are allocating
1750 enough memory to hold the whole image, you can just call
1751 png_read_image() and libpng will read in all the image data and put it
1752 in the memory area supplied. You will need to pass in an array of
1753 pointers to each row.
1754 This function automatically handles interlacing, so you don't need to
1756 call png_set_interlace_handling() or call this function multiple times,
1757 or any of that other stuff necessary with png_read_rows().
1758 png_read_image(png_ptr, row_pointers);
1760 where row_pointers is:
1762 png_bytep row_pointers[height];
1764 You can point to void or char or whatever you use for pixels.
1766 If you don't want to read in the whole image at once, you can use
1768 png_read_rows() instead. If there is no interlacing (check inter‐
1769 lace_type == PNG_INTERLACE_NONE), this is simple:
1770 png_read_rows(png_ptr, row_pointers, NULL,
1772 number_of_rows);
1773 where row_pointers is the same as in the png_read_image() call.
1775 If you are doing this just one row at a time, you can do this with a
1777 single row_pointer instead of an array of row_pointers:
1778 png_bytep row_pointer = row;
1780 png_read_row(png_ptr, row_pointer, NULL);
1781 If the file is interlaced (interlace_type != 0 in the IHDR chunk),
1783 things get somewhat harder. The only current (PNG Specification ver‐
1784 sion 1.2) interlacing type for PNG is (interlace_type == PNG_INTER‐
1785 LACE_ADAM7) is a somewhat complicated 2D interlace scheme, known as
1786 Adam7, that breaks down an image into seven smaller images of varying
1787 size, based on an 8x8 grid.
1788 libpng can fill out those images or it can give them to you "as is".
1790 If you want them filled out, there are two ways to do that. The one
1791 mentioned in the PNG specification is to expand each pixel to cover
1792 those pixels that have not been read yet (the "rectangle" method).
1793 This results in a blocky image for the first pass, which gradually
1794 smooths out as more pixels are read. The other method is the "sparkle"
1795 method, where pixels are drawn only in their final locations, with the
1796 rest of the image remaining whatever colors they were initialized to
1797 before the start of the read. The first method usually looks better,
1798 but tends to be slower, as there are more pixels to put in the rows.
1799 If you don't want libpng to handle the interlacing details, just call
1801 png_read_rows() seven times to read in all seven images. Each of the
1802 images is a valid image by itself, or they can all be combined on an
1803 8x8 grid to form a single image (although if you intend to combine them
1804 you would be far better off using the libpng interlace handling).
1805 The first pass will return an image 1/8 as wide as the entire image
1807 (every 8th column starting in column 0) and 1/8 as high as the original
1808 (every 8th row starting in row 0), the second will be 1/8 as wide
1809 (starting in column 4) and 1/8 as high (also starting in row 0). The
1810 third pass will be 1/4 as wide (every 4th pixel starting in column 0)
1811 and 1/8 as high (every 8th row starting in row 4), and the fourth pass
1812 will be 1/4 as wide and 1/4 as high (every 4th column starting in col‐
1813 umn 2, and every 4th row starting in row 0). The fifth pass will
1814 return an image 1/2 as wide, and 1/4 as high (starting at column 0 and
1815 row 2), while the sixth pass will be 1/2 as wide and 1/2 as high as the
1816 original (starting in column 1 and row 0). The seventh and final pass
1817 will be as wide as the original, and 1/2 as high, containing all of the
1818 odd numbered scanlines. Phew!
1819 If you want libpng to expand the images, call this before calling
1821 png_start_read_image() or png_read_update_info():
1822 if (interlace_type == PNG_INTERLACE_ADAM7)
1824 number_of_passes
1825 = png_set_interlace_handling(png_ptr);
1826 This will return the number of passes needed. Currently, this is
1828 seven, but may change if another interlace type is added. This func‐
1829 tion can be called even if the file is not interlaced, where it will
1830 return one pass.
1831 If you are not going to display the image after each pass, but are
1833 going to wait until the entire image is read in, use the sparkle
1834 effect. This effect is faster and the end result of either method is
1835 exactly the same. If you are planning on displaying the image after
1836 each pass, the "rectangle" effect is generally considered the better
1837 looking one.
1838 If you only want the "sparkle" effect, just call png_read_rows() as
1840 normal, with the third parameter NULL. Make sure you make pass over
1841 the image number_of_passes times, and you don't change the data in the
1842 rows between calls. You can change the locations of the data, just not
1843 the data. Each pass only writes the pixels appropriate for that pass,
1844 and assumes the data from previous passes is still valid.
1845 png_read_rows(png_ptr, row_pointers, NULL,
1847 number_of_rows);
1848 If you only want the first effect (the rectangles), do the same as
1850 before except pass the row buffer in the third parameter, and leave the
1851 second parameter NULL.
1852 png_read_rows(png_ptr, NULL, row_pointers,
1854 number_of_rows);
1855 Finishing a sequential read
1858 After you are finished reading the image through the low-level inter‐
1859 face, you can finish reading the file. If you are interested in com‐
1860 ments or time, which may be stored either before or after the image
1861 data, you should pass the separate png_info struct if you want to keep
1862 the comments from before and after the image separate. If you are not
1863 interested, you can pass NULL.
1864 png_read_end(png_ptr, end_info);
1866 When you are done, you can free all memory allocated by libpng like
1868 this:
1869 png_destroy_read_struct(&png_ptr, &info_ptr,
1871 &end_info);
1872 It is also possible to individually free the info_ptr members that
1874 point to libpng-allocated storage with the following function:
1875 png_free_data(png_ptr, info_ptr, mask, seq)
1877 mask - identifies data to be freed, a mask
1878 containing the bitwise OR of one or
1879 more of
1880 PNG_FREE_PLTE, PNG_FREE_TRNS,
1881 PNG_FREE_HIST, PNG_FREE_ICCP,
1882 PNG_FREE_PCAL, PNG_FREE_ROWS,
1883 PNG_FREE_SCAL, PNG_FREE_SPLT,
1884 PNG_FREE_TEXT, PNG_FREE_UNKN,
1885 or simply PNG_FREE_ALL
1886 seq - sequence number of item to be freed
1887 (-1 for all items)
1888 This function may be safely called when the relevant storage has
1890 already been freed, or has not yet been allocated, or was allocated by
1891 the user and not by libpng, and will in those cases do nothing. The
1892 "seq" parameter is ignored if only one item of the selected data type,
1893 such as PLTE, is allowed. If "seq" is not -1, and multiple items are
1894 allowed for the data type identified in the mask, such as text or sPLT,
1895 only the n'th item in the structure is freed, where n is "seq".
1896 The default behavior is only to free data that was allocated internally
1898 by libpng. This can be changed, so that libpng will not free the data,
1899 or so that it will free data that was allocated by the user with
1900 png_malloc() or png_zalloc() and passed in via a png_set_*() function,
1901 with
1902 png_data_freer(png_ptr, info_ptr, freer, mask)
1904 mask - which data elements are affected
1905 same choices as in png_free_data()
1906 freer - one of
1907 PNG_DESTROY_WILL_FREE_DATA
1908 PNG_SET_WILL_FREE_DATA
1909 PNG_USER_WILL_FREE_DATA
1910 This function only affects data that has already been allocated. You
1912 can call this function after reading the PNG data but before calling
1913 any png_set_*() functions, to control whether the user or the
1914 png_set_*() function is responsible for freeing any existing data that
1915 might be present, and again after the png_set_*() functions to control
1916 whether the user or png_destroy_*() is supposed to free the data. When
1917 the user assumes responsibility for libpng-allocated data, the applica‐
1918 tion must use png_free() to free it, and when the user transfers
1919 responsibility to libpng for data that the user has allocated, the user
1920 must have used png_malloc() or png_zalloc() to allocate it.
1921 If you allocated your row_pointers in a single block, as suggested
1923 above in the description of the high level read interface, you must not
1924 transfer responsibility for freeing it to the png_set_rows or
1925 png_read_destroy function, because they would also try to free the
1926 individual row_pointers[i].
1927 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.trans‐
1929 lated_keyword separately, do not transfer responsibility for freeing
1930 text_ptr to libpng, because when libpng fills a png_text structure it
1931 combines these members with the key member, and png_free_data() will
1932 free only text_ptr.key. Similarly, if you transfer responsibility for
1933 free'ing text_ptr from libpng to your application, your application
1934 must not separately free those members.
1935 The png_free_data() function will turn off the "valid" flag for any‐
1937 thing it frees. If you need to turn the flag off for a chunk that was
1938 freed by your application instead of by libpng, you can use
1939 png_set_invalid(png_ptr, info_ptr, mask);
1941 mask - identifies the chunks to be made invalid,
1942 containing the bitwise OR of one or
1943 more of
1944 PNG_INFO_gAMA, PNG_INFO_sBIT,
1945 PNG_INFO_cHRM, PNG_INFO_PLTE,
1946 PNG_INFO_tRNS, PNG_INFO_bKGD,
1947 PNG_INFO_hIST, PNG_INFO_pHYs,
1948 PNG_INFO_oFFs, PNG_INFO_tIME,
1949 PNG_INFO_pCAL, PNG_INFO_sRGB,
1950 PNG_INFO_iCCP, PNG_INFO_sPLT,
1951 PNG_INFO_sCAL, PNG_INFO_IDAT
1952 For a more compact example of reading a PNG image, see the file exam‐
1954 ple.c.
1955 Reading PNG files progressively
1958 The progressive reader is slightly different then the non-progressive
1959 reader. Instead of calling png_read_info(), png_read_rows(), and
1960 png_read_end(), you make one call to png_process_data(), which calls
1961 callbacks when it has the info, a row, or the end of the image. You
1962 set up these callbacks with png_set_progressive_read_fn(). You don't
1963 have to worry about the input/output functions of libpng, as you are
1964 giving the library the data directly in png_process_data(). I will
1965 assume that you have read the section on reading PNG files above, so I
1966 will only highlight the differences (although I will show all of the
1967 code).
1968 png_structp png_ptr; png_infop info_ptr;
1970 /* An example code fragment of how you would
1972 initialize the progressive reader in your
1973 application. */
1974 int
1975 initialize_png_reader()
1976 {
1977 png_ptr = png_create_read_struct
1978 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1979 user_error_fn, user_warning_fn);
1980 if (!png_ptr)
1981 return (ERROR);
1982 info_ptr = png_create_info_struct(png_ptr);
1983 if (!info_ptr)
1984 {
1985 png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
1986 (png_infopp)NULL);
1987 return (ERROR);
1988 }
1989 if (setjmp(png_jmpbuf(png_ptr)))
1991 {
1992 png_destroy_read_struct(&png_ptr, &info_ptr,
1993 (png_infopp)NULL);
1994 return (ERROR);
1995 }
1996 /* This one's new. You can provide functions
1998 to be called when the header info is valid,
1999 when each row is completed, and when the image
2000 is finished. If you aren't using all functions,
2001 you can specify NULL parameters. Even when all
2002 three functions are NULL, you need to call
2003 png_set_progressive_read_fn(). You can use
2004 any struct as the user_ptr (cast to a void pointer
2005 for the function call), and retrieve the pointer
2006 from inside the callbacks using the function
2007 png_get_progressive_ptr(png_ptr);
2009 which will return a void pointer, which you have
2011 to cast appropriately.
2012 */
2013 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
2014 info_callback, row_callback, end_callback);
2015 return 0;
2017 }
2018 /* A code fragment that you call as you receive blocks
2020 of data */
2021 int
2022 process_data(png_bytep buffer, png_uint_32 length)
2023 {
2024 if (setjmp(png_jmpbuf(png_ptr)))
2025 {
2026 png_destroy_read_struct(&png_ptr, &info_ptr,
2027 (png_infopp)NULL);
2028 return (ERROR);
2029 }
2030 /* This one's new also. Simply give it a chunk
2032 of data from the file stream (in order, of
2033 course). On machines with segmented memory
2034 models machines, don't give it any more than
2035 64K. The library seems to run fine with sizes
2036 of 4K. Although you can give it much less if
2037 necessary (I assume you can give it chunks of
2038 1 byte, I haven't tried less then 256 bytes
2039 yet). When this function returns, you may
2040 want to display any rows that were generated
2041 in the row callback if you don't already do
2042 so there.
2043 */
2044 png_process_data(png_ptr, info_ptr, buffer, length);
2045 return 0;
2046 }
2047 /* This function is called (as set by
2049 png_set_progressive_read_fn() above) when enough data
2050 has been supplied so all of the header has been
2051 read.
2052 */
2053 void
2054 info_callback(png_structp png_ptr, png_infop info)
2055 {
2056 /* Do any setup here, including setting any of
2057 the transformations mentioned in the Reading
2058 PNG files section. For now, you _must_ call
2059 either png_start_read_image() or
2060 png_read_update_info() after all the
2061 transformations are set (even if you don't set
2062 any). You may start getting rows before
2063 png_process_data() returns, so this is your
2064 last chance to prepare for that.
2065 */
2066 }
2067 /* This function is called when each row of image
2069 data is complete */
2070 void
2071 row_callback(png_structp png_ptr, png_bytep new_row,
2072 png_uint_32 row_num, int pass)
2073 {
2074 /* If the image is interlaced, and you turned
2075 on the interlace handler, this function will
2076 be called for every row in every pass. Some
2077 of these rows will not be changed from the
2078 previous pass. When the row is not changed,
2079 the new_row variable will be NULL. The rows
2080 and passes are called in order, so you don't
2081 really need the row_num and pass, but I'm
2082 supplying them because it may make your life
2083 easier.
2084 For the non-NULL rows of interlaced images,
2086 you must call png_progressive_combine_row()
2087 passing in the row and the old row. You can
2088 call this function for NULL rows (it will just
2089 return) and for non-interlaced images (it just
2090 does the memcpy for you) if it will make the
2091 code easier. Thus, you can just do this for
2092 all cases:
2093 */
2094 png_progressive_combine_row(png_ptr, old_row,
2096 new_row);
2097 /* where old_row is what was displayed for
2099 previously for the row. Note that the first
2100 pass (pass == 0, really) will completely cover
2101 the old row, so the rows do not have to be
2102 initialized. After the first pass (and only
2103 for interlaced images), you will have to pass
2104 the current row, and the function will combine
2105 the old row and the new row.
2106 */
2107 }
2108 void
2110 end_callback(png_structp png_ptr, png_infop info)
2111 {
2112 /* This function is called after the whole image
2113 has been read, including any chunks after the
2114 image (up to and including the IEND). You
2115 will usually have the same info chunk as you
2116 had in the header, although some data may have
2117 been added to the comments and time fields.
2118 Most people won't do much here, perhaps setting
2120 a flag that marks the image as finished.
2121 */
2122 }
2123
2128 Much of this is very similar to reading. However, everything of impor‐
2129 tance is repeated here, so you won't have to constantly look back up in
2130 the reading section to understand writing.
2131 Setup
2134 You will want to do the I/O initialization before you get into libpng,
2135 so if it doesn't work, you don't have anything to undo. If you are not
2136 using the standard I/O functions, you will need to replace them with
2137 custom writing functions. See the discussion under Customizing libpng.
2138 FILE *fp = fopen(file_name, "wb");
2140 if (!fp)
2141 {
2142 return (ERROR);
2143 }
2144 Next, png_struct and png_info need to be allocated and initialized. As
2146 these can be both relatively large, you may not want to store these on
2147 the stack, unless you have stack space to spare. Of course, you will
2148 want to check if they return NULL. If you are also reading, you won't
2149 want to name your read structure and your write structure both
2150 "png_ptr"; you can call them anything you like, such as "read_ptr" and
2151 "write_ptr". Look at pngtest.c, for example.
2152 png_structp png_ptr = png_create_write_struct
2154 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2155 user_error_fn, user_warning_fn);
2156 if (!png_ptr)
2157 return (ERROR);
2158 png_infop info_ptr = png_create_info_struct(png_ptr);
2160 if (!info_ptr)
2161 {
2162 png_destroy_write_struct(&png_ptr,
2163 (png_infopp)NULL);
2164 return (ERROR);
2165 }
2166 If you want to use your own memory allocation routines, define
2168 PNG_USER_MEM_SUPPORTED and use png_create_write_struct_2() instead of
2169 png_create_write_struct():
2170 png_structp png_ptr = png_create_write_struct_2
2172 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2173 user_error_fn, user_warning_fn, (png_voidp)
2174 user_mem_ptr, user_malloc_fn, user_free_fn);
2175 After you have these structures, you will need to set up the error han‐
2177 dling. When libpng encounters an error, it expects to longjmp() back
2178 to your routine. Therefore, you will need to call setjmp() and pass
2179 the png_jmpbuf(png_ptr). If you write the file from different rou‐
2180 tines, you will need to update the png_jmpbuf(png_ptr) every time you
2181 enter a new routine that will call a png_*() function. See your docu‐
2182 mentation of setjmp/longjmp for your compiler for more information on
2183 setjmp/longjmp. See the discussion on libpng error handling in the
2184 Customizing Libpng section below for more information on the libpng
2185 error handling.
2186 if (setjmp(png_jmpbuf(png_ptr)))
2188 {
2189 png_destroy_write_struct(&png_ptr, &info_ptr);
2190 fclose(fp);
2191 return (ERROR);
2192 }
2193 ...
2194 return;
2195 If you would rather avoid the complexity of setjmp/longjmp issues, you
2197 can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case errors
2198 will result in a call to PNG_ABORT() which defaults to abort().
2199 Now you need to set up the output code. The default for libpng is to
2201 use the C function fwrite(). If you use this, you will need to pass a
2202 valid FILE * in the function png_init_io(). Be sure that the file is
2203 opened in binary mode. Again, if you wish to handle writing data in
2204 another way, see the discussion on libpng I/O handling in the Customiz‐
2205 ing Libpng section below.
2206 png_init_io(png_ptr, fp);
2208 If you are embedding your PNG into a datastream such as MNG, and don't
2210 want libpng to write the 8-byte signature, or if you have already writ‐
2211 ten the signature in your application, use
2212 png_set_sig_bytes(png_ptr, 8);
2214 to inform libpng that it should not write a signature.
2216 Write callbacks
2219 At this point, you can set up a callback function that will be called
2220 after each row has been written, which you can use to control a
2221 progress meter or the like. It's demonstrated in pngtest.c. You must
2222 supply a function
2223 void write_row_callback(png_ptr, png_uint_32 row,
2225 int pass);
2226 {
2227 /* put your code here */
2228 }
2229 (You can give it another name that you like instead of "write_row_call‐
2231 back")
2232 To inform libpng about your function, use
2234 png_set_write_status_fn(png_ptr, write_row_callback);
2236 You now have the option of modifying how the compression library will
2238 run. The following functions are mainly for testing, but may be useful
2239 in some cases, like if you need to write PNG files extremely fast and
2240 are willing to give up some compression, or if you want to get the max‐
2241 imum possible compression at the expense of slower writing. If you
2242 have no special needs in this area, let the library do what it wants by
2243 not calling this function at all, as it has been tuned to deliver a
2244 good speed/compression ratio. The second parameter to png_set_filter()
2245 is the filter method, for which the only valid values are 0 (as of the
2246 July 1999 PNG specification, version 1.2) or 64 (if you are writing a
2247 PNG datastream that is to be embedded in a MNG datastream). The third
2248 parameter is a flag that indicates which filter type(s) are to be
2249 tested for each scanline. See the PNG specification for details on the
2250 specific filter types.
2251 /* turn on or off filtering, and/or choose
2254 specific filters. You can use either a single
2255 PNG_FILTER_VALUE_NAME or the bitwise OR of one
2256 or more PNG_FILTER_NAME masks. */
2257 png_set_filter(png_ptr, 0,
2258 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
2259 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
2260 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
2261 PNG_FILTER_AVE | PNG_FILTER_VALUE_AVE |
2262 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2263 PNG_ALL_FILTERS);
2264 If an application wants to start and stop using particular filters dur‐
2266 ing compression, it should start out with all of the filters (to ensure
2267 that the previous row of pixels will be stored in case it's needed
2268 later), and then add and remove them after the start of compression.
2269 If you are writing a PNG datastream that is to be embedded in a MNG
2271 datastream, the second parameter can be either 0 or 64.
2272 The png_set_compression_*() functions interface to the zlib compression
2274 library, and should mostly be ignored unless you really know what you
2275 are doing. The only generally useful call is png_set_compres‐
2276 sion_level() which changes how much time zlib spends on trying to com‐
2277 press the image data. See the Compression Library (zlib.h and algo‐
2278 rithm.txt, distributed with zlib) for details on the compression lev‐
2279 els.
2280 /* set the zlib compression level */
2282 png_set_compression_level(png_ptr,
2283 Z_BEST_COMPRESSION);
2284 /* set other zlib parameters */
2286 png_set_compression_mem_level(png_ptr, 8);
2287 png_set_compression_strategy(png_ptr,
2288 Z_DEFAULT_STRATEGY);
2289 png_set_compression_window_bits(png_ptr, 15);
2290 png_set_compression_method(png_ptr, 8);
2291 png_set_compression_buffer_size(png_ptr, 8192)
2292 extern PNG_EXPORT(void,png_set_zbuf_size)
2294 Setting the contents of info for output
2297 You now need to fill in the png_info structure with all the data you
2298 wish to write before the actual image. Note that the only thing you
2299 are allowed to write after the image is the text chunks and the time
2300 chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
2301 the latest PNG specification for more information on that. If you wish
2302 to write them before the image, fill them in now, and flag that data as
2303 being valid. If you want to wait until after the data, don't fill them
2304 until png_write_end(). For all the fields in png_info and their data
2305 types, see png.h. For explanations of what the fields contain, see the
2306 PNG specification.
2307 Some of the more important parts of the png_info are:
2309 png_set_IHDR(png_ptr, info_ptr, width, height,
2311 bit_depth, color_type, interlace_type,
2312 compression_type, filter_method)
2313 width - holds the width of the image
2314 in pixels (up to 2^31).
2315 height - holds the height of the image
2316 in pixels (up to 2^31).
2317 bit_depth - holds the bit depth of one of the
2318 image channels.
2319 (valid values are 1, 2, 4, 8, 16
2320 and depend also on the
2321 color_type. See also significant
2322 bits (sBIT) below).
2323 color_type - describes which color/alpha
2324 channels are present.
2325 PNG_COLOR_TYPE_GRAY
2326 (bit depths 1, 2, 4, 8, 16)
2327 PNG_COLOR_TYPE_GRAY_ALPHA
2328 (bit depths 8, 16)
2329 PNG_COLOR_TYPE_PALETTE
2330 (bit depths 1, 2, 4, 8)
2331 PNG_COLOR_TYPE_RGB
2332 (bit_depths 8, 16)
2333 PNG_COLOR_TYPE_RGB_ALPHA
2334 (bit_depths 8, 16)
2335 PNG_COLOR_MASK_PALETTE
2337 PNG_COLOR_MASK_COLOR
2338 PNG_COLOR_MASK_ALPHA
2339 interlace_type - PNG_INTERLACE_NONE or
2341 PNG_INTERLACE_ADAM7
2342 compression_type - (must be
2343 PNG_COMPRESSION_TYPE_DEFAULT)
2344 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
2345 or, if you are writing a PNG to
2346 be embedded in a MNG datastream,
2347 can also be
2348 PNG_INTRAPIXEL_DIFFERENCING)
2349 If you call png_set_IHDR(), the call must appear before any of the
2351 other png_set_*() functions, which might require access to some of the
2352 IHDR settings. The remaining png_set_*() functions can be called in
2353 any order.
2354 png_set_PLTE(png_ptr, info_ptr, palette,
2356 num_palette);
2357 palette - the palette for the file
2358 (array of png_color)
2359 num_palette - number of entries in the palette
2360 png_set_gAMA(png_ptr, info_ptr, gamma);
2362 gamma - the gamma the image was created
2363 at (PNG_INFO_gAMA)
2364 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
2366 srgb_intent - the rendering intent
2367 (PNG_INFO_sRGB) The presence of
2368 the sRGB chunk means that the pixel
2369 data is in the sRGB color space.
2370 This chunk also implies specific
2371 values of gAMA and cHRM. Rendering
2372 intent is the CSS-1 property that
2373 has been defined by the International
2374 Color Consortium
2375 (http://www.color.org).
2376 It can be one of
2377 PNG_sRGB_INTENT_SATURATION,
2378 PNG_sRGB_INTENT_PERCEPTUAL,
2379 PNG_sRGB_INTENT_ABSOLUTE, or
2380 PNG_sRGB_INTENT_RELATIVE.
2381 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
2384 srgb_intent);
2385 srgb_intent - the rendering intent
2386 (PNG_INFO_sRGB) The presence of the
2387 sRGB chunk means that the pixel
2388 data is in the sRGB color space.
2389 This function also causes gAMA and
2390 cHRM chunks with the specific values
2391 that are consistent with sRGB to be
2392 written.
2393 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
2395 profile, proflen);
2396 name - The profile name.
2397 compression - The compression type; always
2398 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
2399 You may give NULL to this argument to
2400 ignore it.
2401 profile - International Color Consortium color
2402 profile data. May contain NULs.
2403 proflen - length of profile data in bytes.
2404 png_set_sBIT(png_ptr, info_ptr, sig_bit);
2406 sig_bit - the number of significant bits for
2407 (PNG_INFO_sBIT) each of the gray, red,
2408 green, and blue channels, whichever are
2409 appropriate for the given color type
2410 (png_color_16)
2411 png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
2413 trans_values);
2414 trans - array of transparent entries for
2415 palette (PNG_INFO_tRNS)
2416 trans_values - graylevel or color sample values of
2417 the single transparent color for
2418 non-paletted images (PNG_INFO_tRNS)
2419 num_trans - number of transparent entries
2420 (PNG_INFO_tRNS)
2421 png_set_hIST(png_ptr, info_ptr, hist);
2423 (PNG_INFO_hIST)
2424 hist - histogram of palette (array of
2425 png_uint_16)
2426 png_set_tIME(png_ptr, info_ptr, mod_time);
2428 mod_time - time image was last modified
2429 (PNG_VALID_tIME)
2430 png_set_bKGD(png_ptr, info_ptr, background);
2432 background - background color (PNG_VALID_bKGD)
2433 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
2435 text_ptr - array of png_text holding image
2436 comments
2437 text_ptr[i].compression - type of compression used
2438 on "text" PNG_TEXT_COMPRESSION_NONE
2439 PNG_TEXT_COMPRESSION_zTXt
2440 PNG_ITXT_COMPRESSION_NONE
2441 PNG_ITXT_COMPRESSION_zTXt
2442 text_ptr[i].key - keyword for comment. Must contain
2443 1-79 characters.
2444 text_ptr[i].text - text comments for current
2445 keyword. Can be NULL or empty.
2446 text_ptr[i].text_length - length of text string,
2447 after decompression, 0 for iTXt
2448 text_ptr[i].itxt_length - length of itxt string,
2449 after decompression, 0 for tEXt/zTXt
2450 text_ptr[i].lang - language of comment (NULL or
2451 empty for unknown).
2452 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
2453 or empty for unknown).
2454 num_text - number of comments
2455 png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
2457 num_spalettes);
2458 palette_ptr - array of png_sPLT_struct structures
2459 to be added to the list of palettes
2460 in the info structure.
2461 num_spalettes - number of palette structures to be
2462 added.
2463 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
2465 unit_type);
2466 offset_x - positive offset from the left
2467 edge of the screen
2468 offset_y - positive offset from the top
2469 edge of the screen
2470 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2471 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2473 unit_type);
2474 res_x - pixels/unit physical resolution
2475 in x direction
2476 res_y - pixels/unit physical resolution
2477 in y direction
2478 unit_type - PNG_RESOLUTION_UNKNOWN,
2479 PNG_RESOLUTION_METER
2480 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
2482 unit - physical scale units (an integer)
2483 width - width of a pixel in physical scale units
2484 height - height of a pixel in physical scale units
2485 (width and height are doubles)
2486 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2488 unit - physical scale units (an integer)
2489 width - width of a pixel in physical scale units
2490 height - height of a pixel in physical scale units
2491 (width and height are strings like "2.54")
2492 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
2494 num_unknowns)
2495 unknowns - array of png_unknown_chunk
2496 structures holding unknown chunks
2497 unknowns[i].name - name of unknown chunk
2498 unknowns[i].data - data of unknown chunk
2499 unknowns[i].size - size of unknown chunk's data
2500 unknowns[i].location - position to write chunk in file
2501 0: do not write chunk
2502 PNG_HAVE_IHDR: before PLTE
2503 PNG_HAVE_PLTE: before IDAT
2504 PNG_AFTER_IDAT: after IDAT
2505 The "location" member is set automatically according to what part of
2507 the output file has already been written. You can change its value
2508 after calling png_set_unknown_chunks() as demonstrated in pngtest.c.
2509 Within each of the "locations", the chunks are sequenced according to
2510 their position in the structure (that is, the value of "i", which is
2511 the order in which the chunk was either read from the input file or
2512 defined with png_set_unknown_chunks).
2513 A quick word about text and num_text. text is an array of png_text
2515 structures. num_text is the number of valid structures in the array.
2516 Each png_text structure holds a language code, a keyword, a text value,
2517 and a compression type.
2518 The compression types have the same valid numbers as the compression
2520 types of the image data. Currently, the only valid number is zero.
2521 However, you can store text either compressed or uncompressed, unlike
2522 images, which always have to be compressed. So if you don't want the
2523 text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
2524 Because tEXt and zTXt chunks don't have a language field, if you spec‐
2525 ify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt any language
2526 code or translated keyword will not be written out.
2527 Until text gets around 1000 bytes, it is not worth compressing it.
2529 After the text has been written out to the file, the compression type
2530 is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
2531 so that it isn't written out again at the end (in case you are calling
2532 png_write_end() with the same struct.
2533 The keywords that are given in the PNG Specification are:
2535 Title Short (one line) title or
2537 caption for image
2538 Author Name of image's creator
2539 Description Description of image (possibly long)
2540 Copyright Copyright notice
2541 Creation Time Time of original image creation
2542 (usually RFC 1123 format, see below)
2543 Software Software used to create the image
2544 Disclaimer Legal disclaimer
2545 Warning Warning of nature of content
2546 Source Device used to create the image
2547 Comment Miscellaneous comment; conversion
2548 from other image format
2549 The keyword-text pairs work like this. Keywords should be short simple
2551 descriptions of what the comment is about. Some typical keywords are
2552 found in the PNG specification, as is some recommendations on keywords.
2553 You can repeat keywords in a file. You can even write some text before
2554 the image and some after. For example, you may want to put a descrip‐
2555 tion of the image before the image, but leave the disclaimer until
2556 after, so viewers working over modem connections don't have to wait for
2557 the disclaimer to go over the modem before they start seeing the image.
2558 Finally, keywords should be full words, not abbreviations. Keywords
2559 and text are in the ISO 8859-1 (Latin-1) character set (a superset of
2560 regular ASCII) and can not contain NUL characters, and should not con‐
2561 tain control or other unprintable characters. To make the comments
2562 widely readable, stick with basic ASCII, and avoid machine specific
2563 character set extensions like the IBM-PC character set. The keyword
2564 must be present, but you can leave off the text string on non-com‐
2565 pressed pairs. Compressed pairs must have a text string, as only the
2566 text string is compressed anyway, so the compression would be meaning‐
2567 less.
2568 PNG supports modification time via the png_time structure. Two conver‐
2570 sion routines are provided, png_convert_from_time_t() for time_t and
2571 png_convert_from_struct_tm() for struct tm. The time_t routine uses
2572 gmtime(). You don't have to use either of these, but if you wish to
2573 fill in the png_time structure directly, you should provide the time in
2574 universal time (GMT) if possible instead of your local time. Note that
2575 the year number is the full year (e.g. 1998, rather than 98 - PNG is
2576 year 2000 compliant!), and that months start with 1.
2577 If you want to store the time of the original image creation, you
2579 should use a plain tEXt chunk with the "Creation Time" keyword. This
2580 is necessary because the "creation time" of a PNG image is somewhat
2581 vague, depending on whether you mean the PNG file, the time the image
2582 was created in a non-PNG format, a still photo from which the image was
2583 scanned, or possibly the subject matter itself. In order to facilitate
2584 machine-readable dates, it is recommended that the "Creation Time" tEXt
2585 chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
2586 although this isn't a requirement. Unlike the tIME chunk, the "Cre‐
2587 ation Time" tEXt chunk is not expected to be automatically changed by
2588 the software. To facilitate the use of RFC 1123 dates, a function
2589 png_convert_to_rfc1123(png_timep) is provided to convert from PNG time
2590 to an RFC 1123 format string.
2591 Writing unknown chunks
2594 You can use the png_set_unknown_chunks function to queue up chunks for
2595 writing. You give it a chunk name, raw data, and a size; that's all
2596 there is to it. The chunks will be written by the next following
2597 png_write_info_before_PLTE, png_write_info, or png_write_end function.
2598 Any chunks previously read into the info structure's unknown-chunk list
2599 will also be written out in a sequence that satisfies the PNG specifi‐
2600 cation's ordering rules.
2601 The high-level write interface
2604 At this point there are two ways to proceed; through the high-level
2605 write interface, or through a sequence of low-level write operations.
2606 You can use the high-level interface if your image data is present in
2607 the info structure. All defined output transformations are permitted,
2608 enabled by the following masks.
2609 PNG_TRANSFORM_IDENTITY No transformation
2611 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
2612 PNG_TRANSFORM_PACKSWAP Change order of packed
2613 pixels to LSB first
2614 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
2615 PNG_TRANSFORM_SHIFT Normalize pixels to the
2616 sBIT depth
2617 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
2618 to BGRA
2619 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
2620 to AG
2621 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
2622 to transparency
2623 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
2624 PNG_TRANSFORM_STRIP_FILLER Strip out filler bytes.
2625 If you have valid image data in the info structure (you can use
2627 png_set_rows() to put image data in the info structure), simply do
2628 this:
2629 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
2631 where png_transforms is an integer containing the bitwise OR of some
2633 set of transformation flags. This call is equivalent to
2634 png_write_info(), followed the set of transformations indicated by the
2635 transform mask, then png_write_image(), and finally png_write_end().
2636 (The final parameter of this call is not yet used. Someday it might
2638 point to transformation parameters required by some future output
2639 transform.)
2640 You must use png_transforms and not call any png_set_transform() func‐
2642 tions when you use png_write_png().
2643 The low-level write interface
2646 If you are going the low-level route instead, you are now ready to
2647 write all the file information up to the actual image data. You do
2648 this with a call to png_write_info().
2649 png_write_info(png_ptr, info_ptr);
2651 Note that there is one transformation you may need to do before
2653 png_write_info(). In PNG files, the alpha channel in an image is the
2654 level of opacity. If your data is supplied as a level of transparency,
2655 you can invert the alpha channel before you write it, so that 0 is
2656 fully transparent and 255 (in 8-bit or paletted images) or 65535 (in
2657 16-bit images) is fully opaque, with
2658 png_set_invert_alpha(png_ptr);
2660 This must appear before png_write_info() instead of later with the
2662 other transformations because in the case of paletted images the tRNS
2663 chunk data has to be inverted before the tRNS chunk is written. If
2664 your image is not a paletted image, the tRNS data (which in such cases
2665 represents a single color to be rendered as transparent) won't need to
2666 be changed, and you can safely do this transformation after your
2667 png_write_info() call.
2668 If you need to write a private chunk that you want to appear before the
2670 PLTE chunk when PLTE is present, you can write the PNG info in two
2671 steps, and insert code to write your own chunk between them:
2672 png_write_info_before_PLTE(png_ptr, info_ptr);
2674 png_set_unknown_chunks(png_ptr, info_ptr, ...);
2675 png_write_info(png_ptr, info_ptr);
2676 After you've written the file information, you can set up the library
2678 to handle any special transformations of the image data. The various
2679 ways to transform the data will be described in the order that they
2680 should occur. This is important, as some of these change the color
2681 type and/or bit depth of the data, and some others only work on certain
2682 color types and bit depths. Even though each transformation checks to
2683 see if it has data that it can do something with, you should make sure
2684 to only enable a transformation if it will be valid for the data. For
2685 example, don't swap red and blue on grayscale data.
2686 PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
2688 the library to strip input data that has 4 or 8 bytes per pixel down to
2689 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
2690 bytes per pixel).
2691 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
2693 where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
2695 PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
2696 is stored XRGB or RGBX.
2697 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
2699 they can, resulting in, for example, 8 pixels per byte for 1 bit files.
2700 If the data is supplied at 1 pixel per byte, use this code, which will
2701 correctly pack the pixels into a single byte:
2702 png_set_packing(png_ptr);
2704 PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
2706 data is of another bit depth, you can write an sBIT chunk into the file
2707 so that decoders can recover the original data if desired.
2708 /* Set the true bit depth of the image data */
2710 if (color_type & PNG_COLOR_MASK_COLOR)
2711 {
2712 sig_bit.red = true_bit_depth;
2713 sig_bit.green = true_bit_depth;
2714 sig_bit.blue = true_bit_depth;
2715 }
2716 else
2717 {
2718 sig_bit.gray = true_bit_depth;
2719 }
2720 if (color_type & PNG_COLOR_MASK_ALPHA)
2721 {
2722 sig_bit.alpha = true_bit_depth;
2723 }
2724 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
2726 If the data is stored in the row buffer in a bit depth other than one
2728 supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
2729 this will scale the values to appear to be the correct bit depth as is
2730 required by PNG.
2731 png_set_shift(png_ptr, &sig_bit);
2733 PNG files store 16 bit pixels in network byte order (big-endian, ie.
2735 most significant bits first). This code would be used if they are sup‐
2736 plied the other way (little-endian, i.e. least significant bits first,
2737 the way PCs store them):
2738 if (bit_depth > 8)
2740 png_set_swap(png_ptr);
2741 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2743 need to change the order the pixels are packed into bytes, you can use:
2744 if (bit_depth < 8)
2746 png_set_packswap(png_ptr);
2747 PNG files store 3 color pixels in red, green, blue order. This code
2749 would be used if they are supplied as blue, green, red:
2750 png_set_bgr(png_ptr);
2752 PNG files describe monochrome as black being zero and white being one.
2754 This code would be used if the pixels are supplied with this reversed
2755 (black being one and white being zero):
2756 png_set_invert_mono(png_ptr);
2758 Finally, you can write your own transformation function if none of the
2760 existing ones meets your needs. This is done by setting a callback
2761 with
2762 png_set_write_user_transform_fn(png_ptr,
2764 write_transform_fn);
2765 You must supply the function
2767 void write_transform_fn(png_ptr ptr, row_info_ptr
2769 row_info, png_bytep data)
2770 See pngtest.c for a working example. Your function will be called
2772 before any of the other transformations are processed.
2773 You can also set up a pointer to a user structure for use by your call‐
2775 back function.
2776 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
2778 The user_channels and user_depth parameters of this function are
2780 ignored when writing; you can set them to zero as shown.
2781 You can retrieve the pointer via the function png_get_user_trans‐
2783 form_ptr(). For example:
2784 voidp write_user_transform_ptr =
2786 png_get_user_transform_ptr(png_ptr);
2787 It is possible to have libpng flush any pending output, either manu‐
2789 ally, or automatically after a certain number of lines have been writ‐
2790 ten. To flush the output stream a single time call:
2791 png_write_flush(png_ptr);
2793 and to have libpng flush the output stream periodically after a certain
2795 number of scanlines have been written, call:
2796 png_set_flush(png_ptr, nrows);
2798 Note that the distance between rows is from the last time
2800 png_write_flush() was called, or the first row of the image if it has
2801 never been called. So if you write 50 lines, and then png_set_flush
2802 25, it will flush the output on the next scanline, and every 25 lines
2803 thereafter, unless png_write_flush() is called before 25 more lines
2804 have been written. If nrows is too small (less than about 10 lines for
2805 a 640 pixel wide RGB image) the image compression may decrease notice‐
2806 ably (although this may be acceptable for real-time applications).
2807 Infrequent flushing will only degrade the compression performance by a
2808 few percent over images that do not use flushing.
2809 Writing the image data
2812 That's it for the transformations. Now you can write the image data.
2813 The simplest way to do this is in one function call. If you have the
2814 whole image in memory, you can just call png_write_image() and libpng
2815 will write the image. You will need to pass in an array of pointers to
2816 each row. This function automatically handles interlacing, so you
2817 don't need to call png_set_interlace_handling() or call this function
2818 multiple times, or any of that other stuff necessary with
2819 png_write_rows().
2820 png_write_image(png_ptr, row_pointers);
2822 where row_pointers is:
2824 png_byte *row_pointers[height];
2826 You can point to void or char or whatever you use for pixels.
2828 If you don't want to write the whole image at once, you can use
2830 png_write_rows() instead. If the file is not interlaced, this is sim‐
2831 ple:
2832 png_write_rows(png_ptr, row_pointers,
2834 number_of_rows);
2835 row_pointers is the same as in the png_write_image() call.
2837 If you are just writing one row at a time, you can do this with a sin‐
2839 gle row_pointer instead of an array of row_pointers:
2840 png_bytep row_pointer = row;
2842 png_write_row(png_ptr, row_pointer);
2844 When the file is interlaced, things can get a good deal more compli‐
2846 cated. The only currently (as of the PNG Specification version 1.2,
2847 dated July 1999) defined interlacing scheme for PNG files is the
2848 "Adam7" interlace scheme, that breaks down an image into seven smaller
2849 images of varying size. libpng will build these images for you, or you
2850 can do them yourself. If you want to build them yourself, see the PNG
2851 specification for details of which pixels to write when.
2852 If you don't want libpng to handle the interlacing details, just use
2854 png_set_interlace_handling() and call png_write_rows() the correct num‐
2855 ber of times to write all seven sub-images.
2856 If you want libpng to build the sub-images, call this before you start
2858 writing any rows:
2859 number_of_passes =
2861 png_set_interlace_handling(png_ptr);
2862 This will return the number of passes needed. Currently, this is
2864 seven, but may change if another interlace type is added.
2865 Then write the complete image number_of_passes times.
2867 png_write_rows(png_ptr, row_pointers,
2869 number_of_rows);
2870 As some of these rows are not used, and thus return immediately, you
2872 may want to read about interlacing in the PNG specification, and only
2873 update the rows that are actually used.
2874 Finishing a sequential write
2877 After you are finished writing the image, you should finish writing the
2878 file. If you are interested in writing comments or time, you should
2879 pass an appropriately filled png_info pointer. If you are not inter‐
2880 ested, you can pass NULL.
2881 png_write_end(png_ptr, info_ptr);
2883 When you are done, you can free all memory used by libpng like this:
2885 png_destroy_write_struct(&png_ptr, &info_ptr);
2887 It is also possible to individually free the info_ptr members that
2889 point to libpng-allocated storage with the following function:
2890 png_free_data(png_ptr, info_ptr, mask, seq)
2892 mask - identifies data to be freed, a mask
2893 containing the bitwise OR of one or
2894 more of
2895 PNG_FREE_PLTE, PNG_FREE_TRNS,
2896 PNG_FREE_HIST, PNG_FREE_ICCP,
2897 PNG_FREE_PCAL, PNG_FREE_ROWS,
2898 PNG_FREE_SCAL, PNG_FREE_SPLT,
2899 PNG_FREE_TEXT, PNG_FREE_UNKN,
2900 or simply PNG_FREE_ALL
2901 seq - sequence number of item to be freed
2902 (-1 for all items)
2903 This function may be safely called when the relevant storage has
2905 already been freed, or has not yet been allocated, or was allocated by
2906 the user and not by libpng, and will in those cases do nothing. The
2907 "seq" parameter is ignored if only one item of the selected data type,
2908 such as PLTE, is allowed. If "seq" is not -1, and multiple items are
2909 allowed for the data type identified in the mask, such as text or sPLT,
2910 only the n'th item in the structure is freed, where n is "seq".
2911 If you allocated data such as a palette that you passed in to libpng
2913 with png_set_*, you must not free it until just before the call to
2914 png_destroy_write_struct().
2915 The default behavior is only to free data that was allocated internally
2917 by libpng. This can be changed, so that libpng will not free the data,
2918 or so that it will free data that was allocated by the user with
2919 png_malloc() or png_zalloc() and passed in via a png_set_*() function,
2920 with
2921 png_data_freer(png_ptr, info_ptr, freer, mask)
2923 mask - which data elements are affected
2924 same choices as in png_free_data()
2925 freer - one of
2926 PNG_DESTROY_WILL_FREE_DATA
2927 PNG_SET_WILL_FREE_DATA
2928 PNG_USER_WILL_FREE_DATA
2929 For example, to transfer responsibility for some data from a read
2931 structure to a write structure, you could use
2932 png_data_freer(read_ptr, read_info_ptr,
2934 PNG_USER_WILL_FREE_DATA,
2935 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2936 png_data_freer(write_ptr, write_info_ptr,
2937 PNG_DESTROY_WILL_FREE_DATA,
2938 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2939 thereby briefly reassigning responsibility for freeing to the user but
2941 immediately afterwards reassigning it once more to the write_destroy
2942 function. Having done this, it would then be safe to destroy the read
2943 structure and continue to use the PLTE, tRNS, and hIST data in the
2944 write structure.
2945 This function only affects data that has already been allocated. You
2947 can call this function before calling after the png_set_*() functions
2948 to control whether the user or png_destroy_*() is supposed to free the
2949 data. When the user assumes responsibility for libpng-allocated data,
2950 the application must use png_free() to free it, and when the user
2951 transfers responsibility to libpng for data that the user has allo‐
2952 cated, the user must have used png_malloc() or png_zalloc() to allocate
2953 it.
2954 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.trans‐
2956 lated_keyword separately, do not transfer responsibility for freeing
2957 text_ptr to libpng, because when libpng fills a png_text structure it
2958 combines these members with the key member, and png_free_data() will
2959 free only text_ptr.key. Similarly, if you transfer responsibility for
2960 free'ing text_ptr from libpng to your application, your application
2961 must not separately free those members. For a more compact example of
2962 writing a PNG image, see the file example.c.
2963
2966 There are two issues here. The first is changing how libpng does stan‐
2967 dard things like memory allocation, input/output, and error handling.
2968 The second deals with more complicated things like adding new chunks,
2969 adding new transformations, and generally changing how libpng works.
2970 Both of those are compile-time issues; that is, they are generally
2971 determined at the time the code is written, and there is rarely a need
2972 to provide the user with a means of changing them.
2973 Memory allocation, input/output, and error handling
2975 All of the memory allocation, input/output, and error handling in
2977 libpng goes through callbacks that are user-settable. The default rou‐
2978 tines are in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respec‐
2979 tively. To change these functions, call the appropriate png_set_*_fn()
2980 function.
2981 Memory allocation is done through the functions png_malloc() and
2983 png_free(). These currently just call the standard C functions. If
2984 your pointers can't access more then 64K at a time, you will want to
2985 set MAXSEG_64K in zlib.h. Since it is unlikely that the method of han‐
2986 dling memory allocation on a platform will change between applications,
2987 these functions must be modified in the library at compile time. If
2988 you prefer to use a different method of allocating and freeing data,
2989 you can use png_create_read_struct_2() or png_create_write_struct_2()
2990 to register your own functions as described above. These functions
2991 also provide a void pointer that can be retrieved via
2992 mem_ptr=png_get_mem_ptr(png_ptr);
2994 Your replacement memory functions must have prototypes as follows:
2996 png_voidp malloc_fn(png_structp png_ptr,
2998 png_size_t size);
2999 void free_fn(png_structp png_ptr, png_voidp ptr);
3000 Your malloc_fn() must return NULL in case of failure. The png_malloc()
3002 function will normally call png_error() if it receives a NULL from the
3003 system memory allocator or from your replacement malloc_fn().
3004 Your free_fn() will never be called with a NULL ptr, since libpng's
3006 png_free() checks for NULL before calling free_fn().
3007 Input/Output in libpng is done through png_read() and png_write(),
3009 which currently just call fread() and fwrite(). The FILE * is stored
3010 in png_struct and is initialized via png_init_io(). If you wish to
3011 change the method of I/O, the library supplies callbacks that you can
3012 set through the function png_set_read_fn() and png_set_write_fn() at
3013 run time, instead of calling the png_init_io() function. These func‐
3014 tions also provide a void pointer that can be retrieved via the func‐
3015 tion png_get_io_ptr(). For example:
3016 png_set_read_fn(png_structp read_ptr,
3018 voidp read_io_ptr, png_rw_ptr read_data_fn)
3019 png_set_write_fn(png_structp write_ptr,
3021 voidp write_io_ptr, png_rw_ptr write_data_fn,
3022 png_flush_ptr output_flush_fn);
3023 voidp read_io_ptr = png_get_io_ptr(read_ptr);
3025 voidp write_io_ptr = png_get_io_ptr(write_ptr);
3026 The replacement I/O functions must have prototypes as follows:
3028 void user_read_data(png_structp png_ptr,
3030 png_bytep data, png_size_t length);
3031 void user_write_data(png_structp png_ptr,
3032 png_bytep data, png_size_t length);
3033 void user_flush_data(png_structp png_ptr);
3034 Supplying NULL for the read, write, or flush functions sets them back
3036 to using the default C stream functions. It is an error to read from a
3037 write stream, and vice versa.
3038 Error handling in libpng is done through png_error() and png_warning().
3040 Errors handled through png_error() are fatal, meaning that png_error()
3041 should never return to its caller. Currently, this is handled via
3042 setjmp() and longjmp() (unless you have compiled libpng with
3043 PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
3044 but you could change this to do things like exit() if you should wish.
3045 On non-fatal errors, png_warning() is called to print a warning mes‐
3047 sage, and then control returns to the calling code. By default
3048 png_error() and png_warning() print a message on stderr via fprintf()
3049 unless the library is compiled with PNG_NO_CONSOLE_IO defined (because
3050 you don't want the messages) or PNG_NO_STDIO defined (because fprintf()
3051 isn't available). If you wish to change the behavior of the error
3052 functions, you will need to set up your own message callbacks. These
3053 functions are normally supplied at the time that the png_struct is cre‐
3054 ated. It is also possible to redirect errors and warnings to your own
3055 replacement functions after png_create_*_struct() has been called by
3056 calling:
3057 png_set_error_fn(png_structp png_ptr,
3059 png_voidp error_ptr, png_error_ptr error_fn,
3060 png_error_ptr warning_fn);
3061 png_voidp error_ptr = png_get_error_ptr(png_ptr);
3063 If NULL is supplied for either error_fn or warning_fn, then the libpng
3065 default function will be used, calling fprintf() and/or longjmp() if a
3066 problem is encountered. The replacement error functions should have
3067 parameters as follows:
3068 void user_error_fn(png_structp png_ptr,
3070 png_const_charp error_msg);
3071 void user_warning_fn(png_structp png_ptr,
3072 png_const_charp warning_msg);
3073 The motivation behind using setjmp() and longjmp() is the C++ throw and
3075 catch exception handling methods. This makes the code much easier to
3076 write, as there is no need to check every return code of every function
3077 call. However, there are some uncertainties about the status of local
3078 variables after a longjmp, so the user may want to be careful about
3079 doing anything after setjmp returns non-zero besides returning itself.
3080 Consult your compiler documentation for more details. For an alterna‐
3081 tive approach, you may wish to use the "cexcept" facility (see
3082 http://cexcept.sourceforge.net).
3083 Custom chunks
3086 If you need to read or write custom chunks, you may need to get deeper
3087 into the libpng code. The library now has mechanisms for storing and
3088 writing chunks of unknown type; you can even declare callbacks for cus‐
3089 tom chunks. However, this may not be good enough if the library code
3090 itself needs to know about interactions between your chunk and existing
3091 `intrinsic' chunks.
3092 If you need to write a new intrinsic chunk, first read the PNG specifi‐
3094 cation. Acquire a first level of understanding of how it works. Pay
3095 particular attention to the sections that describe chunk names, and
3096 look at how other chunks were designed, so you can do things similarly.
3097 Second, check out the sections of libpng that read and write chunks.
3098 Try to find a chunk that is similar to yours and use it as a template.
3099 More details can be found in the comments inside the code. It is best
3100 to handle unknown chunks in a generic method, via callback functions,
3101 instead of by modifying libpng functions.
3102 If you wish to write your own transformation for the data, look through
3104 the part of the code that does the transformations, and check out some
3105 of the simpler ones to get an idea of how they work. Try to find a
3106 similar transformation to the one you want to add and copy off of it.
3107 More details can be found in the comments inside the code itself.
3108 Configuring for 16 bit platforms
3111 You will want to look into zconf.h to tell zlib (and thus libpng) that
3112 it cannot allocate more then 64K at a time. Even if you can, the mem‐
3113 ory won't be accessible. So limit zlib and libpng to 64K by defining
3114 MAXSEG_64K.
3115 Configuring for DOS
3118 For DOS users who only have access to the lower 640K, you will have to
3119 limit zlib's memory usage via a png_set_compression_mem_level() call.
3120 See zlib.h or zconf.h in the zlib library for more information.
3121 Configuring for Medium Model
3124 Libpng's support for medium model has been tested on most of the popu‐
3125 lar compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
3126 defined, and FAR gets defined to far in pngconf.h, and you should be
3127 all set. Everything in the library (except for zlib's structure) is
3128 expecting far data. You must use the typedefs with the p or pp on the
3129 end for pointers (or at least look at them and be careful). Make note
3130 that the rows of data are defined as png_bytepp, which is an unsigned
3131 char far * far *.
3132 Configuring for gui/windowing platforms:
3135 You will need to write new error and warning functions that use the GUI
3136 interface, as described previously, and set them to be the error and
3137 warning functions at the time that png_create_*_struct() is called, in
3138 order to have them available during the structure initialization. They
3139 can be changed later via png_set_error_fn(). On some compilers, you
3140 may also have to change the memory allocators (png_malloc, etc.).
3141 Configuring for compiler xxx:
3144 All includes for libpng are in pngconf.h. If you need to
3145 add/change/delete an include, this is the place to do it. The includes
3146 that are not needed outside libpng are protected by the PNG_INTERNAL
3147 definition, which is only defined for those routines inside libpng
3148 itself. The files in libpng proper only include png.h, which includes
3149 pngconf.h.
3150 Configuring zlib:
3153 There are special functions to configure the compression. Perhaps the
3154 most useful one changes the compression level, which currently uses
3155 input compression values in the range 0 - 9. The library normally uses
3156 the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests have
3157 shown that for a large majority of images, compression values in the
3158 range 3-6 compress nearly as well as higher levels, and do so much
3159 faster. For online applications it may be desirable to have maximum
3160 speed (Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can
3161 also specify no compression (Z_NO_COMPRESSION = 0), but this would cre‐
3162 ate files larger than just storing the raw bitmap. You can specify the
3163 compression level by calling:
3164 png_set_compression_level(png_ptr, level);
3166 Another useful one is to reduce the memory level used by the library.
3168 The memory level defaults to 8, but it can be lowered if you are short
3169 on memory (running DOS, for example, where you only have 640K). Note
3170 that the memory level does have an effect on compression; among other
3171 things, lower levels will result in sections of incompressible data
3172 being emitted in smaller stored blocks, with a correspondingly larger
3173 relative overhead of up to 15% in the worst case.
3174 png_set_compression_mem_level(png_ptr, level);
3176 The other functions are for configuring zlib. They are not recommended
3178 for normal use and may result in writing an invalid PNG file. See
3179 zlib.h for more information on what these mean.
3180 png_set_compression_strategy(png_ptr,
3182 strategy);
3183 png_set_compression_window_bits(png_ptr,
3184 window_bits);
3185 png_set_compression_method(png_ptr, method);
3186 png_set_compression_buffer_size(png_ptr, size);
3187 Controlling row filtering
3190 If you want to control whether libpng uses filtering or not, which fil‐
3191 ters are used, and how it goes about picking row filters, you can call
3192 one of these functions. The selection and configuration of row filters
3193 can have a significant impact on the size and encoding speed and a
3194 somewhat lesser impact on the decoding speed of an image. Filtering is
3195 enabled by default for RGB and grayscale images (with and without
3196 alpha), but not for paletted images nor for any images with bit depths
3197 less than 8 bits/pixel.
3198 The 'method' parameter sets the main filtering method, which is cur‐
3200 rently only '0' in the PNG 1.2 specification. The 'filters' parameter
3201 sets which filter(s), if any, should be used for each scanline. Possi‐
3202 ble values are PNG_ALL_FILTERS and PNG_NO_FILTERS to turn filtering on
3203 and off, respectively.
3204 Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB, PNG_FIL‐
3206 TER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise ORed
3207 together with '|' to specify one or more filters to use. These filters
3208 are described in more detail in the PNG specification. If you intend
3209 to change the filter type during the course of writing the image, you
3210 should start with flags set for all of the filters you intend to use so
3211 that libpng can initialize its internal structures appropriately for
3212 all of the filter types. (Note that this means the first row must
3213 always be adaptively filtered, because libpng currently does not allo‐
3214 cate the filter buffers until png_write_row() is called for the first
3215 time.)
3216 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
3218 PNG_FILTER_UP | PNG_FILTER_AVE |
3219 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
3220 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
3222 filters);
3223 The second parameter can also be
3224 PNG_INTRAPIXEL_DIFFERENCING if you are
3225 writing a PNG to be embedded in a MNG
3226 datastream. This parameter must be the
3227 same as the value of filter_method used
3228 in png_set_IHDR().
3229 It is also possible to influence how libpng chooses from among the
3231 available filters. This is done in one or both of two ways - by
3232 telling it how important it is to keep the same filter for successive
3233 rows, and by telling it the relative computational costs of the fil‐
3234 ters.
3235 double weights[3] = {1.5, 1.3, 1.1},
3237 costs[PNG_FILTER_VALUE_LAST] =
3238 {1.0, 1.3, 1.3, 1.5, 1.7};
3239 png_set_filter_heuristics(png_ptr,
3241 PNG_FILTER_HEURISTIC_WEIGHTED, 3,
3242 weights, costs);
3243 The weights are multiplying factors that indicate to libpng that the
3245 row filter should be the same for successive rows unless another row
3246 filter is that many times better than the previous filter. In the
3247 above example, if the previous 3 filters were SUB, SUB, NONE, the SUB
3248 filter could have a "sum of absolute differences" 1.5 x 1.3 times
3249 higher than other filters and still be chosen, while the NONE filter
3250 could have a sum 1.1 times higher than other filters and still be cho‐
3251 sen. Unspecified weights are taken to be 1.0, and the specified
3252 weights should probably be declining like those above in order to
3253 emphasize recent filters over older filters.
3254 The filter costs specify for each filter type a relative decoding cost
3256 to be considered when selecting row filters. This means that filters
3257 with higher costs are less likely to be chosen over filters with lower
3258 costs, unless their "sum of absolute differences" is that much smaller.
3259 The costs do not necessarily reflect the exact computational speeds of
3260 the various filters, since this would unduly influence the final image
3261 size.
3262 Note that the numbers above were invented purely for this example and
3264 are given only to help explain the function usage. Little testing has
3265 been done to find optimum values for either the costs or the weights.
3266 Removing unwanted object code
3269 There are a bunch of #define's in pngconf.h that control what parts of
3270 libpng are compiled. All the defines end in _SUPPORTED. If you are
3271 never going to use a capability, you can change the #define to #undef
3272 before recompiling libpng and save yourself code and data space, or you
3273 can turn off individual capabilities with defines that begin with
3274 PNG_NO_.
3275 You can also turn all of the transforms and ancillary chunk capabili‐
3277 ties off en masse with compiler directives that define PNG_NO_READ[or
3278 WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, or all
3279 four, along with directives to turn on any of the capabilities that you
3280 do want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the
3281 extra transformations but still leave the library fully capable of
3282 reading and writing PNG files with all known public chunks Use of the
3283 PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
3284 that is incapable of reading or writing ancillary chunks. If you are
3285 not using the progressive reading capability, you can turn that off
3286 with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
3287 capability, which you'll still have).
3288 All the reading and writing specific code are in separate files, so the
3290 linker should only grab the files it needs. However, if you want to
3291 make sure, or if you are building a stand alone library, all the read‐
3292 ing files start with pngr and all the writing files start with pngw.
3293 The files that don't match either (like png.c, pngtrans.c, etc.) are
3294 used for both reading and writing, and always need to be included. The
3295 progressive reader is in pngpread.c
3296 If you are creating or distributing a dynamically linked library (a .so
3298 or DLL file), you should not remove or disable any parts of the
3299 library, as this will cause applications linked with different versions
3300 of the library to fail if they call functions not available in your
3301 library. The size of the library itself should not be an issue,
3302 because only those sections that are actually used will be loaded into
3303 memory.
3304 Requesting debug printout
3307 The macro definition PNG_DEBUG can be used to request debugging print‐
3308 out. Set it to an integer value in the range 0 to 3. Higher numbers
3309 result in increasing amounts of debugging information. The information
3310 is printed to the "stderr" file, unless another file name is specified
3311 in the PNG_DEBUG_FILE macro definition.
3312 When PNG_DEBUG > 0, the following functions (macros) become available:
3314 png_debug(level, message)
3316 png_debug1(level, message, p1)
3317 png_debug2(level, message, p1, p2)
3318 in which "level" is compared to PNG_DEBUG to decide whether to print
3320 the message, "message" is the formatted string to be printed, and p1
3321 and p2 are parameters that are to be embedded in the string according
3322 to printf-style formatting directives. For example,
3323 png_debug1(2, "foo=%d0, foo);
3325 is expanded to
3327 if(PNG_DEBUG > 2)
3329 fprintf(PNG_DEBUG_FILE, "foo=%d0, foo);
3330 When PNG_DEBUG is defined but is zero, the macros aren't defined, but
3332 you can still use PNG_DEBUG to control your own debugging:
3333 #ifdef PNG_DEBUG
3335 fprintf(stderr, ...
3336 #endif
3337 When PNG_DEBUG = 1, the macros are defined, but only png_debug state‐
3339 ments having level = 0 will be printed. There aren't any such state‐
3340 ments in this version of libpng, but if you insert some they will be
3341 printed.
3342
3345 The MNG specification (available at http://www.libpng.org/pub/mng)
3346 allows certain extensions to PNG for PNG images that are embedded in
3347 MNG datastreams. Libpng can support some of these extensions. To
3348 enable them, use the png_permit_mng_features() function:
3349 feature_set = png_permit_mng_features(png_ptr, mask)
3351 mask is a png_uint_32 containing the bitwise OR of the
3352 features you want to enable. These include
3353 PNG_FLAG_MNG_EMPTY_PLTE
3354 PNG_FLAG_MNG_FILTER_64
3355 PNG_ALL_MNG_FEATURES
3356 feature_set is a png_uint_32 that is the bitwise AND of
3357 your mask with the set of MNG features that is
3358 supported by the version of libpng that you are using.
3359 It is an error to use this function when reading or writing a stand‐
3361 alone PNG file with the PNG 8-byte signature. The PNG datastream must
3362 be wrapped in a MNG datastream. As a minimum, it must have the MNG
3363 8-byte signature and the MHDR and MEND chunks. Libpng does not provide
3364 support for these or any other MNG chunks; your application must pro‐
3365 vide its own support for them. You may wish to consider using libmng
3366 (available at http://www.libmng.com) instead.
3367
3370 It should be noted that versions of libpng later than 0.96 are not dis‐
3371 tributed by the original libpng author, Guy Schalnat, nor by Andreas
3372 Dilger, who had taken over from Guy during 1996 and 1997, and distrib‐
3373 uted versions 0.89 through 0.96, but rather by another member of the
3374 original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are still
3375 alive and well, but they have moved on to other things.
3376 The old libpng functions png_read_init(), png_write_init(),
3378 png_info_init(), png_read_destroy(), and png_write_destroy() have been
3379 moved to PNG_INTERNAL in version 0.95 to discourage their use. These
3380 functions will be removed from libpng version 2.0.0.
3381 The preferred method of creating and initializing the libpng structures
3383 is via the png_create_read_struct(), png_create_write_struct(), and
3384 png_create_info_struct() because they isolate the size of the struc‐
3385 tures from the application, allow version error checking, and also
3386 allow the use of custom error handling routines during the initializa‐
3387 tion, which the old functions do not. The functions png_read_destroy()
3388 and png_write_destroy() do not actually free the memory that libpng
3389 allocated for these structs, but just reset the data structures, so
3390 they can be used instead of png_destroy_read_struct() and
3391 png_destroy_write_struct() if you feel there is too much system over‐
3392 head allocating and freeing the png_struct for each image read.
3393 Setting the error callbacks via png_set_message_fn() before
3395 png_read_init() as was suggested in libpng-0.88 is no longer supported
3396 because this caused applications that do not use custom error functions
3397 to fail if the png_ptr was not initialized to zero. It is still possi‐
3398 ble to set the error callbacks AFTER png_read_init(), or to change them
3399 with png_set_error_fn(), which is essentially the same function, but
3400 with a new name to force compilation errors with applications that try
3401 to use the old method.
3402 Starting with version 1.0.7, you can find out which version of the
3404 library you are using at run-time:
3405 png_uint_32 libpng_vn = png_access_version_number();
3407 The number libpng_vn is constructed from the major version, minor ver‐
3409 sion with leading zero, and release number with leading zero, (e.g.,
3410 libpng_vn for version 1.0.7 is 10007).
3411 You can also check which version of png.h you used when compiling your
3413 application:
3414 png_uint_32 application_vn = PNG_LIBPNG_VER;
3416
3419 May 8, 2008
3420 Since the PNG Development group is an ad-hoc body, we can't make an
3422 official declaration.
3423 This is your unofficial assurance that libpng from version 0.71 and
3425 upward through 1.2.29 are Y2K compliant. It is my belief that earlier
3426 versions were also Y2K compliant.
3427 Libpng only has three year fields. One is a 2-byte unsigned integer
3429 that will hold years up to 65535. The other two hold the date in text
3430 format, and will hold years up to 9999.
3431 The integer is
3433 "png_uint_16 year" in png_time_struct.
3434 The strings are
3436 "png_charp time_buffer" in png_struct and
3437 "near_time_buffer", which is a local character string in png.c.
3438 There are seven time-related functions:
3440 png_convert_to_rfc_1123() in png.c
3442 (formerly png_convert_to_rfc_1152() in error)
3443 png_convert_from_struct_tm() in pngwrite.c, called
3444 in pngwrite.c
3445 png_convert_from_time_t() in pngwrite.c
3446 png_get_tIME() in pngget.c
3447 png_handle_tIME() in pngrutil.c, called in pngread.c
3448 png_set_tIME() in pngset.c
3449 png_write_tIME() in pngwutil.c, called in pngwrite.c
3450 All appear to handle dates properly in a Y2K environment. The png_con‐
3452 vert_from_time_t() function calls gmtime() to convert from system clock
3453 time, which returns (year - 1900), which we properly convert to the
3454 full 4-digit year. There is a possibility that applications using
3455 libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
3456 function, or that they are incorrectly passing only a 2-digit year
3457 instead of "year - 1900" into the png_convert_from_struct_tm() func‐
3458 tion, but this is not under our control. The libpng documentation has
3459 always stated that it works with 4-digit years, and the APIs have been
3460 documented as such.
3461 The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
3463 integer to hold the year, and can hold years as large as 65535.
3464 zlib, upon which libpng depends, is also Y2K compliant. It contains no
3466 date-related code.
3467 Glenn Randers-Pehrson
3470 libpng maintainer
3471 PNG Development Group
3472
3475 Note about libpng version numbers:
3476 Due to various miscommunications, unforeseen code incompatibilities and
3478 occasional factors outside the authors' control, version numbering on
3479 the library has not always been consistent and straightforward. The
3480 following table summarizes matters since version 0.89c, which was the
3481 first widely used release:
3482 source png.h png.h shared-lib
3484 version string int version
3485 ------- ------ ----- ----------
3486 0.89c ("beta 3") 0.89 89 1.0.89
3487 0.90 ("beta 4") 0.90 90 0.90
3488 0.95 ("beta 5") 0.95 95 0.95
3489 0.96 ("beta 6") 0.96 96 0.96
3490 0.97b ("beta 7") 1.00.97 97 1.0.1
3491 0.97c 0.97 97 2.0.97
3492 0.98 0.98 98 2.0.98
3493 0.99 0.99 98 2.0.99
3494 0.99a-m 0.99 99 2.0.99
3495 1.00 1.00 100 2.1.0
3496 1.0.0 1.0.0 100 2.1.0
3497 1.0.0 (from here on, the 100 2.1.0
3498 1.0.1 png.h string is 10001 2.1.0
3499 1.0.1a-e identical to the 10002 from here on, the
3500 1.0.2 source version) 10002 shared library is 2.V
3501 1.0.2a-b 10003 where V is the source
3502 1.0.1 10001 code version except as
3503 1.0.1a-e 10002 2.1.0.1a-e noted.
3504 1.0.2 10002 2.1.0.2
3505 1.0.2a-b 10003 2.1.0.2a-b
3506 1.0.3 10003 2.1.0.3
3507 1.0.3a-d 10004 2.1.0.3a-d
3508 1.0.4 10004 2.1.0.4
3509 1.0.4a-f 10005 2.1.0.4a-f
3510 1.0.5 (+ 2 patches) 10005 2.1.0.5
3511 1.0.5a-d 10006 2.1.0.5a-d
3512 1.0.5e-r 10100 2.1.0.5e-r
3513 1.0.5s-v 10006 2.1.0.5s-v
3514 1.0.6 (+ 3 patches) 10006 2.1.0.6
3515 1.0.6d-g 10007 2.1.0.6d-g
3516 1.0.6h 10007 10.6h
3517 1.0.6i 10007 10.6i
3518 1.0.6j 10007 2.1.0.6j
3519 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14
3520 1.0.7beta15-18 1 10007 2.1.0.7beta15-18
3521 1.0.7rc1-2 1 10007 2.1.0.7rc1-2
3522 1.0.7 1 10007 2.1.0.7
3523 1.0.8beta1-4 1 10008 2.1.0.8beta1-4
3524 1.0.8rc1 1 10008 2.1.0.8rc1
3525 1.0.8 1 10008 2.1.0.8
3526 1.0.9beta1-6 1 10009 2.1.0.9beta1-6
3527 1.0.9rc1 1 10009 2.1.0.9rc1
3528 1.0.9beta7-10 1 10009 2.1.0.9beta7-10
3529 1.0.9rc2 1 10009 2.1.0.9rc2
3530 1.0.9 1 10009 2.1.0.9
3531 1.0.10beta1 1 10010 2.1.0.10beta1
3532 1.0.10rc1 1 10010 2.1.0.10rc1
3533 1.0.10 1 10010 2.1.0.10
3534 1.0.11beta1-3 1 10011 2.1.0.11beta1-3
3535 1.0.11rc1 1 10011 2.1.0.11rc1
3536 1.0.11 1 10011 2.1.0.11
3537 1.0.12beta1-2 2 10012 2.1.0.12beta1-2
3538 1.0.12rc1 2 10012 2.1.0.12rc1
3539 1.0.12 2 10012 2.1.0.12
3540 1.1.0a-f - 10100 2.1.1.0a-f abandoned
3541 1.2.0beta1-2 2 10200 2.1.2.0beta1-2
3542 1.2.0beta3-5 3 10200 3.1.2.0beta3-5
3543 1.2.0rc1 3 10200 3.1.2.0rc1
3544 1.2.0 3 10200 3.1.2.0
3545 1.2.1beta-4 3 10201 3.1.2.1beta1-4
3546 1.2.1rc1-2 3 10201 3.1.2.1rc1-2
3547 1.2.1 3 10201 3.1.2.1
3548 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6
3549 1.0.13beta1 10 10013 10.so.0.1.0.13beta1
3550 1.0.13rc1 10 10013 10.so.0.1.0.13rc1
3551 1.2.2rc1 12 10202 12.so.0.1.2.2rc1
3552 1.0.13 10 10013 10.so.0.1.0.13
3553 1.2.2 12 10202 12.so.0.1.2.2
3554 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6
3555 1.2.3 12 10203 12.so.0.1.2.3
3556 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3
3557 1.2.4rc1 13 10204 12.so.0.1.2.4rc1
3558 1.0.14 10 10014 10.so.0.1.0.14
3559 1.2.4 13 10204 12.so.0.1.2.4
3560 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2
3561 1.0.15rc1 10 10015 10.so.0.1.0.15rc1
3562 1.0.15 10 10015 10.so.0.1.0.15
3563 1.2.5 13 10205 12.so.0.1.2.5
3564 1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4
3565 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5
3566 1.0.16 10 10016 10.so.0.1.0.16
3567 1.2.6 13 10206 12.so.0.1.2.6
3568 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2
3569 1.0.17rc1 10 10017 10.so.0.1.0.17rc1
3570 1.2.7rc1 13 10207 12.so.0.1.2.7rc1
3571 1.0.17 10 10017 10.so.0.1.0.17
3572 1.2.7 13 10207 12.so.0.1.2.7
3573 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5
3574 1.0.18rc1-5 10 10018 10.so.0.1.0.18rc1-5
3575 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5
3576 1.0.18 10 10018 10.so.0.1.0.18
3577 1.2.8 13 10208 12.so.0.1.2.8
3578 1.2.9beta1-3 13 10209 12.so.0.1.2.9beta1-3
3579 1.2.9beta4-11 13 10209 12.so.0.9[.0]
3580 1.2.9rc1 13 10209 12.so.0.9[.0]
3581 1.2.9 13 10209 12.so.0.9[.0]
3582 1.2.10beta1-8 13 10210 12.so.0.10[.0]
3583 1.2.10rc1-3 13 10210 12.so.0.10[.0]
3584 1.2.10 13 10210 12.so.0.10[.0]
3585 1.2.11beta1-4 13 10211 12.so.0.11[.0]
3586 1.0.19rc1-5 10 10019 10.so.0.19[.0]
3587 1.2.11rc1-5 13 10211 12.so.0.11[.0]
3588 1.0.19 10 10019 10.so.0.19[.0]
3589 1.2.11 13 10211 12.so.0.11[.0]
3590 1.0.20 10 10020 10.so.0.20[.0]
3591 1.2.12 13 10212 12.so.0.12[.0]
3592 1.2.13beta1 13 10213 12.so.0.13[.0]
3593 1.0.21 10 10021 10.so.0.21[.0]
3594 1.2.13 13 10213 12.so.0.13[.0]
3595 1.2.14beta1-2 13 10214 12.so.0.14[.0]
3596 1.0.22rc1 10 10022 10.so.0.22[.0]
3597 1.2.14rc1 13 10214 12.so.0.14[.0]
3598 1.2.15beta1-6 13 10215 12.so.0.15[.0]
3599 1.0.23rc1-5 10 10023 10.so.0.23[.0]
3600 1.2.15rc1-5 13 10215 12.so.0.15[.0]
3601 1.0.23 10 10023 10.so.0.23[.0]
3602 1.2.15 13 10215 12.so.0.15[.0]
3603 1.2.16beta1-2 13 10216 12.so.0.16[.0]
3604 1.2.16rc1 13 10216 12.so.0.16[.0]
3605 1.0.24 10 10024 10.so.0.24[.0]
3606 1.2.16 13 10216 12.so.0.16[.0]
3607 1.2.17beta1-2 13 10217 12.so.0.17[.0]
3608 1.0.25rc1 10 10025 10.so.0.25[.0]
3609 1.2.17rc1-3 13 10217 12.so.0.17[.0]
3610 1.0.25 10 10025 10.so.0.25[.0]
3611 1.2.17 13 10217 12.so.0.17[.0]
3612 1.0.26 10 10026 10.so.0.26[.0]
3613 1.2.18 13 10218 12.so.0.18[.0]
3614 1.2.19beta1-31 13 10219 12.so.0.19[.0]
3615 1.0.27rc1-6 10 10027 10.so.0.27[.0]
3616 1.2.19rc1-6 13 10219 12.so.0.19[.0]
3617 1.0.27 10 10027 10.so.0.27[.0]
3618 1.2.19 13 10219 12.so.0.19[.0]
3619 1.2.20beta01-04 13 10220 12.so.0.20[.0]
3620 1.0.28rc1-6 10 10028 10.so.0.28[.0]
3621 1.2.20rc1-6 13 10220 12.so.0.20[.0]
3622 1.0.28 10 10028 10.so.0.28[.0]
3623 1.2.20 13 10220 12.so.0.20[.0]
3624 1.2.21beta1-2 13 10221 12.so.0.21[.0]
3625 1.2.21rc1-3 13 10221 12.so.0.21[.0]
3626 1.0.29 10 10029 10.so.0.29[.0]
3627 1.2.21 13 10221 12.so.0.21[.0]
3628 1.2.22beta1-4 13 10222 12.so.0.22[.0]
3629 1.0.30rc1 13 10030 10.so.0.30[.0]
3630 1.2.22rc1 13 10222 12.so.0.22[.0]
3631 1.0.30 10 10030 10.so.0.30[.0]
3632 1.2.22 13 10222 12.so.0.22[.0]
3633 1.2.23beta01-05 13 10223 12.so.0.23[.0]
3634 1.2.23rc01 13 10223 12.so.0.23[.0]
3635 1.2.23 13 10223 12.so.0.23[.0]
3636 1.2.24beta01-02 13 10224 12.so.0.24[.0]
3637 1.2.24rc01 13 10224 12.so.0.24[.0]
3638 1.2.24 13 10224 12.so.0.24[.0]
3639 1.2.25beta01-06 13 10225 12.so.0.25[.0]
3640 1.2.25rc01-02 13 10225 12.so.0.25[.0]
3641 1.0.31 10 10031 10.so.0.31[.0]
3642 1.2.25 13 10225 12.so.0.25[.0]
3643 1.2.26beta01-06 13 10226 12.so.0.26[.0]
3644 1.2.26rc01 13 10226 12.so.0.26[.0]
3645 1.2.26 13 10226 12.so.0.26[.0]
3646 1.0.32 10 10032 10.so.0.32[.0]
3647 1.2.27beta01-06 13 10227 12.so.0.27[.0]
3648 1.2.27rc01 13 10227 12.so.0.27[.0]
3649 1.0.33 10 10033 10.so.0.33[.0]
3650 1.2.27 13 10227 12.so.0.27[.0]
3651 1.0.34 10 10034 10.so.0.34[.0]
3652 1.2.28 13 10228 12.so.0.28[.0]
3653 1.2.29beta01-03 13 10229 12.so.0.29[.0]
3654 1.2.29rc01 13 10229 12.so.0.29[.0]
3655 1.0.35 10 10035 10.so.0.35[.0]
3656 1.2.29 13 10229 12.so.0.29[.0]
3657 Henceforth the source version will match the shared-library minor and
3659 patch numbers; the shared-library major version number will be used for
3660 changes in backward compatibility, as it is intended. The
3661 PNG_PNGLIB_VER macro, which is not used within libpng but is available
3662 for applications, is an unsigned integer of the form xyyzz correspond‐
3663 ing to the source version x.y.z (leading zeros in y and z). Beta ver‐
3664 sions were given the previous public release number plus a letter,
3665 until version 1.0.6j; from then on they were given the upcoming public
3666 release number plus "betaNN" or "rcN".
3667
3670 libpngpf(3), png(5)
3671 libpng:
3673 http://libpng.sourceforge.net (follow the [DOWNLOAD] link)
3675 http://www.libpng.org/pub/png
3676 zlib:
3679 (generally) at the same location as libpng or at
3681 ftp://ftp.info-zip.org/pub/infozip/zlib
3682 PNGspecification:RFC2083
3685 (generally) at the same location as libpng or at
3687 ftp://ftp.rfc-editor.org:/in-notes/rfc2083.txt
3688 or (as a W3C Recommendation) at
3689 http://www.w3.org/TR/REC-png.html
3690 In the case of any inconsistency between the PNG specification and this
3693 library, the specification takes precedence.
3694
3697 This man page: Glenn Randers-Pehrson <glennrp at users.sourceforge.net>
3698 The contributing authors would like to thank all those who helped with
3700 testing, bug fixes, and patience. This wouldn't have been possible
3701 without all of you.
3702 Thanks to Frank J. T. Wojcik for helping with the documentation.
3704 Libpng version 1.2.29 - May 8, 2008: Initially created in 1995 by Guy
3706 Eric Schalnat, then of Group 42, Inc. Currently maintained by Glenn
3707 Randers-Pehrson (glennrp at users.sourceforge.net).
3708 Supported by the PNG development group
3710 png-mng-implement at lists.sf.net (subscription required; visit png-
3711 mng-implement at lists.sourceforge.net (subscription required; visit
3712 https://lists.sourceforge.net/lists/listinfo/png-mng-implement to sub‐
3713 scribe).
3714
3717 (This copy of the libpng notices is provided for your convenience. In
3718 case of any discrepancy between this copy and the notices in the file
3719 png.h that is included in the libpng distribution, the latter shall
3720 prevail.)
3721 If you modify libpng you may insert additional notices immediately fol‐
3723 lowing this sentence.
3724 libpng versions 1.2.6, August 15, 2004, through 1.2.29, May 8, 2008,
3726 are Copyright (c) 2004,2006-2008 Glenn Randers-Pehrson, and are dis‐
3727 tributed according to the same disclaimer and license as libpng-1.2.5
3728 with the following individual added to the list of Contributing Authors
3729 Cosmin Truta
3731 libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002,
3733 are Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are distributed
3734 according to the same disclaimer and license as libpng-1.0.6 with the
3735 following individuals added to the list of Contributing Authors
3736 Simon-Pierre Cadieux
3738 Eric S. Raymond
3739 Gilles Vollant
3740 and with the following additions to the disclaimer:
3742 There is no warranty against interference with your
3744 enjoyment of the library or against infringement.
3745 There is no warranty that our efforts or the library
3746 will fulfill any of your particular purposes or needs.
3747 This library is provided with all faults, and the entire
3748 risk of satisfactory quality, performance, accuracy, and
3749 effort is with the user.
3750 libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
3752 Copyright (c) 1998, 1999 Glenn Randers-Pehrson Distributed according to
3753 the same disclaimer and license as libpng-0.96, with the following
3754 individuals added to the list of Contributing Authors:
3755 Tom Lane
3757 Glenn Randers-Pehrson
3758 Willem van Schaik
3759 libpng versions 0.89, June 1996, through 0.96, May 1997, are Copyright
3761 (c) 1996, 1997 Andreas Dilger Distributed according to the same dis‐
3762 claimer and license as libpng-0.88, with the following individuals
3763 added to the list of Contributing Authors:
3764 John Bowler
3766 Kevin Bracey
3767 Sam Bushell
3768 Magnus Holmgren
3769 Greg Roelofs
3770 Tom Tanner
3771 libpng versions 0.5, May 1995, through 0.88, January 1996, are Copy‐
3773 right (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
3774 For the purposes of this copyright and license, "Contributing Authors"
3776 is defined as the following set of individuals:
3777 Andreas Dilger
3779 Dave Martindale
3780 Guy Eric Schalnat
3781 Paul Schmidt
3782 Tim Wegner
3783 The PNG Reference Library is supplied "AS IS". The Contributing
3785 Authors and Group 42, Inc. disclaim all warranties, expressed or
3786 implied, including, without limitation, the warranties of merchantabil‐
3787 ity and of fitness for any purpose. The Contributing Authors and Group
3788 42, Inc. assume no liability for direct, indirect, incidental, spe‐
3789 cial, exemplary, or consequential damages, which may result from the
3790 use of the PNG Reference Library, even if advised of the possibility of
3791 such damage.
3792 Permission is hereby granted to use, copy, modify, and distribute this
3794 source code, or portions hereof, for any purpose, without fee, subject
3795 to the following restrictions:
3796 1. The origin of this source code must not be misrepresented.
3798 2. Altered versions must be plainly marked as such and
3800 must not be misrepresented as being the original source.
3801 3. This Copyright notice may not be removed or altered from
3803 any source or altered source distribution.
3804 The Contributing Authors and Group 42, Inc. specifically permit, with‐
3806 out fee, and encourage the use of this source code as a component to
3807 supporting the PNG file format in commercial products. If you use this
3808 source code in a product, acknowledgment is not required but would be
3809 appreciated.
3810 A "png_get_copyright" function is available, for convenient use in
3813 "about" boxes and the like:
3814 printf("%s",png_get_copyright(NULL));
3816 Also, the PNG logo (in PNG format, of course) is supplied in the files
3818 "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
3819 Libpng is OSI Certified Open Source Software. OSI Certified Open
3821 Source is a certification mark of the Open Source Initiative.
3822 Glenn Randers-Pehrson glennrp at users.sourceforge.net May 8, 2008
3824 May 8, 2008 LIBPNG(3)
