-.TH LIBPNG 3 "March 15, 1998"
+.TH LIBPNG 3 "January 14, 1999"
.SH NAME
-libpng \- Portable Network Graphics (PNG) Reference Library
+libpng \- Portable Network Graphics (PNG) Reference Library 1.0.3 - January 14, 1999
.SH SYNOPSIS
#include <png.h>
user_png_ver, voidp error_ptr, png_error_ptr error_fn,
png_error_ptr warn_fn);
+png_structp png_create_read_struct_2(png_const_charp user_png_ver,
+png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr
+warn_fn, png_voidp mem_ptr, png_malloc_ptr malloc_fn,
+png_free_ptr free_fn)
+
png_structp png_create_write_struct (png_const_charp
user_png_ver, voidp error_ptr, png_error_ptr error_fn,
png_error_ptr warn_fn);
-void png_debug_free (png_structp png_ptr, png_voidp ptr);
+png_structp png_create_write_struct_2(png_const_charp
+user_png_ver, png_voidp error_ptr, png_error_ptr error_fn,
+png_error_ptr warn_fn, png_voidp mem_ptr,
+png_malloc_ptr malloc_fn, png_free_ptr free_fn)
+
+int png_debug(int level, png_const_charp message)
+
+int png_debug1(int level, png_const_charp message, p1)
-png_voidp png_debug_malloc (png_structp png_ptr, png_uint_32
-size);
+int png_debug2(int level, png_const_charp message, p1, p2)
void png_destroy_info_struct (png_structp png_ptr, png_infopp
info_ptr_ptr);
void png_free (png_structp png_ptr, png_voidp ptr);
+void png_free_default(png_structp png_ptr, png_voidp ptr)
+
png_byte png_get_bit_depth (png_structp png_ptr, png_infop
info_ptr);
png_byte png_get_compression_type (png_structp png_ptr,
png_infop info_ptr);
+png_byte png_get_copyright (png_structp png_ptr);
+
png_voidp png_get_error_ptr (png_structp png_ptr);
png_byte png_get_filter_type (png_structp png_ptr, png_infop
png_uint_32 png_get_gAMA (png_structp png_ptr, png_infop
info_ptr, double *file_gamma);
+png_byte png_get_header_version (png_structp png_ptr);
+
png_uint_32 png_get_hIST (png_structp png_ptr, png_infop
info_ptr, png_uint_16p *hist);
+png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop
+info_ptr, png_uint_32 *width, png_uint_32 *height, int
+*bit_depth, int *color_type, int *interlace_type, int
+*compression_type, int *filter_type);
+
png_uint_32 png_get_image_height (png_structp png_ptr,
png_infop info_ptr);
png_voidp png_get_io_ptr (png_structp png_ptr);
-png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop
-info_ptr, png_uint_32 *width, png_uint_32 *height, int
-*bit_depth, int *color_type, int *interlace_type, int
-*compression_type, int *filter_type);
+png_voidp png_get_mem_ptr(png_structp png_ptr)
png_uint_32 png_get_oFFs (png_structp png_ptr, png_infop
info_ptr, png_uint_32 *offset_x, png_uint_32 *offset_y, int
png_uint_32 png_get_PLTE (png_structp png_ptr, png_infop
info_ptr, png_colorp *palette, int *num_palette);
+png_byte png_get_rgb_to_gray_status (png_structp png_ptr)
+
png_uint_32 png_get_rowbytes (png_structp png_ptr, png_infop
info_ptr);
png_voidp png_malloc (png_structp png_ptr, png_uint_32 size);
+png_voidp png_malloc_default(png_structp png_ptr,
+png_uint_32 size)
+
voidp png_memcpy (png_voidp s1, png_voidp s2, png_size_t size);
png_voidp png_memcpy_check (png_structp png_ptr, png_voidp s1,
color_type, int interlace_type, int compression_type, int
filter_type);
+void png_set_mem_fn(png_structp png_ptr, png_voidp mem_ptr,
+png_malloc_ptr malloc_fn, png_free_ptr free_fn)
+
void png_set_oFFs (png_structp png_ptr, png_infop info_ptr,
png_uint_32 offset_x, png_uint_32 offset_y, int unit_type);
png_rw_ptr read_data_fn);
void png_set_read_status_fn (png_structp png_ptr, png_read_status_ptr
- read_row_fn);
+read_row_fn);
void png_set_read_user_transform_fn (png_structp png_ptr,
- png_user_transform_ptr read_user_transform_fn);
+png_user_transform_ptr read_user_transform_fn);
-void png_set_rgb_to_gray (png_structp png_ptr);
+void png_set_rgb_to_gray (png_structp png_ptr, int error_action);
void png_set_sBIT (png_structp png_ptr, png_infop info_ptr,
png_color_8p sig_bit);
png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn);
void png_set_write_status_fn (png_structp png_ptr, png_write_status_ptr
- write_row_fn);
+write_row_fn);
void png_set_write_user_transform_fn (png_structp png_ptr,
- png_user_transform_ptr write_user_transform_fn);
+png_user_transform_ptr write_user_transform_fn);
int png_sig_cmp (png_bytep sig, png_size_t start, png_size_t
num_to_check);
void png_write_end (png_structp png_ptr, png_infop info_ptr);
void png_write_flush (png_structp png_ptr);
-
+
void png_write_image (png_structp png_ptr, png_bytepp image);
void png_write_info (png_structp png_ptr, png_infop info_ptr);
.SH LIBPNG.TXT
libpng.txt - A description on how to use and modify libpng
- libpng version 1.0.1 March 15, 1998
+ libpng version 1.0.3 - January 14, 1999
Updated and distributed by Glenn Randers-Pehrson
<randeg@alumni.rpi.edu>
- Copyright (c) 1998, Glenn Randers-Pehrson
+ Copyright (c) 1998, 1999 Glenn Randers-Pehrson
For conditions of distribution and use, see copyright
notice in png.h.
based on:
libpng 1.0 beta 6 version 0.96 May 28, 1997
- Updated and distributed by Andreas Dilger
+ Updated and distributed by Andreas Dilger
Copyright (c) 1996, 1997 Andreas Dilger
libpng 1.0 beta 2 - version 0.88 January 26, 1996
W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some
additional chunks are described in the special-purpose public chunks
documents at <ftp://ftp.uu.net/graphics/png/documents/>. Other information
-about PNG can be found at the PNG home page, <http://www.cdrom.com/pub/png/>.
+about PNG, and the latest version of libpng, can be found at the PNG home
+page, <http://www.cdrom.com/pub/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
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/>.
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.
return;
}
fread(header, 1, number, fp);
- is_png = png_check_sig(header, 0, number);
+ is_png = !png_sig_cmp(header, 0, number);
if (!is_png)
{
return;
on Changes to Libpng below regarding the old initialization functions.
png_structp png_ptr = png_create_read_struct
- (PNG_LIBPNG_VER_STRING, (void *)user_error_ptr,
+ (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
if (!png_ptr)
return;
return;
}
+If you want to use your own memory allocation routines,
+define PNG_USER_MEM_SUPPORTED and use
+png_create_read_struct_2() instead of png_create_read_struct():
+
+ png_structp png_ptr = png_create_read_struct_2
+ (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
+ user_error_fn, user_warning_fn, (png_voidp)
+ user_mem_ptr, user_malloc_fn, user_free_fn);
+
+The error handling routines passed to png_create_read_struct()
+and the memory alloc/free routines passed to png_create_struct_2()
+are only necessary if you are not using the libpng supplied error
+handling and memory alloc/free functions.
-The error handling routines passed to png_create_read_struct() are only
-necessary if you are not using the libpng supplied error handling
-functions. When libpng encounters an error, it expects to longjmp back
-to your routine. Therefore, you will need to call setjmp and pass the
-jmpbuf field of your png_struct. If you read the file from different
+When libpng encounters an error, it expects to longjmp back
+to your routine. Therefore, you will need to call setjmp and pass
+your png_ptr->jmpbuf. 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.
You must supply the function
void read_transform_fn(png_ptr ptr, row_info_ptr
- row_info, png_bytep data)
+ 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.
are present.
PNG_COLOR_TYPE_GRAY
(bit depths 1, 2, 4, 8, 16)
- PNG_COLOR_TYPE_GRAY_ALPHA
+ PNG_COLOR_TYPE_GRAY_ALPHA
(bit depths 8, 16)
PNG_COLOR_TYPE_PALETTE
(bit depths 1, 2, 4, 8)
For example, 4 bit/pixel paletted or grayscale data will be returned
2 pixels/byte with the leftmost pixel in the high-order bits of the
byte, unless png_set_packing() is called. 8-bit RGB data will be stored
-in RGBRGBRGB format unless png_set_filler() is called to insert filler
+in RGB RGB RGB format unless png_set_filler() is called to insert filler
bytes, either before or after each RGB triplet. 16-bit RGB data will
-be returned RRGGBBRRGGBB, with the most significant byte of the color
+be returned RRGGBB RRGGBB, with the most significant byte of the color
value first, unless png_set_strip_16() is called to transform it to
-regular RGBRGB triplets.
+regular RGB RGB triplets, or png_set_filler() is called to insert
+filler bytes, either before or after each RRGGBB triplet. Similarly,
+8-bit or 16-bit grayscale data can be modified with png_set_filler()
+or png_set_strip_16().
The following code transforms grayscale images of less than 8 to 8 bits,
changes paletted images to RGB, and adds a full alpha channel if there is
PNG_COLOR_TYPE_RGB) png_set_filler(png_ptr,
filler, PNG_FILLER_BEFORE);
-where "filler" is the number to fill with, and the location is
+where "filler" is the 8 or 16-bit number to fill with, and the location is
either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
you want the filler before the RGB or after. This transformation
does not affect images that already have full alpha channels.
color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
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.
+
+ if (color_type == PNG_COLOR_TYPE_RGB ||
+ color_type == PNG_COLOR_TYPE_RGB_ALPHA)
+ png_set_rgb_to_gray(png_ptr, error_action,
+ float red_weight, float green_weight);
+
+ error_action = 1: silently do the conversion
+ error_action = 2: issue a warning if the original
+ image has any pixel where
+ red != green or red != blue
+ error_action = 3: issue an error and abort the
+ conversion if the original
+ 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)
+
+If you have set error_action = 1 or 2, you can
+later check whether the image really was gray, after processing
+the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
+It will return a png_byte that is zero if the image was gray or
+1 if there were any non-gray pixels. bKGD and sBIT data
+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,
+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;
+
+The default values approximate those recommended in the Charles
+Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
+Copyright (c) 1998-01-04 Charles Poynton poynton@inforamp.net
+
+ Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
+
+Libpng approximates this with
+
+ Y = 0.211 * R + 0.715 * G + 0.074 * B
+
+which can be expressed with integers as
+
+ Y = (54 * R + 183 * G + 19 * B)/256
+
+The calculation is done in a linear colorspace, if the image gamma
+is known.
+
If you have a grayscale and you are using png_set_expand() to change to
-a higher bit-depth you must indicate if the supplied background gray
-is supplied in the original file bit depth (need_expand = 1) or in the
-expanded bit depth (need_expand = 0). Similarly, if you are reading
-a paletted image, you must indicate if you have supplied the background
-as a palette index that needs to be expanded (need_expand = 1). You can
-also specify an RGB triplet that isn't in the palette when setting your
-background for a paletted image.
+a higher bit-depth, you must either supply the background color as a gray
+value at the original file bit-depth (need_expand = 1) or else supply the
+background color as an RGB triplet at the final, expanded bit depth
+(need_expand = 0). Similarly, if you are reading a paletted image, you
+must either supply the background color as a palette index (need_expand = 1)
+or as an RGB triplet that may or may not be in the palette (need_expand = 0).
png_color_16 my_background;
png_color_16p image_background;
- if (png_get_bKGD(png_ptr, info_ptr,
- &image_background))
- png_set_background(png_ptr, image_background),
- PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
+ if (png_get_bKGD(png_ptr, info_ptr, &image_background))
+ png_set_background(png_ptr, image_background,
+ PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
else
png_set_background(png_ptr, &my_background,
PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
The png_set_gamma() function handles gamma transformations of the data.
Pass both the file gamma and the current screen_gamma. If the file does
not have a gamma value, you can pass one anyway if you have an idea what
-it is (usually 0.50 is a good guess for GIF images on PCs). Note
+it is (usually 0.45455 is a good guess for GIF images on PCs). Note
that file gammas are inverted from screen gammas. See the discussions
on gamma in the PNG specification for an excellent description of what
gamma is, and why all applications should support it. It is strongly
if (png_get_gAMA(png_ptr, info_ptr, &gamma))
png_set_gamma(png_ptr, screen_gamma, gamma);
else
- png_set_gamma(png_ptr, screen_gamma, 0.50);
+ png_set_gamma(png_ptr, screen_gamma, 0.45455);
If you need to reduce an RGB file to a paletted file, or if a paletted
file has more entries then will fit on your screen, png_set_dither()
initialize_png_reader()
{
png_ptr = png_create_read_struct
- (PNG_LIBPNG_VER_STRING, (void *)user_error_ptr,
+ (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
if (!png_ptr)
return -1;
to be called when the header info is valid,
when each row is completed, and when the image
is finished. If you aren't using all functions,
- you can specify a NULL parameter. You can use
+ you can specify NULL parameters. Even when all
+ three functions are NULL, you need to call
+ png_set_progressive_read_fn(). You can use
any struct as the user_ptr (cast to a void pointer
for the function call), and retrieve the pointer
from inside the callbacks using the function
of data from the file stream (in order, of
course). On machines with segmented memory
models machines, don't give it any more than
- 64K. The library seems to run fine with sizes
+ 64K. The library seems to run fine with sizes
of 4K. Although you can give it much less if
necessary (I assume you can give it chunks of
1 byte, I haven't tried less then 256 bytes
yet). When this function returns, you may
want to display any rows that were generated
in the row callback if you don't already do
- so there.
+ so there.
*/
png_process_data(png_ptr, info_ptr, buffer, length);
return 0;
}
/* This function is called (as set by
- png_set_progressive_fn() above) when enough data
+ png_set_progressive_read_fn() above) when enough data
has been supplied so all of the header has been
read.
*/
new_row);
/* where old_row is what was displayed for
- previous rows. Note that the first pass
- (pass == 0, really) will completely cover
+ previously for the row. Note that the first
+ pass (pass == 0, really) will completely cover
the old row, so the rows do not have to be
initialized. After the first pass (and only
for interlaced images), you will have to pass
the current row, and the function will combine
the old row and the new row.
- */
+ */
}
void
*/
}
+
+
.SH IV. Writing
Much of this is very similar to reading. However, everything of
so if it doesn't work, you don't have anything to undo. If you are not
using the standard I/O functions, you will need to replace them with
custom writing functions. See the discussion under Customizing libpng.
-
+
FILE *fp = fopen(file_name, "wb");
if (!fp)
{
"read_ptr" and "write_ptr". Look at pngtest.c, for example.
png_structp png_ptr = png_create_write_struct
- (PNG_LIBPNG_VER_STRING, (void *)user_error_ptr,
+ (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
if (!png_ptr)
return;
return;
}
+If you want to use your own memory allocation routines,
+define PNG_USER_MEM_SUPPORTED and use
+png_create_write_struct_2() instead of png_create_read_struct():
+
+ png_structp png_ptr = png_create_write_struct_2
+ (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
+ user_error_fn, user_warning_fn, (png_voidp)
+ user_mem_ptr, user_malloc_fn, user_free_fn);
+
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 jmpbuf field of your png_struct. If you
+setjmp() and pass the png_ptr->jmpbuf. If you
write 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. 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_ptr->jmpbuf))
- {
+ {
png_destroy_write_struct(&png_ptr, &info_ptr);
fclose(fp);
return;
}
+ ...
+ return;
Now you need to set up the output code. The default for libpng is to
use the C function fwrite(). If you use this, you will need to pass a
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
October 1996 PNG specification, version 1.0). 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 types.
+flag that indicates which filter type(s) are to be tested for each
+scanline. See the Compression Library for details on the specific filter
+types.
+
-
/* turn on or off filtering, and/or choose
specific filters */
png_set_filter(png_ptr, 0,
PNG_SRGB_INTENT_PERCEPTUAL,
PNG_SRGB_INTENT_ABSOLUTE, or
PNG_SRGB_INTENT_RELATIVE.
-
+
png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
srgb_intent);
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
+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.
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
created in a non-PNG format, a still photo from which the image was
scanned, or possibly the subject matter itself. In order to facilitate
machine-readable dates, it is recommended that the "Creation Time"
-tEXt chunk use RFC 1123 format dates (e.g. 22 May 1997 18:07:10 GMT"),
+tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
although this isn't a requirement. Unlike the tIME chunk, the
"Creation Time" tEXt chunk is not expected to be automatically changed
by the software. To facilitate the use of RFC 1123 dates, a function
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 bytes. This code tells
-the library to expect input data with 4 bytes per pixel
+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).
png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
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.
-
+
/* Set the true bit depth of the image data */
if (color_type & PNG_COLOR_MASK_COLOR)
{
You must supply the function
void write_transform_fn(png_ptr ptr, row_info_ptr
- row_info, png_bytep data)
+ row_info, png_bytep data)
See pngtest.c for a working example. Your function will be called
before any of the other transformations have been processed.
where row_pointers is:
- png_bytef *row_pointers[height];
+ png_byte *row_pointers[height];
You can point to void or char or whatever you use for pixels.
-If you can't want to write the whole image at once, you can
+If you don't want to write the whole image at once, you can
use png_write_rows() instead. If the file is not interlaced,
this is simple:
adding new transformations, and generally changing how libpng works.
All of the memory allocation, input/output, and error handling in libpng
-goes through callbacks which are user settable. The default routines are
+goes through callbacks that are user settable. The default routines are
in pngmem.c, pngrio.c, pngwio.c, and pngerror.c respectively. To change
these functions, call the appropriate png_set_???_fn() function.
also provide a void pointer that can be retrieved via the function
png_get_io_ptr(). For example:
- png_set_read_fn(png_structp png_ptr,
- voidp io_ptr, png_rw_ptr read_data_fn)
+ png_set_read_fn(png_structp read_ptr,
+ voidp read_io_ptr, png_rw_ptr read_data_fn)
- png_set_write_fn(png_structp png_ptr,
- voidp io_ptr, png_rw_ptr write_data_fn,
+ png_set_write_fn(png_structp write_ptr,
+ voidp write_io_ptr, png_rw_ptr write_data_fn,
png_flush_ptr output_flush_fn);
- voidp io_ptr = png_get_io_ptr(png_ptr);
+ voidp read_io_ptr = png_get_io_ptr(read_ptr);
+ voidp write_io_ptr = png_get_io_ptr(write_ptr);
The replacement I/O functions should have prototypes as follows:
Configuring for DOS:
-For DOS users which only have access to the lower 640K, you will
+For DOS users who only have access to the lower 640K, you will
have to limit zlib's memory usage via a png_set_compression_mem_level()
call. See zlib.h or zconf.h in the zlib library for more information.
all set. Everything in the library (except for zlib's structure) is
expecting far data. You must use the typedefs with the p or pp on
the end for pointers (or at least look at them and be careful). Make
-note that the row's of data are defined as png_bytepp which is a
+note that the row's of data are defined as png_bytepp, which is an
unsigned char far * far *.
Configuring for gui/windowing platforms:
of row filters can have a significant impact on the size and
encoding speed and a somewhat lesser impact on the decoding speed
of an image. Filtering is enabled by default for RGB and grayscale
-images (with and without alpha), and for 8-bit paletted images, but
-not for paletted images with bit depths less than 8 bits/pixel.
+images (with and without alpha), but not for paletted images nor
+for any images with bit depths less than 8 bits/pixel.
The 'method' parameter sets the main filtering method, which is
currently only '0' in the PNG 1.0 specification. The 'filters'
PNG_FILTER_SELECTION_WEIGHTED, 3,
weights, costs);
-The weights are multiplying factors which indicate to libpng that row
-should be the same for successive rows unless another row filter is that
-many times better than the previous filter. In the above example, if
-the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
+The weights are multiplying factors that indicate to libpng that the
+row filter should be the same for successive rows unless another row filter
+is that many times better than the previous filter. In the above example,
+if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
"sum of absolute differences" 1.5 x 1.3 times higher than other filters
and still be chosen, while the NONE filter could have a sum 1.1 times
higher than other filters and still be chosen. Unspecified weights are
There are a bunch of #define's in pngconf.h that control what parts of
libpng are compiled. All the defines end in _SUPPORTED. If you are
-never going to use an ability, you can change the #define to #undef
-before recompiling libpng and save yourself code and data space.
-You can also turn a number of them off en masse with a compiler directive
-that defines PNG_READ[or WRITE]_TRANSFORMS_NOT_SUPPORTED, or
-PNG_READ[or WRITE]_ANCILLARY_CHUNKS_NOT_SUPPORTED, or all four,
+never going to use a capability, you can change the #define to #undef
+before recompiling libpng and save yourself code and data space, or
+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
+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
-want. The PNG_READ[or WRITE]_TRANSFORMS_NOT_SUPPORTED directives disable
+want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable
the extra transformations but still leave the library fully capable of reading
and writing PNG files with all known public chunks [except for sPLT].
-Use of the PNG_READ[or WRITE]_ANCILLARY_CHUNKS_NOT_SUPPORTED directive
+Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive
produces a library that is incapable of reading or writing ancillary chunks.
If you are not using the progressive reading capability, you can
-turn that off with PNG_PROGRESSIVE_READ_NOT_SUPPORTED (don't confuse
+turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse
this with the INTERLACING capability, which you'll still have).
All the reading and writing specific code are in separate files, so the
as this will cause applications linked with different versions of the
library to fail if they call functions not available in your library.
The size of the library itself should not be an issue, because only
-those sections which are actually used will be loaded into memory.
+those sections that are actually used will be loaded into memory.
+
+Requesting debug printout:
+
+The macro definition PNG_DEBUG can be used to request debugging
+printout. Set it to an integer value in the range 0 to 3. Higher
+numbers result in increasing amounts of debugging information. The
+information is printed to the "stderr" file, unless another file
+name is specified in the PNG_DEBUG_FILE macro definition.
+
+When PNG_DEBUG > 0, the following functions (macros) become available:
+
+ png_debug(level, message)
+ png_debug1(level, message, p1)
+ png_debug2(level, message, p1, p2)
+
+in which "level" is compared to PNG_DEBUG to decide whether to print
+the message, "message" is the formatted string to be printed,
+and p1 and p2 are parameters that are to be embedded in the string
+according to printf-style formatting directives. For example,
+
+ png_debug1(2, "foo=%d\n", foo);
+is expanded to
-Changes to Libpng from version 0.88
+ if(PNG_DEBUG > 2)
+ fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
+
+When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
+can still use PNG_DEBUG to control your own debugging:
+
+ #ifdef PNG_DEBUG
+ fprintf(stderr, ...
+ #endif
+
+When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
+having level = 0 will be printed. There aren't any such statements in
+this version of libpng, but if you insert some they will be printed.
+
+.SH VI. 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
Setting the error callbacks via png_set_message_fn() before
png_read_init() as was suggested in libpng-0.88 is no longer supported
-because this caused applications which do not use custom error functions
+because this caused applications that do not use custom error functions
to fail if the png_ptr was not initialized to zero. It is still possible
to set the error callbacks AFTER png_read_init(), or to change them with
png_set_error_fn(), which is essentially the same function, but with a
new name to force compilation errors with applications that try to use
the old method.
+.SH VII. Y2K Compliance in libpng
+
+January 13, 1999
+
+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.81 and
+upward 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
+will hold years up to 65535. The other two hold the date in text
+format, and will hold years up to 9999.
+
+The integer is
+ "png_uint_16 year" in png_time_struct.
+
+The strings are
+ "png_charp time_buffer" in png_struct and
+ "near_time_buffer", which is a local character string in png.c.
+
+There are seven time-related functions:
+
+ png_convert_to_rfc_1123() in png.c
+ (formerly png_convert_to_rfc_1152() in error)
+ png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c
+ png_convert_from_time_t() in pngwrite.c
+ png_get_tIME() in pngget.c
+ png_handle_tIME() in pngrutil.c, called in pngread.c
+ png_set_tIME() in pngset.c
+ png_write_tIME() in pngwutil.c, called in pngwrite.c
+
+All appear to handle dates properly in a Y2K environment. The
+png_convert_from_time_t() function calls gmtime() to convert from system
+clock time, which returns (year - 1900), which we properly convert to
+the full 4-digit year. There is a possibility that applications using
+libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
+function, or incorrectly passing only a 2-digit year instead of
+"year - 1900" into the png_convert_from_struct_tm() function, but this
+is not under our control. The libpng documentation has always stated
+that it works with 4-digit years, and the APIs have been documented as
+such.
+
+The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
+integer to hold the year, and can hold years as large as 65535.
+
+
+ Glenn Randers-Pehrson
+ libpng maintainer
+ PNG Development Group
+
.SH NOTE
Note about libpng version numbers:
Thanks to Frank J. T. Wojcik for helping with the documentation.
-Libpng version 1.0.1 March 15, 1998:
+Libpng version 1.0.3 - January 14, 1999:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (randeg@alumni.rpi.edu).
.SH COPYRIGHT NOTICE:
+Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
+Copyright (c) 1996, 1997 Andreas Dilger
+Copyright (c) 1998, 1999 Glenn Randers-Pehrson
+
The PNG Reference Library (libpng) is supplied "AS IS". The Contributing
Authors and Group 42, Inc. disclaim all warranties, expressed or implied,
including, without limitation, the warranties of merchantability and of
projects / wxWidgets.git / blobdiff