minecraft-pi-reborn/libpng
Archived
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[master] Fixed up some line-wrapping in the documentation.

Browse Source
This commit is contained in:
Glenn Randers-Pehrson 2009-11-12 11:30:03 -06:00
parent bef02a89ea
commit bcb1b414ed
2 changed files with 164 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
libpng-1.2.41beta19.txt
View File

@ -1,6 +1,6 @@
libpng.txt - A description on how to use and modify libpng libpng.txt - A description on how to use and modify libpng
libpng version 1.2.41beta19 - November 11, 2009 libpng version 1.2.41beta19 - November 12, 2009
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net> <glennrp at users.sourceforge.net>
Copyright (c) 1998-2009 Glenn Randers-Pehrson Copyright (c) 1998-2009 Glenn Randers-Pehrson
@ -11,7 +11,7 @@ libpng.txt - A description on how to use and modify libpng
Based on: Based on:
libpng versions 0.97, January 1998, through 1.2.41beta19 - November 11, 2009 libpng versions 0.97, January 1998, through 1.2.41beta19 - November 12, 2009
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2009 Glenn Randers-Pehrson Copyright (c) 1998-2009 Glenn Randers-Pehrson
@ -40,8 +40,8 @@ will need. We assume that libpng is already installed; see the
INSTALL file for instructions on how to install libpng. INSTALL file for instructions on how to install libpng.
For examples of libpng usage, see the files "example.c", "pngtest.c", 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 and the files in the "contrib" directory, all of which are included in
libpng distribution. the libpng distribution.
Libpng was written as a companion to the PNG specification, as a way 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 of reducing the amount of time and effort it takes to support the PNG
@ -458,8 +458,8 @@ dithering, and setting filler.) If this is the case, simply do this:
png_read_png(png_ptr, info_ptr, png_transforms, NULL) png_read_png(png_ptr, info_ptr, png_transforms, NULL)
where png_transforms is an integer containing the bitwise OR of where png_transforms is an integer containing the bitwise OR of some
some set of transformation flags. This call is equivalent to png_read_info(), set of transformation flags. This call is equivalent to png_read_info(),
followed the set of transformations indicated by the transform mask, followed the set of transformations indicated by the transform mask,
then png_read_image(), and finally png_read_end(). then png_read_image(), and finally png_read_end().
@ -610,8 +610,8 @@ These are also important, but their validity depends on whether the chunk
has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
data has been read, or zero if it is missing. The parameters to the data has been read, or zero if it is missing. The parameters to the
png_get_<chunk> are set directly if they are simple data types, or a pointer png_get_<chunk> are set directly if they are simple data types, or a
into the info_ptr is returned for any complex types. pointer into the info_ptr is returned for any complex types.
png_get_PLTE(png_ptr, info_ptr, &palette, png_get_PLTE(png_ptr, info_ptr, &palette,
&num_palette); &num_palette);
@ -957,10 +957,10 @@ values of the pixels:
PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
stored in a PNG image have been "scaled" or "shifted" up to the next stored in a PNG image have been "scaled" or "shifted" up to the next
higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
8 bits/sample in the range [0, 255]). However, it is also possible to to 8 bits/sample in the range [0, 255]). However, it is also possible
convert the PNG pixel data back to the original bit depth of the image. to convert the PNG pixel data back to the original bit depth of the
This call reduces the pixels back down to the original bit depth: image. This call reduces the pixels back down to the original bit depth:
png_color_8p sig_bit; png_color_8p sig_bit;
@ -1407,12 +1407,11 @@ point to libpng-allocated storage with the following function:
This function may be safely called when the relevant storage has This function may be safely called when the relevant storage has
already been freed, or has not yet been allocated, or was allocated already been freed, or has not yet been allocated, or was allocated
by the user and not by libpng, and will in those by the user and not by libpng, and will in those cases do nothing.
cases do nothing. The "seq" parameter is ignored if only one item The "seq" parameter is ignored if only one item of the selected data
of the selected data type, such as PLTE, is allowed. If "seq" is not type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
-1, and multiple items are allowed for the data type identified in are allowed for the data type identified in the mask, such as text or
the mask, such as text or sPLT, only the n'th item in the structure sPLT, only the n'th item in the structure is freed, where n is "seq".
is freed, where n is "seq".
The default behavior is only to free data that was allocated internally The default behavior is only to free data that was allocated internally
by libpng. This can be changed, so that libpng will not free the data, by libpng. This can be changed, so that libpng will not free the data,
@ -1451,8 +1450,8 @@ if you transfer responsibility for free'ing text_ptr from libpng to your
application, your application must not separately free those members. application, your application must not separately free those members.
The png_free_data() function will turn off the "valid" flag for anything The png_free_data() function will turn off the "valid" flag for anything
it frees. If you need to turn the flag off for a chunk that was freed by your it frees. If you need to turn the flag off for a chunk that was freed by
application instead of by libpng, you can use your application instead of by libpng, you can use
png_set_invalid(png_ptr, info_ptr, mask); png_set_invalid(png_ptr, info_ptr, mask);
mask - identifies the chunks to be made invalid, mask - identifies the chunks to be made invalid,
@ -1762,8 +1761,8 @@ the filter method, for which the only valid values are 0 (as of the
July 1999 PNG specification, version 1.2) or 64 (if you are writing July 1999 PNG specification, version 1.2) or 64 (if you are writing
a PNG datastream that is to be embedded in a MNG datastream). The third a PNG datastream that is to be embedded in a MNG datastream). The third
parameter is a flag that indicates which filter type(s) are to be tested parameter is a flag that indicates which filter type(s) are to be tested
for each scanline. See the PNG specification for details on the specific filter for each scanline. See the PNG specification for details on the specific
types. filter types.
/* turn on or off filtering, and/or choose /* turn on or off filtering, and/or choose
@ -2181,10 +2180,10 @@ this with a call to png_write_info().
Note that there is one transformation you may need to do before Note that there is one transformation you may need to do before
png_write_info(). In PNG files, the alpha channel in an image is the png_write_info(). In PNG files, the alpha channel in an image is the
level of opacity. If your data is supplied as a level of level of opacity. If your data is supplied as a level of transparency,
transparency, you can invert the alpha channel before you write it, so you can invert the alpha channel before you write it, so that 0 is
that 0 is fully transparent and 255 (in 8-bit or paletted images) or fully transparent and 255 (in 8-bit or paletted images) or 65535
65535 (in 16-bit images) is fully opaque, with (in 16-bit images) is fully opaque, with
png_set_invert_alpha(png_ptr); png_set_invert_alpha(png_ptr);
@ -2371,14 +2370,13 @@ a single row_pointer instead of an array of row_pointers:
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 When the file is interlaced, things can get a good deal more complicated.
complicated. The only currently (as of the PNG Specification The only currently (as of the PNG Specification version 1.2, dated July
version 1.2, dated July 1999) defined interlacing scheme for PNG files 1999) defined interlacing scheme for PNG files is the "Adam7" interlace
is the "Adam7" interlace scheme, that breaks down an scheme, that breaks down an image into seven smaller images of varying
image into seven smaller images of varying size. libpng will build size. libpng will build these images for you, or you can do them
these images for you, or you can do them yourself. If you want to yourself. If you want to build them yourself, see the PNG specification
build them yourself, see the PNG specification for details of which for details of which pixels to write when.
pixels to write when.
If you don't want libpng to handle the interlacing details, just If you don't want libpng to handle the interlacing details, just
use png_set_interlace_handling() and call png_write_rows() the use png_set_interlace_handling() and call png_write_rows() the
@ -2390,17 +2388,17 @@ writing any rows:
number_of_passes = number_of_passes =
png_set_interlace_handling(png_ptr); png_set_interlace_handling(png_ptr);
This will return the number of passes needed. Currently, this This will return the number of passes needed. Currently, this is seven,
is seven, but may change if another interlace type is added. but may change if another interlace type is added.
Then write the complete image number_of_passes times. Then write the complete image number_of_passes times.
png_write_rows(png_ptr, row_pointers, png_write_rows(png_ptr, row_pointers,
number_of_rows); number_of_rows);
As some of these rows are not used, and thus return immediately, As some of these rows are not used, and thus return immediately, you may
you may want to read about interlacing in the PNG specification, want to read about interlacing in the PNG specification, and only update
and only update the rows that are actually used. the rows that are actually used.
Finishing a sequential write Finishing a sequential write
@ -2433,15 +2431,14 @@ point to libpng-allocated storage with the following function:
This function may be safely called when the relevant storage has This function may be safely called when the relevant storage has
already been freed, or has not yet been allocated, or was allocated already been freed, or has not yet been allocated, or was allocated
by the user and not by libpng, and will in those by the user and not by libpng, and will in those cases do nothing.
cases do nothing. The "seq" parameter is ignored if only one item The "seq" parameter is ignored if only one item of the selected data
of the selected data type, such as PLTE, is allowed. If "seq" is not type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
-1, and multiple items are allowed for the data type identified in are allowed for the data type identified in the mask, such as text or
the mask, such as text or sPLT, only the n'th item in the structure sPLT, only the n'th item in the structure is freed, where n is "seq".
is freed, where n is "seq".
If you allocated data such as a palette that you passed If you allocated data such as a palette that you passed in to libpng
in to libpng with png_set_*, you must not free it until just before the call to with png_set_*, you must not free it until just before the call to
png_destroy_write_struct(). png_destroy_write_struct().
The default behavior is only to free data that was allocated internally The default behavior is only to free data that was allocated internally
@ -2507,16 +2504,18 @@ 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. these functions, call the appropriate png_set_*_fn() function.
Memory allocation is done through the functions png_malloc() Memory allocation is done through the functions png_malloc(), png_calloc(),
and png_free(). These currently just call the standard C functions. If and png_free(). These currently just call the standard C functions.
your pointers can't access more then 64K at a time, you will want to set png_calloc() calls png_malloc() and then png_memset() to clear the newly
MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling allocated memory to zero. If your pointers can't access more then 64K
memory allocation on a platform will change between applications, these at a time, you will want to set MAXSEG_64K in zlib.h. Since it is
functions must be modified in the library at compile time. If you prefer unlikely that the method of handling memory allocation on a platform
to use a different method of allocating and freeing data, you can use will change between applications, these functions must be modified in
png_create_read_struct_2() or png_create_write_struct_2() to register the library at compile time. If you prefer to use a different method
your own functions as described above. of allocating and freeing data, you can use png_create_read_struct_2() or
These functions also provide a void pointer that can be retrieved via png_create_write_struct_2() to register your own functions as described
above. These functions also provide a void pointer that can be retrieved
via
mem_ptr=png_get_mem_ptr(png_ptr); mem_ptr=png_get_mem_ptr(png_ptr);
@ -2608,10 +2607,10 @@ The motivation behind using setjmp() and longjmp() is the C++ throw and
catch exception handling methods. This makes the code much easier to write, catch exception handling methods. This makes the code much easier to write,
as there is no need to check every return code of every function call. 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 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 after a longjmp, so the user may want to be careful about doing anything
setjmp returns non-zero besides returning itself. Consult your compiler after setjmp returns non-zero besides returning itself. Consult your
documentation for more details. For an alternative approach, you may wish compiler documentation for more details. For an alternative approach, you
to use the "cexcept" facility (see http://cexcept.sourceforge.net). may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
Custom chunks Custom chunks
@ -2623,15 +2622,14 @@ library code itself needs to know about interactions between your
chunk and existing `intrinsic' chunks. chunk and existing `intrinsic' chunks.
If you need to write a new intrinsic chunk, first read the PNG If you need to write a new intrinsic chunk, first read the PNG
specification. Acquire a first level of specification. Acquire a first level of understanding of how it works.
understanding of how it works. Pay particular attention to the Pay particular attention to the sections that describe chunk names,
sections that describe chunk names, and look at how other chunks were and look at how other chunks were designed, so you can do things
designed, so you can do things similarly. Second, check out the similarly. Second, check out the sections of libpng that read and
sections of libpng that read and write chunks. Try to find a chunk write chunks. Try to find a chunk that is similar to yours and use
that is similar to yours and use it as a template. More details can it as a template. More details can be found in the comments inside
be found in the comments inside the code. It is best to handle unknown the code. It is best to handle unknown chunks in a generic method,
chunks in a generic method, via callback functions, instead of by via callback functions, instead of by modifying libpng functions.
modifying libpng functions.
If you wish to write your own transformation for the data, look through If you wish to write your own transformation for the data, look through
the part of the code that does the transformations, and check out some of the part of the code that does the transformations, and check out some of
@ -2808,14 +2806,14 @@ off en masse with compiler directives that define
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
or all four, or all four,
along with directives to turn on any of the capabilities that you do along with directives to turn on any of the capabilities that you do
want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
the extra transformations but still leave the library fully capable of reading transformations but still leave the library fully capable of reading
and writing PNG files with all known public chunks and writing PNG files with all known public chunks. Use of the
Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
produces a library that is incapable of reading or writing ancillary chunks. that is incapable of reading or writing ancillary chunks. If you are
If you are not using the progressive reading capability, you can not using the progressive reading capability, you can turn that off
turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
this with the INTERLACING capability, which you'll still have). capability, which you'll still have).
All the reading and writing specific code are in separate files, so the All the reading and writing specific code are in separate files, so the
linker should only grab the files it needs. However, if you want to linker should only grab the files it needs. However, if you want to
@ -3028,13 +3026,13 @@ They have been replaced, respectively, by:
PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
deprecated since libpng-1.0.16 and libpng-1.2.6. deprecated since libpng-1.0.16 and libpng-1.2.6.
The deprecated function The function
png_check_sig(sig, num) png_check_sig(sig, num)
was replaced with was replaced with
!png_sig_cmp(sig, 0, num) !png_sig_cmp(sig, 0, num)
It has been deprecated since libpng-0.90. It has been deprecated since libpng-0.90.
The deprecated function The function
png_set_gray_1_2_4_to_8() png_set_gray_1_2_4_to_8()
which also expands tRNS to alpha was replaced with which also expands tRNS to alpha was replaced with
png_set_expand_gray_1_2_4_to_8() png_set_expand_gray_1_2_4_to_8()
@ -3172,12 +3170,11 @@ when there is only one macro being tested.
We do not use the TAB character for indentation in the C sources. We do not use the TAB character for indentation in the C sources.
Other rules can be inferred by inspecting the libpng Other rules can be inferred by inspecting the libpng source.
source.
XIII. Y2K Compliance in libpng XIII. Y2K Compliance in libpng
November 11, 2009 November 12, 2009
Since the PNG Development group is an ad-hoc body, we can't make Since the PNG Development group is an ad-hoc body, we can't make
an official declaration. an official declaration.

171
libpng.3
View File

@ -1,4 +1,4 @@
.TH LIBPNG 3 "November 11, 2009" .TH LIBPNG 3 "November 12, 2009"
.SH NAME .SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.2.41beta19 libpng \- Portable Network Graphics (PNG) Reference Library 1.2.41beta19
.SH SYNOPSIS .SH SYNOPSIS
@ -821,7 +821,7 @@ Following is a copy of the libpng.txt file that accompanies libpng.
.SH LIBPNG.TXT .SH LIBPNG.TXT
libpng.txt - A description on how to use and modify libpng libpng.txt - A description on how to use and modify libpng
libpng version 1.2.41beta19 - November 11, 2009 libpng version 1.2.41beta19 - November 12, 2009
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net> <glennrp at users.sourceforge.net>
Copyright (c) 1998-2009 Glenn Randers-Pehrson Copyright (c) 1998-2009 Glenn Randers-Pehrson
@ -832,7 +832,7 @@ libpng.txt - A description on how to use and modify libpng
Based on: Based on:
libpng versions 0.97, January 1998, through 1.2.41beta19 - November 11, 2009 libpng versions 0.97, January 1998, through 1.2.41beta19 - November 12, 2009
Updated and distributed by Glenn Randers-Pehrson Updated and distributed by Glenn Randers-Pehrson
Copyright (c) 1998-2009 Glenn Randers-Pehrson Copyright (c) 1998-2009 Glenn Randers-Pehrson
@ -861,8 +861,8 @@ will need. We assume that libpng is already installed; see the
INSTALL file for instructions on how to install libpng. INSTALL file for instructions on how to install libpng.
For examples of libpng usage, see the files "example.c", "pngtest.c", 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 and the files in the "contrib" directory, all of which are included in
libpng distribution. the libpng distribution.
Libpng was written as a companion to the PNG specification, as a way 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 of reducing the amount of time and effort it takes to support the PNG
@ -1279,8 +1279,8 @@ dithering, and setting filler.) If this is the case, simply do this:
png_read_png(png_ptr, info_ptr, png_transforms, NULL) png_read_png(png_ptr, info_ptr, png_transforms, NULL)
where png_transforms is an integer containing the bitwise OR of where png_transforms is an integer containing the bitwise OR of some
some set of transformation flags. This call is equivalent to png_read_info(), set of transformation flags. This call is equivalent to png_read_info(),
followed the set of transformations indicated by the transform mask, followed the set of transformations indicated by the transform mask,
then png_read_image(), and finally png_read_end(). then png_read_image(), and finally png_read_end().
@ -1431,8 +1431,8 @@ These are also important, but their validity depends on whether the chunk
has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
data has been read, or zero if it is missing. The parameters to the data has been read, or zero if it is missing. The parameters to the
png_get_<chunk> are set directly if they are simple data types, or a pointer png_get_<chunk> are set directly if they are simple data types, or a
into the info_ptr is returned for any complex types. pointer into the info_ptr is returned for any complex types.
png_get_PLTE(png_ptr, info_ptr, &palette, png_get_PLTE(png_ptr, info_ptr, &palette,
&num_palette); &num_palette);
@ -1778,10 +1778,10 @@ values of the pixels:
PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
stored in a PNG image have been "scaled" or "shifted" up to the next stored in a PNG image have been "scaled" or "shifted" up to the next
higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
8 bits/sample in the range [0, 255]). However, it is also possible to to 8 bits/sample in the range [0, 255]). However, it is also possible
convert the PNG pixel data back to the original bit depth of the image. to convert the PNG pixel data back to the original bit depth of the
This call reduces the pixels back down to the original bit depth: image. This call reduces the pixels back down to the original bit depth:
png_color_8p sig_bit; png_color_8p sig_bit;
@ -2228,12 +2228,11 @@ point to libpng-allocated storage with the following function:
This function may be safely called when the relevant storage has This function may be safely called when the relevant storage has
already been freed, or has not yet been allocated, or was allocated already been freed, or has not yet been allocated, or was allocated
by the user and not by libpng, and will in those by the user and not by libpng, and will in those cases do nothing.
cases do nothing. The "seq" parameter is ignored if only one item The "seq" parameter is ignored if only one item of the selected data
of the selected data type, such as PLTE, is allowed. If "seq" is not type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
-1, and multiple items are allowed for the data type identified in are allowed for the data type identified in the mask, such as text or
the mask, such as text or sPLT, only the n'th item in the structure sPLT, only the n'th item in the structure is freed, where n is "seq".
is freed, where n is "seq".
The default behavior is only to free data that was allocated internally The default behavior is only to free data that was allocated internally
by libpng. This can be changed, so that libpng will not free the data, by libpng. This can be changed, so that libpng will not free the data,
@ -2272,8 +2271,8 @@ if you transfer responsibility for free'ing text_ptr from libpng to your
application, your application must not separately free those members. application, your application must not separately free those members.
The png_free_data() function will turn off the "valid" flag for anything The png_free_data() function will turn off the "valid" flag for anything
it frees. If you need to turn the flag off for a chunk that was freed by your it frees. If you need to turn the flag off for a chunk that was freed by
application instead of by libpng, you can use your application instead of by libpng, you can use
png_set_invalid(png_ptr, info_ptr, mask); png_set_invalid(png_ptr, info_ptr, mask);
mask - identifies the chunks to be made invalid, mask - identifies the chunks to be made invalid,
@ -2583,8 +2582,8 @@ the filter method, for which the only valid values are 0 (as of the
July 1999 PNG specification, version 1.2) or 64 (if you are writing July 1999 PNG specification, version 1.2) or 64 (if you are writing
a PNG datastream that is to be embedded in a MNG datastream). The third a PNG datastream that is to be embedded in a MNG datastream). The third
parameter is a flag that indicates which filter type(s) are to be tested parameter is a flag that indicates which filter type(s) are to be tested
for each scanline. See the PNG specification for details on the specific filter for each scanline. See the PNG specification for details on the specific
types. filter types.
/* turn on or off filtering, and/or choose /* turn on or off filtering, and/or choose
@ -3002,10 +3001,10 @@ this with a call to png_write_info().
Note that there is one transformation you may need to do before Note that there is one transformation you may need to do before
png_write_info(). In PNG files, the alpha channel in an image is the png_write_info(). In PNG files, the alpha channel in an image is the
level of opacity. If your data is supplied as a level of level of opacity. If your data is supplied as a level of transparency,
transparency, you can invert the alpha channel before you write it, so you can invert the alpha channel before you write it, so that 0 is
that 0 is fully transparent and 255 (in 8-bit or paletted images) or fully transparent and 255 (in 8-bit or paletted images) or 65535
65535 (in 16-bit images) is fully opaque, with (in 16-bit images) is fully opaque, with
png_set_invert_alpha(png_ptr); png_set_invert_alpha(png_ptr);
@ -3192,14 +3191,13 @@ a single row_pointer instead of an array of row_pointers:
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 When the file is interlaced, things can get a good deal more complicated.
complicated. The only currently (as of the PNG Specification The only currently (as of the PNG Specification version 1.2, dated July
version 1.2, dated July 1999) defined interlacing scheme for PNG files 1999) defined interlacing scheme for PNG files is the "Adam7" interlace
is the "Adam7" interlace scheme, that breaks down an scheme, that breaks down an image into seven smaller images of varying
image into seven smaller images of varying size. libpng will build size. libpng will build these images for you, or you can do them
these images for you, or you can do them yourself. If you want to yourself. If you want to build them yourself, see the PNG specification
build them yourself, see the PNG specification for details of which for details of which pixels to write when.
pixels to write when.
If you don't want libpng to handle the interlacing details, just If you don't want libpng to handle the interlacing details, just
use png_set_interlace_handling() and call png_write_rows() the use png_set_interlace_handling() and call png_write_rows() the
@ -3211,17 +3209,17 @@ writing any rows:
number_of_passes = number_of_passes =
png_set_interlace_handling(png_ptr); png_set_interlace_handling(png_ptr);
This will return the number of passes needed. Currently, this This will return the number of passes needed. Currently, this is seven,
is seven, but may change if another interlace type is added. but may change if another interlace type is added.
Then write the complete image number_of_passes times. Then write the complete image number_of_passes times.
png_write_rows(png_ptr, row_pointers, png_write_rows(png_ptr, row_pointers,
number_of_rows); number_of_rows);
As some of these rows are not used, and thus return immediately, As some of these rows are not used, and thus return immediately, you may
you may want to read about interlacing in the PNG specification, want to read about interlacing in the PNG specification, and only update
and only update the rows that are actually used. the rows that are actually used.
.SS Finishing a sequential write .SS Finishing a sequential write
@ -3254,15 +3252,14 @@ point to libpng-allocated storage with the following function:
This function may be safely called when the relevant storage has This function may be safely called when the relevant storage has
already been freed, or has not yet been allocated, or was allocated already been freed, or has not yet been allocated, or was allocated
by the user and not by libpng, and will in those by the user and not by libpng, and will in those cases do nothing.
cases do nothing. The "seq" parameter is ignored if only one item The "seq" parameter is ignored if only one item of the selected data
of the selected data type, such as PLTE, is allowed. If "seq" is not type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
-1, and multiple items are allowed for the data type identified in are allowed for the data type identified in the mask, such as text or
the mask, such as text or sPLT, only the n'th item in the structure sPLT, only the n'th item in the structure is freed, where n is "seq".
is freed, where n is "seq".
If you allocated data such as a palette that you passed If you allocated data such as a palette that you passed in to libpng
in to libpng with png_set_*, you must not free it until just before the call to with png_set_*, you must not free it until just before the call to
png_destroy_write_struct(). png_destroy_write_struct().
The default behavior is only to free data that was allocated internally The default behavior is only to free data that was allocated internally
@ -3328,16 +3325,18 @@ 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. these functions, call the appropriate png_set_*_fn() function.
Memory allocation is done through the functions png_malloc() Memory allocation is done through the functions png_malloc(), png_calloc(),
and png_free(). These currently just call the standard C functions. If and png_free(). These currently just call the standard C functions.
your pointers can't access more then 64K at a time, you will want to set png_calloc() calls png_malloc() and then png_memset() to clear the newly
MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling allocated memory to zero. If your pointers can't access more then 64K
memory allocation on a platform will change between applications, these at a time, you will want to set MAXSEG_64K in zlib.h. Since it is
functions must be modified in the library at compile time. If you prefer unlikely that the method of handling memory allocation on a platform
to use a different method of allocating and freeing data, you can use will change between applications, these functions must be modified in
png_create_read_struct_2() or png_create_write_struct_2() to register the library at compile time. If you prefer to use a different method
your own functions as described above. of allocating and freeing data, you can use png_create_read_struct_2() or
These functions also provide a void pointer that can be retrieved via png_create_write_struct_2() to register your own functions as described
above. These functions also provide a void pointer that can be retrieved
via
mem_ptr=png_get_mem_ptr(png_ptr); mem_ptr=png_get_mem_ptr(png_ptr);
@ -3429,10 +3428,10 @@ The motivation behind using setjmp() and longjmp() is the C++ throw and
catch exception handling methods. This makes the code much easier to write, catch exception handling methods. This makes the code much easier to write,
as there is no need to check every return code of every function call. 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 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 after a longjmp, so the user may want to be careful about doing anything
setjmp returns non-zero besides returning itself. Consult your compiler after setjmp returns non-zero besides returning itself. Consult your
documentation for more details. For an alternative approach, you may wish compiler documentation for more details. For an alternative approach, you
to use the "cexcept" facility (see http://cexcept.sourceforge.net). may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
.SS Custom chunks .SS Custom chunks
@ -3444,15 +3443,14 @@ library code itself needs to know about interactions between your
chunk and existing `intrinsic' chunks. chunk and existing `intrinsic' chunks.
If you need to write a new intrinsic chunk, first read the PNG If you need to write a new intrinsic chunk, first read the PNG
specification. Acquire a first level of specification. Acquire a first level of understanding of how it works.
understanding of how it works. Pay particular attention to the Pay particular attention to the sections that describe chunk names,
sections that describe chunk names, and look at how other chunks were and look at how other chunks were designed, so you can do things
designed, so you can do things similarly. Second, check out the similarly. Second, check out the sections of libpng that read and
sections of libpng that read and write chunks. Try to find a chunk write chunks. Try to find a chunk that is similar to yours and use
that is similar to yours and use it as a template. More details can it as a template. More details can be found in the comments inside
be found in the comments inside the code. It is best to handle unknown the code. It is best to handle unknown chunks in a generic method,
chunks in a generic method, via callback functions, instead of by via callback functions, instead of by modifying libpng functions.
modifying libpng functions.
If you wish to write your own transformation for the data, look through If you wish to write your own transformation for the data, look through
the part of the code that does the transformations, and check out some of the part of the code that does the transformations, and check out some of
@ -3629,14 +3627,14 @@ off en masse with compiler directives that define
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
or all four, or all four,
along with directives to turn on any of the capabilities that you do along with directives to turn on any of the capabilities that you do
want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
the extra transformations but still leave the library fully capable of reading transformations but still leave the library fully capable of reading
and writing PNG files with all known public chunks and writing PNG files with all known public chunks. Use of the
Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
produces a library that is incapable of reading or writing ancillary chunks. that is incapable of reading or writing ancillary chunks. If you are
If you are not using the progressive reading capability, you can not using the progressive reading capability, you can turn that off
turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
this with the INTERLACING capability, which you'll still have). capability, which you'll still have).
All the reading and writing specific code are in separate files, so the All the reading and writing specific code are in separate files, so the
linker should only grab the files it needs. However, if you want to linker should only grab the files it needs. However, if you want to
@ -3849,13 +3847,13 @@ They have been replaced, respectively, by:
PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
deprecated since libpng-1.0.16 and libpng-1.2.6. deprecated since libpng-1.0.16 and libpng-1.2.6.
The deprecated function The function
png_check_sig(sig, num) png_check_sig(sig, num)
was replaced with was replaced with
!png_sig_cmp(sig, 0, num) !png_sig_cmp(sig, 0, num)
It has been deprecated since libpng-0.90. It has been deprecated since libpng-0.90.
The deprecated function The function
png_set_gray_1_2_4_to_8() png_set_gray_1_2_4_to_8()
which also expands tRNS to alpha was replaced with which also expands tRNS to alpha was replaced with
png_set_expand_gray_1_2_4_to_8() png_set_expand_gray_1_2_4_to_8()
@ -3993,12 +3991,11 @@ when there is only one macro being tested.
We do not use the TAB character for indentation in the C sources. We do not use the TAB character for indentation in the C sources.
Other rules can be inferred by inspecting the libpng Other rules can be inferred by inspecting the libpng source.
source.
.SH XIII. Y2K Compliance in libpng .SH XIII. Y2K Compliance in libpng
November 11, 2009 November 12, 2009
Since the PNG Development group is an ad-hoc body, we can't make Since the PNG Development group is an ad-hoc body, we can't make
an official declaration. an official declaration.
@ -4344,7 +4341,7 @@ possible without all of you.
Thanks to Frank J. T. Wojcik for helping with the documentation. Thanks to Frank J. T. Wojcik for helping with the documentation.
Libpng version 1.2.41beta19 - November 11, 2009: Libpng version 1.2.41beta19 - November 12, 2009:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
@ -4367,7 +4364,7 @@ this sentence.
This code is released under the libpng license. This code is released under the libpng license.
libpng versions 1.2.6, August 15, 2004, through 1.2.41beta19, November 11, 2009, are libpng versions 1.2.6, August 15, 2004, through 1.2.41beta19, November 12, 2009, are
Copyright (c) 2004,2006-2008 Glenn Randers-Pehrson, and are Copyright (c) 2004,2006-2008 Glenn Randers-Pehrson, and are
distributed according to the same disclaimer and license as libpng-1.2.5 distributed according to the same disclaimer and license as libpng-1.2.5
with the following individual added to the list of Contributing Authors with the following individual added to the list of Contributing Authors
@ -4466,7 +4463,7 @@ certification mark of the Open Source Initiative.
Glenn Randers-Pehrson Glenn Randers-Pehrson
glennrp at users.sourceforge.net glennrp at users.sourceforge.net
November 11, 2009 November 12, 2009
.\" end of man page .\" end of man page