1
libpng.txt - A description on how to use and modify libpng
3
libpng version 1.4.4 - September 23, 2010
4
Updated and distributed by Glenn Randers-Pehrson
5
<glennrp at users.sourceforge.net>
6
Copyright (c) 1998-2010 Glenn Randers-Pehrson
8
This document is released under the libpng license.
9
For conditions of distribution and use, see the disclaimer
14
libpng versions 0.97, January 1998, through 1.4.4 - September 23, 2010
15
Updated and distributed by Glenn Randers-Pehrson
16
Copyright (c) 1998-2010 Glenn Randers-Pehrson
18
libpng 1.0 beta 6 version 0.96 May 28, 1997
19
Updated and distributed by Andreas Dilger
20
Copyright (c) 1996, 1997 Andreas Dilger
22
libpng 1.0 beta 2 - version 0.88 January 26, 1996
23
For conditions of distribution and use, see copyright
24
notice in png.h. Copyright (c) 1995, 1996 Guy Eric
25
Schalnat, Group 42, Inc.
27
Updated/rewritten per request in the libpng FAQ
28
Copyright (c) 1995, 1996 Frank J. T. Wojcik
29
December 18, 1995 & January 20, 1996
33
This file describes how to use and modify the PNG reference library
34
(known as libpng) for your own use. There are five sections to this
35
file: introduction, structures, reading, writing, and modification and
36
configuration notes for various special platforms. In addition to this
37
file, example.c is a good starting point for using the library, as
38
it is heavily commented and should include everything most people
39
will need. We assume that libpng is already installed; see the
40
INSTALL file for instructions on how to install libpng.
42
For examples of libpng usage, see the files "example.c", "pngtest.c",
43
and the files in the "contrib" directory, all of which are included in
44
the libpng distribution.
46
Libpng was written as a companion to the PNG specification, as a way
47
of reducing the amount of time and effort it takes to support the PNG
48
file format in application programs.
50
The PNG specification (second edition), November 2003, is available as
51
a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
52
<http://www.w3.org/TR/2003/REC-PNG-20031110/
53
The W3C and ISO documents have identical technical content.
55
The PNG-1.2 specification is available at
56
<http://www.libpng.org/pub/png/documents/>. It is technically equivalent
57
to the PNG specification (second edition) but has some additional material.
59
The PNG-1.0 specification is available
60
as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
61
W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
63
Some additional chunks are described in the special-purpose public chunks
64
documents at <http://www.libpng.org/pub/png/documents/>.
67
about PNG, and the latest version of libpng, can be found at the PNG home
68
page, <http://www.libpng.org/pub/png/>.
70
Most users will not have to modify the library significantly; advanced
71
users may want to modify it more. All attempts were made to make it as
72
complete as possible, while keeping the code easy to understand.
73
Currently, this library only supports C. Support for other languages
76
Libpng has been designed to handle multiple sessions at one time,
77
to be easily modifiable, to be portable to the vast majority of
78
machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
79
to use. The ultimate goal of libpng is to promote the acceptance of
80
the PNG file format in whatever way possible. While there is still
81
work to be done (see the TODO file), libpng should cover the
82
majority of the needs of its users.
84
Libpng uses zlib for its compression and decompression of PNG files.
85
Further information about zlib, and the latest version of zlib, can
86
be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
87
The zlib compression utility is a general purpose utility that is
88
useful for more than PNG files, and can be used without libpng.
89
See the documentation delivered with zlib for more details.
90
You can usually find the source files for the zlib utility wherever you
91
find the libpng source files.
93
Libpng is thread safe, provided the threads are using different
94
instances of the structures. Each thread should have its own
95
png_struct and png_info instances, and thus its own image.
96
Libpng does not protect itself against two threads using the
97
same instance of a structure.
101
There are two main structures that are important to libpng, png_struct
102
and png_info. The first, png_struct, is an internal structure that
103
will not, for the most part, be used by a user except as the first
104
variable passed to every libpng function call.
106
The png_info structure is designed to provide information about the
107
PNG file. At one time, the fields of png_info were intended to be
108
directly accessible to the user. However, this tended to cause problems
109
with applications using dynamically loaded libraries, and as a result
110
a set of interface functions for png_info (the png_get_*() and png_set_*()
111
functions) was developed. The fields of png_info are still available for
112
older applications, but it is suggested that applications use the new
113
interfaces if at all possible.
115
Applications that do make direct access to the members of png_struct (except
116
for png_ptr->jmpbuf) must be recompiled whenever the library is updated,
117
and applications that make direct access to the members of png_info must
118
be recompiled if they were compiled or loaded with libpng version 1.0.6,
119
in which the members were in a different order. In version 1.0.7, the
120
members of the png_info structure reverted to the old order, as they were
121
in versions 0.97c through 1.0.5. Starting with version 2.0.0, both
122
structures are going to be hidden, and the contents of the structures will
123
only be accessible through the png_get/png_set functions.
125
The png.h header file is an invaluable reference for programming with libpng.
126
And while I'm on the topic, make sure you include the libpng header file:
132
We'll now walk you through the possible functions to call when reading
133
in a PNG file sequentially, briefly explaining the syntax and purpose
134
of each one. See example.c and png.h for more detail. While
135
progressive reading is covered in the next section, you will still
136
need some of the functions discussed in this section to read a PNG
141
You will want to do the I/O initialization(*) before you get into libpng,
142
so if it doesn't work, you don't have much to undo. Of course, you
143
will also want to insure that you are, in fact, dealing with a PNG
144
file. Libpng provides a simple check to see if a file is a PNG file.
145
To use it, pass in the first 1 to 8 bytes of the file to the function
146
png_sig_cmp(), and it will return 0 (false) if the bytes match the
147
corresponding bytes of the PNG signature, or nonzero (true) otherwise.
148
Of course, the more bytes you pass in, the greater the accuracy of the
151
If you are intending to keep the file pointer open for use in libpng,
152
you must ensure you don't read more than 8 bytes from the beginning
153
of the file, and you also have to make a call to png_set_sig_bytes_read()
154
with the number of bytes you read from the beginning. Libpng will
155
then only check the bytes (if any) that your program didn't read.
157
(*): If you are not using the standard I/O functions, you will need
158
to replace them with custom functions. See the discussion under
162
FILE *fp = fopen(file_name, "rb");
167
fread(header, 1, number, fp);
168
is_png = !png_sig_cmp(header, 0, number);
175
Next, png_struct and png_info need to be allocated and initialized. In
176
order to ensure that the size of these structures is correct even with a
177
dynamically linked libpng, there are functions to initialize and
178
allocate the structures. We also pass the library version, optional
179
pointers to error handling functions, and a pointer to a data struct for
180
use by the error functions, if necessary (the pointer and functions can
181
be NULL if the default error handlers are to be used). See the section
182
on Changes to Libpng below regarding the old initialization functions.
183
The structure allocation functions quietly return NULL if they fail to
184
create the structure, so your application should check for that.
186
png_structp png_ptr = png_create_read_struct
187
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
188
user_error_fn, user_warning_fn);
192
png_infop info_ptr = png_create_info_struct(png_ptr);
195
png_destroy_read_struct(&png_ptr,
196
(png_infopp)NULL, (png_infopp)NULL);
200
png_infop end_info = png_create_info_struct(png_ptr);
203
png_destroy_read_struct(&png_ptr, &info_ptr,
208
If you want to use your own memory allocation routines,
209
define PNG_USER_MEM_SUPPORTED and use
210
png_create_read_struct_2() instead of png_create_read_struct():
212
png_structp png_ptr = png_create_read_struct_2
213
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
214
user_error_fn, user_warning_fn, (png_voidp)
215
user_mem_ptr, user_malloc_fn, user_free_fn);
217
The error handling routines passed to png_create_read_struct()
218
and the memory alloc/free routines passed to png_create_struct_2()
219
are only necessary if you are not using the libpng supplied error
220
handling and memory alloc/free functions.
222
When libpng encounters an error, it expects to longjmp back
223
to your routine. Therefore, you will need to call setjmp and pass
224
your png_jmpbuf(png_ptr). If you read the file from different
225
routines, you will need to update the jmpbuf field every time you enter
226
a new routine that will call a png_*() function.
228
See your documentation of setjmp/longjmp for your compiler for more
229
information on setjmp/longjmp. See the discussion on libpng error
230
handling in the Customizing Libpng section below for more information
231
on the libpng error handling. If an error occurs, and libpng longjmp's
232
back to your setjmp, you will want to call png_destroy_read_struct() to
235
if (setjmp(png_jmpbuf(png_ptr)))
237
png_destroy_read_struct(&png_ptr, &info_ptr,
243
If you would rather avoid the complexity of setjmp/longjmp issues,
244
you can compile libpng with PNG_NO_SETJMP, in which case
245
errors will result in a call to PNG_ABORT() which defaults to abort().
247
You can #define PNG_ABORT() to a function that does something
248
more useful than abort(), as long as your function does not
251
Now you need to set up the input code. The default for libpng is to
252
use the C function fread(). If you use this, you will need to pass a
253
valid FILE * in the function png_init_io(). Be sure that the file is
254
opened in binary mode. If you wish to handle reading data in another
255
way, you need not call the png_init_io() function, but you must then
256
implement the libpng I/O methods discussed in the Customizing Libpng
259
png_init_io(png_ptr, fp);
261
If you had previously opened the file and read any of the signature from
262
the beginning in order to see if this was a PNG file, you need to let
263
libpng know that there are some bytes missing from the start of the file.
265
png_set_sig_bytes(png_ptr, number);
267
You can change the zlib compression buffer size to be used while
268
reading compressed data with
270
png_set_compression_buffer_size(png_ptr, buffer_size);
272
where the default size is 8192 bytes. Note that the buffer size
273
is changed immediately and the buffer is reallocated immediately,
274
instead of setting a flag to be acted upon later.
276
Setting up callback code
278
You can set up a callback function to handle any unknown chunks in the
279
input stream. You must supply the function
281
read_chunk_callback(png_ptr ptr,
282
png_unknown_chunkp chunk);
284
/* The unknown chunk structure contains your
285
chunk data, along with similar data for any other
292
/* Note that libpng has already taken care of
295
/* put your code here. Search for your chunk in the
296
unknown chunk structure, process it, and return one
299
return (-n); /* chunk had an error */
300
return (0); /* did not recognize */
301
return (n); /* success */
304
(You can give your function another name that you like instead of
305
"read_chunk_callback")
307
To inform libpng about your function, use
309
png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
310
read_chunk_callback);
312
This names not only the callback function, but also a user pointer that
313
you can retrieve with
315
png_get_user_chunk_ptr(png_ptr);
317
If you call the png_set_read_user_chunk_fn() function, then all unknown
318
chunks will be saved when read, in case your callback function will need
319
one or more of them. This behavior can be changed with the
320
png_set_keep_unknown_chunks() function, described below.
322
At this point, you can set up a callback function that will be
323
called after each row has been read, which you can use to control
324
a progress meter or the like. It's demonstrated in pngtest.c.
325
You must supply a function
327
void read_row_callback(png_ptr ptr, png_uint_32 row,
330
/* put your code here */
333
(You can give it another name that you like instead of "read_row_callback")
335
To inform libpng about your function, use
337
png_set_read_status_fn(png_ptr, read_row_callback);
339
Unknown-chunk handling
341
Now you get to set the way the library processes unknown chunks in the
342
input PNG stream. Both known and unknown chunks will be read. Normal
343
behavior is that known chunks will be parsed into information in
344
various info_ptr members while unknown chunks will be discarded. This
345
behavior can be wasteful if your application will never use some known
346
chunk types. To change this, you can call:
348
png_set_keep_unknown_chunks(png_ptr, keep,
349
chunk_list, num_chunks);
350
keep - 0: default unknown chunk handling
351
1: ignore; do not keep
352
2: keep only if safe-to-copy
353
3: keep even if unsafe-to-copy
354
You can use these definitions:
355
PNG_HANDLE_CHUNK_AS_DEFAULT 0
356
PNG_HANDLE_CHUNK_NEVER 1
357
PNG_HANDLE_CHUNK_IF_SAFE 2
358
PNG_HANDLE_CHUNK_ALWAYS 3
359
chunk_list - list of chunks affected (a byte string,
360
five bytes per chunk, NULL or '\0' if
362
num_chunks - number of chunks affected; if 0, all
363
unknown chunks are affected. If nonzero,
364
only the chunks in the list are affected
366
Unknown chunks declared in this way will be saved as raw data onto a
367
list of png_unknown_chunk structures. If a chunk that is normally
368
known to libpng is named in the list, it will be handled as unknown,
369
according to the "keep" directive. If a chunk is named in successive
370
instances of png_set_keep_unknown_chunks(), the final instance will
371
take precedence. The IHDR and IEND chunks should not be named in
372
chunk_list; if they are, libpng will process them normally anyway.
374
Here is an example of the usage of png_set_keep_unknown_chunks(),
375
where the private "vpAg" chunk will later be processed by a user chunk
378
png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'};
380
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
381
png_byte unused_chunks[]=
383
104, 73, 83, 84, (png_byte) '\0', /* hIST */
384
105, 84, 88, 116, (png_byte) '\0', /* iTXt */
385
112, 67, 65, 76, (png_byte) '\0', /* pCAL */
386
115, 67, 65, 76, (png_byte) '\0', /* sCAL */
387
115, 80, 76, 84, (png_byte) '\0', /* sPLT */
388
116, 73, 77, 69, (png_byte) '\0', /* tIME */
394
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
395
/* ignore all unknown chunks: */
396
png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
397
/* except for vpAg: */
398
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
399
/* also ignore unused known chunks: */
400
png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
401
(int)sizeof(unused_chunks)/5);
406
The PNG specification allows the width and height of an image to be as
407
large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
408
Since very few applications really need to process such large images,
409
we have imposed an arbitrary 1-million limit on rows and columns.
410
Larger images will be rejected immediately with a png_error() call. If
411
you wish to override this limit, you can use
413
png_set_user_limits(png_ptr, width_max, height_max);
415
to set your own limits, or use width_max = height_max = 0x7fffffffL
416
to allow all valid dimensions (libpng may reject some very large images
417
anyway because of potential buffer overflow conditions).
419
You should put this statement after you create the PNG structure and
420
before calling png_read_info(), png_read_png(), or png_process_data().
421
If you need to retrieve the limits that are being applied, use
423
width_max = png_get_user_width_max(png_ptr);
424
height_max = png_get_user_height_max(png_ptr);
426
The PNG specification sets no limit on the number of ancillary chunks
427
allowed in a PNG datastream. You can impose a limit on the total number
428
of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
430
png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
432
where 0x7fffffffL means unlimited. You can retrieve this limit with
434
chunk_cache_max = png_get_chunk_cache_max(png_ptr);
436
This limit also applies to the number of buffers that can be allocated
437
by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
439
You can also set a limit on the amount of memory that a compressed chunk
440
other than IDAT can occupy, with
442
png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
444
and you can retrieve the limit with
446
chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
448
Any chunks that would cause either of these limits to be exceeded will
451
The high-level read interface
453
At this point there are two ways to proceed; through the high-level
454
read interface, or through a sequence of low-level read operations.
455
You can use the high-level interface if (a) you are willing to read
456
the entire image into memory, and (b) the input transformations
457
you want to do are limited to the following set:
459
PNG_TRANSFORM_IDENTITY No transformation
460
PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
462
PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
463
PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
465
PNG_TRANSFORM_PACKSWAP Change order of packed
467
PNG_TRANSFORM_EXPAND Perform set_expand()
468
PNG_TRANSFORM_INVERT_MONO Invert monochrome images
469
PNG_TRANSFORM_SHIFT Normalize pixels to the
471
PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
473
PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
475
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
477
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
478
PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
479
to RGB (or GA to RGBA)
481
(This excludes setting a background color, doing gamma transformation,
482
quantizing, and setting filler.) If this is the case, simply do this:
484
png_read_png(png_ptr, info_ptr, png_transforms, NULL)
486
where png_transforms is an integer containing the bitwise OR of some
487
set of transformation flags. This call is equivalent to png_read_info(),
488
followed the set of transformations indicated by the transform mask,
489
then png_read_image(), and finally png_read_end().
491
(The final parameter of this call is not yet used. Someday it might point
492
to transformation parameters required by some future input transform.)
494
You must use png_transforms and not call any png_set_transform() functions
495
when you use png_read_png().
497
After you have called png_read_png(), you can retrieve the image data
500
row_pointers = png_get_rows(png_ptr, info_ptr);
502
where row_pointers is an array of pointers to the pixel data for each row:
504
png_bytep row_pointers[height];
506
If you know your image size and pixel size ahead of time, you can allocate
507
row_pointers prior to calling png_read_png() with
509
if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
511
"Image is too tall to process in memory");
512
if (width > PNG_UINT_32_MAX/pixel_size)
514
"Image is too wide to process in memory");
515
row_pointers = png_malloc(png_ptr,
516
height*png_sizeof(png_bytep));
517
for (int i=0; i<height, i++)
518
row_pointers[i]=NULL; /* security precaution */
519
for (int i=0; i<height, i++)
520
row_pointers[i]=png_malloc(png_ptr,
522
png_set_rows(png_ptr, info_ptr, &row_pointers);
524
Alternatively you could allocate your image in one big block and define
525
row_pointers[i] to point into the proper places in your block.
527
If you use png_set_rows(), the application is responsible for freeing
528
row_pointers (and row_pointers[i], if they were separately allocated).
530
If you don't allocate row_pointers ahead of time, png_read_png() will
531
do it, and it'll be free'ed when you call png_destroy_*().
533
The low-level read interface
535
If you are going the low-level route, you are now ready to read all
536
the file information up to the actual image data. You do this with a
537
call to png_read_info().
539
png_read_info(png_ptr, info_ptr);
541
This will process all chunks up to but not including the image data.
543
Querying the info structure
545
Functions are used to get the information from the info_ptr once it
546
has been read. Note that these fields may not be completely filled
547
in until png_read_end() has read the chunk data following the image.
549
png_get_IHDR(png_ptr, info_ptr, &width, &height,
550
&bit_depth, &color_type, &interlace_type,
551
&compression_type, &filter_method);
553
width - holds the width of the image
554
in pixels (up to 2^31).
555
height - holds the height of the image
556
in pixels (up to 2^31).
557
bit_depth - holds the bit depth of one of the
558
image channels. (valid values are
559
1, 2, 4, 8, 16 and depend also on
560
the color_type. See also
561
significant bits (sBIT) below).
562
color_type - describes which color/alpha channels
565
(bit depths 1, 2, 4, 8, 16)
566
PNG_COLOR_TYPE_GRAY_ALPHA
568
PNG_COLOR_TYPE_PALETTE
569
(bit depths 1, 2, 4, 8)
572
PNG_COLOR_TYPE_RGB_ALPHA
575
PNG_COLOR_MASK_PALETTE
579
filter_method - (must be PNG_FILTER_TYPE_BASE
580
for PNG 1.0, and can also be
581
PNG_INTRAPIXEL_DIFFERENCING if
582
the PNG datastream is embedded in
583
a MNG-1.0 datastream)
584
compression_type - (must be PNG_COMPRESSION_TYPE_BASE
586
interlace_type - (PNG_INTERLACE_NONE or
589
Any or all of interlace_type, compression_type, or
590
filter_method can be NULL if you are
591
not interested in their values.
593
Note that png_get_IHDR() returns 32-bit data into
594
the application's width and height variables.
595
This is an unsafe situation if these are 16-bit
596
variables. In such situations, the
597
png_get_image_width() and png_get_image_height()
598
functions described below are safer.
600
width = png_get_image_width(png_ptr,
602
height = png_get_image_height(png_ptr,
604
bit_depth = png_get_bit_depth(png_ptr,
606
color_type = png_get_color_type(png_ptr,
608
filter_method = png_get_filter_type(png_ptr,
610
compression_type = png_get_compression_type(png_ptr,
612
interlace_type = png_get_interlace_type(png_ptr,
615
channels = png_get_channels(png_ptr, info_ptr);
616
channels - number of channels of info for the
617
color type (valid values are 1 (GRAY,
618
PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
619
4 (RGB_ALPHA or RGB + filler byte))
620
rowbytes = png_get_rowbytes(png_ptr, info_ptr);
621
rowbytes - number of bytes needed to hold a row
623
signature = png_get_signature(png_ptr, info_ptr);
624
signature - holds the signature read from the
625
file (if any). The data is kept in
626
the same offset it would be if the
627
whole signature were read (i.e. if an
628
application had already read in 4
629
bytes of signature before starting
630
libpng, the remaining 4 bytes would
631
be in signature[4] through signature[7]
632
(see png_set_sig_bytes())).
634
These are also important, but their validity depends on whether the chunk
635
has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
636
png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
637
data has been read, or zero if it is missing. The parameters to the
638
png_get_<chunk> are set directly if they are simple data types, or a
639
pointer into the info_ptr is returned for any complex types.
641
png_get_PLTE(png_ptr, info_ptr, &palette,
643
palette - the palette for the file
645
num_palette - number of entries in the palette
647
png_get_gAMA(png_ptr, info_ptr, &gamma);
648
gamma - the gamma the file is written
651
png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
652
srgb_intent - the rendering intent (PNG_INFO_sRGB)
653
The presence of the sRGB chunk
654
means that the pixel data is in the
655
sRGB color space. This chunk also
656
implies specific values of gAMA and
659
png_get_iCCP(png_ptr, info_ptr, &name,
660
&compression_type, &profile, &proflen);
661
name - The profile name.
662
compression - The compression type; always
663
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
664
You may give NULL to this argument to
666
profile - International Color Consortium color
667
profile data. May contain NULs.
668
proflen - length of profile data in bytes.
670
png_get_sBIT(png_ptr, info_ptr, &sig_bit);
671
sig_bit - the number of significant bits for
672
(PNG_INFO_sBIT) each of the gray,
673
red, green, and blue channels,
674
whichever are appropriate for the
675
given color type (png_color_16)
677
png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
678
&num_trans, &trans_color);
679
trans_alpha - array of alpha (transparency)
680
entries for palette (PNG_INFO_tRNS)
681
trans_color - graylevel or color sample values of
682
the single transparent color for
683
non-paletted images (PNG_INFO_tRNS)
684
num_trans - number of transparent entries
687
png_get_hIST(png_ptr, info_ptr, &hist);
689
hist - histogram of palette (array of
692
png_get_tIME(png_ptr, info_ptr, &mod_time);
693
mod_time - time image was last modified
696
png_get_bKGD(png_ptr, info_ptr, &background);
697
background - background color (PNG_VALID_bKGD)
698
valid 16-bit red, green and blue
699
values, regardless of color_type
701
num_comments = png_get_text(png_ptr, info_ptr,
702
&text_ptr, &num_text);
703
num_comments - number of comments
704
text_ptr - array of png_text holding image
706
text_ptr[i].compression - type of compression used
707
on "text" PNG_TEXT_COMPRESSION_NONE
708
PNG_TEXT_COMPRESSION_zTXt
709
PNG_ITXT_COMPRESSION_NONE
710
PNG_ITXT_COMPRESSION_zTXt
711
text_ptr[i].key - keyword for comment. Must contain
713
text_ptr[i].text - text comments for current
714
keyword. Can be empty.
715
text_ptr[i].text_length - length of text string,
716
after decompression, 0 for iTXt
717
text_ptr[i].itxt_length - length of itxt string,
718
after decompression, 0 for tEXt/zTXt
719
text_ptr[i].lang - language of comment (empty
721
text_ptr[i].lang_key - keyword in UTF-8
722
(empty string for unknown).
723
Note that the itxt_length, lang, and lang_key
724
members of the text_ptr structure only exist
725
when the library is built with iTXt chunk support.
727
num_text - number of comments (same as
728
num_comments; you can put NULL here
729
to avoid the duplication)
730
Note while png_set_text() will accept text, language,
731
and translated keywords that can be NULL pointers, the
732
structure returned by png_get_text will always contain
733
regular zero-terminated C strings. They might be
734
empty strings but they will never be NULL pointers.
736
num_spalettes = png_get_sPLT(png_ptr, info_ptr,
738
palette_ptr - array of palette structures holding
739
contents of one or more sPLT chunks
741
num_spalettes - number of sPLT chunks read.
743
png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
745
offset_x - positive offset from the left edge
747
offset_y - positive offset from the top edge
749
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
751
png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
753
res_x - pixels/unit physical resolution in
755
res_y - pixels/unit physical resolution in
757
unit_type - PNG_RESOLUTION_UNKNOWN,
760
png_get_sCAL(png_ptr, info_ptr, &unit, &width,
762
unit - physical scale units (an integer)
763
width - width of a pixel in physical scale units
764
height - height of a pixel in physical scale units
765
(width and height are doubles)
767
png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
769
unit - physical scale units (an integer)
770
width - width of a pixel in physical scale units
771
height - height of a pixel in physical scale units
772
(width and height are strings like "2.54")
774
num_unknown_chunks = png_get_unknown_chunks(png_ptr,
776
unknowns - array of png_unknown_chunk
777
structures holding unknown chunks
778
unknowns[i].name - name of unknown chunk
779
unknowns[i].data - data of unknown chunk
780
unknowns[i].size - size of unknown chunk's data
781
unknowns[i].location - position of chunk in file
783
The value of "i" corresponds to the order in which the
784
chunks were read from the PNG file or inserted with the
785
png_set_unknown_chunks() function.
787
The data from the pHYs chunk can be retrieved in several convenient
790
res_x = png_get_x_pixels_per_meter(png_ptr,
792
res_y = png_get_y_pixels_per_meter(png_ptr,
794
res_x_and_y = png_get_pixels_per_meter(png_ptr,
796
res_x = png_get_x_pixels_per_inch(png_ptr,
798
res_y = png_get_y_pixels_per_inch(png_ptr,
800
res_x_and_y = png_get_pixels_per_inch(png_ptr,
802
aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
805
(Each of these returns 0 [signifying "unknown"] if
806
the data is not present or if res_x is 0;
807
res_x_and_y is 0 if res_x != res_y)
809
The data from the oFFs chunk can be retrieved in several convenient
812
x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
813
y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
814
x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
815
y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
817
(Each of these returns 0 [signifying "unknown" if both
818
x and y are 0] if the data is not present or if the
819
chunk is present but the unit is the pixel)
821
For more information, see the png_info definition in png.h and the
822
PNG specification for chunk contents. Be careful with trusting
823
rowbytes, as some of the transformations could increase the space
824
needed to hold a row (expand, filler, gray_to_rgb, etc.).
825
See png_read_update_info(), below.
827
A quick word about text_ptr and num_text. PNG stores comments in
828
keyword/text pairs, one pair per chunk, with no limit on the number
829
of text chunks, and a 2^31 byte limit on their size. While there are
830
suggested keywords, there is no requirement to restrict the use to these
831
strings. It is strongly suggested that keywords and text be sensible
832
to humans (that's the point), so don't use abbreviations. Non-printing
833
symbols are not allowed. See the PNG specification for more details.
834
There is also no requirement to have text after the keyword.
836
Keywords should be limited to 79 Latin-1 characters without leading or
837
trailing spaces, but non-consecutive spaces are allowed within the
838
keyword. It is possible to have the same keyword any number of times.
839
The text_ptr is an array of png_text structures, each holding a
840
pointer to a language string, a pointer to a keyword and a pointer to
841
a text string. The text string, language code, and translated
842
keyword may be empty or NULL pointers. The keyword/text
843
pairs are put into the array in the order that they are received.
844
However, some or all of the text chunks may be after the image, so, to
845
make sure you have read all the text chunks, don't mess with these
846
until after you read the stuff after the image. This will be
847
mentioned again below in the discussion that goes with png_read_end().
849
Input transformations
851
After you've read the header information, you can set up the library
852
to handle any special transformations of the image data. The various
853
ways to transform the data will be described in the order that they
854
should occur. This is important, as some of these change the color
855
type and/or bit depth of the data, and some others only work on
856
certain color types and bit depths. Even though each transformation
857
checks to see if it has data that it can do something with, you should
858
make sure to only enable a transformation if it will be valid for the
859
data. For example, don't swap red and blue on grayscale data.
861
The colors used for the background and transparency values should be
862
supplied in the same format/depth as the current image data. They
863
are stored in the same format/depth as the image data in a bKGD or tRNS
864
chunk, so this is what libpng expects for this data. The colors are
865
transformed to keep in sync with the image data when an application
866
calls the png_read_update_info() routine (see below).
868
Data will be decoded into the supplied row buffers packed into bytes
869
unless the library has been told to transform it into another format.
870
For example, 4 bit/pixel paletted or grayscale data will be returned
871
2 pixels/byte with the leftmost pixel in the high-order bits of the
872
byte, unless png_set_packing() is called. 8-bit RGB data will be stored
873
in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
874
is called to insert filler bytes, either before or after each RGB triplet.
875
16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
876
byte of the color value first, unless png_set_strip_16() is called to
877
transform it to regular RGB RGB triplets, or png_set_filler() or
878
png_set_add alpha() is called to insert filler bytes, either before or
879
after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
881
png_set_filler(), png_set_add_alpha(), or png_set_strip_16().
883
The following code transforms grayscale images of less than 8 to 8 bits,
884
changes paletted images to RGB, and adds a full alpha channel if there is
885
transparency information in a tRNS chunk. This is most useful on
886
grayscale images with bit depths of 2 or 4 or if there is a multiple-image
887
viewing application that wishes to treat all images in the same way.
889
if (color_type == PNG_COLOR_TYPE_PALETTE)
890
png_set_palette_to_rgb(png_ptr);
892
if (color_type == PNG_COLOR_TYPE_GRAY &&
893
bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
895
if (png_get_valid(png_ptr, info_ptr,
896
PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
898
These three functions are actually aliases for png_set_expand(), added
899
in libpng version 1.0.4, with the function names expanded to improve code
900
readability. In some future version they may actually do different
903
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
904
added. It expands the sample depth without changing tRNS to alpha.
906
As of libpng version 1.4.4, not all possible expansions are supported.
908
In the following table, the 01 means grayscale with depth<8, 31 means
909
indexed with depth<8, other numerals represent the color type, "T" means
910
the tRNS chunk is present, A means an alpha channel is present, and O
911
means tRNS or alpha is present but all pixels in the image are opaque.
913
FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
932
"-" means the transformation is not supported.
933
"X" means the transformation is obtained by png_set_expand().
934
"1" means the transformation is obtained by
935
png_set_expand_gray_1_2_4_to_8
936
"G" means the transformation is obtained by
937
png_set_gray_to_rgb().
938
"P" means the transformation is obtained by
939
png_set_expand_palette_to_rgb().
940
"T" means the transformation is obtained by
941
png_set_tRNS_to_alpha().
943
PNG can have files with 16 bits per channel. If you only can handle
944
8 bits per channel, this will strip the pixels down to 8 bit.
947
png_set_strip_16(png_ptr);
949
If, for some reason, you don't need the alpha channel on an image,
950
and you want to remove it rather than combining it with the background
951
(but the image author certainly had in mind that you *would* combine
952
it with the background, so that's what you should probably do):
954
if (color_type & PNG_COLOR_MASK_ALPHA)
955
png_set_strip_alpha(png_ptr);
957
In PNG files, the alpha channel in an image
958
is the level of opacity. If you need the alpha channel in an image to
959
be the level of transparency instead of opacity, you can invert the
960
alpha channel (or the tRNS chunk data) after it's read, so that 0 is
961
fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
962
images) is fully transparent, with
964
png_set_invert_alpha(png_ptr);
966
PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
967
they can, resulting in, for example, 8 pixels per byte for 1 bit
968
files. This code expands to 1 pixel per byte without changing the
969
values of the pixels:
972
png_set_packing(png_ptr);
974
PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
975
stored in a PNG image have been "scaled" or "shifted" up to the next
976
higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
977
to 8 bits/sample in the range [0, 255]). However, it is also possible
978
to convert the PNG pixel data back to the original bit depth of the
979
image. This call reduces the pixels back down to the original bit depth:
981
png_color_8p sig_bit;
983
if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
984
png_set_shift(png_ptr, sig_bit);
986
PNG files store 3-color pixels in red, green, blue order. This code
987
changes the storage of the pixels to blue, green, red:
989
if (color_type == PNG_COLOR_TYPE_RGB ||
990
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
991
png_set_bgr(png_ptr);
993
PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
994
into 4 or 8 bytes for windowing systems that need them in this format:
996
if (color_type == PNG_COLOR_TYPE_RGB)
997
png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
999
where "filler" is the 8 or 16-bit number to fill with, and the location is
1000
either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1001
you want the filler before the RGB or after. This transformation
1002
does not affect images that already have full alpha channels. To add an
1003
opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
1004
will generate RGBA pixels.
1006
Note that png_set_filler() does not change the color type. If you want
1007
to do that, you can add a true alpha channel with
1009
if (color_type == PNG_COLOR_TYPE_RGB ||
1010
color_type == PNG_COLOR_TYPE_GRAY)
1011
png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1013
where "filler" contains the alpha value to assign to each pixel.
1014
This function was added in libpng-1.2.7.
1016
If you are reading an image with an alpha channel, and you need the
1017
data as ARGB instead of the normal PNG format RGBA:
1019
if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1020
png_set_swap_alpha(png_ptr);
1022
For some uses, you may want a grayscale image to be represented as
1023
RGB. This code will do that conversion:
1025
if (color_type == PNG_COLOR_TYPE_GRAY ||
1026
color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1027
png_set_gray_to_rgb(png_ptr);
1029
Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
1032
if (color_type == PNG_COLOR_TYPE_RGB ||
1033
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1034
png_set_rgb_to_gray_fixed(png_ptr, error_action,
1035
int red_weight, int green_weight);
1037
error_action = 1: silently do the conversion
1038
error_action = 2: issue a warning if the original
1039
image has any pixel where
1040
red != green or red != blue
1041
error_action = 3: issue an error and abort the
1042
conversion if the original
1043
image has any pixel where
1044
red != green or red != blue
1046
red_weight: weight of red component times 100000
1047
green_weight: weight of green component times 100000
1048
If either weight is negative, default
1049
weights (21268, 71514) are used.
1051
If you have set error_action = 1 or 2, you can
1052
later check whether the image really was gray, after processing
1053
the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1054
It will return a png_byte that is zero if the image was gray or
1055
1 if there were any non-gray pixels. bKGD and sBIT data
1056
will be silently converted to grayscale, using the green channel
1057
data, regardless of the error_action setting.
1059
With red_weight+green_weight<=100000,
1060
the normalized graylevel is computed:
1062
int rw = red_weight * 65536;
1063
int gw = green_weight * 65536;
1064
int bw = 65536 - (rw + gw);
1065
gray = (rw*red + gw*green + bw*blue)/65536;
1067
The default values approximate those recommended in the Charles
1068
Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
1069
Copyright (c) 1998-01-04 Charles Poynton <poynton at inforamp.net>
1071
Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1073
Libpng approximates this with
1075
Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
1077
which can be expressed with integers as
1079
Y = (6969 * R + 23434 * G + 2365 * B)/32768
1081
The calculation is done in a linear colorspace, if the image gamma
1084
If you have a grayscale and you are using png_set_expand_depth(),
1085
png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to
1086
a higher bit-depth, you must either supply the background color as a gray
1087
value at the original file bit-depth (need_expand = 1) or else supply the
1088
background color as an RGB triplet at the final, expanded bit depth
1089
(need_expand = 0). Similarly, if you are reading a paletted image, you
1090
must either supply the background color as a palette index (need_expand = 1)
1091
or as an RGB triplet that may or may not be in the palette (need_expand = 0).
1093
png_color_16 my_background;
1094
png_color_16p image_background;
1096
if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1097
png_set_background(png_ptr, image_background,
1098
PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
1100
png_set_background(png_ptr, &my_background,
1101
PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
1103
The png_set_background() function tells libpng to composite images
1104
with alpha or simple transparency against the supplied background
1105
color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
1106
you may use this color, or supply another color more suitable for
1107
the current display (e.g., the background color from a web page). You
1108
need to tell libpng whether the color is in the gamma space of the
1109
display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
1110
(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
1111
that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
1112
know why anyone would use this, but it's here).
1114
To properly display PNG images on any kind of system, the application needs
1115
to know what the display gamma is. Ideally, the user will know this, and
1116
the application will allow them to set it. One method of allowing the user
1117
to set the display gamma separately for each system is to check for a
1118
SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be
1121
Note that display_gamma is the overall gamma correction required to produce
1122
pleasing results, which depends on the lighting conditions in the surrounding
1123
environment. In a dim or brightly lit room, no compensation other than
1124
the physical gamma exponent of the monitor is needed, while in a dark room
1125
a slightly smaller exponent is better.
1127
double gamma, screen_gamma;
1129
if (/* We have a user-defined screen
1132
screen_gamma = user_defined_screen_gamma;
1134
/* One way that applications can share the same
1135
screen gamma value */
1136
else if ((gamma_str = getenv("SCREEN_GAMMA"))
1139
screen_gamma = (double)atof(gamma_str);
1141
/* If we don't have another value */
1144
screen_gamma = 2.2; /* A good guess for a
1145
PC monitor in a bright office or a dim room */
1146
screen_gamma = 2.0; /* A good guess for a
1147
PC monitor in a dark room */
1148
screen_gamma = 1.7 or 1.0; /* A good
1149
guess for Mac systems */
1152
The png_set_gamma() function handles gamma transformations of the data.
1153
Pass both the file gamma and the current screen_gamma. If the file does
1154
not have a gamma value, you can pass one anyway if you have an idea what
1155
it is (usually 0.45455 is a good guess for GIF images on PCs). Note
1156
that file gammas are inverted from screen gammas. See the discussions
1157
on gamma in the PNG specification for an excellent description of what
1158
gamma is, and why all applications should support it. It is strongly
1159
recommended that PNG viewers support gamma correction.
1161
if (png_get_gAMA(png_ptr, info_ptr, &gamma))
1162
png_set_gamma(png_ptr, screen_gamma, gamma);
1164
png_set_gamma(png_ptr, screen_gamma, 0.45455);
1166
If you need to reduce an RGB file to a paletted file, or if a paletted
1167
file has more entries then will fit on your screen, png_set_quantize()
1168
will do that. Note that this is a simple match dither that merely
1169
finds the closest color available. This should work fairly well with
1170
optimized palettes, and fairly badly with linear color cubes. If you
1171
pass a palette that is larger then maximum_colors, the file will
1172
reduce the number of colors in the palette so it will fit into
1173
maximum_colors. If there is a histogram, it will use it to make
1174
more intelligent choices when reducing the palette. If there is no
1175
histogram, it may not do as good a job.
1177
if (color_type & PNG_COLOR_MASK_COLOR)
1179
if (png_get_valid(png_ptr, info_ptr,
1182
png_uint_16p histogram = NULL;
1184
png_get_hIST(png_ptr, info_ptr,
1186
png_set_quantize(png_ptr, palette, num_palette,
1187
max_screen_colors, histogram, 1);
1191
png_color std_color_cube[MAX_SCREEN_COLORS] =
1194
png_set_quantize(png_ptr, std_color_cube,
1195
MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1200
PNG files describe monochrome as black being zero and white being one.
1201
The following code will reverse this (make black be one and white be
1204
if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
1205
png_set_invert_mono(png_ptr);
1207
This function can also be used to invert grayscale and gray-alpha images:
1209
if (color_type == PNG_COLOR_TYPE_GRAY ||
1210
color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1211
png_set_invert_mono(png_ptr);
1213
PNG files store 16 bit pixels in network byte order (big-endian,
1214
ie. most significant bits first). This code changes the storage to the
1215
other way (little-endian, i.e. least significant bits first, the
1216
way PCs store them):
1218
if (bit_depth == 16)
1219
png_set_swap(png_ptr);
1221
If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1222
need to change the order the pixels are packed into bytes, you can use:
1225
png_set_packswap(png_ptr);
1227
Finally, you can write your own transformation function if none of
1228
the existing ones meets your needs. This is done by setting a callback
1231
png_set_read_user_transform_fn(png_ptr,
1234
You must supply the function
1236
void read_transform_fn(png_ptr ptr, row_info_ptr
1237
row_info, png_bytep data)
1239
See pngtest.c for a working example. Your function will be called
1240
after all of the other transformations have been processed.
1242
You can also set up a pointer to a user structure for use by your
1243
callback function, and you can inform libpng that your transform
1244
function will change the number of channels or bit depth with the
1247
png_set_user_transform_info(png_ptr, user_ptr,
1248
user_depth, user_channels);
1250
The user's application, not libpng, is responsible for allocating and
1251
freeing any memory required for the user structure.
1253
You can retrieve the pointer via the function
1254
png_get_user_transform_ptr(). For example:
1256
voidp read_user_transform_ptr =
1257
png_get_user_transform_ptr(png_ptr);
1259
The last thing to handle is interlacing; this is covered in detail below,
1260
but you must call the function here if you want libpng to handle expansion
1261
of the interlaced image.
1263
number_of_passes = png_set_interlace_handling(png_ptr);
1265
After setting the transformations, libpng can update your png_info
1266
structure to reflect any transformations you've requested with this
1267
call. This is most useful to update the info structure's rowbytes
1268
field so you can use it to allocate your image memory. This function
1269
will also update your palette with the correct screen_gamma and
1270
background if these have been given with the calls above.
1272
png_read_update_info(png_ptr, info_ptr);
1274
After you call png_read_update_info(), you can allocate any
1275
memory you need to hold the image. The row data is simply
1276
raw byte data for all forms of images. As the actual allocation
1277
varies among applications, no example will be given. If you
1278
are allocating one large chunk, you will need to build an
1279
array of pointers to each row, as it will be needed for some
1280
of the functions below.
1284
After you've allocated memory, you can read the image data.
1285
The simplest way to do this is in one function call. If you are
1286
allocating enough memory to hold the whole image, you can just
1287
call png_read_image() and libpng will read in all the image data
1288
and put it in the memory area supplied. You will need to pass in
1289
an array of pointers to each row.
1291
This function automatically handles interlacing, so you don't need
1292
to call png_set_interlace_handling() or call this function multiple
1293
times, or any of that other stuff necessary with png_read_rows().
1295
png_read_image(png_ptr, row_pointers);
1297
where row_pointers is:
1299
png_bytep row_pointers[height];
1301
You can point to void or char or whatever you use for pixels.
1303
If you don't want to read in the whole image at once, you can
1304
use png_read_rows() instead. If there is no interlacing (check
1305
interlace_type == PNG_INTERLACE_NONE), this is simple:
1307
png_read_rows(png_ptr, row_pointers, NULL,
1310
where row_pointers is the same as in the png_read_image() call.
1312
If you are doing this just one row at a time, you can do this with
1313
a single row_pointer instead of an array of row_pointers:
1315
png_bytep row_pointer = row;
1316
png_read_row(png_ptr, row_pointer, NULL);
1318
If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
1319
get somewhat harder. The only current (PNG Specification version 1.2)
1320
interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
1321
is a somewhat complicated 2D interlace scheme, known as Adam7, that
1322
breaks down an image into seven smaller images of varying size, based
1325
libpng can fill out those images or it can give them to you "as is".
1326
If you want them filled out, there are two ways to do that. The one
1327
mentioned in the PNG specification is to expand each pixel to cover
1328
those pixels that have not been read yet (the "rectangle" method).
1329
This results in a blocky image for the first pass, which gradually
1330
smooths out as more pixels are read. The other method is the "sparkle"
1331
method, where pixels are drawn only in their final locations, with the
1332
rest of the image remaining whatever colors they were initialized to
1333
before the start of the read. The first method usually looks better,
1334
but tends to be slower, as there are more pixels to put in the rows.
1336
If you don't want libpng to handle the interlacing details, just call
1337
png_read_rows() seven times to read in all seven images. Each of the
1338
images is a valid image by itself, or they can all be combined on an
1339
8x8 grid to form a single image (although if you intend to combine them
1340
you would be far better off using the libpng interlace handling).
1342
The first pass will return an image 1/8 as wide as the entire image
1343
(every 8th column starting in column 0) and 1/8 as high as the original
1344
(every 8th row starting in row 0), the second will be 1/8 as wide
1345
(starting in column 4) and 1/8 as high (also starting in row 0). The
1346
third pass will be 1/4 as wide (every 4th pixel starting in column 0) and
1347
1/8 as high (every 8th row starting in row 4), and the fourth pass will
1348
be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,
1349
and every 4th row starting in row 0). The fifth pass will return an
1350
image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),
1351
while the sixth pass will be 1/2 as wide and 1/2 as high as the original
1352
(starting in column 1 and row 0). The seventh and final pass will be as
1353
wide as the original, and 1/2 as high, containing all of the odd
1354
numbered scanlines. Phew!
1356
If you want libpng to expand the images, call this before calling
1357
png_start_read_image() or png_read_update_info():
1359
if (interlace_type == PNG_INTERLACE_ADAM7)
1361
= png_set_interlace_handling(png_ptr);
1363
This will return the number of passes needed. Currently, this
1364
is seven, but may change if another interlace type is added.
1365
This function can be called even if the file is not interlaced,
1366
where it will return one pass.
1368
If you are not going to display the image after each pass, but are
1369
going to wait until the entire image is read in, use the sparkle
1370
effect. This effect is faster and the end result of either method
1371
is exactly the same. If you are planning on displaying the image
1372
after each pass, the "rectangle" effect is generally considered the
1375
If you only want the "sparkle" effect, just call png_read_rows() as
1376
normal, with the third parameter NULL. Make sure you make pass over
1377
the image number_of_passes times, and you don't change the data in the
1378
rows between calls. You can change the locations of the data, just
1379
not the data. Each pass only writes the pixels appropriate for that
1380
pass, and assumes the data from previous passes is still valid.
1382
png_read_rows(png_ptr, row_pointers, NULL,
1385
If you only want the first effect (the rectangles), do the same as
1386
before except pass the row buffer in the third parameter, and leave
1387
the second parameter NULL.
1389
png_read_rows(png_ptr, NULL, row_pointers,
1392
Finishing a sequential read
1394
After you are finished reading the image through the
1395
low-level interface, you can finish reading the file. If you are
1396
interested in comments or time, which may be stored either before or
1397
after the image data, you should pass the separate png_info struct if
1398
you want to keep the comments from before and after the image
1399
separate. If you are not interested, you can pass NULL.
1401
png_read_end(png_ptr, end_info);
1403
When you are done, you can free all memory allocated by libpng like this:
1405
png_destroy_read_struct(&png_ptr, &info_ptr,
1408
It is also possible to individually free the info_ptr members that
1409
point to libpng-allocated storage with the following function:
1411
png_free_data(png_ptr, info_ptr, mask, seq)
1412
mask - identifies data to be freed, a mask
1413
containing the bitwise OR of one or
1415
PNG_FREE_PLTE, PNG_FREE_TRNS,
1416
PNG_FREE_HIST, PNG_FREE_ICCP,
1417
PNG_FREE_PCAL, PNG_FREE_ROWS,
1418
PNG_FREE_SCAL, PNG_FREE_SPLT,
1419
PNG_FREE_TEXT, PNG_FREE_UNKN,
1420
or simply PNG_FREE_ALL
1421
seq - sequence number of item to be freed
1424
This function may be safely called when the relevant storage has
1425
already been freed, or has not yet been allocated, or was allocated
1426
by the user and not by libpng, and will in those cases do nothing.
1427
The "seq" parameter is ignored if only one item of the selected data
1428
type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
1429
are allowed for the data type identified in the mask, such as text or
1430
sPLT, only the n'th item in the structure is freed, where n is "seq".
1432
The default behavior is only to free data that was allocated internally
1433
by libpng. This can be changed, so that libpng will not free the data,
1434
or so that it will free data that was allocated by the user with png_malloc()
1435
or png_zalloc() and passed in via a png_set_*() function, with
1437
png_data_freer(png_ptr, info_ptr, freer, mask)
1438
mask - which data elements are affected
1439
same choices as in png_free_data()
1441
PNG_DESTROY_WILL_FREE_DATA
1442
PNG_SET_WILL_FREE_DATA
1443
PNG_USER_WILL_FREE_DATA
1445
This function only affects data that has already been allocated.
1446
You can call this function after reading the PNG data but before calling
1447
any png_set_*() functions, to control whether the user or the png_set_*()
1448
function is responsible for freeing any existing data that might be present,
1449
and again after the png_set_*() functions to control whether the user
1450
or png_destroy_*() is supposed to free the data. When the user assumes
1451
responsibility for libpng-allocated data, the application must use
1452
png_free() to free it, and when the user transfers responsibility to libpng
1453
for data that the user has allocated, the user must have used png_malloc()
1454
or png_zalloc() to allocate it.
1456
If you allocated your row_pointers in a single block, as suggested above in
1457
the description of the high level read interface, you must not transfer
1458
responsibility for freeing it to the png_set_rows or png_read_destroy function,
1459
because they would also try to free the individual row_pointers[i].
1461
If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
1462
separately, do not transfer responsibility for freeing text_ptr to libpng,
1463
because when libpng fills a png_text structure it combines these members with
1464
the key member, and png_free_data() will free only text_ptr.key. Similarly,
1465
if you transfer responsibility for free'ing text_ptr from libpng to your
1466
application, your application must not separately free those members.
1468
The png_free_data() function will turn off the "valid" flag for anything
1469
it frees. If you need to turn the flag off for a chunk that was freed by
1470
your application instead of by libpng, you can use
1472
png_set_invalid(png_ptr, info_ptr, mask);
1473
mask - identifies the chunks to be made invalid,
1474
containing the bitwise OR of one or
1476
PNG_INFO_gAMA, PNG_INFO_sBIT,
1477
PNG_INFO_cHRM, PNG_INFO_PLTE,
1478
PNG_INFO_tRNS, PNG_INFO_bKGD,
1479
PNG_INFO_hIST, PNG_INFO_pHYs,
1480
PNG_INFO_oFFs, PNG_INFO_tIME,
1481
PNG_INFO_pCAL, PNG_INFO_sRGB,
1482
PNG_INFO_iCCP, PNG_INFO_sPLT,
1483
PNG_INFO_sCAL, PNG_INFO_IDAT
1485
For a more compact example of reading a PNG image, see the file example.c.
1487
Reading PNG files progressively
1489
The progressive reader is slightly different then the non-progressive
1490
reader. Instead of calling png_read_info(), png_read_rows(), and
1491
png_read_end(), you make one call to png_process_data(), which calls
1492
callbacks when it has the info, a row, or the end of the image. You
1493
set up these callbacks with png_set_progressive_read_fn(). You don't
1494
have to worry about the input/output functions of libpng, as you are
1495
giving the library the data directly in png_process_data(). I will
1496
assume that you have read the section on reading PNG files above,
1497
so I will only highlight the differences (although I will show
1500
png_structp png_ptr;
1503
/* An example code fragment of how you would
1504
initialize the progressive reader in your
1507
initialize_png_reader()
1509
png_ptr = png_create_read_struct
1510
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1511
user_error_fn, user_warning_fn);
1514
info_ptr = png_create_info_struct(png_ptr);
1517
png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
1522
if (setjmp(png_jmpbuf(png_ptr)))
1524
png_destroy_read_struct(&png_ptr, &info_ptr,
1529
/* This one's new. You can provide functions
1530
to be called when the header info is valid,
1531
when each row is completed, and when the image
1532
is finished. If you aren't using all functions,
1533
you can specify NULL parameters. Even when all
1534
three functions are NULL, you need to call
1535
png_set_progressive_read_fn(). You can use
1536
any struct as the user_ptr (cast to a void pointer
1537
for the function call), and retrieve the pointer
1538
from inside the callbacks using the function
1540
png_get_progressive_ptr(png_ptr);
1542
which will return a void pointer, which you have
1543
to cast appropriately.
1545
png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
1546
info_callback, row_callback, end_callback);
1551
/* A code fragment that you call as you receive blocks
1554
process_data(png_bytep buffer, png_uint_32 length)
1556
if (setjmp(png_jmpbuf(png_ptr)))
1558
png_destroy_read_struct(&png_ptr, &info_ptr,
1563
/* This one's new also. Simply give it a chunk
1564
of data from the file stream (in order, of
1565
course). On machines with segmented memory
1566
models machines, don't give it any more than
1567
64K. The library seems to run fine with sizes
1568
of 4K. Although you can give it much less if
1569
necessary (I assume you can give it chunks of
1570
1 byte, I haven't tried less then 256 bytes
1571
yet). When this function returns, you may
1572
want to display any rows that were generated
1573
in the row callback if you don't already do
1576
png_process_data(png_ptr, info_ptr, buffer, length);
1580
/* This function is called (as set by
1581
png_set_progressive_read_fn() above) when enough data
1582
has been supplied so all of the header has been
1586
info_callback(png_structp png_ptr, png_infop info)
1588
/* Do any setup here, including setting any of
1589
the transformations mentioned in the Reading
1590
PNG files section. For now, you _must_ call
1591
either png_start_read_image() or
1592
png_read_update_info() after all the
1593
transformations are set (even if you don't set
1594
any). You may start getting rows before
1595
png_process_data() returns, so this is your
1596
last chance to prepare for that.
1600
/* This function is called when each row of image
1603
row_callback(png_structp png_ptr, png_bytep new_row,
1604
png_uint_32 row_num, int pass)
1606
/* If the image is interlaced, and you turned
1607
on the interlace handler, this function will
1608
be called for every row in every pass. Some
1609
of these rows will not be changed from the
1610
previous pass. When the row is not changed,
1611
the new_row variable will be NULL. The rows
1612
and passes are called in order, so you don't
1613
really need the row_num and pass, but I'm
1614
supplying them because it may make your life
1617
For the non-NULL rows of interlaced images,
1618
you must call png_progressive_combine_row()
1619
passing in the row and the old row. You can
1620
call this function for NULL rows (it will just
1621
return) and for non-interlaced images (it just
1622
does the memcpy for you) if it will make the
1623
code easier. Thus, you can just do this for
1627
png_progressive_combine_row(png_ptr, old_row,
1630
/* where old_row is what was displayed for
1631
previously for the row. Note that the first
1632
pass (pass == 0, really) will completely cover
1633
the old row, so the rows do not have to be
1634
initialized. After the first pass (and only
1635
for interlaced images), you will have to pass
1636
the current row, and the function will combine
1637
the old row and the new row.
1642
end_callback(png_structp png_ptr, png_infop info)
1644
/* This function is called after the whole image
1645
has been read, including any chunks after the
1646
image (up to and including the IEND). You
1647
will usually have the same info chunk as you
1648
had in the header, although some data may have
1649
been added to the comments and time fields.
1651
Most people won't do much here, perhaps setting
1652
a flag that marks the image as finished.
1660
Much of this is very similar to reading. However, everything of
1661
importance is repeated here, so you won't have to constantly look
1662
back up in the reading section to understand writing.
1666
You will want to do the I/O initialization before you get into libpng,
1667
so if it doesn't work, you don't have anything to undo. If you are not
1668
using the standard I/O functions, you will need to replace them with
1669
custom writing functions. See the discussion under Customizing libpng.
1671
FILE *fp = fopen(file_name, "wb");
1677
Next, png_struct and png_info need to be allocated and initialized.
1678
As these can be both relatively large, you may not want to store these
1679
on the stack, unless you have stack space to spare. Of course, you
1680
will want to check if they return NULL. If you are also reading,
1681
you won't want to name your read structure and your write structure
1682
both "png_ptr"; you can call them anything you like, such as
1683
"read_ptr" and "write_ptr". Look at pngtest.c, for example.
1685
png_structp png_ptr = png_create_write_struct
1686
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1687
user_error_fn, user_warning_fn);
1691
png_infop info_ptr = png_create_info_struct(png_ptr);
1694
png_destroy_write_struct(&png_ptr,
1699
If you want to use your own memory allocation routines,
1700
define PNG_USER_MEM_SUPPORTED and use
1701
png_create_write_struct_2() instead of png_create_write_struct():
1703
png_structp png_ptr = png_create_write_struct_2
1704
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1705
user_error_fn, user_warning_fn, (png_voidp)
1706
user_mem_ptr, user_malloc_fn, user_free_fn);
1708
After you have these structures, you will need to set up the
1709
error handling. When libpng encounters an error, it expects to
1710
longjmp() back to your routine. Therefore, you will need to call
1711
setjmp() and pass the png_jmpbuf(png_ptr). If you
1712
write the file from different routines, you will need to update
1713
the png_jmpbuf(png_ptr) every time you enter a new routine that will
1714
call a png_*() function. See your documentation of setjmp/longjmp
1715
for your compiler for more information on setjmp/longjmp. See
1716
the discussion on libpng error handling in the Customizing Libpng
1717
section below for more information on the libpng error handling.
1719
if (setjmp(png_jmpbuf(png_ptr)))
1721
png_destroy_write_struct(&png_ptr, &info_ptr);
1728
If you would rather avoid the complexity of setjmp/longjmp issues,
1729
you can compile libpng with PNG_NO_SETJMP, in which case
1730
errors will result in a call to PNG_ABORT() which defaults to abort().
1732
You can #define PNG_ABORT() to a function that does something
1733
more useful than abort(), as long as your function does not
1736
Now you need to set up the output code. The default for libpng is to
1737
use the C function fwrite(). If you use this, you will need to pass a
1738
valid FILE * in the function png_init_io(). Be sure that the file is
1739
opened in binary mode. Again, if you wish to handle writing data in
1740
another way, see the discussion on libpng I/O handling in the Customizing
1741
Libpng section below.
1743
png_init_io(png_ptr, fp);
1745
If you are embedding your PNG into a datastream such as MNG, and don't
1746
want libpng to write the 8-byte signature, or if you have already
1747
written the signature in your application, use
1749
png_set_sig_bytes(png_ptr, 8);
1751
to inform libpng that it should not write a signature.
1755
At this point, you can set up a callback function that will be
1756
called after each row has been written, which you can use to control
1757
a progress meter or the like. It's demonstrated in pngtest.c.
1758
You must supply a function
1760
void write_row_callback(png_ptr, png_uint_32 row,
1763
/* put your code here */
1766
(You can give it another name that you like instead of "write_row_callback")
1768
To inform libpng about your function, use
1770
png_set_write_status_fn(png_ptr, write_row_callback);
1772
You now have the option of modifying how the compression library will
1773
run. The following functions are mainly for testing, but may be useful
1774
in some cases, like if you need to write PNG files extremely fast and
1775
are willing to give up some compression, or if you want to get the
1776
maximum possible compression at the expense of slower writing. If you
1777
have no special needs in this area, let the library do what it wants by
1778
not calling this function at all, as it has been tuned to deliver a good
1779
speed/compression ratio. The second parameter to png_set_filter() is
1780
the filter method, for which the only valid values are 0 (as of the
1781
July 1999 PNG specification, version 1.2) or 64 (if you are writing
1782
a PNG datastream that is to be embedded in a MNG datastream). The third
1783
parameter is a flag that indicates which filter type(s) are to be tested
1784
for each scanline. See the PNG specification for details on the specific
1788
/* turn on or off filtering, and/or choose
1789
specific filters. You can use either a single
1790
PNG_FILTER_VALUE_NAME or the bitwise OR of one
1791
or more PNG_FILTER_NAME masks. */
1792
png_set_filter(png_ptr, 0,
1793
PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
1794
PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
1795
PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
1796
PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |
1797
PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
1801
wants to start and stop using particular filters during compression,
1802
it should start out with all of the filters (to ensure that the previous
1803
row of pixels will be stored in case it's needed later), and then add
1804
and remove them after the start of compression.
1806
If you are writing a PNG datastream that is to be embedded in a MNG
1807
datastream, the second parameter can be either 0 or 64.
1809
The png_set_compression_*() functions interface to the zlib compression
1810
library, and should mostly be ignored unless you really know what you are
1811
doing. The only generally useful call is png_set_compression_level()
1812
which changes how much time zlib spends on trying to compress the image
1813
data. See the Compression Library (zlib.h and algorithm.txt, distributed
1814
with zlib) for details on the compression levels.
1816
/* set the zlib compression level */
1817
png_set_compression_level(png_ptr,
1818
Z_BEST_COMPRESSION);
1820
/* set other zlib parameters */
1821
png_set_compression_mem_level(png_ptr, 8);
1822
png_set_compression_strategy(png_ptr,
1823
Z_DEFAULT_STRATEGY);
1824
png_set_compression_window_bits(png_ptr, 15);
1825
png_set_compression_method(png_ptr, 8);
1826
png_set_compression_buffer_size(png_ptr, 8192)
1828
extern PNG_EXPORT(void,png_set_zbuf_size)
1830
Setting the contents of info for output
1832
You now need to fill in the png_info structure with all the data you
1833
wish to write before the actual image. Note that the only thing you
1834
are allowed to write after the image is the text chunks and the time
1835
chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
1836
the latest PNG specification for more information on that. If you
1837
wish to write them before the image, fill them in now, and flag that
1838
data as being valid. If you want to wait until after the data, don't
1839
fill them until png_write_end(). For all the fields in png_info and
1840
their data types, see png.h. For explanations of what the fields
1841
contain, see the PNG specification.
1843
Some of the more important parts of the png_info are:
1845
png_set_IHDR(png_ptr, info_ptr, width, height,
1846
bit_depth, color_type, interlace_type,
1847
compression_type, filter_method)
1848
width - holds the width of the image
1849
in pixels (up to 2^31).
1850
height - holds the height of the image
1851
in pixels (up to 2^31).
1852
bit_depth - holds the bit depth of one of the
1854
(valid values are 1, 2, 4, 8, 16
1855
and depend also on the
1856
color_type. See also significant
1858
color_type - describes which color/alpha
1859
channels are present.
1861
(bit depths 1, 2, 4, 8, 16)
1862
PNG_COLOR_TYPE_GRAY_ALPHA
1864
PNG_COLOR_TYPE_PALETTE
1865
(bit depths 1, 2, 4, 8)
1868
PNG_COLOR_TYPE_RGB_ALPHA
1871
PNG_COLOR_MASK_PALETTE
1872
PNG_COLOR_MASK_COLOR
1873
PNG_COLOR_MASK_ALPHA
1875
interlace_type - PNG_INTERLACE_NONE or
1877
compression_type - (must be
1878
PNG_COMPRESSION_TYPE_DEFAULT)
1879
filter_method - (must be PNG_FILTER_TYPE_DEFAULT
1880
or, if you are writing a PNG to
1881
be embedded in a MNG datastream,
1883
PNG_INTRAPIXEL_DIFFERENCING)
1885
If you call png_set_IHDR(), the call must appear before any of the
1886
other png_set_*() functions, because they might require access to some of
1887
the IHDR settings. The remaining png_set_*() functions can be called
1890
If you wish, you can reset the compression_type, interlace_type, or
1891
filter_method later by calling png_set_IHDR() again; if you do this, the
1892
width, height, bit_depth, and color_type must be the same in each call.
1894
png_set_PLTE(png_ptr, info_ptr, palette,
1896
palette - the palette for the file
1897
(array of png_color)
1898
num_palette - number of entries in the palette
1900
png_set_gAMA(png_ptr, info_ptr, gamma);
1901
gamma - the gamma the image was created
1904
png_set_sRGB(png_ptr, info_ptr, srgb_intent);
1905
srgb_intent - the rendering intent
1906
(PNG_INFO_sRGB) The presence of
1907
the sRGB chunk means that the pixel
1908
data is in the sRGB color space.
1909
This chunk also implies specific
1910
values of gAMA and cHRM. Rendering
1911
intent is the CSS-1 property that
1912
has been defined by the International
1914
(http://www.color.org).
1916
PNG_sRGB_INTENT_SATURATION,
1917
PNG_sRGB_INTENT_PERCEPTUAL,
1918
PNG_sRGB_INTENT_ABSOLUTE, or
1919
PNG_sRGB_INTENT_RELATIVE.
1922
png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
1924
srgb_intent - the rendering intent
1925
(PNG_INFO_sRGB) The presence of the
1926
sRGB chunk means that the pixel
1927
data is in the sRGB color space.
1928
This function also causes gAMA and
1929
cHRM chunks with the specific values
1930
that are consistent with sRGB to be
1933
png_set_iCCP(png_ptr, info_ptr, name, compression_type,
1935
name - The profile name.
1936
compression - The compression type; always
1937
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1938
You may give NULL to this argument to
1940
profile - International Color Consortium color
1941
profile data. May contain NULs.
1942
proflen - length of profile data in bytes.
1944
png_set_sBIT(png_ptr, info_ptr, sig_bit);
1945
sig_bit - the number of significant bits for
1946
(PNG_INFO_sBIT) each of the gray, red,
1947
green, and blue channels, whichever are
1948
appropriate for the given color type
1951
png_set_tRNS(png_ptr, info_ptr, trans_alpha,
1952
num_trans, trans_color);
1953
trans_alpha - array of alpha (transparency)
1954
entries for palette (PNG_INFO_tRNS)
1955
trans_color - graylevel or color sample values
1956
(in order red, green, blue) of the
1957
single transparent color for
1958
non-paletted images (PNG_INFO_tRNS)
1959
num_trans - number of transparent entries
1962
png_set_hIST(png_ptr, info_ptr, hist);
1964
hist - histogram of palette (array of
1967
png_set_tIME(png_ptr, info_ptr, mod_time);
1968
mod_time - time image was last modified
1971
png_set_bKGD(png_ptr, info_ptr, background);
1972
background - background color (PNG_VALID_bKGD)
1974
png_set_text(png_ptr, info_ptr, text_ptr, num_text);
1975
text_ptr - array of png_text holding image
1977
text_ptr[i].compression - type of compression used
1978
on "text" PNG_TEXT_COMPRESSION_NONE
1979
PNG_TEXT_COMPRESSION_zTXt
1980
PNG_ITXT_COMPRESSION_NONE
1981
PNG_ITXT_COMPRESSION_zTXt
1982
text_ptr[i].key - keyword for comment. Must contain
1984
text_ptr[i].text - text comments for current
1985
keyword. Can be NULL or empty.
1986
text_ptr[i].text_length - length of text string,
1987
after decompression, 0 for iTXt
1988
text_ptr[i].itxt_length - length of itxt string,
1989
after decompression, 0 for tEXt/zTXt
1990
text_ptr[i].lang - language of comment (NULL or
1992
text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
1993
or empty for unknown).
1994
Note that the itxt_length, lang, and lang_key
1995
members of the text_ptr structure only exist
1996
when the library is built with iTXt chunk support.
1998
num_text - number of comments
2000
png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
2002
palette_ptr - array of png_sPLT_struct structures
2003
to be added to the list of palettes
2004
in the info structure.
2005
num_spalettes - number of palette structures to be
2008
png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
2010
offset_x - positive offset from the left
2012
offset_y - positive offset from the top
2014
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2016
png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2018
res_x - pixels/unit physical resolution
2020
res_y - pixels/unit physical resolution
2022
unit_type - PNG_RESOLUTION_UNKNOWN,
2023
PNG_RESOLUTION_METER
2025
png_set_sCAL(png_ptr, info_ptr, unit, width, height)
2026
unit - physical scale units (an integer)
2027
width - width of a pixel in physical scale units
2028
height - height of a pixel in physical scale units
2029
(width and height are doubles)
2031
png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2032
unit - physical scale units (an integer)
2033
width - width of a pixel in physical scale units
2034
height - height of a pixel in physical scale units
2035
(width and height are strings like "2.54")
2037
png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
2039
unknowns - array of png_unknown_chunk
2040
structures holding unknown chunks
2041
unknowns[i].name - name of unknown chunk
2042
unknowns[i].data - data of unknown chunk
2043
unknowns[i].size - size of unknown chunk's data
2044
unknowns[i].location - position to write chunk in file
2045
0: do not write chunk
2046
PNG_HAVE_IHDR: before PLTE
2047
PNG_HAVE_PLTE: before IDAT
2048
PNG_AFTER_IDAT: after IDAT
2050
The "location" member is set automatically according to
2051
what part of the output file has already been written.
2052
You can change its value after calling png_set_unknown_chunks()
2053
as demonstrated in pngtest.c. Within each of the "locations",
2054
the chunks are sequenced according to their position in the
2055
structure (that is, the value of "i", which is the order in which
2056
the chunk was either read from the input file or defined with
2057
png_set_unknown_chunks).
2059
A quick word about text and num_text. text is an array of png_text
2060
structures. num_text is the number of valid structures in the array.
2061
Each png_text structure holds a language code, a keyword, a text value,
2062
and a compression type.
2064
The compression types have the same valid numbers as the compression
2065
types of the image data. Currently, the only valid number is zero.
2066
However, you can store text either compressed or uncompressed, unlike
2067
images, which always have to be compressed. So if you don't want the
2068
text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
2069
Because tEXt and zTXt chunks don't have a language field, if you
2070
specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
2071
any language code or translated keyword will not be written out.
2073
Until text gets around 1000 bytes, it is not worth compressing it.
2074
After the text has been written out to the file, the compression type
2075
is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
2076
so that it isn't written out again at the end (in case you are calling
2077
png_write_end() with the same struct.
2079
The keywords that are given in the PNG Specification are:
2081
Title Short (one line) title or
2083
Author Name of image's creator
2084
Description Description of image (possibly long)
2085
Copyright Copyright notice
2086
Creation Time Time of original image creation
2087
(usually RFC 1123 format, see below)
2088
Software Software used to create the image
2089
Disclaimer Legal disclaimer
2090
Warning Warning of nature of content
2091
Source Device used to create the image
2092
Comment Miscellaneous comment; conversion
2093
from other image format
2095
The keyword-text pairs work like this. Keywords should be short
2096
simple descriptions of what the comment is about. Some typical
2097
keywords are found in the PNG specification, as is some recommendations
2098
on keywords. You can repeat keywords in a file. You can even write
2099
some text before the image and some after. For example, you may want
2100
to put a description of the image before the image, but leave the
2101
disclaimer until after, so viewers working over modem connections
2102
don't have to wait for the disclaimer to go over the modem before
2103
they start seeing the image. Finally, keywords should be full
2104
words, not abbreviations. Keywords and text are in the ISO 8859-1
2105
(Latin-1) character set (a superset of regular ASCII) and can not
2106
contain NUL characters, and should not contain control or other
2107
unprintable characters. To make the comments widely readable, stick
2108
with basic ASCII, and avoid machine specific character set extensions
2109
like the IBM-PC character set. The keyword must be present, but
2110
you can leave off the text string on non-compressed pairs.
2111
Compressed pairs must have a text string, as only the text string
2112
is compressed anyway, so the compression would be meaningless.
2114
PNG supports modification time via the png_time structure. Two
2115
conversion routines are provided, png_convert_from_time_t() for
2116
time_t and png_convert_from_struct_tm() for struct tm. The
2117
time_t routine uses gmtime(). You don't have to use either of
2118
these, but if you wish to fill in the png_time structure directly,
2119
you should provide the time in universal time (GMT) if possible
2120
instead of your local time. Note that the year number is the full
2121
year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
2122
that months start with 1.
2124
If you want to store the time of the original image creation, you should
2125
use a plain tEXt chunk with the "Creation Time" keyword. This is
2126
necessary because the "creation time" of a PNG image is somewhat vague,
2127
depending on whether you mean the PNG file, the time the image was
2128
created in a non-PNG format, a still photo from which the image was
2129
scanned, or possibly the subject matter itself. In order to facilitate
2130
machine-readable dates, it is recommended that the "Creation Time"
2131
tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
2132
although this isn't a requirement. Unlike the tIME chunk, the
2133
"Creation Time" tEXt chunk is not expected to be automatically changed
2134
by the software. To facilitate the use of RFC 1123 dates, a function
2135
png_convert_to_rfc1123(png_timep) is provided to convert from PNG
2136
time to an RFC 1123 format string.
2138
Writing unknown chunks
2140
You can use the png_set_unknown_chunks function to queue up chunks
2141
for writing. You give it a chunk name, raw data, and a size; that's
2142
all there is to it. The chunks will be written by the next following
2143
png_write_info_before_PLTE, png_write_info, or png_write_end function.
2144
Any chunks previously read into the info structure's unknown-chunk
2145
list will also be written out in a sequence that satisfies the PNG
2146
specification's ordering rules.
2148
The high-level write interface
2150
At this point there are two ways to proceed; through the high-level
2151
write interface, or through a sequence of low-level write operations.
2152
You can use the high-level interface if your image data is present
2153
in the info structure. All defined output
2154
transformations are permitted, enabled by the following masks.
2156
PNG_TRANSFORM_IDENTITY No transformation
2157
PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
2158
PNG_TRANSFORM_PACKSWAP Change order of packed
2160
PNG_TRANSFORM_INVERT_MONO Invert monochrome images
2161
PNG_TRANSFORM_SHIFT Normalize pixels to the
2163
PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
2165
PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
2167
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
2169
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
2170
PNG_TRANSFORM_STRIP_FILLER Strip out filler
2172
PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
2174
PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing
2177
If you have valid image data in the info structure (you can use
2178
png_set_rows() to put image data in the info structure), simply do this:
2180
png_write_png(png_ptr, info_ptr, png_transforms, NULL)
2182
where png_transforms is an integer containing the bitwise OR of some set of
2183
transformation flags. This call is equivalent to png_write_info(),
2184
followed the set of transformations indicated by the transform mask,
2185
then png_write_image(), and finally png_write_end().
2187
(The final parameter of this call is not yet used. Someday it might point
2188
to transformation parameters required by some future output transform.)
2190
You must use png_transforms and not call any png_set_transform() functions
2191
when you use png_write_png().
2193
The low-level write interface
2195
If you are going the low-level route instead, you are now ready to
2196
write all the file information up to the actual image data. You do
2197
this with a call to png_write_info().
2199
png_write_info(png_ptr, info_ptr);
2201
Note that there is one transformation you may need to do before
2202
png_write_info(). In PNG files, the alpha channel in an image is the
2203
level of opacity. If your data is supplied as a level of transparency,
2204
you can invert the alpha channel before you write it, so that 0 is
2205
fully transparent and 255 (in 8-bit or paletted images) or 65535
2206
(in 16-bit images) is fully opaque, with
2208
png_set_invert_alpha(png_ptr);
2210
This must appear before png_write_info() instead of later with the
2211
other transformations because in the case of paletted images the tRNS
2212
chunk data has to be inverted before the tRNS chunk is written. If
2213
your image is not a paletted image, the tRNS data (which in such cases
2214
represents a single color to be rendered as transparent) won't need to
2215
be changed, and you can safely do this transformation after your
2216
png_write_info() call.
2218
If you need to write a private chunk that you want to appear before
2219
the PLTE chunk when PLTE is present, you can write the PNG info in
2220
two steps, and insert code to write your own chunk between them:
2222
png_write_info_before_PLTE(png_ptr, info_ptr);
2223
png_set_unknown_chunks(png_ptr, info_ptr, ...);
2224
png_write_info(png_ptr, info_ptr);
2226
After you've written the file information, you can set up the library
2227
to handle any special transformations of the image data. The various
2228
ways to transform the data will be described in the order that they
2229
should occur. This is important, as some of these change the color
2230
type and/or bit depth of the data, and some others only work on
2231
certain color types and bit depths. Even though each transformation
2232
checks to see if it has data that it can do something with, you should
2233
make sure to only enable a transformation if it will be valid for the
2234
data. For example, don't swap red and blue on grayscale data.
2236
PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
2237
the library to strip input data that has 4 or 8 bytes per pixel down
2238
to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
2241
png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
2243
where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
2244
PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
2245
is stored XRGB or RGBX.
2247
PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
2248
they can, resulting in, for example, 8 pixels per byte for 1 bit files.
2249
If the data is supplied at 1 pixel per byte, use this code, which will
2250
correctly pack the pixels into a single byte:
2252
png_set_packing(png_ptr);
2254
PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
2255
data is of another bit depth, you can write an sBIT chunk into the
2256
file so that decoders can recover the original data if desired.
2258
/* Set the true bit depth of the image data */
2259
if (color_type & PNG_COLOR_MASK_COLOR)
2261
sig_bit.red = true_bit_depth;
2262
sig_bit.green = true_bit_depth;
2263
sig_bit.blue = true_bit_depth;
2267
sig_bit.gray = true_bit_depth;
2269
if (color_type & PNG_COLOR_MASK_ALPHA)
2271
sig_bit.alpha = true_bit_depth;
2274
png_set_sBIT(png_ptr, info_ptr, &sig_bit);
2276
If the data is stored in the row buffer in a bit depth other than
2277
one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
2278
this will scale the values to appear to be the correct bit depth as
2281
png_set_shift(png_ptr, &sig_bit);
2283
PNG files store 16 bit pixels in network byte order (big-endian,
2284
ie. most significant bits first). This code would be used if they are
2285
supplied the other way (little-endian, i.e. least significant bits
2286
first, the way PCs store them):
2289
png_set_swap(png_ptr);
2291
If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2292
need to change the order the pixels are packed into bytes, you can use:
2295
png_set_packswap(png_ptr);
2297
PNG files store 3 color pixels in red, green, blue order. This code
2298
would be used if they are supplied as blue, green, red:
2300
png_set_bgr(png_ptr);
2302
PNG files describe monochrome as black being zero and white being
2303
one. This code would be used if the pixels are supplied with this reversed
2304
(black being one and white being zero):
2306
png_set_invert_mono(png_ptr);
2308
Finally, you can write your own transformation function if none of
2309
the existing ones meets your needs. This is done by setting a callback
2312
png_set_write_user_transform_fn(png_ptr,
2313
write_transform_fn);
2315
You must supply the function
2317
void write_transform_fn(png_ptr ptr, row_info_ptr
2318
row_info, png_bytep data)
2320
See pngtest.c for a working example. Your function will be called
2321
before any of the other transformations are processed.
2323
You can also set up a pointer to a user structure for use by your
2326
png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
2328
The user_channels and user_depth parameters of this function are ignored
2329
when writing; you can set them to zero as shown.
2331
You can retrieve the pointer via the function png_get_user_transform_ptr().
2334
voidp write_user_transform_ptr =
2335
png_get_user_transform_ptr(png_ptr);
2337
It is possible to have libpng flush any pending output, either manually,
2338
or automatically after a certain number of lines have been written. To
2339
flush the output stream a single time call:
2341
png_write_flush(png_ptr);
2343
and to have libpng flush the output stream periodically after a certain
2344
number of scanlines have been written, call:
2346
png_set_flush(png_ptr, nrows);
2348
Note that the distance between rows is from the last time png_write_flush()
2349
was called, or the first row of the image if it has never been called.
2350
So if you write 50 lines, and then png_set_flush 25, it will flush the
2351
output on the next scanline, and every 25 lines thereafter, unless
2352
png_write_flush() is called before 25 more lines have been written.
2353
If nrows is too small (less than about 10 lines for a 640 pixel wide
2354
RGB image) the image compression may decrease noticeably (although this
2355
may be acceptable for real-time applications). Infrequent flushing will
2356
only degrade the compression performance by a few percent over images
2357
that do not use flushing.
2359
Writing the image data
2361
That's it for the transformations. Now you can write the image data.
2362
The simplest way to do this is in one function call. If you have the
2363
whole image in memory, you can just call png_write_image() and libpng
2364
will write the image. You will need to pass in an array of pointers to
2365
each row. This function automatically handles interlacing, so you don't
2366
need to call png_set_interlace_handling() or call this function multiple
2367
times, or any of that other stuff necessary with png_write_rows().
2369
png_write_image(png_ptr, row_pointers);
2371
where row_pointers is:
2373
png_byte *row_pointers[height];
2375
You can point to void or char or whatever you use for pixels.
2377
If you don't want to write the whole image at once, you can
2378
use png_write_rows() instead. If the file is not interlaced,
2381
png_write_rows(png_ptr, row_pointers,
2384
row_pointers is the same as in the png_write_image() call.
2386
If you are just writing one row at a time, you can do this with
2387
a single row_pointer instead of an array of row_pointers:
2389
png_bytep row_pointer = row;
2391
png_write_row(png_ptr, row_pointer);
2393
When the file is interlaced, things can get a good deal more complicated.
2394
The only currently (as of the PNG Specification version 1.2, dated July
2395
1999) defined interlacing scheme for PNG files is the "Adam7" interlace
2396
scheme, that breaks down an image into seven smaller images of varying
2397
size. libpng will build these images for you, or you can do them
2398
yourself. If you want to build them yourself, see the PNG specification
2399
for details of which pixels to write when.
2401
If you don't want libpng to handle the interlacing details, just
2402
use png_set_interlace_handling() and call png_write_rows() the
2403
correct number of times to write all seven sub-images.
2405
If you want libpng to build the sub-images, call this before you start
2409
png_set_interlace_handling(png_ptr);
2411
This will return the number of passes needed. Currently, this is seven,
2412
but may change if another interlace type is added.
2414
Then write the complete image number_of_passes times.
2416
png_write_rows(png_ptr, row_pointers,
2419
As some of these rows are not used, and thus return immediately, you may
2420
want to read about interlacing in the PNG specification, and only update
2421
the rows that are actually used.
2423
Finishing a sequential write
2425
After you are finished writing the image, you should finish writing
2426
the file. If you are interested in writing comments or time, you should
2427
pass an appropriately filled png_info pointer. If you are not interested,
2430
png_write_end(png_ptr, info_ptr);
2432
When you are done, you can free all memory used by libpng like this:
2434
png_destroy_write_struct(&png_ptr, &info_ptr);
2436
It is also possible to individually free the info_ptr members that
2437
point to libpng-allocated storage with the following function:
2439
png_free_data(png_ptr, info_ptr, mask, seq)
2440
mask - identifies data to be freed, a mask
2441
containing the bitwise OR of one or
2443
PNG_FREE_PLTE, PNG_FREE_TRNS,
2444
PNG_FREE_HIST, PNG_FREE_ICCP,
2445
PNG_FREE_PCAL, PNG_FREE_ROWS,
2446
PNG_FREE_SCAL, PNG_FREE_SPLT,
2447
PNG_FREE_TEXT, PNG_FREE_UNKN,
2448
or simply PNG_FREE_ALL
2449
seq - sequence number of item to be freed
2452
This function may be safely called when the relevant storage has
2453
already been freed, or has not yet been allocated, or was allocated
2454
by the user and not by libpng, and will in those cases do nothing.
2455
The "seq" parameter is ignored if only one item of the selected data
2456
type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
2457
are allowed for the data type identified in the mask, such as text or
2458
sPLT, only the n'th item in the structure is freed, where n is "seq".
2460
If you allocated data such as a palette that you passed in to libpng
2461
with png_set_*, you must not free it until just before the call to
2462
png_destroy_write_struct().
2464
The default behavior is only to free data that was allocated internally
2465
by libpng. This can be changed, so that libpng will not free the data,
2466
or so that it will free data that was allocated by the user with png_malloc()
2467
or png_zalloc() and passed in via a png_set_*() function, with
2469
png_data_freer(png_ptr, info_ptr, freer, mask)
2470
mask - which data elements are affected
2471
same choices as in png_free_data()
2473
PNG_DESTROY_WILL_FREE_DATA
2474
PNG_SET_WILL_FREE_DATA
2475
PNG_USER_WILL_FREE_DATA
2477
For example, to transfer responsibility for some data from a read structure
2478
to a write structure, you could use
2480
png_data_freer(read_ptr, read_info_ptr,
2481
PNG_USER_WILL_FREE_DATA,
2482
PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2483
png_data_freer(write_ptr, write_info_ptr,
2484
PNG_DESTROY_WILL_FREE_DATA,
2485
PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2487
thereby briefly reassigning responsibility for freeing to the user but
2488
immediately afterwards reassigning it once more to the write_destroy
2489
function. Having done this, it would then be safe to destroy the read
2490
structure and continue to use the PLTE, tRNS, and hIST data in the write
2493
This function only affects data that has already been allocated.
2494
You can call this function before calling after the png_set_*() functions
2495
to control whether the user or png_destroy_*() is supposed to free the data.
2496
When the user assumes responsibility for libpng-allocated data, the
2497
application must use
2498
png_free() to free it, and when the user transfers responsibility to libpng
2499
for data that the user has allocated, the user must have used png_malloc()
2500
or png_zalloc() to allocate it.
2502
If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
2503
separately, do not transfer responsibility for freeing text_ptr to libpng,
2504
because when libpng fills a png_text structure it combines these members with
2505
the key member, and png_free_data() will free only text_ptr.key. Similarly,
2506
if you transfer responsibility for free'ing text_ptr from libpng to your
2507
application, your application must not separately free those members.
2508
For a more compact example of writing a PNG image, see the file example.c.
2510
V. Modifying/Customizing libpng:
2512
There are two issues here. The first is changing how libpng does
2513
standard things like memory allocation, input/output, and error handling.
2514
The second deals with more complicated things like adding new chunks,
2515
adding new transformations, and generally changing how libpng works.
2516
Both of those are compile-time issues; that is, they are generally
2517
determined at the time the code is written, and there is rarely a need
2518
to provide the user with a means of changing them.
2520
Memory allocation, input/output, and error handling
2522
All of the memory allocation, input/output, and error handling in libpng
2523
goes through callbacks that are user-settable. The default routines are
2524
in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
2525
these functions, call the appropriate png_set_*_fn() function.
2527
Memory allocation is done through the functions png_malloc(), png_calloc(),
2528
and png_free(). These currently just call the standard C functions.
2529
png_calloc() calls png_malloc() and then png_memset() to clear the newly
2530
allocated memory to zero. If your pointers can't access more then 64K
2531
at a time, you will want to set MAXSEG_64K in zlib.h. Since it is
2532
unlikely that the method of handling memory allocation on a platform
2533
will change between applications, these functions must be modified in
2534
the library at compile time. If you prefer to use a different method
2535
of allocating and freeing data, you can use png_create_read_struct_2() or
2536
png_create_write_struct_2() to register your own functions as described
2537
above. These functions also provide a void pointer that can be retrieved
2540
mem_ptr=png_get_mem_ptr(png_ptr);
2542
Your replacement memory functions must have prototypes as follows:
2544
png_voidp malloc_fn(png_structp png_ptr,
2545
png_alloc_size_t size);
2546
void free_fn(png_structp png_ptr, png_voidp ptr);
2548
Your malloc_fn() must return NULL in case of failure. The png_malloc()
2549
function will normally call png_error() if it receives a NULL from the
2550
system memory allocator or from your replacement malloc_fn().
2552
Your free_fn() will never be called with a NULL ptr, since libpng's
2553
png_free() checks for NULL before calling free_fn().
2555
Input/Output in libpng is done through png_read() and png_write(),
2556
which currently just call fread() and fwrite(). The FILE * is stored in
2557
png_struct and is initialized via png_init_io(). If you wish to change
2558
the method of I/O, the library supplies callbacks that you can set
2559
through the function png_set_read_fn() and png_set_write_fn() at run
2560
time, instead of calling the png_init_io() function. These functions
2561
also provide a void pointer that can be retrieved via the function
2562
png_get_io_ptr(). For example:
2564
png_set_read_fn(png_structp read_ptr,
2565
voidp read_io_ptr, png_rw_ptr read_data_fn)
2567
png_set_write_fn(png_structp write_ptr,
2568
voidp write_io_ptr, png_rw_ptr write_data_fn,
2569
png_flush_ptr output_flush_fn);
2571
voidp read_io_ptr = png_get_io_ptr(read_ptr);
2572
voidp write_io_ptr = png_get_io_ptr(write_ptr);
2574
The replacement I/O functions must have prototypes as follows:
2576
void user_read_data(png_structp png_ptr,
2577
png_bytep data, png_size_t length);
2578
void user_write_data(png_structp png_ptr,
2579
png_bytep data, png_size_t length);
2580
void user_flush_data(png_structp png_ptr);
2582
The user_read_data() function is responsible for detecting and
2583
handling end-of-data errors.
2585
Supplying NULL for the read, write, or flush functions sets them back
2586
to using the default C stream functions, which expect the io_ptr to
2587
point to a standard *FILE structure. It is probably a mistake
2588
to use NULL for one of write_data_fn and output_flush_fn but not both
2589
of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
2590
It is an error to read from a write stream, and vice versa.
2592
Error handling in libpng is done through png_error() and png_warning().
2593
Errors handled through png_error() are fatal, meaning that png_error()
2594
should never return to its caller. Currently, this is handled via
2595
setjmp() and longjmp() (unless you have compiled libpng with
2596
PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
2597
but you could change this to do things like exit() if you should wish,
2598
as long as your function does not return.
2600
On non-fatal errors, png_warning() is called
2601
to print a warning message, and then control returns to the calling code.
2602
By default png_error() and png_warning() print a message on stderr via
2603
fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
2604
(because you don't want the messages) or PNG_NO_STDIO defined (because
2605
fprintf() isn't available). If you wish to change the behavior of the error
2606
functions, you will need to set up your own message callbacks. These
2607
functions are normally supplied at the time that the png_struct is created.
2608
It is also possible to redirect errors and warnings to your own replacement
2609
functions after png_create_*_struct() has been called by calling:
2611
png_set_error_fn(png_structp png_ptr,
2612
png_voidp error_ptr, png_error_ptr error_fn,
2613
png_error_ptr warning_fn);
2615
png_voidp error_ptr = png_get_error_ptr(png_ptr);
2617
If NULL is supplied for either error_fn or warning_fn, then the libpng
2618
default function will be used, calling fprintf() and/or longjmp() if a
2619
problem is encountered. The replacement error functions should have
2620
parameters as follows:
2622
void user_error_fn(png_structp png_ptr,
2623
png_const_charp error_msg);
2624
void user_warning_fn(png_structp png_ptr,
2625
png_const_charp warning_msg);
2627
The motivation behind using setjmp() and longjmp() is the C++ throw and
2628
catch exception handling methods. This makes the code much easier to write,
2629
as there is no need to check every return code of every function call.
2630
However, there are some uncertainties about the status of local variables
2631
after a longjmp, so the user may want to be careful about doing anything
2632
after setjmp returns non-zero besides returning itself. Consult your
2633
compiler documentation for more details. For an alternative approach, you
2634
may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
2638
If you need to read or write custom chunks, you may need to get deeper
2639
into the libpng code. The library now has mechanisms for storing
2640
and writing chunks of unknown type; you can even declare callbacks
2641
for custom chunks. However, this may not be good enough if the
2642
library code itself needs to know about interactions between your
2643
chunk and existing `intrinsic' chunks.
2645
If you need to write a new intrinsic chunk, first read the PNG
2646
specification. Acquire a first level of understanding of how it works.
2647
Pay particular attention to the sections that describe chunk names,
2648
and look at how other chunks were designed, so you can do things
2649
similarly. Second, check out the sections of libpng that read and
2650
write chunks. Try to find a chunk that is similar to yours and use
2651
it as a template. More details can be found in the comments inside
2652
the code. It is best to handle unknown chunks in a generic method,
2653
via callback functions, instead of by modifying libpng functions.
2655
If you wish to write your own transformation for the data, look through
2656
the part of the code that does the transformations, and check out some of
2657
the simpler ones to get an idea of how they work. Try to find a similar
2658
transformation to the one you want to add and copy off of it. More details
2659
can be found in the comments inside the code itself.
2661
Configuring for 16 bit platforms
2663
You will want to look into zconf.h to tell zlib (and thus libpng) that
2664
it cannot allocate more then 64K at a time. Even if you can, the memory
2665
won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
2669
For DOS users who only have access to the lower 640K, you will
2670
have to limit zlib's memory usage via a png_set_compression_mem_level()
2671
call. See zlib.h or zconf.h in the zlib library for more information.
2673
Configuring for Medium Model
2675
Libpng's support for medium model has been tested on most of the popular
2676
compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
2677
defined, and FAR gets defined to far in pngconf.h, and you should be
2678
all set. Everything in the library (except for zlib's structure) is
2679
expecting far data. You must use the typedefs with the p or pp on
2680
the end for pointers (or at least look at them and be careful). Make
2681
note that the rows of data are defined as png_bytepp, which is an
2682
unsigned char far * far *.
2684
Configuring for gui/windowing platforms:
2686
You will need to write new error and warning functions that use the GUI
2687
interface, as described previously, and set them to be the error and
2688
warning functions at the time that png_create_*_struct() is called,
2689
in order to have them available during the structure initialization.
2690
They can be changed later via png_set_error_fn(). On some compilers,
2691
you may also have to change the memory allocators (png_malloc, etc.).
2693
Configuring for compiler xxx:
2695
All includes for libpng are in pngconf.h. If you need to add, change
2696
or delete an include, this is the place to do it.
2697
The includes that are not needed outside libpng are placed in pngpriv.h,
2698
which is only used by the routines inside libpng itself.
2699
The files in libpng proper only include pngpriv.h and png.h, which
2700
in turn includes pngconf.h.
2704
There are special functions to configure the compression. Perhaps the
2705
most useful one changes the compression level, which currently uses
2706
input compression values in the range 0 - 9. The library normally
2707
uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
2708
have shown that for a large majority of images, compression values in
2709
the range 3-6 compress nearly as well as higher levels, and do so much
2710
faster. For online applications it may be desirable to have maximum speed
2711
(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
2712
specify no compression (Z_NO_COMPRESSION = 0), but this would create
2713
files larger than just storing the raw bitmap. You can specify the
2714
compression level by calling:
2716
png_set_compression_level(png_ptr, level);
2718
Another useful one is to reduce the memory level used by the library.
2719
The memory level defaults to 8, but it can be lowered if you are
2720
short on memory (running DOS, for example, where you only have 640K).
2721
Note that the memory level does have an effect on compression; among
2722
other things, lower levels will result in sections of incompressible
2723
data being emitted in smaller stored blocks, with a correspondingly
2724
larger relative overhead of up to 15% in the worst case.
2726
png_set_compression_mem_level(png_ptr, level);
2728
The other functions are for configuring zlib. They are not recommended
2729
for normal use and may result in writing an invalid PNG file. See
2730
zlib.h for more information on what these mean.
2732
png_set_compression_strategy(png_ptr,
2734
png_set_compression_window_bits(png_ptr,
2736
png_set_compression_method(png_ptr, method);
2737
png_set_compression_buffer_size(png_ptr, size);
2739
Controlling row filtering
2741
If you want to control whether libpng uses filtering or not, which
2742
filters are used, and how it goes about picking row filters, you
2743
can call one of these functions. The selection and configuration
2744
of row filters can have a significant impact on the size and
2745
encoding speed and a somewhat lesser impact on the decoding speed
2746
of an image. Filtering is enabled by default for RGB and grayscale
2747
images (with and without alpha), but not for paletted images nor
2748
for any images with bit depths less than 8 bits/pixel.
2750
The 'method' parameter sets the main filtering method, which is
2751
currently only '0' in the PNG 1.2 specification. The 'filters'
2752
parameter sets which filter(s), if any, should be used for each
2753
scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
2754
to turn filtering on and off, respectively.
2756
Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
2757
PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
2758
ORed together with '|' to specify one or more filters to use.
2759
These filters are described in more detail in the PNG specification.
2760
If you intend to change the filter type during the course of writing
2761
the image, you should start with flags set for all of the filters
2762
you intend to use so that libpng can initialize its internal
2763
structures appropriately for all of the filter types. (Note that this
2764
means the first row must always be adaptively filtered, because libpng
2765
currently does not allocate the filter buffers until png_write_row()
2766
is called for the first time.)
2768
filters = PNG_FILTER_NONE | PNG_FILTER_SUB
2769
PNG_FILTER_UP | PNG_FILTER_AVG |
2770
PNG_FILTER_PAETH | PNG_ALL_FILTERS;
2772
png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
2774
The second parameter can also be
2775
PNG_INTRAPIXEL_DIFFERENCING if you are
2776
writing a PNG to be embedded in a MNG
2777
datastream. This parameter must be the
2778
same as the value of filter_method used
2781
It is also possible to influence how libpng chooses from among the
2782
available filters. This is done in one or both of two ways - by
2783
telling it how important it is to keep the same filter for successive
2784
rows, and by telling it the relative computational costs of the filters.
2786
double weights[3] = {1.5, 1.3, 1.1},
2787
costs[PNG_FILTER_VALUE_LAST] =
2788
{1.0, 1.3, 1.3, 1.5, 1.7};
2790
png_set_filter_heuristics(png_ptr,
2791
PNG_FILTER_HEURISTIC_WEIGHTED, 3,
2794
The weights are multiplying factors that indicate to libpng that the
2795
row filter should be the same for successive rows unless another row filter
2796
is that many times better than the previous filter. In the above example,
2797
if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
2798
"sum of absolute differences" 1.5 x 1.3 times higher than other filters
2799
and still be chosen, while the NONE filter could have a sum 1.1 times
2800
higher than other filters and still be chosen. Unspecified weights are
2801
taken to be 1.0, and the specified weights should probably be declining
2802
like those above in order to emphasize recent filters over older filters.
2804
The filter costs specify for each filter type a relative decoding cost
2805
to be considered when selecting row filters. This means that filters
2806
with higher costs are less likely to be chosen over filters with lower
2807
costs, unless their "sum of absolute differences" is that much smaller.
2808
The costs do not necessarily reflect the exact computational speeds of
2809
the various filters, since this would unduly influence the final image
2812
Note that the numbers above were invented purely for this example and
2813
are given only to help explain the function usage. Little testing has
2814
been done to find optimum values for either the costs or the weights.
2816
Removing unwanted object code
2818
There are a bunch of #define's in pngconf.h that control what parts of
2819
libpng are compiled. All the defines end in _SUPPORTED. If you are
2820
never going to use a capability, you can change the #define to #undef
2821
before recompiling libpng and save yourself code and data space, or
2822
you can turn off individual capabilities with defines that begin with
2825
You can also turn all of the transforms and ancillary chunk capabilities
2826
off en masse with compiler directives that define
2827
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
2829
along with directives to turn on any of the capabilities that you do
2830
want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
2831
transformations but still leave the library fully capable of reading
2832
and writing PNG files with all known public chunks. Use of the
2833
PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
2834
that is incapable of reading or writing ancillary chunks. If you are
2835
not using the progressive reading capability, you can turn that off
2836
with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
2837
capability, which you'll still have).
2839
All the reading and writing specific code are in separate files, so the
2840
linker should only grab the files it needs. However, if you want to
2841
make sure, or if you are building a stand alone library, all the
2842
reading files start with pngr and all the writing files start with
2843
pngw. The files that don't match either (like png.c, pngtrans.c, etc.)
2844
are used for both reading and writing, and always need to be included.
2845
The progressive reader is in pngpread.c
2847
If you are creating or distributing a dynamically linked library (a .so
2848
or DLL file), you should not remove or disable any parts of the library,
2849
as this will cause applications linked with different versions of the
2850
library to fail if they call functions not available in your library.
2851
The size of the library itself should not be an issue, because only
2852
those sections that are actually used will be loaded into memory.
2854
Requesting debug printout
2856
The macro definition PNG_DEBUG can be used to request debugging
2857
printout. Set it to an integer value in the range 0 to 3. Higher
2858
numbers result in increasing amounts of debugging information. The
2859
information is printed to the "stderr" file, unless another file
2860
name is specified in the PNG_DEBUG_FILE macro definition.
2862
When PNG_DEBUG > 0, the following functions (macros) become available:
2864
png_debug(level, message)
2865
png_debug1(level, message, p1)
2866
png_debug2(level, message, p1, p2)
2868
in which "level" is compared to PNG_DEBUG to decide whether to print
2869
the message, "message" is the formatted string to be printed,
2870
and p1 and p2 are parameters that are to be embedded in the string
2871
according to printf-style formatting directives. For example,
2873
png_debug1(2, "foo=%d\n", foo);
2878
fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
2880
When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
2881
can still use PNG_DEBUG to control your own debugging:
2887
When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
2888
having level = 0 will be printed. There aren't any such statements in
2889
this version of libpng, but if you insert some they will be printed.
2893
The MNG specification (available at http://www.libpng.org/pub/mng) allows
2894
certain extensions to PNG for PNG images that are embedded in MNG datastreams.
2895
Libpng can support some of these extensions. To enable them, use the
2896
png_permit_mng_features() function:
2898
feature_set = png_permit_mng_features(png_ptr, mask)
2899
mask is a png_uint_32 containing the bitwise OR of the
2900
features you want to enable. These include
2901
PNG_FLAG_MNG_EMPTY_PLTE
2902
PNG_FLAG_MNG_FILTER_64
2903
PNG_ALL_MNG_FEATURES
2904
feature_set is a png_uint_32 that is the bitwise AND of
2905
your mask with the set of MNG features that is
2906
supported by the version of libpng that you are using.
2908
It is an error to use this function when reading or writing a standalone
2909
PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
2910
in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
2911
and the MHDR and MEND chunks. Libpng does not provide support for these
2912
or any other MNG chunks; your application must provide its own support for
2913
them. You may wish to consider using libmng (available at
2914
http://www.libmng.com) instead.
2916
VII. Changes to Libpng from version 0.88
2918
It should be noted that versions of libpng later than 0.96 are not
2919
distributed by the original libpng author, Guy Schalnat, nor by
2920
Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
2921
distributed versions 0.89 through 0.96, but rather by another member
2922
of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
2923
still alive and well, but they have moved on to other things.
2925
The old libpng functions png_read_init(), png_write_init(),
2926
png_info_init(), png_read_destroy(), and png_write_destroy() have been
2927
moved to PNG_INTERNAL in version 0.95 to discourage their use. These
2928
functions will be removed from libpng version 2.0.0.
2930
The preferred method of creating and initializing the libpng structures is
2931
via the png_create_read_struct(), png_create_write_struct(), and
2932
png_create_info_struct() because they isolate the size of the structures
2933
from the application, allow version error checking, and also allow the
2934
use of custom error handling routines during the initialization, which
2935
the old functions do not. The functions png_read_destroy() and
2936
png_write_destroy() do not actually free the memory that libpng
2937
allocated for these structs, but just reset the data structures, so they
2938
can be used instead of png_destroy_read_struct() and
2939
png_destroy_write_struct() if you feel there is too much system overhead
2940
allocating and freeing the png_struct for each image read.
2942
Setting the error callbacks via png_set_message_fn() before
2943
png_read_init() as was suggested in libpng-0.88 is no longer supported
2944
because this caused applications that do not use custom error functions
2945
to fail if the png_ptr was not initialized to zero. It is still possible
2946
to set the error callbacks AFTER png_read_init(), or to change them with
2947
png_set_error_fn(), which is essentially the same function, but with a new
2948
name to force compilation errors with applications that try to use the old
2951
Starting with version 1.0.7, you can find out which version of the library
2952
you are using at run-time:
2954
png_uint_32 libpng_vn = png_access_version_number();
2956
The number libpng_vn is constructed from the major version, minor
2957
version with leading zero, and release number with leading zero,
2958
(e.g., libpng_vn for version 1.0.7 is 10007).
2960
You can also check which version of png.h you used when compiling your
2963
png_uint_32 application_vn = PNG_LIBPNG_VER;
2965
VIII. Changes to Libpng from version 1.0.x to 1.2.x
2967
Support for user memory management was enabled by default. To
2968
accomplish this, the functions png_create_read_struct_2(),
2969
png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
2970
png_malloc_default(), and png_free_default() were added.
2972
Support for the iTXt chunk has been enabled by default as of
2975
Support for certain MNG features was enabled.
2977
Support for numbered error messages was added. However, we never got
2978
around to actually numbering the error messages. The function
2979
png_set_strip_error_numbers() was added (Note: the prototype for this
2980
function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
2981
builds of libpng-1.2.15. It was restored in libpng-1.2.36).
2983
The png_malloc_warn() function was added at libpng-1.2.3. This issues
2984
a png_warning and returns NULL instead of aborting when it fails to
2985
acquire the requested memory allocation.
2987
Support for setting user limits on image width and height was enabled
2988
by default. The functions png_set_user_limits(), png_get_user_width_max(),
2989
and png_get_user_height_max() were added at libpng-1.2.6.
2991
The png_set_add_alpha() function was added at libpng-1.2.7.
2993
The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
2994
Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
2995
tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
2998
A number of macro definitions in support of runtime selection of
2999
assembler code features (especially Intel MMX code support) were
3000
added at libpng-1.2.0:
3002
PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
3003
PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
3004
PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
3005
PNG_ASM_FLAG_MMX_READ_INTERLACE
3006
PNG_ASM_FLAG_MMX_READ_FILTER_SUB
3007
PNG_ASM_FLAG_MMX_READ_FILTER_UP
3008
PNG_ASM_FLAG_MMX_READ_FILTER_AVG
3009
PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
3010
PNG_ASM_FLAGS_INITIALIZED
3016
We added the following functions in support of runtime
3017
selection of assembler code features:
3019
png_get_mmx_flagmask()
3020
png_set_mmx_thresholds()
3022
png_get_mmx_bitdepth_threshold()
3023
png_get_mmx_rowbytes_threshold()
3026
We replaced all of these functions with simple stubs in libpng-1.2.20,
3027
when the Intel assembler code was removed due to a licensing issue.
3029
These macros are deprecated:
3031
PNG_READ_TRANSFORMS_NOT_SUPPORTED
3032
PNG_PROGRESSIVE_READ_NOT_SUPPORTED
3033
PNG_NO_SEQUENTIAL_READ_SUPPORTED
3034
PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
3035
PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
3036
PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
3038
They have been replaced, respectively, by:
3040
PNG_NO_READ_TRANSFORMS
3041
PNG_NO_PROGRESSIVE_READ
3042
PNG_NO_SEQUENTIAL_READ
3043
PNG_NO_WRITE_TRANSFORMS
3044
PNG_NO_READ_ANCILLARY_CHUNKS
3045
PNG_NO_WRITE_ANCILLARY_CHUNKS
3047
PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
3048
deprecated since libpng-1.0.16 and libpng-1.2.6.
3051
png_check_sig(sig, num)
3053
!png_sig_cmp(sig, 0, num)
3054
It has been deprecated since libpng-0.90.
3057
png_set_gray_1_2_4_to_8()
3058
which also expands tRNS to alpha was replaced with
3059
png_set_expand_gray_1_2_4_to_8()
3060
which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
3062
IX. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
3064
Private libpng prototypes and macro definitions were moved from
3065
png.h and pngconf.h into a new pngpriv.h header file.
3067
Functions png_set_benign_errors(), png_benign_error(), and
3068
png_chunk_benign_error() were added.
3070
Support for setting the maximum amount of memory that the application
3071
will allocate for reading chunks was added, as a security measure.
3072
The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
3073
were added to the library.
3075
We implemented support for I/O states by adding png_ptr member io_state
3076
and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
3078
We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
3081
Checking for and reporting of errors in the IHDR chunk is more thorough.
3083
Support for global arrays was removed, to improve thread safety.
3085
Some obsolete/deprecated macros and functions have been removed.
3087
Typecasted NULL definitions such as
3088
#define png_voidp_NULL (png_voidp)NULL
3089
were eliminated. If you used these in your application, just use
3092
The png_struct and info_struct members "trans" and "trans_values" were
3093
changed to "trans_alpha" and "trans_color", respectively.
3095
The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
3098
The PNG_1_0_X and PNG_1_2_X macros were eliminated.
3100
The PNG_LEGACY_SUPPORTED macro was eliminated.
3102
Many WIN32_WCE #ifdefs were removed.
3104
The functions png_read_init(info_ptr), png_write_init(info_ptr),
3105
png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
3106
have been removed. They have been deprecated since libpng-0.95.
3108
The png_permit_empty_plte() was removed. It has been deprecated
3109
since libpng-1.0.9. Use png_permit_mng_features() instead.
3111
We removed the obsolete stub functions png_get_mmx_flagmask(),
3112
png_set_mmx_thresholds(), png_get_asm_flags(),
3113
png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
3114
png_set_asm_flags(), and png_mmx_supported()
3116
We removed the obsolete png_check_sig(), png_memcpy_check(), and
3117
png_memset_check() functions. Instead use !png_sig_cmp(), png_memcpy(),
3118
and png_memset(), respectively.
3120
The function png_set_gray_1_2_4_to_8() was removed. It has been
3121
deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
3122
png_set_expand_gray_1_2_4_to_8() because the former function also
3123
expanded palette images.
3125
We changed the prototype for png_malloc() from
3126
png_malloc(png_structp png_ptr, png_uint_32 size)
3128
png_malloc(png_structp png_ptr, png_alloc_size_t size)
3130
This also applies to the prototype for the user replacement malloc_fn().
3132
The png_calloc() function was added and is used in place of
3133
of "png_malloc(); png_memset();" except in the case in png_read_png()
3134
where the array consists of pointers; in this case a "for" loop is used
3135
after the png_malloc() to set the pointers to NULL, to give robust.
3136
behavior in case the application runs out of memory part-way through
3139
We changed the prototypes of png_get_compression_buffer_size() and
3140
png_set_compression_buffer_size() to work with png_size_t instead of
3143
Support for numbered error messages was removed by default, since we
3144
never got around to actually numbering the error messages. The function
3145
png_set_strip_error_numbers() was removed from the library by default.
3147
The png_zalloc() and png_zfree() functions are no longer exported.
3148
The png_zalloc() function no longer zeroes out the memory that it
3151
Support for dithering was disabled by default in libpng-1.4.0, because
3152
been well tested and doesn't actually "dither". The code was not
3153
removed, however, and could be enabled by building libpng with
3154
PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support
3155
was reenabled, but the function was renamed png_set_quantize() to
3156
reflect more accurately what it actually does. At the same time,
3157
the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
3158
PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS.
3160
We removed the trailing '.' from the warning and error messages.
3164
The png_get_io_ptr() function has been present since libpng-0.88, has never
3165
changed, and is unaffected by conditional compilation macros. It is the
3166
best choice for use in configure scripts for detecting the presence of any
3167
libpng version since 0.88. In an autoconf "configure.in" you could use
3169
AC_CHECK_LIB(png, png_get_io_ptr, ...
3171
XI. Source code repository
3173
Since about February 2009, version 1.2.34, libpng has been under "git" source
3174
control. The git repository was built from old libpng-x.y.z.tar.gz files
3175
going back to version 0.70. You can access the git repository (read only)
3178
git://libpng.git.sourceforge.net/gitroot/libpng
3180
or you can browse it via "gitweb" at
3182
http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
3184
Patches can be sent to glennrp at users.sourceforge.net or to
3185
png-mng-implement at lists.sourceforge.net or you can upload them to
3186
the libpng bug tracker at
3188
http://libpng.sourceforge.net
3192
Our coding style is similar to the "Allman" style, with curly
3193
braces on separate lines:
3200
else if (another condition)
3205
The braces can be omitted from simple one-line actions:
3210
We use 3-space indentation, except for continued statements which
3211
are usually indented the same as the first line of the statement
3212
plus four more spaces.
3214
For macro definitions we use 2-space indentation, always leaving the "#"
3215
in the first column.
3217
#ifndef PNG_NO_FEATURE
3218
# ifndef PNG_FEATURE_SUPPORTED
3219
# define PNG_FEATURE_SUPPORTED
3223
Comments appear with the leading "/*" at the same indentation as
3224
the statement that follows the comment:
3226
/* Single-line comment */
3229
/* This is a multiple-line
3234
Very short comments can be placed after the end of the statement
3235
to which they pertain:
3237
statement; /* comment */
3239
We don't use C++ style ("//") comments. We have, however,
3240
used them in the past in some now-abandoned MMX assembler
3243
Functions and their curly braces are not indented, and
3244
exported functions are marked with PNGAPI:
3246
/* This is a public function that is visible to
3247
* application programers. It does thus-and-so.
3250
png_exported_function(png_ptr, png_info, foo)
3255
The prototypes for all exported functions appear in png.h,
3256
above the comment that says
3258
/* Maintainer: Put new public prototypes here ... */
3260
We mark all non-exported functions with "/* PRIVATE */"":
3263
png_non_exported_function(png_ptr, png_info, foo)
3268
The prototypes for non-exported functions (except for those in
3271
above the comment that says
3273
/* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
3275
The names of all exported functions and variables begin
3276
with "png_", and all publicly visible C preprocessor
3277
macros begin with "PNG_".
3279
We put a space after each comma and after each semicolon
3280
in "for" statments, and we put spaces before and after each
3281
C binary operator and after "for" or "while", and before
3282
"?". We don't put a space between a typecast and the expression
3283
being cast, nor do we put one between a function name and the
3284
left parenthesis that follows it:
3286
for (i = 2; i > 0; --i)
3287
y[i] = a(x) + (int)b;
3289
We prefer #ifdef and #ifndef to #if defined() and if !defined()
3290
when there is only one macro being tested.
3292
We do not use the TAB character for indentation in the C sources.
3294
Lines do not exceed 80 characters.
3296
Other rules can be inferred by inspecting the libpng source.
3298
XIII. Y2K Compliance in libpng
3302
Since the PNG Development group is an ad-hoc body, we can't make
3303
an official declaration.
3305
This is your unofficial assurance that libpng from version 0.71 and
3306
upward through 1.4.4 are Y2K compliant. It is my belief that earlier
3307
versions were also Y2K compliant.
3309
Libpng only has three year fields. One is a 2-byte unsigned integer that
3310
will hold years up to 65535. The other two hold the date in text
3311
format, and will hold years up to 9999.
3314
"png_uint_16 year" in png_time_struct.
3317
"png_charp time_buffer" in png_struct and
3318
"near_time_buffer", which is a local character string in png.c.
3320
There are seven time-related functions:
3322
png_convert_to_rfc_1123() in png.c
3323
(formerly png_convert_to_rfc_1152() in error)
3324
png_convert_from_struct_tm() in pngwrite.c, called
3326
png_convert_from_time_t() in pngwrite.c
3327
png_get_tIME() in pngget.c
3328
png_handle_tIME() in pngrutil.c, called in pngread.c
3329
png_set_tIME() in pngset.c
3330
png_write_tIME() in pngwutil.c, called in pngwrite.c
3332
All appear to handle dates properly in a Y2K environment. The
3333
png_convert_from_time_t() function calls gmtime() to convert from system
3334
clock time, which returns (year - 1900), which we properly convert to
3335
the full 4-digit year. There is a possibility that applications using
3336
libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
3337
function, or that they are incorrectly passing only a 2-digit year
3338
instead of "year - 1900" into the png_convert_from_struct_tm() function,
3339
but this is not under our control. The libpng documentation has always
3340
stated that it works with 4-digit years, and the APIs have been
3343
The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
3344
integer to hold the year, and can hold years as large as 65535.
3346
zlib, upon which libpng depends, is also Y2K compliant. It contains
3347
no date-related code.
3350
Glenn Randers-Pehrson
3352
PNG Development Group
added
removed
source/Irrlicht/libpng/libpng-1.4.4.txt
