Imported from libpng-1.0.6.tar
diff --git a/libpng.3 b/libpng.3
index 8a2d29e..05b37a2 100644
--- a/libpng.3
+++ b/libpng.3
@@ -1,6 +1,6 @@
-.TH LIBPNG 3 "February 18, 2000"
+.TH LIBPNG 3 "March 21, 2000"
.SH NAME
-libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5s
+libpng \- Portable Network Graphics (PNG) Reference Library 1.0.6
.SH SYNOPSIS
\fI\fB
@@ -538,7 +538,11 @@
\fI\fB
-\fBvoid png_set_rgb_to_gray (png_structp \fP\fIpng_ptr\fP\fB, int \fIerror_action\fP\fB);\fP
+\fBvoid png_set_rgb_to_gray (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIerror_action\fP\fB, double \fP\fIred\fP\fB, double \fIgreen\fP\fB);\fP
+
+\fI\fB
+
+\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_fixed_point \fP\fIred\fP\fB, png_fixed_point \fIgreen\fP\fB);\fP
\fI\fB
@@ -709,7 +713,7 @@
.SH LIBPNG.TXT
libpng.txt - A description on how to use and modify libpng
- libpng version 1.0.5s - February 18, 2000
+ libpng version 1.0.6 - March 21, 2000
Updated and distributed by Glenn Randers-Pehrson
<randeg@alum.rpi.edu>
Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson
@@ -746,7 +750,9 @@
of reducing the amount of time and effort it takes to support the PNG
file format in application programs.
-The PNG-1.2 specification is available at <http://www.cdrom.com/png>.
+The PNG-1.2 specification is available at <http://www.cdrom.com/pub/png>
+(will be moving to <http://www.libpng.org>)
+and at <ftp://ftp.uu.net/graphics/png/documents/>.
The PNG-1.0 specification is available
as RFC 2083 <ftp://ftp.uu.net/graphics/png/documents/> and as a
@@ -756,7 +762,9 @@
Other information
about PNG, and the latest version of libpng, can be found at the PNG home
-page, <http://www.cdrom.com/pub/png/>.
+page, <http://www.cdrom.com/pub/png/> (will be moving to
+<http://www.libpng.org>)
+and at <ftp://ftp.uu.net/graphics/png/>.
Most users will not have to modify the library significantly; advanced
users may want to modify it more. All attempts were made to make it as
@@ -774,7 +782,7 @@
Libpng uses zlib for its compression and decompression of PNG files.
Further information about zlib, and the latest version of zlib, can
-be found at the zlib home page, <http://www.cdrom.com/pub/infozip/zlib/>.
+be found at the zlib home page, <ftp://ftp.freesoftware.com/pub/infozip/zlib/>.
The zlib compression utility is a general purpose utility that is
useful for more than PNG files, and can be used without libpng.
See the documentation delivered with zlib for more details.
@@ -899,9 +907,9 @@
When libpng encounters an error, it expects to longjmp back
to your routine. Therefore, you will need to call setjmp and pass
-your png_jmp_env(png_ptr). If you read the file from different
+your png_jmpbuf(png_ptr). If you read the file from different
routines, you will need to update the jmpbuf field every time you enter
-a new routine that will call a png_ function.
+a new routine that will call a png_*() function.
See your documentation of setjmp/longjmp for your compiler for more
information on setjmp/longjmp. See the discussion on libpng error
@@ -910,7 +918,7 @@
back to your setjmp, you will want to call png_destroy_read_struct() to
free any memory.
- if (setjmp(png_jmp_env(png_ptr)))
+ if (setjmp(png_jmpbuf(png_ptr)))
{
png_destroy_read_struct(&png_ptr, &info_ptr,
&end_info);
@@ -990,38 +998,6 @@
png_set_read_status_fn(png_ptr, read_row_callback);
-Finally, you can write your own transformation function if none of
-the existing ones meets your needs. This is done by setting a callback
-with
-
- png_set_read_user_transform_fn(png_ptr,
- read_transform_fn);
-
-You must supply the function
-
- void read_transform_fn(png_ptr ptr, row_info_ptr
- row_info, png_bytep data)
-
-See pngtest.c for a working example. Your function will be called
-after all of the other transformations have been processed.
-
-You can also set up a pointer to a user structure for use by your
-callback function, and you can inform libpng that your transform
-function will change the number of channels or bit depth with the
-function
-
- png_set_user_transform_info(png_ptr, user_ptr,
- user_depth, user_channels);
-
-The user's application, not libpng, is responsible for allocating and
-freeing any memory required for the user structure.
-
-You can retrieve the pointer via the function
-png_get_user_transform_ptr(). For example:
-
- voidp read_user_transform_ptr =
- png_get_user_transform_ptr(png_ptr);
-
.SS Unknown-chunk handling
Now you get to set the way the library processes unknown chunks in the
@@ -1093,24 +1069,6 @@
This will process all chunks up to but not including the image data.
-There is one transformation you may need to set up before doing
-png_read_info(), however. In PNG files, the alpha channel in an image
-is the level of opacity. If you need the alpha channel in an image to
-be the level of transparency instead of opacity, you can invert the
-alpha channel (or the tRNS chunk data) after it's read, so that 0 is
-fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
-images) is fully transparent, with
-
- png_set_invert_alpha(png_ptr);
-
-This must appear before png_write_info() instead of later with the
-other transformations because in the case of paletted images the tRNS
-chunk data has to be inverted before the tRNS chunk is written.
-If your image is not a paletted image, the tRNS data (which in such cases
-represents a single color to be rendered as transparent) won't need to
-be changed, and you can safely do this transformation after your
-png_read_info() call.
-
.SS Querying the info structure
Functions are used to get the information from the info_ptr once it
@@ -1437,6 +1395,15 @@
if (color_type & PNG_COLOR_MASK_ALPHA)
png_set_strip_alpha(png_ptr);
+In PNG files, the alpha channel in an image
+is the level of opacity. If you need the alpha channel in an image to
+be the level of transparency instead of opacity, you can invert the
+alpha channel (or the tRNS chunk data) after it's read, so that 0 is
+fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
+images) is fully transparent, with
+
+ png_set_invert_alpha(png_ptr);
+
PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
they can, resulting in, for example, 8 pixels per byte for 1 bit
files. This code expands to 1 pixel per byte without changing the
@@ -1490,14 +1457,12 @@
png_set_gray_to_rgb(png_ptr);
Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
-with alpha. This is intended for conversion of images that really are
-gray (red == green == blue), so the function simply strips out the red
-and blue channels, leaving the green channel in the gray position.
+with alpha.
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
- png_set_rgb_to_gray(png_ptr, error_action,
- double red_weight, double green_weight);
+ png_set_rgb_to_gray_fixed(png_ptr, error_action,
+ int red_weight, int green_weight);
error_action = 1: silently do the conversion
error_action = 2: issue a warning if the original
@@ -1508,10 +1473,10 @@
image has any pixel where
red != green or red != blue
- red_weight: weight of red component
- (NULL -> default 54/256)
- green_weight: weight of green component
- (NULL -> default 183/256)
+ red_weight: weight of red component times 100000
+ green_weight: weight of green component times 100000
+ If either weight is negative, default
+ weights (21268, 71514) are used.
If you have set error_action = 1 or 2, you can
later check whether the image really was gray, after processing
@@ -1521,13 +1486,13 @@
will be silently converted to grayscale, using the green channel
data, regardless of the error_action setting.
-With 0.0<=red_weight+green_weight<=1.0,
+With red_weight+green_weight<=100000,
the normalized graylevel is computed:
- int rw = red_weight * 256;
- int gw = green_weight * 256;
- int bw = 256 - (rw + gw);
- gray = (rw*red + gw*green + bw*blue)/256;
+ int rw = red_weight * 65536;
+ int gw = green_weight * 65536;
+ int bw = 65536 - (rw + gw);
+ gray = (rw*red + gw*green + bw*blue)/65536;
The default values approximate those recommended in the Charles
Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
@@ -1537,11 +1502,11 @@
Libpng approximates this with
- Y = 0.211 * R + 0.715 * G + 0.074 * B
+ Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
which can be expressed with integers as
- Y = (54 * R + 183 * G + 19 * B)/256
+ Y = (6969 * R + 23434 * G + 2365 * B)/32768
The calculation is done in a linear colorspace, if the image gamma
is known.
@@ -1672,6 +1637,38 @@
if (bit_depth < 8)
png_set_packswap(png_ptr);
+Finally, you can write your own transformation function if none of
+the existing ones meets your needs. This is done by setting a callback
+with
+
+ png_set_read_user_transform_fn(png_ptr,
+ read_transform_fn);
+
+You must supply the function
+
+ void read_transform_fn(png_ptr ptr, row_info_ptr
+ row_info, png_bytep data)
+
+See pngtest.c for a working example. Your function will be called
+after all of the other transformations have been processed.
+
+You can also set up a pointer to a user structure for use by your
+callback function, and you can inform libpng that your transform
+function will change the number of channels or bit depth with the
+function
+
+ png_set_user_transform_info(png_ptr, user_ptr,
+ user_depth, user_channels);
+
+The user's application, not libpng, is responsible for allocating and
+freeing any memory required for the user structure.
+
+You can retrieve the pointer via the function
+png_get_user_transform_ptr(). For example:
+
+ voidp read_user_transform_ptr =
+ png_get_user_transform_ptr(png_ptr);
+
The last thing to handle is interlacing; this is covered in detail below,
but you must call the function here if you want libpng to handle expansion
of the interlaced image.
@@ -1726,10 +1723,10 @@
where row_pointers is the same as in the png_read_image() call.
If you are doing this just one row at a time, you can do this with
-row_pointers:
+a single row_pointer instead of an array of row_pointers:
- png_bytep row_pointers = row;
- png_read_row(png_ptr, &row_pointers, NULL);
+ png_bytep row_pointer = row;
+ png_read_row(png_ptr, row_pointers, NULL);
If the file is interlaced (info_ptr->interlace_type != 0), things get
somewhat harder. The only current (PNG Specification version 1.2)
@@ -1880,7 +1877,7 @@
return -1;
}
- if (setjmp(png_jmp_env(png_ptr)))
+ if (setjmp(png_jmpbuf(png_ptr)))
{
png_destroy_read_struct(&png_ptr, &info_ptr,
(png_infopp)NULL);
@@ -1914,7 +1911,7 @@
int
process_data(png_bytep buffer, png_uint_32 length)
{
- if (setjmp(png_jmp_env(png_ptr)))
+ if (setjmp(png_jmpbuf(png_ptr)))
{
png_destroy_read_struct(&png_ptr, &info_ptr,
(png_infopp)NULL);
@@ -2069,15 +2066,15 @@
After you have these structures, you will need to set up the
error handling. When libpng encounters an error, it expects to
longjmp() back to your routine. Therefore, you will need to call
-setjmp() and pass the png_jmp_env(png_ptr). If you
+setjmp() and pass the png_jmpbuf(png_ptr). If you
write the file from different routines, you will need to update
-the png_jmp_env(png_ptr) every time you enter a new routine that will
-call a png_ function. See your documentation of setjmp/longjmp
+the png_jmpbuf(png_ptr) every time you enter a new routine that will
+call a png_*() function. See your documentation of setjmp/longjmp
for your compiler for more information on setjmp/longjmp. See
the discussion on libpng error handling in the Customizing Libpng
section below for more information on the libpng error handling.
- if (setjmp(png_jmp_env(png_ptr)))
+ if (setjmp(png_jmpbuf(png_ptr)))
{
png_destroy_write_struct(&png_ptr, &info_ptr);
fclose(fp);
@@ -2512,14 +2509,15 @@
data. For example, don't swap red and blue on grayscale data.
PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
-the library to expand the input data to 4 or 8 bytes per pixel
-(or expand 1 or 2-byte grayscale data to 2 or 4 bytes per pixel).
+the library to trip input data that has 4 or 8 bytes per pixel down
+to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
+bytes per pixel).
png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
-where the 0 is the value that will be put in the 4th byte, and the
-location is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending
-upon whether the filler byte is stored XRGB or RGBX.
+where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
+PNG_FILLER_AFTER, depending upon whether the filler byte in the is stored
+XRGB or RGBX.
PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
they can, resulting in, for example, 8 pixels per byte for 1 bit files.
@@ -2636,7 +2634,7 @@
.SS Writing the image data
That's it for the transformations. Now you can write the image data.
-The simplest way to do this is in one function call. If have the
+The simplest way to do this is in one function call. If you have the
whole image in memory, you can just call png_write_image() and libpng
will write the image. You will need to pass in an array of pointers to
each row. This function automatically handles interlacing, so you don't
@@ -2661,11 +2659,11 @@
row_pointers is the same as in the png_write_image() call.
If you are just writing one row at a time, you can do this with
-row_pointers:
+a single row_pointer instead of an array of row_pointers:
png_bytep row_pointer = row;
- png_write_row(png_ptr, &row_pointer);
+ png_write_row(png_ptr, row_pointer);
When the file is interlaced, things can get a good deal more
complicated. The only currently (as of January 2000 -- PNG Specification
@@ -3115,13 +3113,13 @@
.SH VII. Y2K Compliance in libpng
-February 18, 2000
+March 21, 2000
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.0.5s are Y2K compliant. It is my belief that earlier
+upward through 1.0.6 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
@@ -3218,7 +3216,7 @@
.br
ftp://ftp.uu.net/pub/archiving/zip/zlib
.br
-http://www.cdrom.com/pub/infozip/zlib
+ftp://ftp.freesoftware.com/pub/infozip/zlib
.LP
.IR PNG specification: RFC 2083
@@ -3247,7 +3245,7 @@
Thanks to Frank J. T. Wojcik for helping with the documentation.
-Libpng version 1.0.5s - February 18, 2000:
+Libpng version 1.0.6 - March 21, 2000:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (randeg@alum.rpi.edu).
@@ -3262,7 +3260,7 @@
Copyright (c) 1996, 1997 Andreas Dilger
(libpng versions 0.90, December 1996, through 0.96, May 1997)
Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson
-(libpng versions 0.97, January 1998, through 1.0.5s, February 18, 2000)
+(libpng versions 0.97, January 1998, through 1.0.6, March 21, 2000)
For the purposes of this copyright and license, "Contributing Authors"
is defined as the following set of individuals: