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.0.6.tar

Browse Source
This commit is contained in:
Glenn Randers-Pehrson
2000-03-21 05:13:06 -06:00
parent a77ef625a6
commit 520a764cd7
74 changed files with 2298 additions and 1436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
libpng.3
View File

@@ -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 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5s
\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 @@ 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.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 @@ 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.
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 @@ documents at <ftp://ftp.uu.net/graphics/png/documents/>.
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 @@ majority of the needs of its users.
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 @@ handling and memory alloc/free functions.
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 @@ on the libpng error handling. If an error occurs, and libpng longjmp's
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 @@ To inform libpng about your function, use
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 @@ call to png_read_info().
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 @@ it with the background, so that's what you should probably do):
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 @@ RGB. This code will do that conversion:
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 @@ and blue channels, leaving the green channel in the gray position.
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 @@ It will return a png_byte that is zero if the image was gray or
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 @@ Copyright (c) 1998-01-04 Charles Poynton poynton@inforamp.net
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 @@ need to change the order the pixels are packed into bytes, you can use:
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 @@ interlace_type == PNG_INTERLACE_NONE), this is simple:
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 @@ png_infop info_ptr;
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 @@ png_infop info_ptr;
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 @@ png_create_write_struct_2() instead of png_create_read_struct():
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 @@ make sure to only enable a transformation if it will be valid for the
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 @@ that do not use flushing.
.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 @@ this is simple:
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 @@ the old method.
.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 @@ or at
.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 @@ possible without all of you.
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) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
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: