1LIBPNG(3) Library Functions Manual LIBPNG(3)
2
6 libpng - Portable Network Graphics (PNG) Reference Library 1.2.46
7
9 #include <png.h>
12 png_uint_32 png_access_version_number (void);
16 int png_check_sig (png_bytep sig, int num);
20 void png_chunk_error (png_structp png_ptr, png_const_charp error);
24 void png_chunk_warning (png_structp png_ptr, png_const_charp message);
28 void png_convert_from_struct_tm (png_timep ptime, struct tm FAR *
32 ttime);
33 void png_convert_from_time_t (png_timep ptime, time_t ttime);
37 png_charp png_convert_to_rfc1123 (png_structp png_ptr, png_timep
41 ptime);
42 png_infop png_create_info_struct (png_structp png_ptr);
46 png_structp png_create_read_struct (png_const_charp user_png_ver,
50 png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn);
51 png_structp png_create_read_struct_2(png_const_charp user_png_ver,
55 png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn,
56 png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);
57 png_structp png_create_write_struct (png_const_charp user_png_ver,
61 png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn);
62 png_structp png_create_write_struct_2(png_const_charp user_png_ver,
66 png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn,
67 png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);
68 int png_debug(int level, png_const_charp message);
72 int png_debug1(int level, png_const_charp message, p1);
76 int png_debug2(int level, png_const_charp message, p1, p2);
80 void png_destroy_info_struct (png_structp png_ptr, png_infopp
84 info_ptr_ptr);
85 void png_destroy_read_struct (png_structpp png_ptr_ptr, png_infopp
89 info_ptr_ptr, png_infopp end_info_ptr_ptr);
90 void png_destroy_write_struct (png_structpp png_ptr_ptr, png_infopp
94 info_ptr_ptr);
95 void png_error (png_structp png_ptr, png_const_charp error);
99 void png_free (png_structp png_ptr, png_voidp ptr);
103 void png_free_chunk_list (png_structp png_ptr);
107 void png_free_default(png_structp png_ptr, png_voidp ptr);
111 void png_free_data (png_structp png_ptr, png_infop info_ptr, int num);
115 png_byte png_get_bit_depth (png_structp png_ptr, png_infop info_ptr);
119 png_uint_32 png_get_bKGD (png_structp png_ptr, png_infop info_ptr,
123 png_color_16p *background);
124 png_byte png_get_channels (png_structp png_ptr, png_infop info_ptr);
128 png_uint_32 png_get_cHRM (png_structp png_ptr, png_infop info_ptr, dou‐
132 ble *white_x, double *white_y, double *red_x, double *red_y, double
133 *green_x, double *green_y, double *blue_x, double *blue_y);
134 png_uint_32 png_get_cHRM_fixed (png_structp png_ptr, png_infop
138 info_ptr, png_uint_32 *white_x, png_uint_32 *white_y, png_uint_32
139 *red_x, png_uint_32 *red_y, png_uint_32 *green_x, png_uint_32 *green_y,
140 png_uint_32 *blue_x, png_uint_32 *blue_y);
141 png_byte png_get_color_type (png_structp png_ptr, png_infop info_ptr);
145 png_byte png_get_compression_type (png_structp png_ptr, png_infop
149 info_ptr);
150 png_byte png_get_copyright (png_structp png_ptr);
154 png_voidp png_get_error_ptr (png_structp png_ptr);
158 png_byte png_get_filter_type (png_structp png_ptr, png_infop info_ptr);
162 png_uint_32 png_get_gAMA (png_structp png_ptr, png_infop info_ptr, dou‐
166 ble *file_gamma);
167 png_uint_32 png_get_gAMA_fixed (png_structp png_ptr, png_infop
171 info_ptr, png_uint_32 *int_file_gamma);
172 png_byte png_get_header_ver (png_structp png_ptr);
176 png_byte png_get_header_version (png_structp png_ptr);
180 png_uint_32 png_get_hIST (png_structp png_ptr, png_infop info_ptr,
184 png_uint_16p *hist);
185 png_uint_32 png_get_iCCP (png_structp png_ptr, png_infop info_ptr,
189 png_charpp name, int *compression_type, png_charpp profile, png_uint_32
190 *proflen);
191 png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop info_ptr,
195 png_uint_32 *width, png_uint_32 *height, int *bit_depth, int
196 *color_type, int *interlace_type, int *compression_type, int *fil‐
197 ter_type);
198 png_uint_32 png_get_image_height (png_structp png_ptr, png_infop
202 info_ptr);
203 png_uint_32 png_get_image_width (png_structp png_ptr, png_infop
207 info_ptr);
208 #if !defined(PNG_1_0_X)
212 png_int_32 png_get_int_32 (png_bytep buf);
214 #endif
216 png_byte png_get_interlace_type (png_structp png_ptr, png_infop
220 info_ptr);
221 png_voidp png_get_io_ptr (png_structp png_ptr);
225 png_byte png_get_libpng_ver (png_structp png_ptr);
229 png_voidp png_get_mem_ptr(png_structp png_ptr);
233 png_uint_32 png_get_oFFs (png_structp png_ptr, png_infop info_ptr,
237 png_uint_32 *offset_x, png_uint_32 *offset_y, int *unit_type);
238 png_uint_32 png_get_pCAL (png_structp png_ptr, png_infop info_ptr,
242 png_charp *purpose, png_int_32 *X0, png_int_32 *X1, int *type, int
243 *nparams, png_charp *units, png_charpp *params);
244 png_uint_32 png_get_pHYs (png_structp png_ptr, png_infop info_ptr,
248 png_uint_32 *res_x, png_uint_32 *res_y, int *unit_type);
249 float png_get_pixel_aspect_ratio (png_structp png_ptr, png_infop
253 info_ptr);
254 png_uint_32 png_get_pixels_per_meter (png_structp png_ptr, png_infop
258 info_ptr);
259 png_voidp png_get_progressive_ptr (png_structp png_ptr);
263 png_uint_32 png_get_PLTE (png_structp png_ptr, png_infop info_ptr,
267 png_colorp *palette, int *num_palette);
268 png_byte png_get_rgb_to_gray_status (png_structp png_ptr)
272 png_uint_32 png_get_rowbytes (png_structp png_ptr, png_infop info_ptr);
274 png_bytepp png_get_rows (png_structp png_ptr, png_infop info_ptr);
278 png_uint_32 png_get_sBIT (png_structp png_ptr, png_infop info_ptr,
282 png_color_8p *sig_bit);
283 png_bytep png_get_signature (png_structp png_ptr, png_infop info_ptr);
287 png_uint_32 png_get_sPLT (png_structp png_ptr, png_infop info_ptr,
291 png_spalette_p *splt_ptr);
292 png_uint_32 png_get_sRGB (png_structp png_ptr, png_infop info_ptr, int
296 *intent);
297 png_uint_32 png_get_text (png_structp png_ptr, png_infop info_ptr,
301 png_textp *text_ptr, int *num_text);
302 png_uint_32 png_get_tIME (png_structp png_ptr, png_infop info_ptr,
306 png_timep *mod_time);
307 png_uint_32 png_get_tRNS (png_structp png_ptr, png_infop info_ptr,
311 png_bytep *trans, int *num_trans, png_color_16p *trans_values);
312 #if !defined(PNG_1_0_X)
316 png_uint_16 png_get_uint_16 (png_bytep buf);
318 png_uint_32 png_get_uint_31 (png_bytep buf);
322 png_uint_32 png_get_uint_32 (png_bytep buf);
326 #endif
328 png_uint_32 png_get_unknown_chunks (png_structp png_ptr, png_infop
332 info_ptr, png_unknown_chunkpp unknowns);
333 png_voidp png_get_user_chunk_ptr (png_structp png_ptr);
337 png_uint_32 png_get_user_height_max( png_structp png_ptr);
341 png_voidp png_get_user_transform_ptr (png_structp png_ptr);
345 png_uint_32 png_get_user_width_max (png_structp png_ptr);
349 png_uint_32 png_get_valid (png_structp png_ptr, png_infop info_ptr,
353 png_uint_32 flag);
354 png_int_32 png_get_x_offset_microns (png_structp png_ptr, png_infop
358 info_ptr);
359 png_int_32 png_get_x_offset_pixels (png_structp png_ptr, png_infop
363 info_ptr);
364 png_uint_32 png_get_x_pixels_per_meter (png_structp png_ptr, png_infop
368 info_ptr);
369 png_int_32 png_get_y_offset_microns (png_structp png_ptr, png_infop
373 info_ptr);
374 png_int_32 png_get_y_offset_pixels (png_structp png_ptr, png_infop
378 info_ptr);
379 png_uint_32 png_get_y_pixels_per_meter (png_structp png_ptr, png_infop
383 info_ptr);
384 png_uint_32 png_get_compression_buffer_size (png_structp png_ptr);
388 int png_handle_as_unknown (png_structp png_ptr, png_bytep chunk_name);
392 void png_init_io (png_structp png_ptr, FILE *fp);
396 DEPRECATED: void png_info_init (png_infop info_ptr);
400 DEPRECATED: void png_info_init_2 (png_infopp ptr_ptr, png_size_t
404 png_info_struct_size);
405 png_voidp png_malloc (png_structp png_ptr, png_uint_32 size);
409 png_voidp png_malloc_default(png_structp png_ptr, png_uint_32 size);
413 voidp png_memcpy (png_voidp s1, png_voidp s2, png_size_t size);
417 png_voidp png_memcpy_check (png_structp png_ptr, png_voidp s1,
421 png_voidp s2, png_uint_32 size);
422 voidp png_memset (png_voidp s1, int value, png_size_t size);
426 png_voidp png_memset_check (png_structp png_ptr, png_voidp s1, int
430 value, png_uint_32 size);
431 DEPRECATED: void png_permit_empty_plte (png_structp png_ptr, int
435 empty_plte_permitted);
436 void png_process_data (png_structp png_ptr, png_infop info_ptr,
440 png_bytep buffer, png_size_t buffer_size);
441 void png_progressive_combine_row (png_structp png_ptr, png_bytep
445 old_row, png_bytep new_row);
446 void png_read_destroy (png_structp png_ptr, png_infop info_ptr,
450 png_infop end_info_ptr);
451 void png_read_end (png_structp png_ptr, png_infop info_ptr);
455 void png_read_image (png_structp png_ptr, png_bytepp image);
459 DEPRECATED: void png_read_init (png_structp png_ptr);
463 DEPRECATED: void png_read_init_2 (png_structpp ptr_ptr, png_const_charp
467 user_png_ver, png_size_t png_struct_size, png_size_t png_info_size);
468 void png_read_info (png_structp png_ptr, png_infop info_ptr);
472 void png_read_png (png_structp png_ptr, png_infop info_ptr, int trans‐
476 forms, png_voidp params);
477 void png_read_row (png_structp png_ptr, png_bytep row, png_bytep dis‐
481 play_row);
482 void png_read_rows (png_structp png_ptr, png_bytepp row, png_bytepp
486 display_row, png_uint_32 num_rows);
487 void png_read_update_info (png_structp png_ptr, png_infop info_ptr);
491 #if !defined(PNG_1_0_X)
495 png_save_int_32 (png_bytep buf, png_int_32 i);
497 void png_save_uint_16 (png_bytep buf, unsigned int i);
501 void png_save_uint_32 (png_bytep buf, png_uint_32 i);
505 void png_set_add_alpha (png_structp png_ptr, png_uint_32 filler, int
509 flags);
510 #endif
512 void png_set_background (png_structp png_ptr, png_color_16p back‐
516 ground_color, int background_gamma_code, int need_expand, double back‐
517 ground_gamma);
518 void png_set_bgr (png_structp png_ptr);
522 void png_set_bKGD (png_structp png_ptr, png_infop info_ptr,
526 png_color_16p background);
527 void png_set_cHRM (png_structp png_ptr, png_infop info_ptr, double
531 white_x, double white_y, double red_x, double red_y, double green_x,
532 double green_y, double blue_x, double blue_y);
533 void png_set_cHRM_fixed (png_structp png_ptr, png_infop info_ptr,
537 png_uint_32 white_x, png_uint_32 white_y, png_uint_32 red_x,
538 png_uint_32 red_y, png_uint_32 green_x, png_uint_32 green_y,
539 png_uint_32 blue_x, png_uint_32 blue_y);
540 void png_set_compression_level (png_structp png_ptr, int level);
544 void png_set_compression_mem_level (png_structp png_ptr, int
548 mem_level);
549 void png_set_compression_method (png_structp png_ptr, int method);
553 void png_set_compression_strategy (png_structp png_ptr, int strategy);
557 void png_set_compression_window_bits (png_structp png_ptr, int win‐
561 dow_bits);
562 void png_set_crc_action (png_structp png_ptr, int crit_action, int
566 ancil_action);
567 void png_set_dither (png_structp png_ptr, png_colorp palette, int
571 num_palette, int maximum_colors, png_uint_16p histogram, int
572 full_dither);
573 void png_set_error_fn (png_structp png_ptr, png_voidp error_ptr,
577 png_error_ptr error_fn, png_error_ptr warning_fn);
578 void png_set_expand (png_structp png_ptr);
582 void png_set_expand_gray_1_2_4_to_8(png_structp png_ptr);
586 void png_set_filler (png_structp png_ptr, png_uint_32 filler, int
590 flags);
591 void png_set_filter (png_structp png_ptr, int method, int filters);
595 void png_set_filter_heuristics (png_structp png_ptr, int heuris‐
599 tic_method, int num_weights, png_doublep filter_weights, png_doublep
600 filter_costs);
601 void png_set_flush (png_structp png_ptr, int nrows);
605 void png_set_gamma (png_structp png_ptr, double screen_gamma, double
609 default_file_gamma);
610 void png_set_gAMA (png_structp png_ptr, png_infop info_ptr, double
614 file_gamma);
615 void png_set_gAMA_fixed (png_structp png_ptr, png_infop info_ptr,
619 png_uint_32 file_gamma);
620 void png_set_gray_1_2_4_to_8(png_structp png_ptr);
624 void png_set_gray_to_rgb (png_structp png_ptr);
628 void png_set_hIST (png_structp png_ptr, png_infop info_ptr,
632 png_uint_16p hist);
633 void png_set_iCCP (png_structp png_ptr, png_infop info_ptr, png_charp
637 name, int compression_type, png_charp profile, png_uint_32 proflen);
638 int png_set_interlace_handling (png_structp png_ptr);
642 void png_set_invalid (png_structp png_ptr, png_infop info_ptr, int
646 mask);
647 void png_set_invert_alpha (png_structp png_ptr);
651 void png_set_invert_mono (png_structp png_ptr);
655 void png_set_IHDR (png_structp png_ptr, png_infop info_ptr, png_uint_32
659 width, png_uint_32 height, int bit_depth, int color_type, int inter‐
660 lace_type, int compression_type, int filter_type);
661 void png_set_keep_unknown_chunks (png_structp png_ptr, int keep,
665 png_bytep chunk_list, int num_chunks);
666 void png_set_mem_fn(png_structp png_ptr, png_voidp mem_ptr, png_mal‐
670 loc_ptr malloc_fn, png_free_ptr free_fn);
671 void png_set_oFFs (png_structp png_ptr, png_infop info_ptr, png_uint_32
675 offset_x, png_uint_32 offset_y, int unit_type);
676 void png_set_packing (png_structp png_ptr);
680 void png_set_packswap (png_structp png_ptr);
684 void png_set_palette_to_rgb(png_structp png_ptr);
688 void png_set_pCAL (png_structp png_ptr, png_infop info_ptr, png_charp
692 purpose, png_int_32 X0, png_int_32 X1, int type, int nparams, png_charp
693 units, png_charpp params);
694 void png_set_pHYs (png_structp png_ptr, png_infop info_ptr, png_uint_32
698 res_x, png_uint_32 res_y, int unit_type);
699 void png_set_progressive_read_fn (png_structp png_ptr, png_voidp pro‐
703 gressive_ptr, png_progressive_info_ptr info_fn, png_progressive_row_ptr
704 row_fn, png_progressive_end_ptr end_fn);
705 void png_set_PLTE (png_structp png_ptr, png_infop info_ptr, png_colorp
709 palette, int num_palette);
710 void png_set_read_fn (png_structp png_ptr, png_voidp io_ptr, png_rw_ptr
714 read_data_fn);
715 void png_set_read_status_fn (png_structp png_ptr, png_read_status_ptr
719 read_row_fn);
720 void png_set_read_user_transform_fn (png_structp png_ptr,
724 png_user_transform_ptr read_user_transform_fn);
725 void png_set_rgb_to_gray (png_structp png_ptr, int error_action, double
729 red, double green);
730 void png_set_rgb_to_gray_fixed (png_structp png_ptr, int error_action
734 png_fixed_point red, png_fixed_point green);
735 void png_set_rows (png_structp png_ptr, png_infop info_ptr, png_bytepp
739 row_pointers);
740 void png_set_sBIT (png_structp png_ptr, png_infop info_ptr,
744 png_color_8p sig_bit);
745 void png_set_sCAL (png_structp png_ptr, png_infop info_ptr, png_charp
749 unit, double width, double height);
750 void png_set_shift (png_structp png_ptr, png_color_8p true_bits);
754 void png_set_sig_bytes (png_structp png_ptr, int num_bytes);
758 void png_set_sPLT (png_structp png_ptr, png_infop info_ptr,
762 png_spalette_p splt_ptr, int num_spalettes);
763 void png_set_sRGB (png_structp png_ptr, png_infop info_ptr, int
767 intent);
768 void png_set_sRGB_gAMA_and_cHRM (png_structp png_ptr, png_infop
772 info_ptr, int intent);
773 void png_set_strip_16 (png_structp png_ptr);
777 void png_set_strip_alpha (png_structp png_ptr);
781 void png_set_swap (png_structp png_ptr);
785 void png_set_swap_alpha (png_structp png_ptr);
789 void png_set_text (png_structp png_ptr, png_infop info_ptr, png_textp
793 text_ptr, int num_text);
794 void png_set_tIME (png_structp png_ptr, png_infop info_ptr, png_timep
798 mod_time);
799 void png_set_tRNS (png_structp png_ptr, png_infop info_ptr, png_bytep
803 trans, int num_trans, png_color_16p trans_values);
804 void png_set_tRNS_to_alpha(png_structp png_ptr);
808 png_uint_32 png_set_unknown_chunks (png_structp png_ptr, png_infop
812 info_ptr, png_unknown_chunkp unknowns, int num, int location);
813 void png_set_unknown_chunk_location(png_structp png_ptr, png_infop
817 info_ptr, int chunk, int location);
818 void png_set_read_user_chunk_fn (png_structp png_ptr, png_voidp
822 user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn);
823 void png_set_user_limits (png_structp png_ptr, png_uint_32
827 user_width_max, png_uint_32 user_height_max);
828 void png_set_user_transform_info (png_structp png_ptr, png_voidp
832 user_transform_ptr, int user_transform_depth, int user_transform_chan‐
833 nels);
834 void png_set_write_fn (png_structp png_ptr, png_voidp io_ptr,
838 png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn);
839 void png_set_write_status_fn (png_structp png_ptr, png_write_status_ptr
843 write_row_fn);
844 void png_set_write_user_transform_fn (png_structp png_ptr,
848 png_user_transform_ptr write_user_transform_fn);
849 void png_set_compression_buffer_size(png_structp png_ptr, png_uint_32
853 size);
854 int png_sig_cmp (png_bytep sig, png_size_t start, png_size_t
858 num_to_check);
859 void png_start_read_image (png_structp png_ptr);
863 void png_warning (png_structp png_ptr, png_const_charp message);
867 void png_write_chunk (png_structp png_ptr, png_bytep chunk_name,
871 png_bytep data, png_size_t length);
872 void png_write_chunk_data (png_structp png_ptr, png_bytep data,
876 png_size_t length);
877 void png_write_chunk_end (png_structp png_ptr);
881 void png_write_chunk_start (png_structp png_ptr, png_bytep chunk_name,
885 png_uint_32 length);
886 void png_write_destroy (png_structp png_ptr);
890 void png_write_end (png_structp png_ptr, png_infop info_ptr);
894 void png_write_flush (png_structp png_ptr);
898 void png_write_image (png_structp png_ptr, png_bytepp image);
902 DEPRECATED: void png_write_init (png_structp png_ptr);
906 DEPRECATED: void png_write_init_2 (png_structpp ptr_ptr,
910 png_const_charp user_png_ver, png_size_t png_struct_size, png_size_t
911 png_info_size);
912 void png_write_info (png_structp png_ptr, png_infop info_ptr);
916 void png_write_info_before_PLTE (png_structp png_ptr, png_infop
920 info_ptr);
921 void png_write_png (png_structp png_ptr, png_infop info_ptr, int trans‐
925 forms, png_voidp params);
926 void png_write_row (png_structp png_ptr, png_bytep row);
930 void png_write_rows (png_structp png_ptr, png_bytepp row, png_uint_32
934 num_rows);
935 voidpf png_zalloc (voidpf png_ptr, uInt items, uInt size);
939 void png_zfree (voidpf png_ptr, voidpf ptr);
943
948 The libpng library supports encoding, decoding, and various manipula‐
949 tions of the Portable Network Graphics (PNG) format image files. It
950 uses the zlib(3) compression library. Following is a copy of the
951 libpng.txt file that accompanies libpng.
952
954 libpng.txt - A description on how to use and modify libpng
955 libpng version 1.2.46 - July 9, 2011
957 Updated and distributed by Glenn Randers-Pehrson
958 <glennrp at users.sourceforge.net>
959 Copyright (c) 1998-2009 Glenn Randers-Pehrson
960 This document is released under the libpng license.
962 For conditions of distribution and use, see the disclaimer
963 and license in png.h
964 Based on:
966 libpng versions 0.97, January 1998, through 1.2.46 - July 9, 2011
968 Updated and distributed by Glenn Randers-Pehrson
969 Copyright (c) 1998-2009 Glenn Randers-Pehrson
970 libpng 1.0 beta 6 version 0.96 May 28, 1997
972 Updated and distributed by Andreas Dilger
973 Copyright (c) 1996, 1997 Andreas Dilger
974 libpng 1.0 beta 2 - version 0.88 January 26, 1996
976 For conditions of distribution and use, see copyright
977 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
978 Schalnat, Group 42, Inc.
979 Updated/rewritten per request in the libpng FAQ
981 Copyright (c) 1995, 1996 Frank J. T. Wojcik
982 December 18, 1995 & January 20, 1996
983
986 This file describes how to use and modify the PNG reference library
987 (known as libpng) for your own use. There are five sections to this
988 file: introduction, structures, reading, writing, and modification and
989 configuration notes for various special platforms. In addition to this
990 file, example.c is a good starting point for using the library, as it
991 is heavily commented and should include everything most people will
992 need. We assume that libpng is already installed; see the INSTALL file
993 for instructions on how to install libpng.
994 For examples of libpng usage, see the files "example.c", "pngtest.c",
996 and the files in the "contrib" directory, all of which are included in
997 the libpng distribution.
998 Libpng was written as a companion to the PNG specification, as a way of
1000 reducing the amount of time and effort it takes to support the PNG file
1001 format in application programs.
1002 The PNG specification (second edition), November 2003, is available as
1004 a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
1005 <http://www.w3.org/TR/2003/REC-PNG-20031110/ The W3C and ISO documents
1006 have identical technical content.
1007 The PNG-1.2 specification is available at
1009 <http://www.libpng.org/pub/png/documents/>. It is technically equiva‐
1010 lent to the PNG specification (second edition) but has some additional
1011 material.
1012 The PNG-1.0 specification is available as RFC 2083
1014 <http://www.libpng.org/pub/png/documents/> and as a W3C Recommendation
1015 <http://www.w3.org/TR/REC.png.html>.
1016 Some additional chunks are described in the special-purpose public
1018 chunks documents at <http://www.libpng.org/pub/png/documents/>.
1019 Other information about PNG, and the latest version of libpng, can be
1021 found at the PNG home page, <http://www.libpng.org/pub/png/>.
1022 Most users will not have to modify the library significantly; advanced
1024 users may want to modify it more. All attempts were made to make it as
1025 complete as possible, while keeping the code easy to understand. Cur‐
1026 rently, this library only supports C. Support for other languages is
1027 being considered.
1028 Libpng has been designed to handle multiple sessions at one time, to be
1030 easily modifiable, to be portable to the vast majority of machines
1031 (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy to use.
1032 The ultimate goal of libpng is to promote the acceptance of the PNG
1033 file format in whatever way possible. While there is still work to be
1034 done (see the TODO file), libpng should cover the majority of the needs
1035 of its users.
1036 Libpng uses zlib for its compression and decompression of PNG files.
1038 Further information about zlib, and the latest version of zlib, can be
1039 found at the zlib home page, <http://www.info-
1040 zip.org/pub/infozip/zlib/>. The zlib compression utility is a general
1041 purpose utility that is useful for more than PNG files, and can be used
1042 without libpng. See the documentation delivered with zlib for more
1043 details. You can usually find the source files for the zlib utility
1044 wherever you find the libpng source files.
1045 Libpng is thread safe, provided the threads are using different
1047 instances of the structures. Each thread should have its own
1048 png_struct and png_info instances, and thus its own image. Libpng does
1049 not protect itself against two threads using the same instance of a
1050 structure.
1051
1054 There are two main structures that are important to libpng, png_struct
1055 and png_info. The first, png_struct, is an internal structure that
1056 will not, for the most part, be used by a user except as the first
1057 variable passed to every libpng function call.
1058 The png_info structure is designed to provide information about the PNG
1060 file. At one time, the fields of png_info were intended to be directly
1061 accessible to the user. However, this tended to cause problems with
1062 applications using dynamically loaded libraries, and as a result a set
1063 of interface functions for png_info (the png_get_*() and png_set_*()
1064 functions) was developed. The fields of png_info are still available
1065 for older applications, but it is suggested that applications use the
1066 new interfaces if at all possible.
1067 Applications that do make direct access to the members of png_struct
1069 (except for png_ptr->jmpbuf) must be recompiled whenever the library is
1070 updated, and applications that make direct access to the members of
1071 png_info must be recompiled if they were compiled or loaded with libpng
1072 version 1.0.6, in which the members were in a different order. In ver‐
1073 sion 1.0.7, the members of the png_info structure reverted to the old
1074 order, as they were in versions 0.97c through 1.0.5. Starting with
1075 version 2.0.0, both structures are going to be hidden, and the contents
1076 of the structures will only be accessible through the png_get/png_set
1077 functions.
1078 The png.h header file is an invaluable reference for programming with
1080 libpng. And while I'm on the topic, make sure you include the libpng
1081 header file:
1082 #include <png.h>
1084
1087 We'll now walk you through the possible functions to call when reading
1088 in a PNG file sequentially, briefly explaining the syntax and purpose
1089 of each one. See example.c and png.h for more detail. While progres‐
1090 sive reading is covered in the next section, you will still need some
1091 of the functions discussed in this section to read a PNG file.
1092 Setup
1095 You will want to do the I/O initialization(*) before you get into
1096 libpng, so if it doesn't work, you don't have much to undo. Of course,
1097 you will also want to insure that you are, in fact, dealing with a PNG
1098 file. Libpng provides a simple check to see if a file is a PNG file.
1099 To use it, pass in the first 1 to 8 bytes of the file to the function
1100 png_sig_cmp(), and it will return 0 (false) if the bytes match the cor‐
1101 responding bytes of the PNG signature, or nonzero (true) otherwise. Of
1102 course, the more bytes you pass in, the greater the accuracy of the
1103 prediction.
1104 If you are intending to keep the file pointer open for use in libpng,
1106 you must ensure you don't read more than 8 bytes from the beginning of
1107 the file, and you also have to make a call to png_set_sig_bytes_read()
1108 with the number of bytes you read from the beginning. Libpng will then
1109 only check the bytes (if any) that your program didn't read.
1110 (*): If you are not using the standard I/O functions, you will need to
1112 replace them with custom functions. See the discussion under Customiz‐
1113 ing libpng.
1114 FILE *fp = fopen(file_name, "rb");
1117 if (!fp)
1118 {
1119 return (ERROR);
1120 }
1121 fread(header, 1, number, fp);
1122 is_png = !png_sig_cmp(header, 0, number);
1123 if (!is_png)
1124 {
1125 return (NOT_PNG);
1126 }
1127 Next, png_struct and png_info need to be allocated and initialized. In
1130 order to ensure that the size of these structures is correct even with
1131 a dynamically linked libpng, there are functions to initialize and
1132 allocate the structures. We also pass the library version, optional
1133 pointers to error handling functions, and a pointer to a data struct
1134 for use by the error functions, if necessary (the pointer and functions
1135 can be NULL if the default error handlers are to be used). See the
1136 section on Changes to Libpng below regarding the old initialization
1137 functions. The structure allocation functions quietly return NULL if
1138 they fail to create the structure, so your application should check for
1139 that.
1140 png_structp png_ptr = png_create_read_struct
1142 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1143 user_error_fn, user_warning_fn);
1144 if (!png_ptr)
1145 return (ERROR);
1146 png_infop info_ptr = png_create_info_struct(png_ptr);
1148 if (!info_ptr)
1149 {
1150 png_destroy_read_struct(&png_ptr,
1151 (png_infopp)NULL, (png_infopp)NULL);
1152 return (ERROR);
1153 }
1154 png_infop end_info = png_create_info_struct(png_ptr);
1156 if (!end_info)
1157 {
1158 png_destroy_read_struct(&png_ptr, &info_ptr,
1159 (png_infopp)NULL);
1160 return (ERROR);
1161 }
1162 If you want to use your own memory allocation routines, define
1164 PNG_USER_MEM_SUPPORTED and use png_create_read_struct_2() instead of
1165 png_create_read_struct():
1166 png_structp png_ptr = png_create_read_struct_2
1168 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1169 user_error_fn, user_warning_fn, (png_voidp)
1170 user_mem_ptr, user_malloc_fn, user_free_fn);
1171 The error handling routines passed to png_create_read_struct() and the
1173 memory alloc/free routines passed to png_create_struct_2() are only
1174 necessary if you are not using the libpng supplied error handling and
1175 memory alloc/free functions.
1176 When libpng encounters an error, it expects to longjmp back to your
1178 routine. Therefore, you will need to call setjmp and pass your
1179 png_jmpbuf(png_ptr). If you read the file from different routines, you
1180 will need to update the jmpbuf field every time you enter a new routine
1181 that will call a png_*() function.
1182 See your documentation of setjmp/longjmp for your compiler for more
1184 information on setjmp/longjmp. See the discussion on libpng error han‐
1185 dling in the Customizing Libpng section below for more information on
1186 the libpng error handling. If an error occurs, and libpng longjmp's
1187 back to your setjmp, you will want to call png_destroy_read_struct() to
1188 free any memory.
1189 if (setjmp(png_jmpbuf(png_ptr)))
1191 {
1192 png_destroy_read_struct(&png_ptr, &info_ptr,
1193 &end_info);
1194 fclose(fp);
1195 return (ERROR);
1196 }
1197 If you would rather avoid the complexity of setjmp/longjmp issues, you
1199 can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case errors
1200 will result in a call to PNG_ABORT() which defaults to abort().
1201 Now you need to set up the input code. The default for libpng is to
1203 use the C function fread(). If you use this, you will need to pass a
1204 valid FILE * in the function png_init_io(). Be sure that the file is
1205 opened in binary mode. If you wish to handle reading data in another
1206 way, you need not call the png_init_io() function, but you must then
1207 implement the libpng I/O methods discussed in the Customizing Libpng
1208 section below.
1209 png_init_io(png_ptr, fp);
1211 If you had previously opened the file and read any of the signature
1213 from the beginning in order to see if this was a PNG file, you need to
1214 let libpng know that there are some bytes missing from the start of the
1215 file.
1216 png_set_sig_bytes(png_ptr, number);
1218 Setting up callback code
1221 You can set up a callback function to handle any unknown chunks in the
1222 input stream. You must supply the function
1223 read_chunk_callback(png_ptr ptr,
1225 png_unknown_chunkp chunk);
1226 {
1227 /* The unknown chunk structure contains your
1228 chunk data, along with similar data for any other
1229 unknown chunks: */
1230 png_byte name[5];
1232 png_byte *data;
1233 png_size_t size;
1234 /* Note that libpng has already taken care of
1236 the CRC handling */
1237 /* put your code here. Search for your chunk in the
1239 unknown chunk structure, process it, and return one
1240 of the following: */
1241 return (-n); /* chunk had an error */
1243 return (0); /* did not recognize */
1244 return (n); /* success */
1245 }
1246 (You can give your function another name that you like instead of
1248 "read_chunk_callback")
1249 To inform libpng about your function, use
1251 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
1253 read_chunk_callback);
1254 This names not only the callback function, but also a user pointer that
1256 you can retrieve with
1257 png_get_user_chunk_ptr(png_ptr);
1259 If you call the png_set_read_user_chunk_fn() function, then all unknown
1261 chunks will be saved when read, in case your callback function will
1262 need one or more of them. This behavior can be changed with the
1263 png_set_keep_unknown_chunks() function, described below.
1264 At this point, you can set up a callback function that will be called
1266 after each row has been read, which you can use to control a progress
1267 meter or the like. It's demonstrated in pngtest.c. You must supply a
1268 function
1269 void read_row_callback(png_ptr ptr, png_uint_32 row,
1271 int pass);
1272 {
1273 /* put your code here */
1274 }
1275 (You can give it another name that you like instead of "read_row_call‐
1277 back")
1278 To inform libpng about your function, use
1280 png_set_read_status_fn(png_ptr, read_row_callback);
1282 Unknown-chunk handling
1285 Now you get to set the way the library processes unknown chunks in the
1286 input PNG stream. Both known and unknown chunks will be read. Normal
1287 behavior is that known chunks will be parsed into information in vari‐
1288 ous info_ptr members while unknown chunks will be discarded. This
1289 behavior can be wasteful if your application will never use some known
1290 chunk types. To change this, you can call:
1291 png_set_keep_unknown_chunks(png_ptr, keep,
1293 chunk_list, num_chunks);
1294 keep - 0: default unknown chunk handling
1295 1: ignore; do not keep
1296 2: keep only if safe-to-copy
1297 3: keep even if unsafe-to-copy
1298 You can use these definitions:
1299 PNG_HANDLE_CHUNK_AS_DEFAULT 0
1300 PNG_HANDLE_CHUNK_NEVER 1
1301 PNG_HANDLE_CHUNK_IF_SAFE 2
1302 PNG_HANDLE_CHUNK_ALWAYS 3
1303 chunk_list - list of chunks affected (a byte string,
1304 five bytes per chunk, NULL or ' ' if
1305 num_chunks is 0)
1306 num_chunks - number of chunks affected; if 0, all
1307 unknown chunks are affected. If nonzero,
1308 only the chunks in the list are affected
1309 Unknown chunks declared in this way will be saved as raw data onto a
1311 list of png_unknown_chunk structures. If a chunk that is normally
1312 known to libpng is named in the list, it will be handled as unknown,
1313 according to the "keep" directive. If a chunk is named in successive
1314 instances of png_set_keep_unknown_chunks(), the final instance will
1315 take precedence. The IHDR and IEND chunks should not be named in
1316 chunk_list; if they are, libpng will process them normally anyway.
1317 Here is an example of the usage of png_set_keep_unknown_chunks(), where
1319 the private "vpAg" chunk will later be processed by a user chunk call‐
1320 back function:
1321 png_byte vpAg[5]={118, 112, 65, 103, (png_byte) ' '};
1323 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1325 png_byte unused_chunks[]=
1326 {
1327 104, 73, 83, 84, (png_byte) ' ', /* hIST */
1328 105, 84, 88, 116, (png_byte) ' ', /* iTXt */
1329 112, 67, 65, 76, (png_byte) ' ', /* pCAL */
1330 115, 67, 65, 76, (png_byte) ' ', /* sCAL */
1331 115, 80, 76, 84, (png_byte) ' ', /* sPLT */
1332 116, 73, 77, 69, (png_byte) ' ', /* tIME */
1333 };
1334 #endif
1335 ...
1337 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1339 /* ignore all unknown chunks: */
1340 png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
1341 /* except for vpAg: */
1342 png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
1343 /* also ignore unused known chunks: */
1344 png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
1345 (int)sizeof(unused_chunks)/5);
1346 #endif
1347 User limits
1350 The PNG specification allows the width and height of an image to be as
1351 large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
1352 Since very few applications really need to process such large images,
1353 we have imposed an arbitrary 1-million limit on rows and columns.
1354 Larger images will be rejected immediately with a png_error() call. If
1355 you wish to override this limit, you can use
1356 png_set_user_limits(png_ptr, width_max, height_max);
1358 to set your own limits, or use width_max = height_max = 0x7fffffffL to
1360 allow all valid dimensions (libpng may reject some very large images
1361 anyway because of potential buffer overflow conditions).
1362 You should put this statement after you create the PNG structure and
1364 before calling png_read_info(), png_read_png(), or png_process_data().
1365 If you need to retrieve the limits that are being applied, use
1366 width_max = png_get_user_width_max(png_ptr);
1368 height_max = png_get_user_height_max(png_ptr);
1369 The PNG specification sets no limit on the number of ancillary chunks
1371 allowed in a PNG datastream. You can impose a limit on the total num‐
1372 ber of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored,
1373 with
1374 png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
1376 where 0x7fffffffL means unlimited. You can retrieve this limit with
1378 chunk_cache_max = png_get_chunk_cache_max(png_ptr);
1380 This limit also applies to the number of buffers that can be allocated
1382 by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP
1383 chunks.
1384 The high-level read interface
1387 At this point there are two ways to proceed; through the high-level
1388 read interface, or through a sequence of low-level read operations.
1389 You can use the high-level interface if (a) you are willing to read the
1390 entire image into memory, and (b) the input transformations you want to
1391 do are limited to the following set:
1392 PNG_TRANSFORM_IDENTITY No transformation
1394 PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
1395 8 bits
1396 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
1397 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
1398 samples to bytes
1399 PNG_TRANSFORM_PACKSWAP Change order of packed
1400 pixels to LSB first
1401 PNG_TRANSFORM_EXPAND Perform set_expand()
1402 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
1403 PNG_TRANSFORM_SHIFT Normalize pixels to the
1404 sBIT depth
1405 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
1406 to BGRA
1407 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
1408 to AG
1409 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
1410 to transparency
1411 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
1412 PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
1413 to RGB (or GA to RGBA)
1414 (This excludes setting a background color, doing gamma transformation,
1416 dithering, and setting filler.) If this is the case, simply do this:
1417 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1419 where png_transforms is an integer containing the bitwise OR of some
1421 set of transformation flags. This call is equivalent to
1422 png_read_info(), followed the set of transformations indicated by the
1423 transform mask, then png_read_image(), and finally png_read_end().
1424 (The final parameter of this call is not yet used. Someday it might
1426 point to transformation parameters required by some future input trans‐
1427 form.)
1428 You must use png_transforms and not call any png_set_transform() func‐
1430 tions when you use png_read_png().
1431 After you have called png_read_png(), you can retrieve the image data
1433 with
1434 row_pointers = png_get_rows(png_ptr, info_ptr);
1436 where row_pointers is an array of pointers to the pixel data for each
1438 row:
1439 png_bytep row_pointers[height];
1441 If you know your image size and pixel size ahead of time, you can allo‐
1443 cate row_pointers prior to calling png_read_png() with
1444 if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
1446 png_error (png_ptr,
1447 "Image is too tall to process in memory");
1448 if (width > PNG_UINT_32_MAX/pixel_size)
1449 png_error (png_ptr,
1450 "Image is too wide to process in memory");
1451 row_pointers = png_malloc(png_ptr,
1452 height*png_sizeof(png_bytep));
1453 for (int i=0; i<height, i++)
1454 row_pointers[i]=NULL; /* security precaution */
1455 for (int i=0; i<height, i++)
1456 row_pointers[i]=png_malloc(png_ptr,
1457 width*pixel_size);
1458 png_set_rows(png_ptr, info_ptr, &row_pointers);
1459 Alternatively you could allocate your image in one big block and define
1461 row_pointers[i] to point into the proper places in your block.
1462 If you use png_set_rows(), the application is responsible for freeing
1464 row_pointers (and row_pointers[i], if they were separately allocated).
1465 If you don't allocate row_pointers ahead of time, png_read_png() will
1467 do it, and it'll be free'ed when you call png_destroy_*().
1468 The low-level read interface
1471 If you are going the low-level route, you are now ready to read all the
1472 file information up to the actual image data. You do this with a call
1473 to png_read_info().
1474 png_read_info(png_ptr, info_ptr);
1476 This will process all chunks up to but not including the image data.
1478 Querying the info structure
1481 Functions are used to get the information from the info_ptr once it has
1482 been read. Note that these fields may not be completely filled in
1483 until png_read_end() has read the chunk data following the image.
1484 png_get_IHDR(png_ptr, info_ptr, &width, &height,
1486 &bit_depth, &color_type, &interlace_type,
1487 &compression_type, &filter_method);
1488 width - holds the width of the image
1490 in pixels (up to 2^31).
1491 height - holds the height of the image
1492 in pixels (up to 2^31).
1493 bit_depth - holds the bit depth of one of the
1494 image channels. (valid values are
1495 1, 2, 4, 8, 16 and depend also on
1496 the color_type. See also
1497 significant bits (sBIT) below).
1498 color_type - describes which color/alpha channels
1499 are present.
1500 PNG_COLOR_TYPE_GRAY
1501 (bit depths 1, 2, 4, 8, 16)
1502 PNG_COLOR_TYPE_GRAY_ALPHA
1503 (bit depths 8, 16)
1504 PNG_COLOR_TYPE_PALETTE
1505 (bit depths 1, 2, 4, 8)
1506 PNG_COLOR_TYPE_RGB
1507 (bit_depths 8, 16)
1508 PNG_COLOR_TYPE_RGB_ALPHA
1509 (bit_depths 8, 16)
1510 PNG_COLOR_MASK_PALETTE
1512 PNG_COLOR_MASK_COLOR
1513 PNG_COLOR_MASK_ALPHA
1514 filter_method - (must be PNG_FILTER_TYPE_BASE
1516 for PNG 1.0, and can also be
1517 PNG_INTRAPIXEL_DIFFERENCING if
1518 the PNG datastream is embedded in
1519 a MNG-1.0 datastream)
1520 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1521 for PNG 1.0)
1522 interlace_type - (PNG_INTERLACE_NONE or
1523 PNG_INTERLACE_ADAM7)
1524 Any or all of interlace_type, compression_type, or
1526 filter_method can be NULL if you are
1527 not interested in their values.
1528 Note that png_get_IHDR() returns 32-bit data into
1530 the application's width and height variables.
1531 This is an unsafe situation if these are 16-bit
1532 variables. In such situations, the
1533 png_get_image_width() and png_get_image_height()
1534 functions described below are safer.
1535 width = png_get_image_width(png_ptr,
1537 info_ptr);
1538 height = png_get_image_height(png_ptr,
1539 info_ptr);
1540 bit_depth = png_get_bit_depth(png_ptr,
1541 info_ptr);
1542 color_type = png_get_color_type(png_ptr,
1543 info_ptr);
1544 filter_method = png_get_filter_type(png_ptr,
1545 info_ptr);
1546 compression_type = png_get_compression_type(png_ptr,
1547 info_ptr);
1548 interlace_type = png_get_interlace_type(png_ptr,
1549 info_ptr);
1550 channels = png_get_channels(png_ptr, info_ptr);
1552 channels - number of channels of info for the
1553 color type (valid values are 1 (GRAY,
1554 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1555 4 (RGB_ALPHA or RGB + filler byte))
1556 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1557 rowbytes - number of bytes needed to hold a row
1558 signature = png_get_signature(png_ptr, info_ptr);
1560 signature - holds the signature read from the
1561 file (if any). The data is kept in
1562 the same offset it would be if the
1563 whole signature were read (i.e. if an
1564 application had already read in 4
1565 bytes of signature before starting
1566 libpng, the remaining 4 bytes would
1567 be in signature[4] through signature[7]
1568 (see png_set_sig_bytes())).
1569 These are also important, but their validity depends on whether the
1571 chunk has been read. The png_get_valid(png_ptr, info_ptr,
1572 PNG_INFO_<chunk>) and png_get_<chunk>(png_ptr, info_ptr, ...) functions
1573 return non-zero if the data has been read, or zero if it is missing.
1574 The parameters to the png_get_<chunk> are set directly if they are sim‐
1575 ple data types, or a pointer into the info_ptr is returned for any com‐
1576 plex types.
1577 png_get_PLTE(png_ptr, info_ptr, &palette,
1579 &num_palette);
1580 palette - the palette for the file
1581 (array of png_color)
1582 num_palette - number of entries in the palette
1583 png_get_gAMA(png_ptr, info_ptr, &gamma);
1585 gamma - the gamma the file is written
1586 at (PNG_INFO_gAMA)
1587 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1589 srgb_intent - the rendering intent (PNG_INFO_sRGB)
1590 The presence of the sRGB chunk
1591 means that the pixel data is in the
1592 sRGB color space. This chunk also
1593 implies specific values of gAMA and
1594 cHRM.
1595 png_get_iCCP(png_ptr, info_ptr, &name,
1597 &compression_type, &profile, &proflen);
1598 name - The profile name.
1599 compression - The compression type; always
1600 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1601 You may give NULL to this argument to
1602 ignore it.
1603 profile - International Color Consortium color
1604 profile data. May contain NULs.
1605 proflen - length of profile data in bytes.
1606 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1608 sig_bit - the number of significant bits for
1609 (PNG_INFO_sBIT) each of the gray,
1610 red, green, and blue channels,
1611 whichever are appropriate for the
1612 given color type (png_color_16)
1613 png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
1615 &trans_values);
1616 trans - array of transparent
1617 entries for palette (PNG_INFO_tRNS)
1618 trans_values - graylevel or color sample values of
1619 the single transparent color for
1620 non-paletted images (PNG_INFO_tRNS)
1621 num_trans - number of transparent entries
1622 (PNG_INFO_tRNS)
1623 png_get_hIST(png_ptr, info_ptr, &hist);
1625 (PNG_INFO_hIST)
1626 hist - histogram of palette (array of
1627 png_uint_16)
1628 png_get_tIME(png_ptr, info_ptr, &mod_time);
1630 mod_time - time image was last modified
1631 (PNG_VALID_tIME)
1632 png_get_bKGD(png_ptr, info_ptr, &background);
1634 background - background color (PNG_VALID_bKGD)
1635 valid 16-bit red, green and blue
1636 values, regardless of color_type
1637 num_comments = png_get_text(png_ptr, info_ptr,
1639 &text_ptr, &num_text);
1640 num_comments - number of comments
1641 text_ptr - array of png_text holding image
1642 comments
1643 text_ptr[i].compression - type of compression used
1644 on "text" PNG_TEXT_COMPRESSION_NONE
1645 PNG_TEXT_COMPRESSION_zTXt
1646 PNG_ITXT_COMPRESSION_NONE
1647 PNG_ITXT_COMPRESSION_zTXt
1648 text_ptr[i].key - keyword for comment. Must contain
1649 1-79 characters.
1650 text_ptr[i].text - text comments for current
1651 keyword. Can be empty.
1652 text_ptr[i].text_length - length of text string,
1653 after decompression, 0 for iTXt
1654 text_ptr[i].itxt_length - length of itxt string,
1655 after decompression, 0 for tEXt/zTXt
1656 text_ptr[i].lang - language of comment (empty
1657 string for unknown).
1658 text_ptr[i].lang_key - keyword in UTF-8
1659 (empty string for unknown).
1660 Note that the itxt_length, lang, and lang_key
1661 members of the text_ptr structure only exist
1662 when the library is built with iTXt chunk support.
1663 num_text - number of comments (same as
1665 num_comments; you can put NULL here
1666 to avoid the duplication)
1667 Note while png_set_text() will accept text, language,
1668 and translated keywords that can be NULL pointers, the
1669 structure returned by png_get_text will always contain
1670 regular zero-terminated C strings. They might be
1671 empty strings but they will never be NULL pointers.
1672 num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1674 &palette_ptr);
1675 palette_ptr - array of palette structures holding
1676 contents of one or more sPLT chunks
1677 read.
1678 num_spalettes - number of sPLT chunks read.
1679 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
1681 &unit_type);
1682 offset_x - positive offset from the left edge
1683 of the screen
1684 offset_y - positive offset from the top edge
1685 of the screen
1686 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1687 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
1689 &unit_type);
1690 res_x - pixels/unit physical resolution in
1691 x direction
1692 res_y - pixels/unit physical resolution in
1693 x direction
1694 unit_type - PNG_RESOLUTION_UNKNOWN,
1695 PNG_RESOLUTION_METER
1696 png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1698 &height)
1699 unit - physical scale units (an integer)
1700 width - width of a pixel in physical scale units
1701 height - height of a pixel in physical scale units
1702 (width and height are doubles)
1703 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1705 &height)
1706 unit - physical scale units (an integer)
1707 width - width of a pixel in physical scale units
1708 height - height of a pixel in physical scale units
1709 (width and height are strings like "2.54")
1710 num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1712 info_ptr, &unknowns)
1713 unknowns - array of png_unknown_chunk
1714 structures holding unknown chunks
1715 unknowns[i].name - name of unknown chunk
1716 unknowns[i].data - data of unknown chunk
1717 unknowns[i].size - size of unknown chunk's data
1718 unknowns[i].location - position of chunk in file
1719 The value of "i" corresponds to the order in which the
1721 chunks were read from the PNG file or inserted with the
1722 png_set_unknown_chunks() function.
1723 The data from the pHYs chunk can be retrieved in several convenient
1725 forms:
1726 res_x = png_get_x_pixels_per_meter(png_ptr,
1728 info_ptr)
1729 res_y = png_get_y_pixels_per_meter(png_ptr,
1730 info_ptr)
1731 res_x_and_y = png_get_pixels_per_meter(png_ptr,
1732 info_ptr)
1733 res_x = png_get_x_pixels_per_inch(png_ptr,
1734 info_ptr)
1735 res_y = png_get_y_pixels_per_inch(png_ptr,
1736 info_ptr)
1737 res_x_and_y = png_get_pixels_per_inch(png_ptr,
1738 info_ptr)
1739 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
1740 info_ptr)
1741 (Each of these returns 0 [signifying "unknown"] if
1743 the data is not present or if res_x is 0;
1744 res_x_and_y is 0 if res_x != res_y)
1745 The data from the oFFs chunk can be retrieved in several convenient
1747 forms:
1748 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1750 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1751 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1752 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1753 (Each of these returns 0 [signifying "unknown" if both
1755 x and y are 0] if the data is not present or if the
1756 chunk is present but the unit is the pixel)
1757 For more information, see the png_info definition in png.h and the PNG
1759 specification for chunk contents. Be careful with trusting rowbytes,
1760 as some of the transformations could increase the space needed to hold
1761 a row (expand, filler, gray_to_rgb, etc.). See png_read_update_info(),
1762 below.
1763 A quick word about text_ptr and num_text. PNG stores comments in key‐
1765 word/text pairs, one pair per chunk, with no limit on the number of
1766 text chunks, and a 2^31 byte limit on their size. While there are sug‐
1767 gested keywords, there is no requirement to restrict the use to these
1768 strings. It is strongly suggested that keywords and text be sensible
1769 to humans (that's the point), so don't use abbreviations. Non-printing
1770 symbols are not allowed. See the PNG specification for more details.
1771 There is also no requirement to have text after the keyword.
1772 Keywords should be limited to 79 Latin-1 characters without leading or
1774 trailing spaces, but non-consecutive spaces are allowed within the key‐
1775 word. It is possible to have the same keyword any number of times.
1776 The text_ptr is an array of png_text structures, each holding a pointer
1777 to a language string, a pointer to a keyword and a pointer to a text
1778 string. The text string, language code, and translated keyword may be
1779 empty or NULL pointers. The keyword/text pairs are put into the array
1780 in the order that they are received. However, some or all of the text
1781 chunks may be after the image, so, to make sure you have read all the
1782 text chunks, don't mess with these until after you read the stuff after
1783 the image. This will be mentioned again below in the discussion that
1784 goes with png_read_end().
1785 Input transformations
1788 After you've read the header information, you can set up the library to
1789 handle any special transformations of the image data. The various ways
1790 to transform the data will be described in the order that they should
1791 occur. This is important, as some of these change the color type
1792 and/or bit depth of the data, and some others only work on certain
1793 color types and bit depths. Even though each transformation checks to
1794 see if it has data that it can do something with, you should make sure
1795 to only enable a transformation if it will be valid for the data. For
1796 example, don't swap red and blue on grayscale data.
1797 The colors used for the background and transparency values should be
1799 supplied in the same format/depth as the current image data. They are
1800 stored in the same format/depth as the image data in a bKGD or tRNS
1801 chunk, so this is what libpng expects for this data. The colors are
1802 transformed to keep in sync with the image data when an application
1803 calls the png_read_update_info() routine (see below).
1804 Data will be decoded into the supplied row buffers packed into bytes
1806 unless the library has been told to transform it into another format.
1807 For example, 4 bit/pixel paletted or grayscale data will be returned 2
1808 pixels/byte with the leftmost pixel in the high-order bits of the byte,
1809 unless png_set_packing() is called. 8-bit RGB data will be stored in
1810 RGB RGB RGB format unless png_set_filler() or png_set_add_alpha() is
1811 called to insert filler bytes, either before or after each RGB triplet.
1812 16-bit RGB data will be returned RRGGBB RRGGBB, with the most signifi‐
1813 cant byte of the color value first, unless png_set_strip_16() is called
1814 to transform it to regular RGB RGB triplets, or png_set_filler() or
1815 png_set_add alpha() is called to insert filler bytes, either before or
1816 after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data
1817 can be modified with png_set_filler(), png_set_add_alpha(), or
1818 png_set_strip_16().
1819 The following code transforms grayscale images of less than 8 to 8
1821 bits, changes paletted images to RGB, and adds a full alpha channel if
1822 there is transparency information in a tRNS chunk. This is most useful
1823 on grayscale images with bit depths of 2 or 4 or if there is a multi‐
1824 ple-image viewing application that wishes to treat all images in the
1825 same way.
1826 if (color_type == PNG_COLOR_TYPE_PALETTE)
1828 png_set_palette_to_rgb(png_ptr);
1829 if (color_type == PNG_COLOR_TYPE_GRAY &&
1831 bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
1832 if (png_get_valid(png_ptr, info_ptr,
1834 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1835 These three functions are actually aliases for png_set_expand(), added
1837 in libpng version 1.0.4, with the function names expanded to improve
1838 code readability. In some future version they may actually do differ‐
1839 ent things.
1840 As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was added.
1842 It expands the sample depth without changing tRNS to alpha.
1843 As of libpng version 1.2.46, not all possible expansions are supported.
1845 In the following table, the 01 means grayscale with depth<8, 31 means
1847 indexed with depth<8, other numerals represent the color type, "T"
1848 means the tRNS chunk is present, A means an alpha channel is present,
1849 and O means tRNS or alpha is present but all pixels in the image are
1850 opaque.
1851 FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
1853 TO
1854 01 -
1855 31 -
1856 0 1 -
1857 0T -
1858 0O -
1859 2 GX -
1860 2T -
1861 2O -
1862 3 1 -
1863 3T -
1864 3O -
1865 4A T -
1866 4O -
1867 6A GX TX TX -
1868 6O GX TX -
1869 Within the matrix,
1871 "-" means the transformation is not supported.
1872 "X" means the transformation is obtained by png_set_expand().
1873 "1" means the transformation is obtained by
1874 png_set_expand_gray_1_2_4_to_8
1875 "G" means the transformation is obtained by
1876 png_set_gray_to_rgb().
1877 "P" means the transformation is obtained by
1878 png_set_expand_palette_to_rgb().
1879 "T" means the transformation is obtained by
1880 png_set_tRNS_to_alpha().
1881 PNG can have files with 16 bits per channel. If you only can handle 8
1883 bits per channel, this will strip the pixels down to 8 bit.
1884 if (bit_depth == 16)
1886 png_set_strip_16(png_ptr);
1887 If, for some reason, you don't need the alpha channel on an image, and
1889 you want to remove it rather than combining it with the background (but
1890 the image author certainly had in mind that you *would* combine it with
1891 the background, so that's what you should probably do):
1892 if (color_type & PNG_COLOR_MASK_ALPHA)
1894 png_set_strip_alpha(png_ptr);
1895 In PNG files, the alpha channel in an image is the level of opacity.
1897 If you need the alpha channel in an image to be the level of trans‐
1898 parency instead of opacity, you can invert the alpha channel (or the
1899 tRNS chunk data) after it's read, so that 0 is fully opaque and 255 (in
1900 8-bit or paletted images) or 65535 (in 16-bit images) is fully trans‐
1901 parent, with
1902 png_set_invert_alpha(png_ptr);
1904 The PNG format only supports pixels with postmultiplied alpha. If you
1906 want to replace the pixels, after reading them, with pixels that have
1907 premultiplied color samples, you can do this with
1908 png_set_premultiply_alpha(png_ptr);
1910 If you do this, any input with a tRNS chunk will be expanded to have an
1912 alpha channel.
1913 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1915 they can, resulting in, for example, 8 pixels per byte for 1 bit files.
1916 This code expands to 1 pixel per byte without changing the values of
1917 the pixels:
1918 if (bit_depth < 8)
1920 png_set_packing(png_ptr);
1921 PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
1923 stored in a PNG image have been "scaled" or "shifted" up to the next
1924 higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
1925 to 8 bits/sample in the range [0, 255]). However, it is also possible
1926 to convert the PNG pixel data back to the original bit depth of the
1927 image. This call reduces the pixels back down to the original bit
1928 depth:
1929 png_color_8p sig_bit;
1931 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1933 png_set_shift(png_ptr, sig_bit);
1934 PNG files store 3-color pixels in red, green, blue order. This code
1936 changes the storage of the pixels to blue, green, red:
1937 if (color_type == PNG_COLOR_TYPE_RGB ||
1939 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1940 png_set_bgr(png_ptr);
1941 PNG files store RGB pixels packed into 3 or 6 bytes. This code expands
1943 them into 4 or 8 bytes for windowing systems that need them in this
1944 format:
1945 if (color_type == PNG_COLOR_TYPE_RGB)
1947 png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
1948 where "filler" is the 8 or 16-bit number to fill with, and the location
1950 is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1951 you want the filler before the RGB or after. This transformation does
1952 not affect images that already have full alpha channels. To add an
1953 opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER
1954 which will generate RGBA pixels.
1955 Note that png_set_filler() does not change the color type. If you want
1957 to do that, you can add a true alpha channel with
1958 if (color_type == PNG_COLOR_TYPE_RGB ||
1960 color_type == PNG_COLOR_TYPE_GRAY)
1961 png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1962 where "filler" contains the alpha value to assign to each pixel. This
1964 function was added in libpng-1.2.7.
1965 If you are reading an image with an alpha channel, and you need the
1967 data as ARGB instead of the normal PNG format RGBA:
1968 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1970 png_set_swap_alpha(png_ptr);
1971 For some uses, you may want a grayscale image to be represented as RGB.
1973 This code will do that conversion:
1974 if (color_type == PNG_COLOR_TYPE_GRAY ||
1976 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1977 png_set_gray_to_rgb(png_ptr);
1978 Conversely, you can convert an RGB or RGBA image to grayscale or
1980 grayscale with alpha.
1981 if (color_type == PNG_COLOR_TYPE_RGB ||
1983 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1984 png_set_rgb_to_gray_fixed(png_ptr, error_action,
1985 int red_weight, int green_weight);
1986 error_action = 1: silently do the conversion
1988 error_action = 2: issue a warning if the original
1989 image has any pixel where
1990 red != green or red != blue
1991 error_action = 3: issue an error and abort the
1992 conversion if the original
1993 image has any pixel where
1994 red != green or red != blue
1995 red_weight: weight of red component times 100000
1997 green_weight: weight of green component times 100000
1998 If either weight is negative, default
1999 weights (21268, 71514) are used.
2000 If you have set error_action = 1 or 2, you can later check whether the
2002 image really was gray, after processing the image rows, with the
2003 png_get_rgb_to_gray_status(png_ptr) function. It will return a
2004 png_byte that is zero if the image was gray or 1 if there were any non-
2005 gray pixels. bKGD and sBIT data will be silently converted to
2006 grayscale, using the green channel data, regardless of the error_action
2007 setting.
2008 With red_weight+green_weight<=100000, the normalized graylevel is com‐
2010 puted:
2011 int rw = red_weight * 65536;
2013 int gw = green_weight * 65536;
2014 int bw = 65536 - (rw + gw);
2015 gray = (rw*red + gw*green + bw*blue)/65536;
2016 The default values approximate those recommended in the Charles Poyn‐
2018 ton's Color FAQ, <http://www.inforamp.net/~poynton/> Copyright (c)
2019 1998-01-04 Charles Poynton <poynton at inforamp.net>
2020 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
2022 Libpng approximates this with
2024 Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
2026 which can be expressed with integers as
2028 Y = (6969 * R + 23434 * G + 2365 * B)/32768
2030 The calculation is done in a linear colorspace, if the image gamma is
2032 known.
2033 If you have a grayscale and you are using png_set_expand_depth(),
2035 png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to a
2036 higher bit-depth, you must either supply the background color as a gray
2037 value at the original file bit-depth (need_expand = 1) or else supply
2038 the background color as an RGB triplet at the final, expanded bit depth
2039 (need_expand = 0). Similarly, if you are reading a paletted image, you
2040 must either supply the background color as a palette index (need_expand
2041 = 1) or as an RGB triplet that may or may not be in the palette
2042 (need_expand = 0).
2043 png_color_16 my_background;
2045 png_color_16p image_background;
2046 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
2048 png_set_background(png_ptr, image_background,
2049 PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
2050 else
2051 png_set_background(png_ptr, &my_background,
2052 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
2053 The png_set_background() function tells libpng to composite images with
2055 alpha or simple transparency against the supplied background color. If
2056 the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), you may use
2057 this color, or supply another color more suitable for the current dis‐
2058 play (e.g., the background color from a web page). You need to tell
2059 libpng whether the color is in the gamma space of the display
2060 (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
2061 (PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one that
2062 is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't know
2063 why anyone would use this, but it's here).
2064 To properly display PNG images on any kind of system, the application
2066 needs to know what the display gamma is. Ideally, the user will know
2067 this, and the application will allow them to set it. One method of
2068 allowing the user to set the display gamma separately for each system
2069 is to check for a SCREEN_GAMMA or DISPLAY_GAMMA environment variable,
2070 which will hopefully be correctly set.
2071 Note that display_gamma is the overall gamma correction required to
2073 produce pleasing results, which depends on the lighting conditions in
2074 the surrounding environment. In a dim or brightly lit room, no compen‐
2075 sation other than the physical gamma exponent of the monitor is needed,
2076 while in a dark room a slightly smaller exponent is better.
2077 double gamma, screen_gamma;
2079 if (/* We have a user-defined screen
2081 gamma value */)
2082 {
2083 screen_gamma = user_defined_screen_gamma;
2084 }
2085 /* One way that applications can share the same
2086 screen gamma value */
2087 else if ((gamma_str = getenv("SCREEN_GAMMA"))
2088 != NULL)
2089 {
2090 screen_gamma = (double)atof(gamma_str);
2091 }
2092 /* If we don't have another value */
2093 else
2094 {
2095 screen_gamma = 2.2; /* A good guess for a
2096 PC monitor in a bright office or a dim room */
2097 screen_gamma = 2.0; /* A good guess for a
2098 PC monitor in a dark room */
2099 screen_gamma = 1.7 or 1.0; /* A good
2100 guess for Mac systems */
2101 }
2102 The png_set_gamma() function handles gamma transformations of the data.
2104 Pass both the file gamma and the current screen_gamma. If the file
2105 does not have a gamma value, you can pass one anyway if you have an
2106 idea what it is (usually 0.45455 is a good guess for GIF images on
2107 PCs). Note that file gammas are inverted from screen gammas. See the
2108 discussions on gamma in the PNG specification for an excellent descrip‐
2109 tion of what gamma is, and why all applications should support it. It
2110 is strongly recommended that PNG viewers support gamma correction.
2111 if (png_get_gAMA(png_ptr, info_ptr, &gamma))
2113 png_set_gamma(png_ptr, screen_gamma, gamma);
2114 else
2115 png_set_gamma(png_ptr, screen_gamma, 0.45455);
2116 If you need to reduce an RGB file to a paletted file, or if a paletted
2118 file has more entries then will fit on your screen, png_set_dither()
2119 will do that. Note that this is a simple match dither that merely
2120 finds the closest color available. This should work fairly well with
2121 optimized palettes, and fairly badly with linear color cubes. If you
2122 pass a palette that is larger then maximum_colors, the file will reduce
2123 the number of colors in the palette so it will fit into maximum_colors.
2124 If there is a histogram, it will use it to make more intelligent
2125 choices when reducing the palette. If there is no histogram, it may
2126 not do as good a job.
2127 if (color_type & PNG_COLOR_MASK_COLOR)
2129 {
2130 if (png_get_valid(png_ptr, info_ptr,
2131 PNG_INFO_PLTE))
2132 {
2133 png_uint_16p histogram = NULL;
2134 png_get_hIST(png_ptr, info_ptr,
2136 &histogram);
2137 png_set_dither(png_ptr, palette, num_palette,
2138 max_screen_colors, histogram, 1);
2139 }
2140 else
2141 {
2142 png_color std_color_cube[MAX_SCREEN_COLORS] =
2143 { ... colors ... };
2144 png_set_dither(png_ptr, std_color_cube,
2146 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
2147 NULL,0);
2148 }
2149 }
2150 PNG files describe monochrome as black being zero and white being one.
2152 The following code will reverse this (make black be one and white be
2153 zero):
2154 if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
2156 png_set_invert_mono(png_ptr);
2157 This function can also be used to invert grayscale and gray-alpha
2159 images:
2160 if (color_type == PNG_COLOR_TYPE_GRAY ||
2162 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
2163 png_set_invert_mono(png_ptr);
2164 PNG files store 16 bit pixels in network byte order (big-endian, ie.
2166 most significant bits first). This code changes the storage to the
2167 other way (little-endian, i.e. least significant bits first, the way
2168 PCs store them):
2169 if (bit_depth == 16)
2171 png_set_swap(png_ptr);
2172 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2174 need to change the order the pixels are packed into bytes, you can use:
2175 if (bit_depth < 8)
2177 png_set_packswap(png_ptr);
2178 Finally, you can write your own transformation function if none of the
2180 existing ones meets your needs. This is done by setting a callback
2181 with
2182 png_set_read_user_transform_fn(png_ptr,
2184 read_transform_fn);
2185 You must supply the function
2187 void read_transform_fn(png_ptr ptr, row_info_ptr
2189 row_info, png_bytep data)
2190 See pngtest.c for a working example. Your function will be called
2192 after all of the other transformations have been processed.
2193 You can also set up a pointer to a user structure for use by your call‐
2195 back function, and you can inform libpng that your transform function
2196 will change the number of channels or bit depth with the function
2197 png_set_user_transform_info(png_ptr, user_ptr,
2199 user_depth, user_channels);
2200 The user's application, not libpng, is responsible for allocating and
2202 freeing any memory required for the user structure.
2203 You can retrieve the pointer via the function png_get_user_trans‐
2205 form_ptr(). For example:
2206 voidp read_user_transform_ptr =
2208 png_get_user_transform_ptr(png_ptr);
2209 The last thing to handle is interlacing; this is covered in detail
2211 below, but you must call the function here if you want libpng to handle
2212 expansion of the interlaced image.
2213 number_of_passes = png_set_interlace_handling(png_ptr);
2215 After setting the transformations, libpng can update your png_info
2217 structure to reflect any transformations you've requested with this
2218 call. This is most useful to update the info structure's rowbytes
2219 field so you can use it to allocate your image memory. This function
2220 will also update your palette with the correct screen_gamma and back‐
2221 ground if these have been given with the calls above.
2222 png_read_update_info(png_ptr, info_ptr);
2224 After you call png_read_update_info(), you can allocate any memory you
2226 need to hold the image. The row data is simply raw byte data for all
2227 forms of images. As the actual allocation varies among applications,
2228 no example will be given. If you are allocating one large chunk, you
2229 will need to build an array of pointers to each row, as it will be
2230 needed for some of the functions below.
2231 Reading image data
2234 After you've allocated memory, you can read the image data. The sim‐
2235 plest way to do this is in one function call. If you are allocating
2236 enough memory to hold the whole image, you can just call
2237 png_read_image() and libpng will read in all the image data and put it
2238 in the memory area supplied. You will need to pass in an array of
2239 pointers to each row.
2240 This function automatically handles interlacing, so you don't need to
2242 call png_set_interlace_handling() or call this function multiple times,
2243 or any of that other stuff necessary with png_read_rows().
2244 png_read_image(png_ptr, row_pointers);
2246 where row_pointers is:
2248 png_bytep row_pointers[height];
2250 You can point to void or char or whatever you use for pixels.
2252 If you don't want to read in the whole image at once, you can use
2254 png_read_rows() instead. If there is no interlacing (check inter‐
2255 lace_type == PNG_INTERLACE_NONE), this is simple:
2256 png_read_rows(png_ptr, row_pointers, NULL,
2258 number_of_rows);
2259 where row_pointers is the same as in the png_read_image() call.
2261 If you are doing this just one row at a time, you can do this with a
2263 single row_pointer instead of an array of row_pointers:
2264 png_bytep row_pointer = row;
2266 png_read_row(png_ptr, row_pointer, NULL);
2267 If the file is interlaced (interlace_type != 0 in the IHDR chunk),
2269 things get somewhat harder. The only current (PNG Specification ver‐
2270 sion 1.2) interlacing type for PNG is (interlace_type == PNG_INTER‐
2271 LACE_ADAM7) is a somewhat complicated 2D interlace scheme, known as
2272 Adam7, that breaks down an image into seven smaller images of varying
2273 size, based on an 8x8 grid.
2274 libpng can fill out those images or it can give them to you "as is".
2276 If you want them filled out, there are two ways to do that. The one
2277 mentioned in the PNG specification is to expand each pixel to cover
2278 those pixels that have not been read yet (the "rectangle" method).
2279 This results in a blocky image for the first pass, which gradually
2280 smooths out as more pixels are read. The other method is the "sparkle"
2281 method, where pixels are drawn only in their final locations, with the
2282 rest of the image remaining whatever colors they were initialized to
2283 before the start of the read. The first method usually looks better,
2284 but tends to be slower, as there are more pixels to put in the rows.
2285 If you don't want libpng to handle the interlacing details, just call
2287 png_read_rows() seven times to read in all seven images. Each of the
2288 images is a valid image by itself, or they can all be combined on an
2289 8x8 grid to form a single image (although if you intend to combine them
2290 you would be far better off using the libpng interlace handling).
2291 The first pass will return an image 1/8 as wide as the entire image
2293 (every 8th column starting in column 0) and 1/8 as high as the original
2294 (every 8th row starting in row 0), the second will be 1/8 as wide
2295 (starting in column 4) and 1/8 as high (also starting in row 0). The
2296 third pass will be 1/4 as wide (every 4th pixel starting in column 0)
2297 and 1/8 as high (every 8th row starting in row 4), and the fourth pass
2298 will be 1/4 as wide and 1/4 as high (every 4th column starting in col‐
2299 umn 2, and every 4th row starting in row 0). The fifth pass will
2300 return an image 1/2 as wide, and 1/4 as high (starting at column 0 and
2301 row 2), while the sixth pass will be 1/2 as wide and 1/2 as high as the
2302 original (starting in column 1 and row 0). The seventh and final pass
2303 will be as wide as the original, and 1/2 as high, containing all of the
2304 odd numbered scanlines. Phew!
2305 If you want libpng to expand the images, call this before calling
2307 png_start_read_image() or png_read_update_info():
2308 if (interlace_type == PNG_INTERLACE_ADAM7)
2310 number_of_passes
2311 = png_set_interlace_handling(png_ptr);
2312 This will return the number of passes needed. Currently, this is
2314 seven, but may change if another interlace type is added. This func‐
2315 tion can be called even if the file is not interlaced, where it will
2316 return one pass.
2317 If you are not going to display the image after each pass, but are
2319 going to wait until the entire image is read in, use the sparkle
2320 effect. This effect is faster and the end result of either method is
2321 exactly the same. If you are planning on displaying the image after
2322 each pass, the "rectangle" effect is generally considered the better
2323 looking one.
2324 If you only want the "sparkle" effect, just call png_read_rows() as
2326 normal, with the third parameter NULL. Make sure you make pass over
2327 the image number_of_passes times, and you don't change the data in the
2328 rows between calls. You can change the locations of the data, just not
2329 the data. Each pass only writes the pixels appropriate for that pass,
2330 and assumes the data from previous passes is still valid.
2331 png_read_rows(png_ptr, row_pointers, NULL,
2333 number_of_rows);
2334 If you only want the first effect (the rectangles), do the same as
2336 before except pass the row buffer in the third parameter, and leave the
2337 second parameter NULL.
2338 png_read_rows(png_ptr, NULL, row_pointers,
2340 number_of_rows);
2341 Finishing a sequential read
2344 After you are finished reading the image through the low-level inter‐
2345 face, you can finish reading the file. If you are interested in com‐
2346 ments or time, which may be stored either before or after the image
2347 data, you should pass the separate png_info struct if you want to keep
2348 the comments from before and after the image separate. If you are not
2349 interested, you can pass NULL.
2350 png_read_end(png_ptr, end_info);
2352 When you are done, you can free all memory allocated by libpng like
2354 this:
2355 png_destroy_read_struct(&png_ptr, &info_ptr,
2357 &end_info);
2358 It is also possible to individually free the info_ptr members that
2360 point to libpng-allocated storage with the following function:
2361 png_free_data(png_ptr, info_ptr, mask, seq)
2363 mask - identifies data to be freed, a mask
2364 containing the bitwise OR of one or
2365 more of
2366 PNG_FREE_PLTE, PNG_FREE_TRNS,
2367 PNG_FREE_HIST, PNG_FREE_ICCP,
2368 PNG_FREE_PCAL, PNG_FREE_ROWS,
2369 PNG_FREE_SCAL, PNG_FREE_SPLT,
2370 PNG_FREE_TEXT, PNG_FREE_UNKN,
2371 or simply PNG_FREE_ALL
2372 seq - sequence number of item to be freed
2373 (-1 for all items)
2374 This function may be safely called when the relevant storage has
2376 already been freed, or has not yet been allocated, or was allocated by
2377 the user and not by libpng, and will in those cases do nothing. The
2378 "seq" parameter is ignored if only one item of the selected data type,
2379 such as PLTE, is allowed. If "seq" is not -1, and multiple items are
2380 allowed for the data type identified in the mask, such as text or sPLT,
2381 only the n'th item in the structure is freed, where n is "seq".
2382 The default behavior is only to free data that was allocated internally
2384 by libpng. This can be changed, so that libpng will not free the data,
2385 or so that it will free data that was allocated by the user with
2386 png_malloc() or png_zalloc() and passed in via a png_set_*() function,
2387 with
2388 png_data_freer(png_ptr, info_ptr, freer, mask)
2390 mask - which data elements are affected
2391 same choices as in png_free_data()
2392 freer - one of
2393 PNG_DESTROY_WILL_FREE_DATA
2394 PNG_SET_WILL_FREE_DATA
2395 PNG_USER_WILL_FREE_DATA
2396 This function only affects data that has already been allocated. You
2398 can call this function after reading the PNG data but before calling
2399 any png_set_*() functions, to control whether the user or the
2400 png_set_*() function is responsible for freeing any existing data that
2401 might be present, and again after the png_set_*() functions to control
2402 whether the user or png_destroy_*() is supposed to free the data. When
2403 the user assumes responsibility for libpng-allocated data, the applica‐
2404 tion must use png_free() to free it, and when the user transfers
2405 responsibility to libpng for data that the user has allocated, the user
2406 must have used png_malloc() or png_zalloc() to allocate it.
2407 If you allocated your row_pointers in a single block, as suggested
2409 above in the description of the high level read interface, you must not
2410 transfer responsibility for freeing it to the png_set_rows or
2411 png_read_destroy function, because they would also try to free the
2412 individual row_pointers[i].
2413 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.trans‐
2415 lated_keyword separately, do not transfer responsibility for freeing
2416 text_ptr to libpng, because when libpng fills a png_text structure it
2417 combines these members with the key member, and png_free_data() will
2418 free only text_ptr.key. Similarly, if you transfer responsibility for
2419 free'ing text_ptr from libpng to your application, your application
2420 must not separately free those members.
2421 The png_free_data() function will turn off the "valid" flag for any‐
2423 thing it frees. If you need to turn the flag off for a chunk that was
2424 freed by your application instead of by libpng, you can use
2425 png_set_invalid(png_ptr, info_ptr, mask);
2427 mask - identifies the chunks to be made invalid,
2428 containing the bitwise OR of one or
2429 more of
2430 PNG_INFO_gAMA, PNG_INFO_sBIT,
2431 PNG_INFO_cHRM, PNG_INFO_PLTE,
2432 PNG_INFO_tRNS, PNG_INFO_bKGD,
2433 PNG_INFO_hIST, PNG_INFO_pHYs,
2434 PNG_INFO_oFFs, PNG_INFO_tIME,
2435 PNG_INFO_pCAL, PNG_INFO_sRGB,
2436 PNG_INFO_iCCP, PNG_INFO_sPLT,
2437 PNG_INFO_sCAL, PNG_INFO_IDAT
2438 For a more compact example of reading a PNG image, see the file exam‐
2440 ple.c.
2441 Reading PNG files progressively
2444 The progressive reader is slightly different then the non-progressive
2445 reader. Instead of calling png_read_info(), png_read_rows(), and
2446 png_read_end(), you make one call to png_process_data(), which calls
2447 callbacks when it has the info, a row, or the end of the image. You
2448 set up these callbacks with png_set_progressive_read_fn(). You don't
2449 have to worry about the input/output functions of libpng, as you are
2450 giving the library the data directly in png_process_data(). I will
2451 assume that you have read the section on reading PNG files above, so I
2452 will only highlight the differences (although I will show all of the
2453 code).
2454 png_structp png_ptr; png_infop info_ptr;
2456 /* An example code fragment of how you would
2458 initialize the progressive reader in your
2459 application. */
2460 int
2461 initialize_png_reader()
2462 {
2463 png_ptr = png_create_read_struct
2464 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2465 user_error_fn, user_warning_fn);
2466 if (!png_ptr)
2467 return (ERROR);
2468 info_ptr = png_create_info_struct(png_ptr);
2469 if (!info_ptr)
2470 {
2471 png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
2472 (png_infopp)NULL);
2473 return (ERROR);
2474 }
2475 if (setjmp(png_jmpbuf(png_ptr)))
2477 {
2478 png_destroy_read_struct(&png_ptr, &info_ptr,
2479 (png_infopp)NULL);
2480 return (ERROR);
2481 }
2482 /* This one's new. You can provide functions
2484 to be called when the header info is valid,
2485 when each row is completed, and when the image
2486 is finished. If you aren't using all functions,
2487 you can specify NULL parameters. Even when all
2488 three functions are NULL, you need to call
2489 png_set_progressive_read_fn(). You can use
2490 any struct as the user_ptr (cast to a void pointer
2491 for the function call), and retrieve the pointer
2492 from inside the callbacks using the function
2493 png_get_progressive_ptr(png_ptr);
2495 which will return a void pointer, which you have
2497 to cast appropriately.
2498 */
2499 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
2500 info_callback, row_callback, end_callback);
2501 return 0;
2503 }
2504 /* A code fragment that you call as you receive blocks
2506 of data */
2507 int
2508 process_data(png_bytep buffer, png_uint_32 length)
2509 {
2510 if (setjmp(png_jmpbuf(png_ptr)))
2511 {
2512 png_destroy_read_struct(&png_ptr, &info_ptr,
2513 (png_infopp)NULL);
2514 return (ERROR);
2515 }
2516 /* This one's new also. Simply give it a chunk
2518 of data from the file stream (in order, of
2519 course). On machines with segmented memory
2520 models machines, don't give it any more than
2521 64K. The library seems to run fine with sizes
2522 of 4K. Although you can give it much less if
2523 necessary (I assume you can give it chunks of
2524 1 byte, I haven't tried less then 256 bytes
2525 yet). When this function returns, you may
2526 want to display any rows that were generated
2527 in the row callback if you don't already do
2528 so there.
2529 */
2530 png_process_data(png_ptr, info_ptr, buffer, length);
2531 return 0;
2532 }
2533 /* This function is called (as set by
2535 png_set_progressive_read_fn() above) when enough data
2536 has been supplied so all of the header has been
2537 read.
2538 */
2539 void
2540 info_callback(png_structp png_ptr, png_infop info)
2541 {
2542 /* Do any setup here, including setting any of
2543 the transformations mentioned in the Reading
2544 PNG files section. For now, you _must_ call
2545 either png_start_read_image() or
2546 png_read_update_info() after all the
2547 transformations are set (even if you don't set
2548 any). You may start getting rows before
2549 png_process_data() returns, so this is your
2550 last chance to prepare for that.
2551 */
2552 }
2553 /* This function is called when each row of image
2555 data is complete */
2556 void
2557 row_callback(png_structp png_ptr, png_bytep new_row,
2558 png_uint_32 row_num, int pass)
2559 {
2560 /* If the image is interlaced, and you turned
2561 on the interlace handler, this function will
2562 be called for every row in every pass. Some
2563 of these rows will not be changed from the
2564 previous pass. When the row is not changed,
2565 the new_row variable will be NULL. The rows
2566 and passes are called in order, so you don't
2567 really need the row_num and pass, but I'm
2568 supplying them because it may make your life
2569 easier.
2570 For the non-NULL rows of interlaced images,
2572 you must call png_progressive_combine_row()
2573 passing in the row and the old row. You can
2574 call this function for NULL rows (it will just
2575 return) and for non-interlaced images (it just
2576 does the memcpy for you) if it will make the
2577 code easier. Thus, you can just do this for
2578 all cases:
2579 */
2580 png_progressive_combine_row(png_ptr, old_row,
2582 new_row);
2583 /* where old_row is what was displayed for
2585 previously for the row. Note that the first
2586 pass (pass == 0, really) will completely cover
2587 the old row, so the rows do not have to be
2588 initialized. After the first pass (and only
2589 for interlaced images), you will have to pass
2590 the current row, and the function will combine
2591 the old row and the new row.
2592 */
2593 }
2594 void
2596 end_callback(png_structp png_ptr, png_infop info)
2597 {
2598 /* This function is called after the whole image
2599 has been read, including any chunks after the
2600 image (up to and including the IEND). You
2601 will usually have the same info chunk as you
2602 had in the header, although some data may have
2603 been added to the comments and time fields.
2604 Most people won't do much here, perhaps setting
2606 a flag that marks the image as finished.
2607 */
2608 }
2609
2614 Much of this is very similar to reading. However, everything of impor‐
2615 tance is repeated here, so you won't have to constantly look back up in
2616 the reading section to understand writing.
2617 Setup
2620 You will want to do the I/O initialization before you get into libpng,
2621 so if it doesn't work, you don't have anything to undo. If you are not
2622 using the standard I/O functions, you will need to replace them with
2623 custom writing functions. See the discussion under Customizing libpng.
2624 FILE *fp = fopen(file_name, "wb");
2626 if (!fp)
2627 {
2628 return (ERROR);
2629 }
2630 Next, png_struct and png_info need to be allocated and initialized. As
2632 these can be both relatively large, you may not want to store these on
2633 the stack, unless you have stack space to spare. Of course, you will
2634 want to check if they return NULL. If you are also reading, you won't
2635 want to name your read structure and your write structure both
2636 "png_ptr"; you can call them anything you like, such as "read_ptr" and
2637 "write_ptr". Look at pngtest.c, for example.
2638 png_structp png_ptr = png_create_write_struct
2640 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2641 user_error_fn, user_warning_fn);
2642 if (!png_ptr)
2643 return (ERROR);
2644 png_infop info_ptr = png_create_info_struct(png_ptr);
2646 if (!info_ptr)
2647 {
2648 png_destroy_write_struct(&png_ptr,
2649 (png_infopp)NULL);
2650 return (ERROR);
2651 }
2652 If you want to use your own memory allocation routines, define
2654 PNG_USER_MEM_SUPPORTED and use png_create_write_struct_2() instead of
2655 png_create_write_struct():
2656 png_structp png_ptr = png_create_write_struct_2
2658 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2659 user_error_fn, user_warning_fn, (png_voidp)
2660 user_mem_ptr, user_malloc_fn, user_free_fn);
2661 After you have these structures, you will need to set up the error han‐
2663 dling. When libpng encounters an error, it expects to longjmp() back
2664 to your routine. Therefore, you will need to call setjmp() and pass
2665 the png_jmpbuf(png_ptr). If you write the file from different rou‐
2666 tines, you will need to update the png_jmpbuf(png_ptr) every time you
2667 enter a new routine that will call a png_*() function. See your docu‐
2668 mentation of setjmp/longjmp for your compiler for more information on
2669 setjmp/longjmp. See the discussion on libpng error handling in the
2670 Customizing Libpng section below for more information on the libpng
2671 error handling.
2672 if (setjmp(png_jmpbuf(png_ptr)))
2674 {
2675 png_destroy_write_struct(&png_ptr, &info_ptr);
2676 fclose(fp);
2677 return (ERROR);
2678 }
2679 ...
2680 return;
2681 If you would rather avoid the complexity of setjmp/longjmp issues, you
2683 can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case errors
2684 will result in a call to PNG_ABORT() which defaults to abort().
2685 Now you need to set up the output code. The default for libpng is to
2687 use the C function fwrite(). If you use this, you will need to pass a
2688 valid FILE * in the function png_init_io(). Be sure that the file is
2689 opened in binary mode. Again, if you wish to handle writing data in
2690 another way, see the discussion on libpng I/O handling in the Customiz‐
2691 ing Libpng section below.
2692 png_init_io(png_ptr, fp);
2694 If you are embedding your PNG into a datastream such as MNG, and don't
2696 want libpng to write the 8-byte signature, or if you have already writ‐
2697 ten the signature in your application, use
2698 png_set_sig_bytes(png_ptr, 8);
2700 to inform libpng that it should not write a signature.
2702 Write callbacks
2705 At this point, you can set up a callback function that will be called
2706 after each row has been written, which you can use to control a
2707 progress meter or the like. It's demonstrated in pngtest.c. You must
2708 supply a function
2709 void write_row_callback(png_ptr, png_uint_32 row,
2711 int pass);
2712 {
2713 /* put your code here */
2714 }
2715 (You can give it another name that you like instead of "write_row_call‐
2717 back")
2718 To inform libpng about your function, use
2720 png_set_write_status_fn(png_ptr, write_row_callback);
2722 You now have the option of modifying how the compression library will
2724 run. The following functions are mainly for testing, but may be useful
2725 in some cases, like if you need to write PNG files extremely fast and
2726 are willing to give up some compression, or if you want to get the max‐
2727 imum possible compression at the expense of slower writing. If you
2728 have no special needs in this area, let the library do what it wants by
2729 not calling this function at all, as it has been tuned to deliver a
2730 good speed/compression ratio. The second parameter to png_set_filter()
2731 is the filter method, for which the only valid values are 0 (as of the
2732 July 1999 PNG specification, version 1.2) or 64 (if you are writing a
2733 PNG datastream that is to be embedded in a MNG datastream). The third
2734 parameter is a flag that indicates which filter type(s) are to be
2735 tested for each scanline. See the PNG specification for details on the
2736 specific filter types.
2737 /* turn on or off filtering, and/or choose
2740 specific filters. You can use either a single
2741 PNG_FILTER_VALUE_NAME or the bitwise OR of one
2742 or more PNG_FILTER_NAME masks. */
2743 png_set_filter(png_ptr, 0,
2744 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
2745 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
2746 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
2747 PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |
2748 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2749 PNG_ALL_FILTERS);
2750 If an application wants to start and stop using particular filters dur‐
2752 ing compression, it should start out with all of the filters (to ensure
2753 that the previous row of pixels will be stored in case it's needed
2754 later), and then add and remove them after the start of compression.
2755 If you are writing a PNG datastream that is to be embedded in a MNG
2757 datastream, the second parameter can be either 0 or 64.
2758 The png_set_compression_*() functions interface to the zlib compression
2760 library, and should mostly be ignored unless you really know what you
2761 are doing. The only generally useful call is png_set_compres‐
2762 sion_level() which changes how much time zlib spends on trying to com‐
2763 press the image data. See the Compression Library (zlib.h and algo‐
2764 rithm.txt, distributed with zlib) for details on the compression lev‐
2765 els.
2766 /* set the zlib compression level */
2768 png_set_compression_level(png_ptr,
2769 Z_BEST_COMPRESSION);
2770 /* set other zlib parameters */
2772 png_set_compression_mem_level(png_ptr, 8);
2773 png_set_compression_strategy(png_ptr,
2774 Z_DEFAULT_STRATEGY);
2775 png_set_compression_window_bits(png_ptr, 15);
2776 png_set_compression_method(png_ptr, 8);
2777 png_set_compression_buffer_size(png_ptr, 8192)
2778 extern PNG_EXPORT(void,png_set_zbuf_size)
2780 Setting the contents of info for output
2783 You now need to fill in the png_info structure with all the data you
2784 wish to write before the actual image. Note that the only thing you
2785 are allowed to write after the image is the text chunks and the time
2786 chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
2787 the latest PNG specification for more information on that. If you wish
2788 to write them before the image, fill them in now, and flag that data as
2789 being valid. If you want to wait until after the data, don't fill them
2790 until png_write_end(). For all the fields in png_info and their data
2791 types, see png.h. For explanations of what the fields contain, see the
2792 PNG specification.
2793 Some of the more important parts of the png_info are:
2795 png_set_IHDR(png_ptr, info_ptr, width, height,
2797 bit_depth, color_type, interlace_type,
2798 compression_type, filter_method)
2799 width - holds the width of the image
2800 in pixels (up to 2^31).
2801 height - holds the height of the image
2802 in pixels (up to 2^31).
2803 bit_depth - holds the bit depth of one of the
2804 image channels.
2805 (valid values are 1, 2, 4, 8, 16
2806 and depend also on the
2807 color_type. See also significant
2808 bits (sBIT) below).
2809 color_type - describes which color/alpha
2810 channels are present.
2811 PNG_COLOR_TYPE_GRAY
2812 (bit depths 1, 2, 4, 8, 16)
2813 PNG_COLOR_TYPE_GRAY_ALPHA
2814 (bit depths 8, 16)
2815 PNG_COLOR_TYPE_PALETTE
2816 (bit depths 1, 2, 4, 8)
2817 PNG_COLOR_TYPE_RGB
2818 (bit_depths 8, 16)
2819 PNG_COLOR_TYPE_RGB_ALPHA
2820 (bit_depths 8, 16)
2821 PNG_COLOR_MASK_PALETTE
2823 PNG_COLOR_MASK_COLOR
2824 PNG_COLOR_MASK_ALPHA
2825 interlace_type - PNG_INTERLACE_NONE or
2827 PNG_INTERLACE_ADAM7
2828 compression_type - (must be
2829 PNG_COMPRESSION_TYPE_DEFAULT)
2830 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
2831 or, if you are writing a PNG to
2832 be embedded in a MNG datastream,
2833 can also be
2834 PNG_INTRAPIXEL_DIFFERENCING)
2835 If you call png_set_IHDR(), the call must appear before any of the
2837 other png_set_*() functions, because they might require access to some
2838 of the IHDR settings. The remaining png_set_*() functions can be
2839 called in any order.
2840 If you wish, you can reset the compression_type, interlace_type, or
2842 filter_method later by calling png_set_IHDR() again; if you do this,
2843 the width, height, bit_depth, and color_type must be the same in each
2844 call.
2845 png_set_PLTE(png_ptr, info_ptr, palette,
2847 num_palette);
2848 palette - the palette for the file
2849 (array of png_color)
2850 num_palette - number of entries in the palette
2851 png_set_gAMA(png_ptr, info_ptr, gamma);
2853 gamma - the gamma the image was created
2854 at (PNG_INFO_gAMA)
2855 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
2857 srgb_intent - the rendering intent
2858 (PNG_INFO_sRGB) The presence of
2859 the sRGB chunk means that the pixel
2860 data is in the sRGB color space.
2861 This chunk also implies specific
2862 values of gAMA and cHRM. Rendering
2863 intent is the CSS-1 property that
2864 has been defined by the International
2865 Color Consortium
2866 (http://www.color.org).
2867 It can be one of
2868 PNG_sRGB_INTENT_SATURATION,
2869 PNG_sRGB_INTENT_PERCEPTUAL,
2870 PNG_sRGB_INTENT_ABSOLUTE, or
2871 PNG_sRGB_INTENT_RELATIVE.
2872 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
2875 srgb_intent);
2876 srgb_intent - the rendering intent
2877 (PNG_INFO_sRGB) The presence of the
2878 sRGB chunk means that the pixel
2879 data is in the sRGB color space.
2880 This function also causes gAMA and
2881 cHRM chunks with the specific values
2882 that are consistent with sRGB to be
2883 written.
2884 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
2886 profile, proflen);
2887 name - The profile name.
2888 compression - The compression type; always
2889 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
2890 You may give NULL to this argument to
2891 ignore it.
2892 profile - International Color Consortium color
2893 profile data. May contain NULs.
2894 proflen - length of profile data in bytes.
2895 png_set_sBIT(png_ptr, info_ptr, sig_bit);
2897 sig_bit - the number of significant bits for
2898 (PNG_INFO_sBIT) each of the gray, red,
2899 green, and blue channels, whichever are
2900 appropriate for the given color type
2901 (png_color_16)
2902 png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
2904 trans_values);
2905 trans - array of transparent
2906 entries for palette (PNG_INFO_tRNS)
2907 trans_values - graylevel or color sample values
2908 (in order red, green, blue) of the
2909 single transparent color for
2910 non-paletted images (PNG_INFO_tRNS)
2911 num_trans - number of transparent entries
2912 (PNG_INFO_tRNS)
2913 png_set_hIST(png_ptr, info_ptr, hist);
2915 (PNG_INFO_hIST)
2916 hist - histogram of palette (array of
2917 png_uint_16)
2918 png_set_tIME(png_ptr, info_ptr, mod_time);
2920 mod_time - time image was last modified
2921 (PNG_VALID_tIME)
2922 png_set_bKGD(png_ptr, info_ptr, background);
2924 background - background color (PNG_VALID_bKGD)
2925 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
2927 text_ptr - array of png_text holding image
2928 comments
2929 text_ptr[i].compression - type of compression used
2930 on "text" PNG_TEXT_COMPRESSION_NONE
2931 PNG_TEXT_COMPRESSION_zTXt
2932 PNG_ITXT_COMPRESSION_NONE
2933 PNG_ITXT_COMPRESSION_zTXt
2934 text_ptr[i].key - keyword for comment. Must contain
2935 1-79 characters.
2936 text_ptr[i].text - text comments for current
2937 keyword. Can be NULL or empty.
2938 text_ptr[i].text_length - length of text string,
2939 after decompression, 0 for iTXt
2940 text_ptr[i].itxt_length - length of itxt string,
2941 after decompression, 0 for tEXt/zTXt
2942 text_ptr[i].lang - language of comment (NULL or
2943 empty for unknown).
2944 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
2945 or empty for unknown).
2946 Note that the itxt_length, lang, and lang_key
2947 members of the text_ptr structure only exist
2948 when the library is built with iTXt chunk support.
2949 num_text - number of comments
2951 png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
2953 num_spalettes);
2954 palette_ptr - array of png_sPLT_struct structures
2955 to be added to the list of palettes
2956 in the info structure.
2957 num_spalettes - number of palette structures to be
2958 added.
2959 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
2961 unit_type);
2962 offset_x - positive offset from the left
2963 edge of the screen
2964 offset_y - positive offset from the top
2965 edge of the screen
2966 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2967 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2969 unit_type);
2970 res_x - pixels/unit physical resolution
2971 in x direction
2972 res_y - pixels/unit physical resolution
2973 in y direction
2974 unit_type - PNG_RESOLUTION_UNKNOWN,
2975 PNG_RESOLUTION_METER
2976 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
2978 unit - physical scale units (an integer)
2979 width - width of a pixel in physical scale units
2980 height - height of a pixel in physical scale units
2981 (width and height are doubles)
2982 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2984 unit - physical scale units (an integer)
2985 width - width of a pixel in physical scale units
2986 height - height of a pixel in physical scale units
2987 (width and height are strings like "2.54")
2988 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
2990 num_unknowns)
2991 unknowns - array of png_unknown_chunk
2992 structures holding unknown chunks
2993 unknowns[i].name - name of unknown chunk
2994 unknowns[i].data - data of unknown chunk
2995 unknowns[i].size - size of unknown chunk's data
2996 unknowns[i].location - position to write chunk in file
2997 0: do not write chunk
2998 PNG_HAVE_IHDR: before PLTE
2999 PNG_HAVE_PLTE: before IDAT
3000 PNG_AFTER_IDAT: after IDAT
3001 The "location" member is set automatically according to what part of
3003 the output file has already been written. You can change its value
3004 after calling png_set_unknown_chunks() as demonstrated in pngtest.c.
3005 Within each of the "locations", the chunks are sequenced according to
3006 their position in the structure (that is, the value of "i", which is
3007 the order in which the chunk was either read from the input file or
3008 defined with png_set_unknown_chunks).
3009 A quick word about text and num_text. text is an array of png_text
3011 structures. num_text is the number of valid structures in the array.
3012 Each png_text structure holds a language code, a keyword, a text value,
3013 and a compression type.
3014 The compression types have the same valid numbers as the compression
3016 types of the image data. Currently, the only valid number is zero.
3017 However, you can store text either compressed or uncompressed, unlike
3018 images, which always have to be compressed. So if you don't want the
3019 text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
3020 Because tEXt and zTXt chunks don't have a language field, if you spec‐
3021 ify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt any language
3022 code or translated keyword will not be written out.
3023 Until text gets around 1000 bytes, it is not worth compressing it.
3025 After the text has been written out to the file, the compression type
3026 is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
3027 so that it isn't written out again at the end (in case you are calling
3028 png_write_end() with the same struct.
3029 The keywords that are given in the PNG Specification are:
3031 Title Short (one line) title or
3033 caption for image
3034 Author Name of image's creator
3035 Description Description of image (possibly long)
3036 Copyright Copyright notice
3037 Creation Time Time of original image creation
3038 (usually RFC 1123 format, see below)
3039 Software Software used to create the image
3040 Disclaimer Legal disclaimer
3041 Warning Warning of nature of content
3042 Source Device used to create the image
3043 Comment Miscellaneous comment; conversion
3044 from other image format
3045 The keyword-text pairs work like this. Keywords should be short simple
3047 descriptions of what the comment is about. Some typical keywords are
3048 found in the PNG specification, as is some recommendations on keywords.
3049 You can repeat keywords in a file. You can even write some text before
3050 the image and some after. For example, you may want to put a descrip‐
3051 tion of the image before the image, but leave the disclaimer until
3052 after, so viewers working over modem connections don't have to wait for
3053 the disclaimer to go over the modem before they start seeing the image.
3054 Finally, keywords should be full words, not abbreviations. Keywords
3055 and text are in the ISO 8859-1 (Latin-1) character set (a superset of
3056 regular ASCII) and can not contain NUL characters, and should not con‐
3057 tain control or other unprintable characters. To make the comments
3058 widely readable, stick with basic ASCII, and avoid machine specific
3059 character set extensions like the IBM-PC character set. The keyword
3060 must be present, but you can leave off the text string on non-com‐
3061 pressed pairs. Compressed pairs must have a text string, as only the
3062 text string is compressed anyway, so the compression would be meaning‐
3063 less.
3064 PNG supports modification time via the png_time structure. Two conver‐
3066 sion routines are provided, png_convert_from_time_t() for time_t and
3067 png_convert_from_struct_tm() for struct tm. The time_t routine uses
3068 gmtime(). You don't have to use either of these, but if you wish to
3069 fill in the png_time structure directly, you should provide the time in
3070 universal time (GMT) if possible instead of your local time. Note that
3071 the year number is the full year (e.g. 1998, rather than 98 - PNG is
3072 year 2000 compliant!), and that months start with 1.
3073 If you want to store the time of the original image creation, you
3075 should use a plain tEXt chunk with the "Creation Time" keyword. This
3076 is necessary because the "creation time" of a PNG image is somewhat
3077 vague, depending on whether you mean the PNG file, the time the image
3078 was created in a non-PNG format, a still photo from which the image was
3079 scanned, or possibly the subject matter itself. In order to facilitate
3080 machine-readable dates, it is recommended that the "Creation Time" tEXt
3081 chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
3082 although this isn't a requirement. Unlike the tIME chunk, the "Cre‐
3083 ation Time" tEXt chunk is not expected to be automatically changed by
3084 the software. To facilitate the use of RFC 1123 dates, a function
3085 png_convert_to_rfc1123(png_timep) is provided to convert from PNG time
3086 to an RFC 1123 format string.
3087 Writing unknown chunks
3090 You can use the png_set_unknown_chunks function to queue up chunks for
3091 writing. You give it a chunk name, raw data, and a size; that's all
3092 there is to it. The chunks will be written by the next following
3093 png_write_info_before_PLTE, png_write_info, or png_write_end function.
3094 Any chunks previously read into the info structure's unknown-chunk list
3095 will also be written out in a sequence that satisfies the PNG specifi‐
3096 cation's ordering rules.
3097 The high-level write interface
3100 At this point there are two ways to proceed; through the high-level
3101 write interface, or through a sequence of low-level write operations.
3102 You can use the high-level interface if your image data is present in
3103 the info structure. All defined output transformations are permitted,
3104 enabled by the following masks.
3105 PNG_TRANSFORM_IDENTITY No transformation
3107 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
3108 PNG_TRANSFORM_PACKSWAP Change order of packed
3109 pixels to LSB first
3110 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
3111 PNG_TRANSFORM_SHIFT Normalize pixels to the
3112 sBIT depth
3113 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
3114 to BGRA
3115 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
3116 to AG
3117 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
3118 to transparency
3119 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
3120 PNG_TRANSFORM_STRIP_FILLER Strip out filler
3121 bytes (deprecated).
3122 PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
3123 filler bytes
3124 PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing
3125 filler bytes
3126 If you have valid image data in the info structure (you can use
3128 png_set_rows() to put image data in the info structure), simply do
3129 this:
3130 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
3132 where png_transforms is an integer containing the bitwise OR of some
3134 set of transformation flags. This call is equivalent to
3135 png_write_info(), followed the set of transformations indicated by the
3136 transform mask, then png_write_image(), and finally png_write_end().
3137 (The final parameter of this call is not yet used. Someday it might
3139 point to transformation parameters required by some future output
3140 transform.)
3141 You must use png_transforms and not call any png_set_transform() func‐
3143 tions when you use png_write_png().
3144 The low-level write interface
3147 If you are going the low-level route instead, you are now ready to
3148 write all the file information up to the actual image data. You do
3149 this with a call to png_write_info().
3150 png_write_info(png_ptr, info_ptr);
3152 Note that there is one transformation you may need to do before
3154 png_write_info(). In PNG files, the alpha channel in an image is the
3155 level of opacity. If your data is supplied as a level of transparency,
3156 you can invert the alpha channel before you write it, so that 0 is
3157 fully transparent and 255 (in 8-bit or paletted images) or 65535 (in
3158 16-bit images) is fully opaque, with
3159 png_set_invert_alpha(png_ptr);
3161 This must appear before png_write_info() instead of later with the
3163 other transformations because in the case of paletted images the tRNS
3164 chunk data has to be inverted before the tRNS chunk is written. If
3165 your image is not a paletted image, the tRNS data (which in such cases
3166 represents a single color to be rendered as transparent) won't need to
3167 be changed, and you can safely do this transformation after your
3168 png_write_info() call.
3169 If you need to write a private chunk that you want to appear before the
3171 PLTE chunk when PLTE is present, you can write the PNG info in two
3172 steps, and insert code to write your own chunk between them:
3173 png_write_info_before_PLTE(png_ptr, info_ptr);
3175 png_set_unknown_chunks(png_ptr, info_ptr, ...);
3176 png_write_info(png_ptr, info_ptr);
3177 After you've written the file information, you can set up the library
3179 to handle any special transformations of the image data. The various
3180 ways to transform the data will be described in the order that they
3181 should occur. This is important, as some of these change the color
3182 type and/or bit depth of the data, and some others only work on certain
3183 color types and bit depths. Even though each transformation checks to
3184 see if it has data that it can do something with, you should make sure
3185 to only enable a transformation if it will be valid for the data. For
3186 example, don't swap red and blue on grayscale data.
3187 PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
3189 the library to strip input data that has 4 or 8 bytes per pixel down to
3190 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
3191 bytes per pixel).
3192 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
3194 where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
3196 PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
3197 is stored XRGB or RGBX.
3198 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
3200 they can, resulting in, for example, 8 pixels per byte for 1 bit files.
3201 If the data is supplied at 1 pixel per byte, use this code, which will
3202 correctly pack the pixels into a single byte:
3203 png_set_packing(png_ptr);
3205 PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
3207 data is of another bit depth, you can write an sBIT chunk into the file
3208 so that decoders can recover the original data if desired.
3209 /* Set the true bit depth of the image data */
3211 if (color_type & PNG_COLOR_MASK_COLOR)
3212 {
3213 sig_bit.red = true_bit_depth;
3214 sig_bit.green = true_bit_depth;
3215 sig_bit.blue = true_bit_depth;
3216 }
3217 else
3218 {
3219 sig_bit.gray = true_bit_depth;
3220 }
3221 if (color_type & PNG_COLOR_MASK_ALPHA)
3222 {
3223 sig_bit.alpha = true_bit_depth;
3224 }
3225 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
3227 If the data is stored in the row buffer in a bit depth other than one
3229 supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
3230 this will scale the values to appear to be the correct bit depth as is
3231 required by PNG.
3232 png_set_shift(png_ptr, &sig_bit);
3234 PNG files store 16 bit pixels in network byte order (big-endian, ie.
3236 most significant bits first). This code would be used if they are sup‐
3237 plied the other way (little-endian, i.e. least significant bits first,
3238 the way PCs store them):
3239 if (bit_depth > 8)
3241 png_set_swap(png_ptr);
3242 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
3244 need to change the order the pixels are packed into bytes, you can use:
3245 if (bit_depth < 8)
3247 png_set_packswap(png_ptr);
3248 PNG files store 3 color pixels in red, green, blue order. This code
3250 would be used if they are supplied as blue, green, red:
3251 png_set_bgr(png_ptr);
3253 PNG files describe monochrome as black being zero and white being one.
3255 This code would be used if the pixels are supplied with this reversed
3256 (black being one and white being zero):
3257 png_set_invert_mono(png_ptr);
3259 Finally, you can write your own transformation function if none of the
3261 existing ones meets your needs. This is done by setting a callback
3262 with
3263 png_set_write_user_transform_fn(png_ptr,
3265 write_transform_fn);
3266 You must supply the function
3268 void write_transform_fn(png_ptr ptr, row_info_ptr
3270 row_info, png_bytep data)
3271 See pngtest.c for a working example. Your function will be called
3273 before any of the other transformations are processed.
3274 You can also set up a pointer to a user structure for use by your call‐
3276 back function.
3277 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
3279 The user_channels and user_depth parameters of this function are
3281 ignored when writing; you can set them to zero as shown.
3282 You can retrieve the pointer via the function png_get_user_trans‐
3284 form_ptr(). For example:
3285 voidp write_user_transform_ptr =
3287 png_get_user_transform_ptr(png_ptr);
3288 It is possible to have libpng flush any pending output, either manu‐
3290 ally, or automatically after a certain number of lines have been writ‐
3291 ten. To flush the output stream a single time call:
3292 png_write_flush(png_ptr);
3294 and to have libpng flush the output stream periodically after a certain
3296 number of scanlines have been written, call:
3297 png_set_flush(png_ptr, nrows);
3299 Note that the distance between rows is from the last time
3301 png_write_flush() was called, or the first row of the image if it has
3302 never been called. So if you write 50 lines, and then png_set_flush
3303 25, it will flush the output on the next scanline, and every 25 lines
3304 thereafter, unless png_write_flush() is called before 25 more lines
3305 have been written. If nrows is too small (less than about 10 lines for
3306 a 640 pixel wide RGB image) the image compression may decrease notice‐
3307 ably (although this may be acceptable for real-time applications).
3308 Infrequent flushing will only degrade the compression performance by a
3309 few percent over images that do not use flushing.
3310 Writing the image data
3313 That's it for the transformations. Now you can write the image data.
3314 The simplest way to do this is in one function call. If you have the
3315 whole image in memory, you can just call png_write_image() and libpng
3316 will write the image. You will need to pass in an array of pointers to
3317 each row. This function automatically handles interlacing, so you
3318 don't need to call png_set_interlace_handling() or call this function
3319 multiple times, or any of that other stuff necessary with
3320 png_write_rows().
3321 png_write_image(png_ptr, row_pointers);
3323 where row_pointers is:
3325 png_byte *row_pointers[height];
3327 You can point to void or char or whatever you use for pixels.
3329 If you don't want to write the whole image at once, you can use
3331 png_write_rows() instead. If the file is not interlaced, this is sim‐
3332 ple:
3333 png_write_rows(png_ptr, row_pointers,
3335 number_of_rows);
3336 row_pointers is the same as in the png_write_image() call.
3338 If you are just writing one row at a time, you can do this with a sin‐
3340 gle row_pointer instead of an array of row_pointers:
3341 png_bytep row_pointer = row;
3343 png_write_row(png_ptr, row_pointer);
3345 When the file is interlaced, things can get a good deal more compli‐
3347 cated. The only currently (as of the PNG Specification version 1.2,
3348 dated July 1999) defined interlacing scheme for PNG files is the
3349 "Adam7" interlace scheme, that breaks down an image into seven smaller
3350 images of varying size. libpng will build these images for you, or you
3351 can do them yourself. If you want to build them yourself, see the PNG
3352 specification for details of which pixels to write when.
3353 If you don't want libpng to handle the interlacing details, just use
3355 png_set_interlace_handling() and call png_write_rows() the correct num‐
3356 ber of times to write all seven sub-images.
3357 If you want libpng to build the sub-images, call this before you start
3359 writing any rows:
3360 number_of_passes =
3362 png_set_interlace_handling(png_ptr);
3363 This will return the number of passes needed. Currently, this is
3365 seven, but may change if another interlace type is added.
3366 Then write the complete image number_of_passes times.
3368 png_write_rows(png_ptr, row_pointers,
3370 number_of_rows);
3371 As some of these rows are not used, and thus return immediately, you
3373 may want to read about interlacing in the PNG specification, and only
3374 update the rows that are actually used.
3375 Finishing a sequential write
3378 After you are finished writing the image, you should finish writing the
3379 file. If you are interested in writing comments or time, you should
3380 pass an appropriately filled png_info pointer. If you are not inter‐
3381 ested, you can pass NULL.
3382 png_write_end(png_ptr, info_ptr);
3384 When you are done, you can free all memory used by libpng like this:
3386 png_destroy_write_struct(&png_ptr, &info_ptr);
3388 It is also possible to individually free the info_ptr members that
3390 point to libpng-allocated storage with the following function:
3391 png_free_data(png_ptr, info_ptr, mask, seq)
3393 mask - identifies data to be freed, a mask
3394 containing the bitwise OR of one or
3395 more of
3396 PNG_FREE_PLTE, PNG_FREE_TRNS,
3397 PNG_FREE_HIST, PNG_FREE_ICCP,
3398 PNG_FREE_PCAL, PNG_FREE_ROWS,
3399 PNG_FREE_SCAL, PNG_FREE_SPLT,
3400 PNG_FREE_TEXT, PNG_FREE_UNKN,
3401 or simply PNG_FREE_ALL
3402 seq - sequence number of item to be freed
3403 (-1 for all items)
3404 This function may be safely called when the relevant storage has
3406 already been freed, or has not yet been allocated, or was allocated by
3407 the user and not by libpng, and will in those cases do nothing. The
3408 "seq" parameter is ignored if only one item of the selected data type,
3409 such as PLTE, is allowed. If "seq" is not -1, and multiple items are
3410 allowed for the data type identified in the mask, such as text or sPLT,
3411 only the n'th item in the structure is freed, where n is "seq".
3412 If you allocated data such as a palette that you passed in to libpng
3414 with png_set_*, you must not free it until just before the call to
3415 png_destroy_write_struct().
3416 The default behavior is only to free data that was allocated internally
3418 by libpng. This can be changed, so that libpng will not free the data,
3419 or so that it will free data that was allocated by the user with
3420 png_malloc() or png_zalloc() and passed in via a png_set_*() function,
3421 with
3422 png_data_freer(png_ptr, info_ptr, freer, mask)
3424 mask - which data elements are affected
3425 same choices as in png_free_data()
3426 freer - one of
3427 PNG_DESTROY_WILL_FREE_DATA
3428 PNG_SET_WILL_FREE_DATA
3429 PNG_USER_WILL_FREE_DATA
3430 For example, to transfer responsibility for some data from a read
3432 structure to a write structure, you could use
3433 png_data_freer(read_ptr, read_info_ptr,
3435 PNG_USER_WILL_FREE_DATA,
3436 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3437 png_data_freer(write_ptr, write_info_ptr,
3438 PNG_DESTROY_WILL_FREE_DATA,
3439 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3440 thereby briefly reassigning responsibility for freeing to the user but
3442 immediately afterwards reassigning it once more to the write_destroy
3443 function. Having done this, it would then be safe to destroy the read
3444 structure and continue to use the PLTE, tRNS, and hIST data in the
3445 write structure.
3446 This function only affects data that has already been allocated. You
3448 can call this function before calling after the png_set_*() functions
3449 to control whether the user or png_destroy_*() is supposed to free the
3450 data. When the user assumes responsibility for libpng-allocated data,
3451 the application must use png_free() to free it, and when the user
3452 transfers responsibility to libpng for data that the user has allo‐
3453 cated, the user must have used png_malloc() or png_zalloc() to allocate
3454 it.
3455 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.trans‐
3457 lated_keyword separately, do not transfer responsibility for freeing
3458 text_ptr to libpng, because when libpng fills a png_text structure it
3459 combines these members with the key member, and png_free_data() will
3460 free only text_ptr.key. Similarly, if you transfer responsibility for
3461 free'ing text_ptr from libpng to your application, your application
3462 must not separately free those members. For a more compact example of
3463 writing a PNG image, see the file example.c.
3464
3467 There are two issues here. The first is changing how libpng does stan‐
3468 dard things like memory allocation, input/output, and error handling.
3469 The second deals with more complicated things like adding new chunks,
3470 adding new transformations, and generally changing how libpng works.
3471 Both of those are compile-time issues; that is, they are generally
3472 determined at the time the code is written, and there is rarely a need
3473 to provide the user with a means of changing them.
3474 Memory allocation, input/output, and error handling
3476 All of the memory allocation, input/output, and error handling in
3478 libpng goes through callbacks that are user-settable. The default rou‐
3479 tines are in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respec‐
3480 tively. To change these functions, call the appropriate png_set_*_fn()
3481 function.
3482 Memory allocation is done through the functions png_malloc(), png_cal‐
3484 loc(), and png_free(). These currently just call the standard C func‐
3485 tions. png_calloc() calls png_malloc() and then png_memset() to clear
3486 the newly allocated memory to zero. If your pointers can't access more
3487 then 64K at a time, you will want to set MAXSEG_64K in zlib.h. Since
3488 it is unlikely that the method of handling memory allocation on a plat‐
3489 form will change between applications, these functions must be modified
3490 in the library at compile time. If you prefer to use a different
3491 method of allocating and freeing data, you can use png_cre‐
3492 ate_read_struct_2() or png_create_write_struct_2() to register your own
3493 functions as described above. These functions also provide a void
3494 pointer that can be retrieved via
3495 mem_ptr=png_get_mem_ptr(png_ptr);
3497 Your replacement memory functions must have prototypes as follows:
3499 png_voidp malloc_fn(png_structp png_ptr,
3501 png_size_t size);
3502 void free_fn(png_structp png_ptr, png_voidp ptr);
3503 Your malloc_fn() must return NULL in case of failure. The png_malloc()
3505 function will normally call png_error() if it receives a NULL from the
3506 system memory allocator or from your replacement malloc_fn().
3507 Your free_fn() will never be called with a NULL ptr, since libpng's
3509 png_free() checks for NULL before calling free_fn().
3510 Input/Output in libpng is done through png_read() and png_write(),
3512 which currently just call fread() and fwrite(). The FILE * is stored
3513 in png_struct and is initialized via png_init_io(). If you wish to
3514 change the method of I/O, the library supplies callbacks that you can
3515 set through the function png_set_read_fn() and png_set_write_fn() at
3516 run time, instead of calling the png_init_io() function. These func‐
3517 tions also provide a void pointer that can be retrieved via the func‐
3518 tion png_get_io_ptr(). For example:
3519 png_set_read_fn(png_structp read_ptr,
3521 voidp read_io_ptr, png_rw_ptr read_data_fn)
3522 png_set_write_fn(png_structp write_ptr,
3524 voidp write_io_ptr, png_rw_ptr write_data_fn,
3525 png_flush_ptr output_flush_fn);
3526 voidp read_io_ptr = png_get_io_ptr(read_ptr);
3528 voidp write_io_ptr = png_get_io_ptr(write_ptr);
3529 The replacement I/O functions must have prototypes as follows:
3531 void user_read_data(png_structp png_ptr,
3533 png_bytep data, png_size_t length);
3534 void user_write_data(png_structp png_ptr,
3535 png_bytep data, png_size_t length);
3536 void user_flush_data(png_structp png_ptr);
3537 The user_read_data() function is responsible for detecting and handling
3539 end-of-data errors.
3540 Supplying NULL for the read, write, or flush functions sets them back
3542 to using the default C stream functions, which expect the io_ptr to
3543 point to a standard *FILE structure. It is probably a mistake to use
3544 NULL for one of write_data_fn and output_flush_fn but not both of them,
3545 unless you have built libpng with PNG_NO_WRITE_FLUSH defined. It is an
3546 error to read from a write stream, and vice versa.
3547 Error handling in libpng is done through png_error() and png_warning().
3549 Errors handled through png_error() are fatal, meaning that png_error()
3550 should never return to its caller. Currently, this is handled via
3551 setjmp() and longjmp() (unless you have compiled libpng with
3552 PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
3553 but you could change this to do things like exit() if you should wish.
3554 On non-fatal errors, png_warning() is called to print a warning mes‐
3556 sage, and then control returns to the calling code. By default
3557 png_error() and png_warning() print a message on stderr via fprintf()
3558 unless the library is compiled with PNG_NO_CONSOLE_IO defined (because
3559 you don't want the messages) or PNG_NO_STDIO defined (because fprintf()
3560 isn't available). If you wish to change the behavior of the error
3561 functions, you will need to set up your own message callbacks. These
3562 functions are normally supplied at the time that the png_struct is cre‐
3563 ated. It is also possible to redirect errors and warnings to your own
3564 replacement functions after png_create_*_struct() has been called by
3565 calling:
3566 png_set_error_fn(png_structp png_ptr,
3568 png_voidp error_ptr, png_error_ptr error_fn,
3569 png_error_ptr warning_fn);
3570 png_voidp error_ptr = png_get_error_ptr(png_ptr);
3572 If NULL is supplied for either error_fn or warning_fn, then the libpng
3574 default function will be used, calling fprintf() and/or longjmp() if a
3575 problem is encountered. The replacement error functions should have
3576 parameters as follows:
3577 void user_error_fn(png_structp png_ptr,
3579 png_const_charp error_msg);
3580 void user_warning_fn(png_structp png_ptr,
3581 png_const_charp warning_msg);
3582 The motivation behind using setjmp() and longjmp() is the C++ throw and
3584 catch exception handling methods. This makes the code much easier to
3585 write, as there is no need to check every return code of every function
3586 call. However, there are some uncertainties about the status of local
3587 variables after a longjmp, so the user may want to be careful about
3588 doing anything after setjmp returns non-zero besides returning itself.
3589 Consult your compiler documentation for more details. For an alterna‐
3590 tive approach, you may wish to use the "cexcept" facility (see
3591 http://cexcept.sourceforge.net).
3592 Custom chunks
3595 If you need to read or write custom chunks, you may need to get deeper
3596 into the libpng code. The library now has mechanisms for storing and
3597 writing chunks of unknown type; you can even declare callbacks for cus‐
3598 tom chunks. However, this may not be good enough if the library code
3599 itself needs to know about interactions between your chunk and existing
3600 `intrinsic' chunks.
3601 If you need to write a new intrinsic chunk, first read the PNG specifi‐
3603 cation. Acquire a first level of understanding of how it works. Pay
3604 particular attention to the sections that describe chunk names, and
3605 look at how other chunks were designed, so you can do things similarly.
3606 Second, check out the sections of libpng that read and write chunks.
3607 Try to find a chunk that is similar to yours and use it as a template.
3608 More details can be found in the comments inside the code. It is best
3609 to handle unknown chunks in a generic method, via callback functions,
3610 instead of by modifying libpng functions.
3611 If you wish to write your own transformation for the data, look through
3613 the part of the code that does the transformations, and check out some
3614 of the simpler ones to get an idea of how they work. Try to find a
3615 similar transformation to the one you want to add and copy off of it.
3616 More details can be found in the comments inside the code itself.
3617 Configuring for 16 bit platforms
3620 You will want to look into zconf.h to tell zlib (and thus libpng) that
3621 it cannot allocate more then 64K at a time. Even if you can, the mem‐
3622 ory won't be accessible. So limit zlib and libpng to 64K by defining
3623 MAXSEG_64K.
3624 Configuring for DOS
3627 For DOS users who only have access to the lower 640K, you will have to
3628 limit zlib's memory usage via a png_set_compression_mem_level() call.
3629 See zlib.h or zconf.h in the zlib library for more information.
3630 Configuring for Medium Model
3633 Libpng's support for medium model has been tested on most of the popu‐
3634 lar compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
3635 defined, and FAR gets defined to far in pngconf.h, and you should be
3636 all set. Everything in the library (except for zlib's structure) is
3637 expecting far data. You must use the typedefs with the p or pp on the
3638 end for pointers (or at least look at them and be careful). Make note
3639 that the rows of data are defined as png_bytepp, which is an unsigned
3640 char far * far *.
3641 Configuring for gui/windowing platforms:
3644 You will need to write new error and warning functions that use the GUI
3645 interface, as described previously, and set them to be the error and
3646 warning functions at the time that png_create_*_struct() is called, in
3647 order to have them available during the structure initialization. They
3648 can be changed later via png_set_error_fn(). On some compilers, you
3649 may also have to change the memory allocators (png_malloc, etc.).
3650 Configuring for compiler xxx:
3653 All includes for libpng are in pngconf.h. If you need to add, change
3654 or delete an include, this is the place to do it. The includes that
3655 are not needed outside libpng are protected by the PNG_INTERNAL defini‐
3656 tion, which is only defined for those routines inside libpng itself.
3657 The files in libpng proper only include png.h, which includes png‐
3658 conf.h.
3659 Configuring zlib:
3662 There are special functions to configure the compression. Perhaps the
3663 most useful one changes the compression level, which currently uses
3664 input compression values in the range 0 - 9. The library normally uses
3665 the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests have
3666 shown that for a large majority of images, compression values in the
3667 range 3-6 compress nearly as well as higher levels, and do so much
3668 faster. For online applications it may be desirable to have maximum
3669 speed (Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can
3670 also specify no compression (Z_NO_COMPRESSION = 0), but this would cre‐
3671 ate files larger than just storing the raw bitmap. You can specify the
3672 compression level by calling:
3673 png_set_compression_level(png_ptr, level);
3675 Another useful one is to reduce the memory level used by the library.
3677 The memory level defaults to 8, but it can be lowered if you are short
3678 on memory (running DOS, for example, where you only have 640K). Note
3679 that the memory level does have an effect on compression; among other
3680 things, lower levels will result in sections of incompressible data
3681 being emitted in smaller stored blocks, with a correspondingly larger
3682 relative overhead of up to 15% in the worst case.
3683 png_set_compression_mem_level(png_ptr, level);
3685 The other functions are for configuring zlib. They are not recommended
3687 for normal use and may result in writing an invalid PNG file. See
3688 zlib.h for more information on what these mean.
3689 png_set_compression_strategy(png_ptr,
3691 strategy);
3692 png_set_compression_window_bits(png_ptr,
3693 window_bits);
3694 png_set_compression_method(png_ptr, method);
3695 png_set_compression_buffer_size(png_ptr, size);
3696 Controlling row filtering
3699 If you want to control whether libpng uses filtering or not, which fil‐
3700 ters are used, and how it goes about picking row filters, you can call
3701 one of these functions. The selection and configuration of row filters
3702 can have a significant impact on the size and encoding speed and a
3703 somewhat lesser impact on the decoding speed of an image. Filtering is
3704 enabled by default for RGB and grayscale images (with and without
3705 alpha), but not for paletted images nor for any images with bit depths
3706 less than 8 bits/pixel.
3707 The 'method' parameter sets the main filtering method, which is cur‐
3709 rently only '0' in the PNG 1.2 specification. The 'filters' parameter
3710 sets which filter(s), if any, should be used for each scanline. Possi‐
3711 ble values are PNG_ALL_FILTERS and PNG_NO_FILTERS to turn filtering on
3712 and off, respectively.
3713 Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB, PNG_FIL‐
3715 TER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise ORed
3716 together with '|' to specify one or more filters to use. These filters
3717 are described in more detail in the PNG specification. If you intend
3718 to change the filter type during the course of writing the image, you
3719 should start with flags set for all of the filters you intend to use so
3720 that libpng can initialize its internal structures appropriately for
3721 all of the filter types. (Note that this means the first row must
3722 always be adaptively filtered, because libpng currently does not allo‐
3723 cate the filter buffers until png_write_row() is called for the first
3724 time.)
3725 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
3727 PNG_FILTER_UP | PNG_FILTER_AVG |
3728 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
3729 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
3731 filters);
3732 The second parameter can also be
3733 PNG_INTRAPIXEL_DIFFERENCING if you are
3734 writing a PNG to be embedded in a MNG
3735 datastream. This parameter must be the
3736 same as the value of filter_method used
3737 in png_set_IHDR().
3738 It is also possible to influence how libpng chooses from among the
3740 available filters. This is done in one or both of two ways - by
3741 telling it how important it is to keep the same filter for successive
3742 rows, and by telling it the relative computational costs of the fil‐
3743 ters.
3744 double weights[3] = {1.5, 1.3, 1.1},
3746 costs[PNG_FILTER_VALUE_LAST] =
3747 {1.0, 1.3, 1.3, 1.5, 1.7};
3748 png_set_filter_heuristics(png_ptr,
3750 PNG_FILTER_HEURISTIC_WEIGHTED, 3,
3751 weights, costs);
3752 The weights are multiplying factors that indicate to libpng that the
3754 row filter should be the same for successive rows unless another row
3755 filter is that many times better than the previous filter. In the
3756 above example, if the previous 3 filters were SUB, SUB, NONE, the SUB
3757 filter could have a "sum of absolute differences" 1.5 x 1.3 times
3758 higher than other filters and still be chosen, while the NONE filter
3759 could have a sum 1.1 times higher than other filters and still be cho‐
3760 sen. Unspecified weights are taken to be 1.0, and the specified
3761 weights should probably be declining like those above in order to
3762 emphasize recent filters over older filters.
3763 The filter costs specify for each filter type a relative decoding cost
3765 to be considered when selecting row filters. This means that filters
3766 with higher costs are less likely to be chosen over filters with lower
3767 costs, unless their "sum of absolute differences" is that much smaller.
3768 The costs do not necessarily reflect the exact computational speeds of
3769 the various filters, since this would unduly influence the final image
3770 size.
3771 Note that the numbers above were invented purely for this example and
3773 are given only to help explain the function usage. Little testing has
3774 been done to find optimum values for either the costs or the weights.
3775 Removing unwanted object code
3778 There are a bunch of #define's in pngconf.h that control what parts of
3779 libpng are compiled. All the defines end in _SUPPORTED. If you are
3780 never going to use a capability, you can change the #define to #undef
3781 before recompiling libpng and save yourself code and data space, or you
3782 can turn off individual capabilities with defines that begin with
3783 PNG_NO_.
3784 You can also turn all of the transforms and ancillary chunk capabili‐
3786 ties off en masse with compiler directives that define PNG_NO_READ[or
3787 WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, or all
3788 four, along with directives to turn on any of the capabilities that you
3789 do want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the
3790 extra transformations but still leave the library fully capable of
3791 reading and writing PNG files with all known public chunks. Use of the
3792 PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
3793 that is incapable of reading or writing ancillary chunks. If you are
3794 not using the progressive reading capability, you can turn that off
3795 with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
3796 capability, which you'll still have).
3797 All the reading and writing specific code are in separate files, so the
3799 linker should only grab the files it needs. However, if you want to
3800 make sure, or if you are building a stand alone library, all the read‐
3801 ing files start with pngr and all the writing files start with pngw.
3802 The files that don't match either (like png.c, pngtrans.c, etc.) are
3803 used for both reading and writing, and always need to be included. The
3804 progressive reader is in pngpread.c
3805 If you are creating or distributing a dynamically linked library (a .so
3807 or DLL file), you should not remove or disable any parts of the
3808 library, as this will cause applications linked with different versions
3809 of the library to fail if they call functions not available in your
3810 library. The size of the library itself should not be an issue,
3811 because only those sections that are actually used will be loaded into
3812 memory.
3813 Requesting debug printout
3816 The macro definition PNG_DEBUG can be used to request debugging print‐
3817 out. Set it to an integer value in the range 0 to 3. Higher numbers
3818 result in increasing amounts of debugging information. The information
3819 is printed to the "stderr" file, unless another file name is specified
3820 in the PNG_DEBUG_FILE macro definition.
3821 When PNG_DEBUG > 0, the following functions (macros) become available:
3823 png_debug(level, message)
3825 png_debug1(level, message, p1)
3826 png_debug2(level, message, p1, p2)
3827 in which "level" is compared to PNG_DEBUG to decide whether to print
3829 the message, "message" is the formatted string to be printed, and p1
3830 and p2 are parameters that are to be embedded in the string according
3831 to printf-style formatting directives. For example,
3832 png_debug1(2, "foo=%d0, foo);
3834 is expanded to
3836 if(PNG_DEBUG > 2)
3838 fprintf(PNG_DEBUG_FILE, "foo=%d0, foo);
3839 When PNG_DEBUG is defined but is zero, the macros aren't defined, but
3841 you can still use PNG_DEBUG to control your own debugging:
3842 #ifdef PNG_DEBUG
3844 fprintf(stderr, ...
3845 #endif
3846 When PNG_DEBUG = 1, the macros are defined, but only png_debug state‐
3848 ments having level = 0 will be printed. There aren't any such state‐
3849 ments in this version of libpng, but if you insert some they will be
3850 printed.
3851
3854 The MNG specification (available at http://www.libpng.org/pub/mng)
3855 allows certain extensions to PNG for PNG images that are embedded in
3856 MNG datastreams. Libpng can support some of these extensions. To
3857 enable them, use the png_permit_mng_features() function:
3858 feature_set = png_permit_mng_features(png_ptr, mask)
3860 mask is a png_uint_32 containing the bitwise OR of the
3861 features you want to enable. These include
3862 PNG_FLAG_MNG_EMPTY_PLTE
3863 PNG_FLAG_MNG_FILTER_64
3864 PNG_ALL_MNG_FEATURES
3865 feature_set is a png_uint_32 that is the bitwise AND of
3866 your mask with the set of MNG features that is
3867 supported by the version of libpng that you are using.
3868 It is an error to use this function when reading or writing a stand‐
3870 alone PNG file with the PNG 8-byte signature. The PNG datastream must
3871 be wrapped in a MNG datastream. As a minimum, it must have the MNG
3872 8-byte signature and the MHDR and MEND chunks. Libpng does not provide
3873 support for these or any other MNG chunks; your application must pro‐
3874 vide its own support for them. You may wish to consider using libmng
3875 (available at http://www.libmng.com) instead.
3876
3879 It should be noted that versions of libpng later than 0.96 are not dis‐
3880 tributed by the original libpng author, Guy Schalnat, nor by Andreas
3881 Dilger, who had taken over from Guy during 1996 and 1997, and distrib‐
3882 uted versions 0.89 through 0.96, but rather by another member of the
3883 original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are still
3884 alive and well, but they have moved on to other things.
3885 The old libpng functions png_read_init(), png_write_init(),
3887 png_info_init(), png_read_destroy(), and png_write_destroy() have been
3888 moved to PNG_INTERNAL in version 0.95 to discourage their use. These
3889 functions will be removed from libpng version 2.0.0.
3890 The preferred method of creating and initializing the libpng structures
3892 is via the png_create_read_struct(), png_create_write_struct(), and
3893 png_create_info_struct() because they isolate the size of the struc‐
3894 tures from the application, allow version error checking, and also
3895 allow the use of custom error handling routines during the initializa‐
3896 tion, which the old functions do not. The functions png_read_destroy()
3897 and png_write_destroy() do not actually free the memory that libpng
3898 allocated for these structs, but just reset the data structures, so
3899 they can be used instead of png_destroy_read_struct() and
3900 png_destroy_write_struct() if you feel there is too much system over‐
3901 head allocating and freeing the png_struct for each image read.
3902 Setting the error callbacks via png_set_message_fn() before
3904 png_read_init() as was suggested in libpng-0.88 is no longer supported
3905 because this caused applications that do not use custom error functions
3906 to fail if the png_ptr was not initialized to zero. It is still possi‐
3907 ble to set the error callbacks AFTER png_read_init(), or to change them
3908 with png_set_error_fn(), which is essentially the same function, but
3909 with a new name to force compilation errors with applications that try
3910 to use the old method.
3911 Starting with version 1.0.7, you can find out which version of the
3913 library you are using at run-time:
3914 png_uint_32 libpng_vn = png_access_version_number();
3916 The number libpng_vn is constructed from the major version, minor ver‐
3918 sion with leading zero, and release number with leading zero, (e.g.,
3919 libpng_vn for version 1.0.7 is 10007).
3920 You can also check which version of png.h you used when compiling your
3922 application:
3923 png_uint_32 application_vn = PNG_LIBPNG_VER;
3925
3928 Support for user memory management was enabled by default. To accom‐
3929 plish this, the functions png_create_read_struct_2(), png_cre‐
3930 ate_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(), png_mal‐
3931 loc_default(), and png_free_default() were added.
3932 Support for the iTXt chunk has been enabled by default as of version
3934 1.2.41.
3935 Support for certain MNG features was enabled.
3937 Support for numbered error messages was added. However, we never got
3939 around to actually numbering the error messages. The function
3940 png_set_strip_error_numbers() was added (Note: the prototype for this
3941 function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
3942 builds of libpng-1.2.15. It was restored in libpng-1.2.36).
3943 The png_malloc_warn() function was added at libpng-1.2.3. This issues
3945 a png_warning and returns NULL instead of aborting when it fails to
3946 acquire the requested memory allocation.
3947 Support for setting user limits on image width and height was enabled
3949 by default. The functions png_set_user_limits(),
3950 png_get_user_width_max(), and png_get_user_height_max() were added at
3951 libpng-1.2.6.
3952 The png_set_add_alpha() function was added at libpng-1.2.7.
3954 The function png_set_expand_gray_1_2_4_to_8() was added at
3956 libpng-1.2.9. Unlike png_set_gray_1_2_4_to_8(), the new function does
3957 not expand the tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() func‐
3958 tion is deprecated.
3959 A number of macro definitions in support of runtime selection of assem‐
3961 bler code features (especially Intel MMX code support) were added at
3962 libpng-1.2.0:
3963 PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
3965 PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
3966 PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
3967 PNG_ASM_FLAG_MMX_READ_INTERLACE
3968 PNG_ASM_FLAG_MMX_READ_FILTER_SUB
3969 PNG_ASM_FLAG_MMX_READ_FILTER_UP
3970 PNG_ASM_FLAG_MMX_READ_FILTER_AVG
3971 PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
3972 PNG_ASM_FLAGS_INITIALIZED
3973 PNG_MMX_READ_FLAGS
3974 PNG_MMX_FLAGS
3975 PNG_MMX_WRITE_FLAGS
3976 PNG_MMX_FLAGS
3977 We added the following functions in support of runtime selection of
3979 assembler code features:
3980 png_get_mmx_flagmask()
3982 png_set_mmx_thresholds()
3983 png_get_asm_flags()
3984 png_get_mmx_bitdepth_threshold()
3985 png_get_mmx_rowbytes_threshold()
3986 png_set_asm_flags()
3987 We replaced all of these functions with simple stubs in libpng-1.2.20,
3989 when the Intel assembler code was removed due to a licensing issue.
3990 These macros are deprecated:
3992 PNG_READ_TRANSFORMS_NOT_SUPPORTED
3994 PNG_PROGRESSIVE_READ_NOT_SUPPORTED
3995 PNG_NO_SEQUENTIAL_READ_SUPPORTED
3996 PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
3997 PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
3998 PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
3999 They have been replaced, respectively, by:
4001 PNG_NO_READ_TRANSFORMS
4003 PNG_NO_PROGRESSIVE_READ
4004 PNG_NO_SEQUENTIAL_READ
4005 PNG_NO_WRITE_TRANSFORMS
4006 PNG_NO_READ_ANCILLARY_CHUNKS
4007 PNG_NO_WRITE_ANCILLARY_CHUNKS
4008 PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been deprecated
4010 since libpng-1.0.16 and libpng-1.2.6.
4011 The function
4013 png_check_sig(sig, num) was replaced with
4014 !png_sig_cmp(sig, 0, num) It has been deprecated since libpng-0.90.
4015 The function
4017 png_set_gray_1_2_4_to_8() which also expands tRNS to alpha was
4018 replaced with
4019 png_set_expand_gray_1_2_4_to_8() which does not. It has been depre‐
4020 cated since libpng-1.0.18 and 1.2.9.
4021
4025 The png_get_io_ptr() function has been present since libpng-0.88, has
4026 never changed, and is unaffected by conditional compilation macros. It
4027 is the best choice for use in configure scripts for detecting the pres‐
4028 ence of any libpng version since 0.88. In an autoconf "configure.in"
4029 you could use
4030 AC_CHECK_LIB(png, png_get_io_ptr, ...
4032
4035 Since about February 2009, version 1.2.34, libpng has been under "git"
4036 source control. The git repository was built from old libpng-
4037 x.y.z.tar.gz files going back to version 0.70. You can access the git
4038 repository (read only) at
4039 git://libpng.git.sourceforge.net/gitroot/libpng
4041 or you can browse it via "gitweb" at
4043 http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
4045 Patches can be sent to glennrp at users.sourceforge.net or to png-mng-
4047 implement at lists.sourceforge.net or you can upload them to the libpng
4048 bug tracker at
4049 http://libpng.sourceforge.net
4051
4054 Our coding style is similar to the "Allman" style, with curly braces on
4055 separate lines:
4056 if (condition)
4058 {
4059 action;
4060 }
4061 else if (another condition)
4063 {
4064 another action;
4065 }
4066 The braces can be omitted from simple one-line actions:
4068 if (condition)
4070 return (0);
4071 We use 3-space indentation, except for continued statements which are
4073 usually indented the same as the first line of the statement plus four
4074 more spaces.
4075 For macro definitions we use 2-space indentation, always leaving the
4077 "#" in the first column.
4078 #ifndef PNG_NO_FEATURE
4080 # ifndef PNG_FEATURE_SUPPORTED
4081 # define PNG_FEATURE_SUPPORTED
4082 # endif
4083 #endif
4084 Comments appear with the leading "/*" at the same indentation as the
4086 statement that follows the comment:
4087 /* Single-line comment */
4089 statement;
4090 /* Multiple-line
4092 * comment
4093 */
4094 statement;
4095 Very short comments can be placed at the end of the statement to which
4097 they pertain:
4098 statement; /* comment */
4100 We don't use C++ style ("//") comments. We have, however, used them in
4102 the past in some now-abandoned MMX assembler code.
4103 Functions and their curly braces are not indented, and exported func‐
4105 tions are marked with PNGAPI:
4106 /* This is a public function that is visible to
4108 * application programers. It does thus-and-so.
4109 */
4110 void PNGAPI
4111 png_exported_function(png_ptr, png_info, foo)
4112 {
4113 body;
4114 }
4115 The prototypes for all exported functions appear in png.h, above the
4117 comment that says
4118 /* Maintainer: Put new public prototypes here ... */
4120 We mark all non-exported functions with "/* PRIVATE */"":
4122 void /* PRIVATE */
4124 png_non_exported_function(png_ptr, png_info, foo)
4125 {
4126 body;
4127 }
4128 The prototypes for non-exported functions (except for those in pngtest)
4130 appear in the PNG_INTERNAL section of png.h above the comment that says
4131 /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
4133 The names of all exported functions and variables begin with "png_",
4135 and all publicly visible C preprocessor macros begin with "PNG_".
4136 We put a space after each comma and after each semicolon in "for" stat‐
4138 ments, and we put spaces before and after each C binary operator and
4139 after "for" or "while". We don't put a space between a typecast and
4140 the expression being cast, nor do we put one between a function name
4141 and the left parenthesis that follows it:
4142 for (i = 2; i > 0; --i)
4144 y[i] = a(x) + (int)b;
4145 We prefer #ifdef and #ifndef to #if defined() and if !defined() when
4147 there is only one macro being tested.
4148 We do not use the TAB character for indentation in the C sources.
4150 Lines do not exceed 80 characters.
4152 Other rules can be inferred by inspecting the libpng source.
4154
4157 July 9, 2011
4158 Since the PNG Development group is an ad-hoc body, we can't make an
4160 official declaration.
4161 This is your unofficial assurance that libpng from version 0.71 and
4163 upward through 1.2.46 are Y2K compliant. It is my belief that earlier
4164 versions were also Y2K compliant.
4165 Libpng only has three year fields. One is a 2-byte unsigned integer
4167 that will hold years up to 65535. The other two hold the date in text
4168 format, and will hold years up to 9999.
4169 The integer is
4171 "png_uint_16 year" in png_time_struct.
4172 The strings are
4174 "png_charp time_buffer" in png_struct and
4175 "near_time_buffer", which is a local character string in png.c.
4176 There are seven time-related functions:
4178 png_convert_to_rfc_1123() in png.c
4180 (formerly png_convert_to_rfc_1152() in error)
4181 png_convert_from_struct_tm() in pngwrite.c, called
4182 in pngwrite.c
4183 png_convert_from_time_t() in pngwrite.c
4184 png_get_tIME() in pngget.c
4185 png_handle_tIME() in pngrutil.c, called in pngread.c
4186 png_set_tIME() in pngset.c
4187 png_write_tIME() in pngwutil.c, called in pngwrite.c
4188 All appear to handle dates properly in a Y2K environment. The png_con‐
4190 vert_from_time_t() function calls gmtime() to convert from system clock
4191 time, which returns (year - 1900), which we properly convert to the
4192 full 4-digit year. There is a possibility that applications using
4193 libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
4194 function, or that they are incorrectly passing only a 2-digit year
4195 instead of "year - 1900" into the png_convert_from_struct_tm() func‐
4196 tion, but this is not under our control. The libpng documentation has
4197 always stated that it works with 4-digit years, and the APIs have been
4198 documented as such.
4199 The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
4201 integer to hold the year, and can hold years as large as 65535.
4202 zlib, upon which libpng depends, is also Y2K compliant. It contains no
4204 date-related code.
4205 Glenn Randers-Pehrson
4208 libpng maintainer
4209 PNG Development Group
4210
4213 Note about libpng version numbers:
4214 Due to various miscommunications, unforeseen code incompatibilities and
4216 occasional factors outside the authors' control, version numbering on
4217 the library has not always been consistent and straightforward. The
4218 following table summarizes matters since version 0.89c, which was the
4219 first widely used release:
4220 source png.h png.h shared-lib
4222 version string int version
4223 ------- ------ ----- ----------
4224 0.89c ("beta 3") 0.89 89 1.0.89
4225 0.90 ("beta 4") 0.90 90 0.90
4226 0.95 ("beta 5") 0.95 95 0.95
4227 0.96 ("beta 6") 0.96 96 0.96
4228 0.97b ("beta 7") 1.00.97 97 1.0.1
4229 0.97c 0.97 97 2.0.97
4230 0.98 0.98 98 2.0.98
4231 0.99 0.99 98 2.0.99
4232 0.99a-m 0.99 99 2.0.99
4233 1.00 1.00 100 2.1.0
4234 1.0.0 1.0.0 100 2.1.0
4235 1.0.0 (from here on, the 100 2.1.0
4236 1.0.1 png.h string is 10001 2.1.0
4237 1.0.1a-e identical to the 10002 from here on, the
4238 1.0.2 source version) 10002 shared library is 2.V
4239 1.0.2a-b 10003 where V is the source
4240 1.0.1 10001 code version except as
4241 1.0.1a-e 10002 2.1.0.1a-e noted.
4242 1.0.2 10002 2.1.0.2
4243 1.0.2a-b 10003 2.1.0.2a-b
4244 1.0.3 10003 2.1.0.3
4245 1.0.3a-d 10004 2.1.0.3a-d
4246 1.0.4 10004 2.1.0.4
4247 1.0.4a-f 10005 2.1.0.4a-f
4248 1.0.5 (+ 2 patches) 10005 2.1.0.5
4249 1.0.5a-d 10006 2.1.0.5a-d
4250 1.0.5e-r 10100 2.1.0.5e-r
4251 1.0.5s-v 10006 2.1.0.5s-v
4252 1.0.6 (+ 3 patches) 10006 2.1.0.6
4253 1.0.6d-g 10007 2.1.0.6d-g
4254 1.0.6h 10007 10.6h
4255 1.0.6i 10007 10.6i
4256 1.0.6j 10007 2.1.0.6j
4257 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14
4258 1.0.7beta15-18 1 10007 2.1.0.7beta15-18
4259 1.0.7rc1-2 1 10007 2.1.0.7rc1-2
4260 1.0.7 1 10007 2.1.0.7
4261 1.0.8beta1-4 1 10008 2.1.0.8beta1-4
4262 1.0.8rc1 1 10008 2.1.0.8rc1
4263 1.0.8 1 10008 2.1.0.8
4264 1.0.9beta1-6 1 10009 2.1.0.9beta1-6
4265 1.0.9rc1 1 10009 2.1.0.9rc1
4266 1.0.9beta7-10 1 10009 2.1.0.9beta7-10
4267 1.0.9rc2 1 10009 2.1.0.9rc2
4268 1.0.9 1 10009 2.1.0.9
4269 1.0.10beta1 1 10010 2.1.0.10beta1
4270 1.0.10rc1 1 10010 2.1.0.10rc1
4271 1.0.10 1 10010 2.1.0.10
4272 1.0.11beta1-3 1 10011 2.1.0.11beta1-3
4273 1.0.11rc1 1 10011 2.1.0.11rc1
4274 1.0.11 1 10011 2.1.0.11
4275 1.0.12beta1-2 2 10012 2.1.0.12beta1-2
4276 1.0.12rc1 2 10012 2.1.0.12rc1
4277 1.0.12 2 10012 2.1.0.12
4278 1.1.0a-f - 10100 2.1.1.0a-f abandoned
4279 1.2.0beta1-2 2 10200 2.1.2.0beta1-2
4280 1.2.0beta3-5 3 10200 3.1.2.0beta3-5
4281 1.2.0rc1 3 10200 3.1.2.0rc1
4282 1.2.0 3 10200 3.1.2.0
4283 1.2.1beta-4 3 10201 3.1.2.1beta1-4
4284 1.2.1rc1-2 3 10201 3.1.2.1rc1-2
4285 1.2.1 3 10201 3.1.2.1
4286 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6
4287 1.0.13beta1 10 10013 10.so.0.1.0.13beta1
4288 1.0.13rc1 10 10013 10.so.0.1.0.13rc1
4289 1.2.2rc1 12 10202 12.so.0.1.2.2rc1
4290 1.0.13 10 10013 10.so.0.1.0.13
4291 1.2.2 12 10202 12.so.0.1.2.2
4292 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6
4293 1.2.3 12 10203 12.so.0.1.2.3
4294 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3
4295 1.2.4rc1 13 10204 12.so.0.1.2.4rc1
4296 1.0.14 10 10014 10.so.0.1.0.14
4297 1.2.4 13 10204 12.so.0.1.2.4
4298 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2
4299 1.0.15rc1 10 10015 10.so.0.1.0.15rc1
4300 1.0.15 10 10015 10.so.0.1.0.15
4301 1.2.5 13 10205 12.so.0.1.2.5
4302 1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4
4303 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5
4304 1.0.16 10 10016 10.so.0.1.0.16
4305 1.2.6 13 10206 12.so.0.1.2.6
4306 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2
4307 1.0.17rc1 10 10017 10.so.0.1.0.17rc1
4308 1.2.7rc1 13 10207 12.so.0.1.2.7rc1
4309 1.0.17 10 10017 10.so.0.1.0.17
4310 1.2.7 13 10207 12.so.0.1.2.7
4311 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5
4312 1.0.18rc1-5 10 10018 10.so.0.1.0.18rc1-5
4313 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5
4314 1.0.18 10 10018 10.so.0.1.0.18
4315 1.2.8 13 10208 12.so.0.1.2.8
4316 1.2.9beta1-3 13 10209 12.so.0.1.2.9beta1-3
4317 1.2.9beta4-11 13 10209 12.so.0.9[.0]
4318 1.2.9rc1 13 10209 12.so.0.9[.0]
4319 1.2.9 13 10209 12.so.0.9[.0]
4320 1.2.10beta1-8 13 10210 12.so.0.10[.0]
4321 1.2.10rc1-3 13 10210 12.so.0.10[.0]
4322 1.2.10 13 10210 12.so.0.10[.0]
4323 1.2.11beta1-4 13 10211 12.so.0.11[.0]
4324 1.0.19rc1-5 10 10019 10.so.0.19[.0]
4325 1.2.11rc1-5 13 10211 12.so.0.11[.0]
4326 1.0.19 10 10019 10.so.0.19[.0]
4327 1.2.11 13 10211 12.so.0.11[.0]
4328 1.0.20 10 10020 10.so.0.20[.0]
4329 1.2.12 13 10212 12.so.0.12[.0]
4330 1.2.13beta1 13 10213 12.so.0.13[.0]
4331 1.0.21 10 10021 10.so.0.21[.0]
4332 1.2.13 13 10213 12.so.0.13[.0]
4333 1.2.14beta1-2 13 10214 12.so.0.14[.0]
4334 1.0.22rc1 10 10022 10.so.0.22[.0]
4335 1.2.14rc1 13 10214 12.so.0.14[.0]
4336 1.2.15beta1-6 13 10215 12.so.0.15[.0]
4337 1.0.23rc1-5 10 10023 10.so.0.23[.0]
4338 1.2.15rc1-5 13 10215 12.so.0.15[.0]
4339 1.0.23 10 10023 10.so.0.23[.0]
4340 1.2.15 13 10215 12.so.0.15[.0]
4341 1.2.16beta1-2 13 10216 12.so.0.16[.0]
4342 1.2.16rc1 13 10216 12.so.0.16[.0]
4343 1.0.24 10 10024 10.so.0.24[.0]
4344 1.2.16 13 10216 12.so.0.16[.0]
4345 1.2.17beta1-2 13 10217 12.so.0.17[.0]
4346 1.0.25rc1 10 10025 10.so.0.25[.0]
4347 1.2.17rc1-3 13 10217 12.so.0.17[.0]
4348 1.0.25 10 10025 10.so.0.25[.0]
4349 1.2.17 13 10217 12.so.0.17[.0]
4350 1.0.26 10 10026 10.so.0.26[.0]
4351 1.2.18 13 10218 12.so.0.18[.0]
4352 1.2.19beta1-31 13 10219 12.so.0.19[.0]
4353 1.0.27rc1-6 10 10027 10.so.0.27[.0]
4354 1.2.19rc1-6 13 10219 12.so.0.19[.0]
4355 1.0.27 10 10027 10.so.0.27[.0]
4356 1.2.19 13 10219 12.so.0.19[.0]
4357 1.2.20beta01-04 13 10220 12.so.0.20[.0]
4358 1.0.28rc1-6 10 10028 10.so.0.28[.0]
4359 1.2.20rc1-6 13 10220 12.so.0.20[.0]
4360 1.0.28 10 10028 10.so.0.28[.0]
4361 1.2.20 13 10220 12.so.0.20[.0]
4362 1.2.21beta1-2 13 10221 12.so.0.21[.0]
4363 1.2.21rc1-3 13 10221 12.so.0.21[.0]
4364 1.0.29 10 10029 10.so.0.29[.0]
4365 1.2.21 13 10221 12.so.0.21[.0]
4366 1.2.22beta1-4 13 10222 12.so.0.22[.0]
4367 1.0.30rc1 13 10030 10.so.0.30[.0]
4368 1.2.22rc1 13 10222 12.so.0.22[.0]
4369 1.0.30 10 10030 10.so.0.30[.0]
4370 1.2.22 13 10222 12.so.0.22[.0]
4371 1.2.23beta01-05 13 10223 12.so.0.23[.0]
4372 1.2.23rc01 13 10223 12.so.0.23[.0]
4373 1.2.23 13 10223 12.so.0.23[.0]
4374 1.2.24beta01-02 13 10224 12.so.0.24[.0]
4375 1.2.24rc01 13 10224 12.so.0.24[.0]
4376 1.2.24 13 10224 12.so.0.24[.0]
4377 1.2.25beta01-06 13 10225 12.so.0.25[.0]
4378 1.2.25rc01-02 13 10225 12.so.0.25[.0]
4379 1.0.31 10 10031 10.so.0.31[.0]
4380 1.2.25 13 10225 12.so.0.25[.0]
4381 1.2.26beta01-06 13 10226 12.so.0.26[.0]
4382 1.2.26rc01 13 10226 12.so.0.26[.0]
4383 1.2.26 13 10226 12.so.0.26[.0]
4384 1.0.32 10 10032 10.so.0.32[.0]
4385 1.2.27beta01-06 13 10227 12.so.0.27[.0]
4386 1.2.27rc01 13 10227 12.so.0.27[.0]
4387 1.0.33 10 10033 10.so.0.33[.0]
4388 1.2.27 13 10227 12.so.0.27[.0]
4389 1.0.34 10 10034 10.so.0.34[.0]
4390 1.2.28 13 10228 12.so.0.28[.0]
4391 1.2.29beta01-03 13 10229 12.so.0.29[.0]
4392 1.2.29rc01 13 10229 12.so.0.29[.0]
4393 1.0.35 10 10035 10.so.0.35[.0]
4394 1.2.29 13 10229 12.so.0.29[.0]
4395 1.0.37 10 10037 10.so.0.37[.0]
4396 1.2.30beta01-04 13 10230 12.so.0.30[.0]
4397 1.0.38rc01-08 10 10038 10.so.0.38[.0]
4398 1.2.30rc01-08 13 10230 12.so.0.30[.0]
4399 1.0.38 10 10038 10.so.0.38[.0]
4400 1.2.30 13 10230 12.so.0.30[.0]
4401 1.0.39rc01-03 10 10039 10.so.0.39[.0]
4402 1.2.31rc01-03 13 10231 12.so.0.31[.0]
4403 1.0.39 10 10039 10.so.0.39[.0]
4404 1.2.31 13 10231 12.so.0.31[.0]
4405 1.2.32beta01-02 13 10232 12.so.0.32[.0]
4406 1.0.40rc01 10 10040 10.so.0.40[.0]
4407 1.2.32rc01 13 10232 12.so.0.32[.0]
4408 1.0.40 10 10040 10.so.0.40[.0]
4409 1.2.32 13 10232 12.so.0.32[.0]
4410 1.2.33beta01-02 13 10233 12.so.0.33[.0]
4411 1.2.33rc01-02 13 10233 12.so.0.33[.0]
4412 1.0.41rc01 10 10041 10.so.0.41[.0]
4413 1.2.33 13 10233 12.so.0.33[.0]
4414 1.0.41 10 10041 10.so.0.41[.0]
4415 1.2.34beta01-07 13 10234 12.so.0.34[.0]
4416 1.0.42rc01 10 10042 10.so.0.42[.0]
4417 1.2.34rc01 13 10234 12.so.0.34[.0]
4418 1.0.42 10 10042 10.so.0.42[.0]
4419 1.2.34 13 10234 12.so.0.34[.0]
4420 1.2.35beta01-03 13 10235 12.so.0.35[.0]
4421 1.0.43rc01-02 10 10043 10.so.0.43[.0]
4422 1.2.35rc01-02 13 10235 12.so.0.35[.0]
4423 1.0.43 10 10043 10.so.0.43[.0]
4424 1.2.35 13 10235 12.so.0.35[.0]
4425 1.2.36beta01-05 13 10236 12.so.0.36[.0]
4426 1.2.36rc01 13 10236 12.so.0.36[.0]
4427 1.0.44 10 10044 10.so.0.44[.0]
4428 1.2.36 13 10236 12.so.0.36[.0]
4429 1.2.37beta01-03 13 10237 12.so.0.37[.0]
4430 1.2.37rc01 13 10237 12.so.0.37[.0]
4431 1.2.37 13 10237 12.so.0.37[.0]
4432 1.0.45 10 10045 12.so.0.45[.0]
4433 1.0.46 10 10046 10.so.0.46[.0]
4434 1.2.38beta01 13 10238 12.so.0.38[.0]
4435 1.2.38rc01-03 13 10238 12.so.0.38[.0]
4436 1.0.47 10 10047 10.so.0.47[.0]
4437 1.2.38 13 10238 12.so.0.38[.0]
4438 1.2.39beta01-05 13 10239 12.so.0.39[.0]
4439 1.2.39rc01 13 10239 12.so.0.39[.0]
4440 1.0.48 10 10048 10.so.0.48[.0]
4441 1.2.39 13 10239 12.so.0.39[.0]
4442 1.2.40beta01 13 10240 12.so.0.40[.0]
4443 1.2.40rc01 13 10240 12.so.0.40[.0]
4444 1.0.49 10 10049 10.so.0.49[.0]
4445 1.2.40 13 10240 12.so.0.40[.0]
4446 1.0.50 10 10050 10.so.0.50[.0]
4447 1.2.41beta01-18 13 10241 12.so.0.41[.0]
4448 1.0.51rc01 10 10051 10.so.0.51[.0]
4449 1.2.41rc01-03 13 10241 12.so.0.41[.0]
4450 1.0.51 10 10051 10.so.0.51[.0]
4451 1.2.41 13 10241 12.so.0.41[.0]
4452 1.2.42beta01-02 13 10242 12.so.0.42[.0]
4453 1.2.42rc01-05 13 10242 12.so.0.42[.0]
4454 1.0.52 10 10052 10.so.0.52[.0]
4455 1.2.42 13 10242 12.so.0.42[.0]
4456 1.2.43beta01-05 13 10243 12.so.0.43[.0]
4457 1.0.53rc01-02 10 10053 10.so.0.53[.0]
4458 1.2.43rc01-02 13 10243 12.so.0.43[.0]
4459 1.0.53 10 10053 10.so.0.53[.0]
4460 1.2.43 13 10243 12.so.0.43[.0]
4461 1.2.44beta01-03 13 10244 12.so.0.44[.0]
4462 1.2.44rc01-03 13 10244 12.so.0.44[.0]
4463 1.2.44 13 10244 12.so.0.44[.0]
4464 1.2.45beta01-03 13 10245 12.so.0.45[.0]
4465 1.0.55rc01 10 10055 10.so.0.55[.0]
4466 1.2.45rc01 13 10245 12.so.0.45[.0]
4467 1.0.55 10 10055 10.so.0.55[.0]
4468 1.2.45 13 10245 12.so.0.45[.0]
4469 1.2.46rc01-02 13 10246 12.so.0.46[.0]
4470 1.0.56 10 10056 10.so.0.56[.0]
4471 1.2.46 13 10246 12.so.0.46[.0]
4472 Henceforth the source version will match the shared-library minor and
4474 patch numbers; the shared-library major version number will be used for
4475 changes in backward compatibility, as it is intended. The
4476 PNG_PNGLIB_VER macro, which is not used within libpng but is available
4477 for applications, is an unsigned integer of the form xyyzz correspond‐
4478 ing to the source version x.y.z (leading zeros in y and z). Beta ver‐
4479 sions were given the previous public release number plus a letter,
4480 until version 1.0.6j; from then on they were given the upcoming public
4481 release number plus "betaNN" or "rcN".
4482
4485 libpngpf(3), png(5)
4486 libpng:
4488 http://libpng.sourceforge.net (follow the [DOWNLOAD] link)
4490 http://www.libpng.org/pub/png
4491 zlib:
4494 (generally) at the same location as libpng or at
4496 ftp://ftp.info-zip.org/pub/infozip/zlib
4497 PNGspecification:RFC2083
4500 (generally) at the same location as libpng or at
4502 ftp://ftp.rfc-editor.org:/in-notes/rfc2083.txt
4503 or (as a W3C Recommendation) at
4504 http://www.w3.org/TR/REC-png.html
4505 In the case of any inconsistency between the PNG specification and this
4508 library, the specification takes precedence.
4509
4512 This man page: Glenn Randers-Pehrson <glennrp at users.sourceforge.net>
4513 The contributing authors would like to thank all those who helped with
4515 testing, bug fixes, and patience. This wouldn't have been possible
4516 without all of you.
4517 Thanks to Frank J. T. Wojcik for helping with the documentation.
4519 Libpng version 1.2.46 - July 9, 2011: Initially created in 1995 by Guy
4521 Eric Schalnat, then of Group 42, Inc. Currently maintained by Glenn
4522 Randers-Pehrson (glennrp at users.sourceforge.net).
4523 Supported by the PNG development group
4525 png-mng-implement at lists.sf.net (subscription required; visit png-
4526 mng-implement at lists.sourceforge.net (subscription required; visit
4527 https://lists.sourceforge.net/lists/listinfo/png-mng-implement to sub‐
4528 scribe).
4529
4532 (This copy of the libpng notices is provided for your convenience. In
4533 case of any discrepancy between this copy and the notices in the file
4534 png.h that is included in the libpng distribution, the latter shall
4535 prevail.)
4536 If you modify libpng you may insert additional notices immediately fol‐
4538 lowing this sentence.
4539 This code is released under the libpng license.
4541 libpng versions 1.2.6, August 15, 2004, through 1.2.46, July 9, 2011,
4543 are Copyright (c) 2004,2006-2008 Glenn Randers-Pehrson, and are dis‐
4544 tributed according to the same disclaimer and license as libpng-1.2.5
4545 with the following individual added to the list of Contributing Authors
4546 Cosmin Truta
4548 libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002,
4550 are Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are distributed
4551 according to the same disclaimer and license as libpng-1.0.6 with the
4552 following individuals added to the list of Contributing Authors
4553 Simon-Pierre Cadieux
4555 Eric S. Raymond
4556 Gilles Vollant
4557 and with the following additions to the disclaimer:
4559 There is no warranty against interference with your
4561 enjoyment of the library or against infringement.
4562 There is no warranty that our efforts or the library
4563 will fulfill any of your particular purposes or needs.
4564 This library is provided with all faults, and the entire
4565 risk of satisfactory quality, performance, accuracy, and
4566 effort is with the user.
4567 libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
4569 Copyright (c) 1998, 1999 Glenn Randers-Pehrson Distributed according to
4570 the same disclaimer and license as libpng-0.96, with the following
4571 individuals added to the list of Contributing Authors:
4572 Tom Lane
4574 Glenn Randers-Pehrson
4575 Willem van Schaik
4576 libpng versions 0.89, June 1996, through 0.96, May 1997, are Copyright
4578 (c) 1996, 1997 Andreas Dilger Distributed according to the same dis‐
4579 claimer and license as libpng-0.88, with the following individuals
4580 added to the list of Contributing Authors:
4581 John Bowler
4583 Kevin Bracey
4584 Sam Bushell
4585 Magnus Holmgren
4586 Greg Roelofs
4587 Tom Tanner
4588 libpng versions 0.5, May 1995, through 0.88, January 1996, are Copy‐
4590 right (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
4591 For the purposes of this copyright and license, "Contributing Authors"
4593 is defined as the following set of individuals:
4594 Andreas Dilger
4596 Dave Martindale
4597 Guy Eric Schalnat
4598 Paul Schmidt
4599 Tim Wegner
4600 The PNG Reference Library is supplied "AS IS". The Contributing
4602 Authors and Group 42, Inc. disclaim all warranties, expressed or
4603 implied, including, without limitation, the warranties of merchantabil‐
4604 ity and of fitness for any purpose. The Contributing Authors and Group
4605 42, Inc. assume no liability for direct, indirect, incidental, spe‐
4606 cial, exemplary, or consequential damages, which may result from the
4607 use of the PNG Reference Library, even if advised of the possibility of
4608 such damage.
4609 Permission is hereby granted to use, copy, modify, and distribute this
4611 source code, or portions hereof, for any purpose, without fee, subject
4612 to the following restrictions:
4613 1. The origin of this source code must not be misrepresented.
4615 2. Altered versions must be plainly marked as such and
4617 must not be misrepresented as being the original source.
4618 3. This Copyright notice may not be removed or altered from
4620 any source or altered source distribution.
4621 The Contributing Authors and Group 42, Inc. specifically permit, with‐
4623 out fee, and encourage the use of this source code as a component to
4624 supporting the PNG file format in commercial products. If you use this
4625 source code in a product, acknowledgment is not required but would be
4626 appreciated.
4627 A "png_get_copyright" function is available, for convenient use in
4630 "about" boxes and the like:
4631 printf("%s",png_get_copyright(NULL));
4633 Also, the PNG logo (in PNG format, of course) is supplied in the files
4635 "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
4636 Libpng is OSI Certified Open Source Software. OSI Certified Open
4638 Source is a certification mark of the Open Source Initiative.
4639 Glenn Randers-Pehrson glennrp at users.sourceforge.net July 9, 2011
4641 July 9, 2011 LIBPNG(3)
