mewin/libpng
1
0
Fork 0
mirror of https://git.code.sf.net/p/libpng/code.git synced 2025-07-10 18:04:09 +02:00
Code Issues Projects Releases Wiki Activity

Imported from libpng-1.4.0beta51.tar

Browse Source
This commit is contained in:
Glenn Randers-Pehrson
2009-03-21 08:15:32 -05:00
parent 6917b51660
commit 8fb550cc3e
63 changed files with 480 additions and 263 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
libpng.3
View File

@@ -1,6 +1,6 @@
.TH LIBPNG 3 "March 9, 2009"
.TH LIBPNG 3 "March 21, 2009"
.SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.4.0beta50
libpng \- Portable Network Graphics (PNG) Reference Library 1.4.0beta51
.SH SYNOPSIS
\fI\fB
@@ -809,14 +809,18 @@ Following is a copy of the libpng.txt file that accompanies libpng.
.SH LIBPNG.TXT
libpng.txt - A description on how to use and modify libpng
libpng version 1.4.0beta50 - March 9, 2009
libpng version 1.4.0beta51 - March 21, 2009
Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net>
Copyright (c) 1998-2005 Glenn Randers-Pehrson
Copyright (c) 1998-2009 Glenn Randers-Pehrson
For conditions of distribution and use, see copyright
notice in png.h.
based on:
Based on:
libpng versions 0.97, January 1998, through 1.4.0beta51 - March 21, 2009
Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2008 Glenn Randers-Pehrson
libpng 1.0 beta 6 version 0.96 May 28, 1997
Updated and distributed by Andreas Dilger
@@ -842,6 +846,10 @@ it is heavily commented and should include everything most people
will need. We assume that libpng is already installed; see the
INSTALL file for instructions on how to install libpng.
For examples of libpng usage, see the files "example.c", "pngtest.c",
and the files in the "contrib" directory, all of which are included in the
libpng distribution.
Libpng was written as a companion to the PNG specification, as a way
of reducing the amount of time and effort it takes to support the PNG
file format in application programs.
@@ -852,12 +860,14 @@ a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
The W3C and ISO documents have identical technical content.
The PNG-1.2 specification is available at
<http://www.libpng.org/pub/png/documents/>
<http://www.libpng.org/pub/png/documents/>. It is technically equivalent
to the PNG specification (second edition) but has some additional material.
The PNG-1.0 specification is available
as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some
additional chunks are described in the special-purpose public chunks
W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
Some additional chunks are described in the special-purpose public chunks
documents at <http://www.libpng.org/pub/png/documents/>.
Other information
@@ -1065,15 +1075,19 @@ input stream. You must supply the function
png_unknown_chunkp chunk);
{
/* The unknown chunk structure contains your
chunk data: */
chunk data, along with similar data for any other
unknown chunks: */
png_byte name[5];
png_byte *data;
png_size_t size;
/* Note that libpng has already taken care of
the CRC handling */
/* put your code here. Return one of the
following: */
/* put your code here. Search for your chunk in the
unknown chunk structure, process it, and return one
of the following: */
return (-n); /* chunk had an error */
return (0); /* did not recognize */
@@ -1093,6 +1107,11 @@ you can retrieve with
png_get_user_chunk_ptr(png_ptr);
If you call the png_set_read_user_chunk_fn() function, then all unknown
chunks will be saved when read, in case your callback function will need
one or more of them. This behavior can be changed with the
png_set_keep_unknown_chunks() function, described below.
At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control
a progress meter or the like. It's demonstrated in pngtest.c.
@@ -1109,18 +1128,42 @@ You must supply a function
To inform libpng about your function, use
png_set_read_status_fn(png_ptr, read_row_callback);
.SS Width and height limits
The PNG specification allows the width and height of an image to be as
large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
Since very few applications really need to process such large images,
we have imposed an arbitrary 1-million limit on rows and columns.
Larger images will be rejected immediately with a png_error() call. If
you wish to override this limit, you can use
png_set_user_limits(png_ptr, width_max, height_max);
to set your own limits, or use width_max = height_max = 0x7fffffffL
to allow all valid dimensions (libpng may reject some very large images
anyway because of potential buffer overflow conditions).
You should put this statement after you create the PNG structure and
before calling png_read_info(), png_read_png(), or png_process_data().
If you need to retrieve the limits that are being applied, use
width_max = png_get_user_width_max(png_ptr);
height_max = png_get_user_height_max(png_ptr);
.SS Unknown-chunk handling
Now you get to set the way the library processes unknown chunks in the
input PNG stream. Both known and unknown chunks will be read. Normal
behavior is that known chunks will be parsed into information in
various info_ptr members; unknown chunks will be discarded. To change
this, you can call:
various info_ptr members while unknown chunks will be discarded. This
behavior can be wasteful if your application will never use some known
chunk types. To change this, you can call:
png_set_keep_unknown_chunks(png_ptr, keep,
chunk_list, num_chunks);
keep - 0: do not handle as unknown
1: do not keep
keep - 0: default unknown chunk handling
1: ignore; do not keep
2: keep only if safe-to-copy
3: keep even if unsafe-to-copy
You can use these definitions:
@@ -1143,6 +1186,36 @@ instances of png_set_keep_unknown_chunks(), the final instance will
take precedence. The IHDR and IEND chunks should not be named in
chunk_list; if they are, libpng will process them normally anyway.
Here is an example of the usage of png_set_keep_unknown_chunks(),
where the private "vpAg" chunk will later be processed by a user chunk
callback function:
png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'};
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
png_byte unused_chunks[]=
{
104, 73, 83, 84, (png_byte) '\0', /* hIST */
105, 84, 88, 116, (png_byte) '\0', /* iTXt */
112, 67, 65, 76, (png_byte) '\0', /* pCAL */
115, 67, 65, 76, (png_byte) '\0', /* sCAL */
115, 80, 76, 84, (png_byte) '\0', /* sPLT */
116, 73, 77, 69, (png_byte) '\0', /* tIME */
};
#endif
...
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
/* ignore all unknown chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
/* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
/* also ignore unused known chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
(int)sizeof(unused_chunks)/5);
#endif
.SS User limits
The PNG specification allows the width and height of an image to be as
@@ -1204,7 +1277,7 @@ you want to do are limited to the following set:
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
(This excludes setting a background color, doing gamma transformation,
and setting filler.) If this is the case, simply do this:
dithering, and setting filler.) If this is the case, simply do this:
png_read_png(png_ptr, info_ptr, png_transforms, NULL)
@@ -1231,14 +1304,16 @@ where row_pointers is an array of pointers to the pixel data for each row:
If you know your image size and pixel size ahead of time, you can allocate
row_pointers prior to calling png_read_png() with
if (height > PNG_UINT_32_MAX/sizeof(png_bytep))
if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
png_error (png_ptr,
"Image is too tall to process in memory");
if (width > PNG_UINT_32_MAX/pixel_size)
png_error (png_ptr,
"Image is too wide to process in memory");
row_pointers = png_malloc(png_ptr,
height*sizeof(png_bytep));
height*png_sizeof(png_bytep));
for (int i=0; i<height, i++)
row_pointers[i]=NULL; /* security precaution */
for (int i=0; i<height, i++)
row_pointers[i]=png_malloc(png_ptr,
width*pixel_size);
@@ -1615,8 +1690,43 @@ things.
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
added. It expands the sample depth without changing tRNS to alpha.
%12%At the same time, png_set_gray_1_2_4_to_8() was deprecated, and it
%12%will be removed from a future version.
As of libpng version 1.4.0beta51, not all possible expansions are supported.
In the following table, the 01 means grayscale with depth<8, 31 means
indexed with depth<8, other numerals represent the color type, "T" means
the tRNS chunk is present, A means an alpha channel is present, and O
means tRNS or alpha is present but all pixels in the image are opaque.
FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
TO
01 -
31 -
0 1 -
0T -
0O -
2 GX -
2T -
2O -
3 1 -
3T -
3O -
4A T -
4O -
6A GX TX TX -
6O GX TX -
Within the matrix,
"-" means the transformation is not supported.
"X" means the transformation is obtained by png_set_expand().
"1" means the transformation is obtained by
png_set_expand_gray_1_2_4_to_8
"G" means the transformation is obtained by
png_set_gray_to_rgb().
"P" means the transformation is obtained by
png_set_expand_palette_to_rgb().
"T" means the transformation is obtained by
png_set_tRNS_to_alpha().
PNG can have files with 16 bits per channel. If you only can handle
8 bits per channel, this will strip the pixels down to 8 bit.
@@ -1850,7 +1960,6 @@ recommended that PNG viewers support gamma correction.
else
png_set_gamma(png_ptr, screen_gamma, 0.45455);
PNG files describe monochrome as black being zero and white being one.
The following code will reverse this (make black be one and white be
zero):
@@ -2533,6 +2642,11 @@ Some of the more important parts of the png_info are:
can also be
PNG_INTRAPIXEL_DIFFERENCING)
If you call png_set_IHDR(), the call must appear before any of the
other png_set_*() functions, which might require access to some of
the IHDR settings. The remaining png_set_*() functions can be called
in any order.
png_set_PLTE(png_ptr, info_ptr, palette,
num_palette);
palette - the palette for the file
@@ -2804,7 +2918,6 @@ transformations are permitted, enabled by the following masks.
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
to transparency
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
PNG_TRANSFORM_STRIP_FILLER Strip out filler
bytes (deprecated).
PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
@@ -3149,17 +3262,13 @@ For a more compact example of writing a PNG image, see the file example.c.
.SH V. Modifying/Customizing libpng:
There are three issues here. The first is changing how libpng does
There are two issues here. The first is changing how libpng does
standard things like memory allocation, input/output, and error handling.
The second deals with more complicated things like adding new chunks,
adding new transformations, and generally changing how libpng works.
Both of those are compile-time issues; that is, they are generally
determined at the time the code is written, and there is rarely a need
to provide the user with a means of changing them. The third is a
run-time issue: choosing between and/or tuning one or more alternate
versions of computationally intensive routines; specifically, optimized
assembly-language (and therefore compiler- and platform-dependent)
versions.
to provide the user with a means of changing them.
Memory allocation, input/output, and error handling
@@ -3191,6 +3300,9 @@ Your malloc_fn() must return NULL in case of failure. The png_malloc()
function will normally call png_error() if it receives a NULL from the
system memory allocator or from your replacement malloc_fn().
Your free_fn() will never be called with a NULL ptr, since libpng's
png_free() checks for NULL before calling free_fn().
Input/Output in libpng is done through png_read() and png_write(),
which currently just call fread() and fwrite(). The FILE * is stored in
png_struct and is initialized via png_init_io(). If you wish to change
@@ -3222,8 +3334,11 @@ The user_read_data() function is responsible for detecting and
handling end-of-data errors.
Supplying NULL for the read, write, or flush functions sets them back
to using the default C stream functions. It is an error to read from
a write stream, and vice versa.
to using the default C stream functions, which expect the io_ptr to
point to a standard *FILE structure. It is probably a mistake
to use NULL for one of write_data_fn and output_flush_fn but not both
of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
It is an error to read from a write stream, and vice versa.
Error handling in libpng is done through png_error() and png_warning().
Errors handled through png_error() are fatal, meaning that png_error()
@@ -3329,9 +3444,11 @@ you may also have to change the memory allocators (png_malloc, etc.).
.SS Configuring for compiler xxx:
All includes for libpng are in pngconf.h. If you need to add, change
or delete an include, this is the place to do it. The includes that
are not needed outside libpng are placed inside pngpriv.h, which is
only used by the routines inside libpng itself.
or delete an include, this is the place to do it.
The includes that are not needed outside libpng are placed in pngpriv.h,
which is only used by the routines inside libpng itself.
The files in libpng proper only include pngpriv.h and png.h, which
in turn includes pngconf.h.
.SS Configuring zlib:
@@ -3547,7 +3664,7 @@ or any other MNG chunks; your application must provide its own support for
them. You may wish to consider using libmng (available at
http://www.libmng.com) instead.
.SH VIII. Changes to Libpng from version 0.88
.SH VII. Changes to Libpng from version 0.88
It should be noted that versions of libpng later than 0.96 are not
distributed by the original libpng author, Guy Schalnat, nor by
@@ -3596,15 +3713,15 @@ application:
png_uint_32 application_vn = PNG_LIBPNG_VER;
.SH IX. Y2K Compliance in libpng
.SH VIII. Y2K Compliance in libpng
March 9, 2009
March 21, 2009
Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.
This is your unofficial assurance that libpng from version 0.71 and
upward through 1.4.0beta50 are Y2K compliant. It is my belief that earlier
upward through 1.4.0beta51 are Y2K compliant. It is my belief that earlier
versions were also Y2K compliant.
Libpng only has three year fields. One is a 2-byte unsigned integer that
@@ -3772,7 +3889,7 @@ the first widely used release:
1.4.0beta9-14 14 10400 14.so.0.0[.0]
1.2.13 13 10213 12.so.0.13[.0]
1.4.0beta15-36 14 10400 14.so.0.0[.0]
1.4.0beta37-50 14 10400 14.so.14.0[.0]
1.4.0beta37-51 14 10400 14.so.14.0[.0]
Henceforth the source version will match the shared-library minor
and patch numbers; the shared-library major version number will be
@@ -3828,7 +3945,7 @@ possible without all of you.
Thanks to Frank J. T. Wojcik for helping with the documentation.
Libpng version 1.4.0beta50 - March 9, 2009:
Libpng version 1.4.0beta51 - March 21, 2009:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
@@ -3849,7 +3966,7 @@ included in the libpng distribution, the latter shall prevail.)
If you modify libpng you may insert additional notices immediately following
this sentence.
libpng versions 1.2.6, August 15, 2004, through 1.4.0beta50, March 9, 2009, are
libpng versions 1.2.6, August 15, 2004, through 1.4.0beta51, March 21, 2009, are
Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
distributed according to the same disclaimer and license as libpng-1.2.5
with the following individual added to the list of Contributing Authors
@@ -3948,7 +4065,7 @@ certification mark of the Open Source Initiative.
Glenn Randers-Pehrson
glennrp at users.sourceforge.net
March 9, 2009
March 21, 2009
.\" end of man page