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.6g.tar

Browse Source
This commit is contained in:
Glenn Randers-Pehrson
2000-04-23 23:14:02 -05:00
parent 4accabb590
commit 228bd390ac
47 changed files with 571 additions and 369 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
libpng.3
View File

@@ -1,6 +1,6 @@
.TH LIBPNG 3 "April 14, 2000"
.TH LIBPNG 3 "April 24, 2000"
.SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.0.6f
libpng \- Portable Network Graphics (PNG) Reference Library 1.0.6g
.SH SYNOPSIS
\fI\fB
@@ -234,7 +234,7 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.6f
\fI\fB
\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fP\fI*splt_ptr\fP\fB, int \fInum\fP\fB);\fP
\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP
\fI\fB
@@ -294,6 +294,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.6f
\fI\fB
\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
\fBvoid png_info_init (png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
@@ -614,6 +618,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.6f
\fI\fB
\fBvoid png_set_unknown_chunk_location(png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIchunk\fP\fB, int \fIlocation\fP\fB);\fP
\fI\fB
\fBvoid png_set_read_user_chunk_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_chunk_ptr\fP\fB, png_user_chunk_ptr \fIread_user_chunk_fn\fP\fB);\fP
\fI\fB
@@ -634,6 +642,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.6f
\fI\fB
\fBvoid png_set_compression_buffer_size(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
\fI\fB
\fBint png_sig_cmp (png_bytep \fP\fIsig\fP\fB, png_size_t \fP\fIstart\fP\fB, png_size_t \fInum_to_check\fP\fB);\fP
\fI\fB
@@ -713,7 +725,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.6f - April 14, 2000
libpng version 1.0.6g - April 24, 2000
Updated and distributed by Glenn Randers-Pehrson
<randeg@alum.rpi.edu>
Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson
@@ -1393,8 +1405,8 @@ transparency information in a tRNS chunk. This is most useful on
grayscale images with bit depths of 2 or 4 or if there is a multiple-image
viewing application that wishes to treat all images in the same way.
if (color_type == PNG_COLOR_TYPE_PALETTE &&
bit_depth <= 8) png_set_palette_to_rgb(png_ptr);
if (color_type == PNG_COLOR_TYPE_PALETTE)
png_set_palette_to_rgb(png_ptr);
if (color_type == PNG_COLOR_TYPE_GRAY &&
bit_depth < 8) png_set_gray_1_2_4_to_8(png_ptr);
@@ -1413,17 +1425,6 @@ PNG can have files with 16 bits per channel. If you only can handle
if (bit_depth == 16)
png_set_strip_16(png_ptr);
The png_set_background() function tells libpng to composite images
with alpha or simple transparency against the supplied background
color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
you may use this color, or supply another color more suitable for
the current display (e.g., the background color from a web page). You
need to tell libpng whether the color is in the gamma space of the
display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
know why anyone would use this, but it's here).
If, for some reason, you don't need the alpha channel on an image,
and you want to remove it rather than combining it with the background
(but the image author certainly had in mind that you *would* combine
@@ -1567,6 +1568,17 @@ or as an RGB triplet that may or may not be in the palette (need_expand = 0).
png_set_background(png_ptr, &my_background,
PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
The png_set_background() function tells libpng to composite images
with alpha or simple transparency against the supplied background
color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
you may use this color, or supply another color more suitable for
the current display (e.g., the background color from a web page). You
need to tell libpng whether the color is in the gamma space of the
display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
know why anyone would use this, but it's here).
To properly display PNG images on any kind of system, the application needs
to know what the display gamma is. Ideally, the user will know this, and
the application will allow them to set it. One method of allowing the user
@@ -1763,7 +1775,7 @@ If you are doing this just one row at a time, you can do this with
a single row_pointer instead of an array of row_pointers:
png_bytep row_pointer = row;
png_read_row(png_ptr, row_pointers, NULL);
png_read_row(png_ptr, row_pointer, NULL);
If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
get somewhat harder. The only current (PNG Specification version 1.2)
@@ -2182,21 +2194,33 @@ speed/compression ratio. The second parameter to png_set_filter() is
the filter method, for which the only valid value is '0' (as of the
July 1999 PNG specification, version 1.2). The third parameter is a
flag that indicates which filter type(s) are to be tested for each
scanline. See the Compression Library for details on the specific filter
scanline. See the PNG specification for details on the specific filter
types.
/* turn on or off filtering, and/or choose
specific filters */
specific filters. You can use either a single PNG_FILTER_VALUE_NAME
or the "OR" of one or more PNG_FILTER_NAME masks. */
png_set_filter(png_ptr, 0,
PNG_FILTER_NONE | PNG_FILTER_SUB |
PNG_FILTER_PAETH);
PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
PNG_FILTER_AVE | PNG_FILTER_VALUE_AVE |
PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
PNG_ALL_FILTERS);
If an application
wants to start and stop using particular filters during compression,
it should start out with all of the filters (to ensure that the previous
row of pixels will be stored in case it's needed later), and then add
and remove them after the start of compression.
The png_set_compression_*() functions interface to the zlib compression
library, and should mostly be ignored unless you really know what you are
doing. The only generally useful call is png_set_compression_level()
which changes how much time zlib spends on trying to compress the image
data. See the Compression Library for details on the compression levels.
data. See the Compression Library (zlib.h and algorithm.txt, distributed
with zlib) for details on the compression levels.
/* set the zlib compression level */
png_set_compression_level(png_ptr,
@@ -2208,6 +2232,9 @@ data. See the Compression Library for details on the compression levels.
Z_DEFAULT_STRATEGY);
png_set_compression_window_bits(png_ptr, 15);
png_set_compression_method(png_ptr, 8);
png_set_compression_buffer_size(png_ptr, 8192)
extern PNG_EXPORT(void,png_set_zbuf_size)
.SS Setting the contents of info for output
@@ -2416,18 +2443,17 @@ Some of the more important parts of the png_info are:
A quick word about text and num_text. text is an array of png_text
structures. num_text is the number of valid structures in the array.
If you want, you can use max_text to hold the size of the array, but
libpng ignores it for writing (it does use it for reading). Each
png_text structure holds a language code, a keyword, a text value, and
a compression type.
Each png_text structure holds a language code, a keyword, a text value,
and a compression type.
The compression types have the same valid numbers as the compression
types of the image data. Currently, the only valid number is zero.
However, you can store text either compressed or uncompressed, unlike
images, which always have to be compressed. So if you don't want the
text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
Because compressed-text chunks don't have a language field, if you
specify compression any language code will not be written out.
Because tEXt and zTXt chunks don't have a language field, if you
specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
any language code or translated keyword will not be written out.
Until text gets around 1000 bytes, it is not worth compressing it.
After the text has been written out to the file, the compression type
@@ -2587,8 +2613,8 @@ bytes per pixel).
png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
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_FILLER_AFTER, depending upon whether the filler byte in the pixel
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.
@@ -2599,7 +2625,7 @@ correctly pack the pixels into a single byte:
PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
data is of another bit depth, you can write an sBIT chunk into the
file so that decoders can get the original data if desired.
file so that decoders can recover the original data if desired.
/* Set the true bit depth of the image data */
if (color_type & PNG_COLOR_MASK_COLOR)
@@ -2674,8 +2700,8 @@ callback function.
The user_channels and user_depth parameters of this function are ignored
when writing; you can set them to zero as shown.
You can retrieve the pointer via the function
png_get_user_transform_ptr(). For example:
You can retrieve the pointer via the function png_get_user_transform_ptr().
For example:
voidp write_user_transform_ptr =
png_get_user_transform_ptr(png_ptr);
@@ -2737,7 +2763,7 @@ a single row_pointer instead of an array of row_pointers:
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
complicated. The only currently (as of the PNG Specification
version 1.2, dated July 1999) defined interlacing scheme for PNG files
is the "Adam7" interlace scheme, that breaks down an
image into seven smaller images of varying size. libpng will build
@@ -2828,7 +2854,7 @@ to a write structure, you could use
PNG_DESTROY_WILL_FREE_DATA,
PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
Thereby briefly reassigning responsibility for freeing to the user but
thereby briefly reassigning responsibility for freeing to the user but
immediately afterwards reassigning it once more to the write_destroy
function. Having done this, it would then be safe to destroy the read
structure and continue to use the PLTE, tRNS, and hIST data in the write
@@ -2845,13 +2871,11 @@ adding new transformations, and generally changing how libpng works.
All of the memory allocation, input/output, and error handling in libpng
goes through callbacks that are user settable. The default routines are
in pngmem.c, pngrio.c, pngwio.c, and pngerror.c respectively. To change
in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
these functions, call the appropriate png_set_*_fn() function.
Memory allocation is done through the functions png_large_malloc(),
png_malloc(), png_realloc(), png_large_free(), and png_free(). These
currently just call the standard C functions. The large functions must
handle exactly 64K, but they don't have to handle more than that. If
Memory allocation is done through the functions png_malloc() and png_free().
These currently just call the standard C functions. If
your pointers can't access more then 64K at a time, you will want to set
MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling
memory allocation on a platform will change between applications, these
@@ -2904,8 +2928,8 @@ fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
fprintf() isn't available). If you wish to change the behavior of the error
functions, you will need to set up your own message callbacks. These
functions are normally supplied at the time that the png_struct is created.
It is also possible to change these functions after png_create_*_struct()
has been called by calling:
It is also possible to redirect errors and warnings to your own replacement
functions after png_create_*_struct() has been called by calling:
png_set_error_fn(png_structp png_ptr,
png_voidp error_ptr, png_error_ptr error_fn,
@@ -2929,7 +2953,8 @@ as there is no need to check every return code of every function call.
However, there are some uncertainties about the status of local variables
after a longjmp, so the user may want to be careful about doing anything after
setjmp returns non-zero besides returning itself. Consult your compiler
documentation for more details.
documentation for more details. For an alternative approach, you may wish
to use the "cexcept" facility (see http://cexcept.sourceforge.net).
.SS Custom chunks
@@ -2959,10 +2984,7 @@ can be found in the comments inside the code itself.
.SS Configuring for 16 bit platforms
You may need to change the png_large_malloc() and png_large_free()
routines in pngmem.c, as these are required to allocate 64K, although
there is already support for many of the common DOS compilers. Also,
you will want to look into zconf.h to tell zlib (and thus libpng) that
You will want to look into zconf.h to tell zlib (and thus libpng) that
it cannot allocate more then 64K at a time. Even if you can, the memory
won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
@@ -3031,6 +3053,7 @@ zlib.h for more information on what these mean.
png_set_compression_window_bits(png_ptr,
window_bits);
png_set_compression_method(png_ptr, method);
png_set_compression_buffer_size(png_ptr, size);
.SS Controlling row filtering
@@ -3059,7 +3082,13 @@ you intend to use so that libpng can initialize its internal
structures appropriately for all of the filter types.
filters = PNG_FILTER_NONE | PNG_FILTER_SUB
| PNG_FILTER_UP;
PNG_FILTER_UP | PNG_FILTER_AVE |
PNG_FILTER_PAETH | PNG_ALL_FILTERS;
or
filters = one of PNG_FILTER_VALUE_NONE,
PNG_FILTER_VALUE_SUB, PNG_FILTER_VALUE_UP,
PNG_FILTER_VALUE_AVE, PNG_FILTER_VALUE_PAETH
png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
filters);
@@ -3108,7 +3137,7 @@ you can turn off individual capabilities with defines that begin with
PNG_NO_.
You can also turn all of the transforms and ancillary chunk capabilities
off en masse with compiler directives that define
off en masse with compiler directives that define
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
or all four,
along with directives to turn on any of the capabilities that you do
@@ -3208,13 +3237,13 @@ the old method.
.SH VII. Y2K Compliance in libpng
April 14, 2000
April 24, 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.6f are Y2K compliant. It is my belief that earlier
upward through 1.0.6g 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
@@ -3355,7 +3384,7 @@ possible without all of you.
Thanks to Frank J. T. Wojcik for helping with the documentation.
Libpng version 1.0.6f - April 14, 2000:
Libpng version 1.0.6g - April 24, 2000:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (randeg@alum.rpi.edu).
@@ -3370,7 +3399,7 @@ Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
Copyright (c) 1996, 1997 Andreas Dilger
(libpng versions 0.89c, May 1996, through 0.96, May 1997)
Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson
(libpng versions 0.97, January 1998, through 1.0.6f, April 14, 2000)
(libpng versions 0.97, January 1998, through 1.0.6g, April 24, 2000)
For the purposes of this copyright and license, "Contributing Authors"
is defined as the following set of individuals: