[devel] Minor documentation editing.
This commit is contained in:
Glenn Randers-Pehrson
parent
a5bcab7854
commit
7a28724e6b
@ -1,6 +1,6 @@
|
||||
libpng-manual.txt - A description on how to use and modify libpng
|
||||
|
||||
libpng version 1.5.5beta03 - July 14, 2011
|
||||
libpng version 1.5.5beta03 - July 26, 2011
|
||||
Updated and distributed by Glenn Randers-Pehrson
|
||||
<glennrp at users.sourceforge.net>
|
||||
Copyright (c) 1998-2011 Glenn Randers-Pehrson
|
||||
@ -11,7 +11,7 @@ libpng-manual.txt - A description on how to use and modify libpng
|
||||
|
||||
Based on:
|
||||
|
||||
libpng versions 0.97, January 1998, through 1.5.5beta03 - July 14, 2011
|
||||
libpng versions 0.97, January 1998, through 1.5.5beta03 - July 26, 2011
|
||||
Updated and distributed by Glenn Randers-Pehrson
|
||||
Copyright (c) 1998-2011 Glenn Randers-Pehrson
|
||||
|
||||
@ -107,7 +107,8 @@ PNG file. At one time, the fields of png_info were intended to be
|
||||
directly accessible to the user. However, this tended to cause problems
|
||||
with applications using dynamically loaded libraries, and as a result
|
||||
a set of interface functions for png_info (the png_get_*() and png_set_*()
|
||||
functions) was developed.
|
||||
functions) was developed, and direct access to the png_info fields was
|
||||
deprecated..
|
||||
|
||||
The png_struct structure is the object used by the library to decode a
|
||||
single image. As of 1.5.0 this structure is also not exposed.
|
||||
@ -146,9 +147,9 @@ the value by multiplying by 100,000. As of libpng 1.5.0 a convenience
|
||||
macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
|
||||
which is simply (png_int_32).
|
||||
|
||||
All APIs that take (double) arguments also have an matching API that
|
||||
All APIs that take (double) arguments also have a matching API that
|
||||
takes the corresponding fixed point integer arguments. The fixed point
|
||||
API has the same name as the floating point one with _fixed appended.
|
||||
API has the same name as the floating point one with "_fixed" appended.
|
||||
The actual range of values permitted in the APIs is frequently less than
|
||||
the full range of (png_fixed_point) (-21474 to +21474). When APIs require
|
||||
a non-negative argument the type is recorded as png_uint_32 above. Consult
|
||||
@ -166,6 +167,10 @@ preprocessing directives of the form:
|
||||
#ifdef PNG_feature_SUPPORTED
|
||||
declare-function
|
||||
#endif
|
||||
...
|
||||
#ifdef PNG_feature_SUPPORTED
|
||||
use-function
|
||||
#endif
|
||||
|
||||
The library can be built without support for these APIs, although a
|
||||
standard build will have all implemented APIs. Application programs
|
||||
@ -206,24 +211,25 @@ A variety of methods exist to build libpng. Not all of these support
|
||||
reconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either be
|
||||
rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
|
||||
|
||||
Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt and changing
|
||||
the lines defining the supported features, paying very close attention to
|
||||
the 'option' information in scripts/pnglibconf.dfa that describes those
|
||||
features and their requirements. This is easy to get wrong.
|
||||
Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
|
||||
pnglibconf.h and changing the lines defining the supported features, paying
|
||||
very close attention to the 'option' information in scripts/pnglibconf.dfa
|
||||
that describes those features and their requirements. This is easy to get
|
||||
wrong.
|
||||
|
||||
B. Configuration using DFA_XTRA
|
||||
|
||||
Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
|
||||
variant such as 'nawk' or 'gawk', is available. The configure build will
|
||||
automatically find an appropriate awk and build pnglibconf.h.
|
||||
scripts/pnglibconf.mak contains a set of make rules for doing the same thing if
|
||||
configure is not used, and many of the makefiles in the scripts directory use
|
||||
this approach.
|
||||
The scripts/pnglibconf.mak file contains a set of make rules for doing the
|
||||
same thing if configure is not used, and many of the makefiles in the scripts
|
||||
directory use this approach.
|
||||
|
||||
When rebuilding simply write new file containing changed options and set
|
||||
When rebuilding simply write a new file containing changed options and set
|
||||
DFA_XTRA to the name of this file. This causes the build to append the new file
|
||||
to the end of scripts/pnglibconf.dfa. pngusr.dfa should contain lines of the
|
||||
following forms:
|
||||
to the end of scripts/pnglibconf.dfa. The pngusr.dfa file should contain lines
|
||||
of the following forms:
|
||||
|
||||
everything = off
|
||||
|
||||
@ -255,8 +261,8 @@ C. Configuration using PNG_USR_CONFIG
|
||||
|
||||
If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
|
||||
pngusr.h will automatically be included before the options in
|
||||
scripts/pnglibconf.dfa are processed. pngusr.h should contain only macro
|
||||
definitions turning features on or off or setting settings.
|
||||
scripts/pnglibconf.dfa are processed. Your pngusr.h file should contain only
|
||||
macro definitions turning features on or off or setting settings.
|
||||
|
||||
Apart from the global setting "everything = off" all the options listed above
|
||||
can be set using macros in pngusr.h:
|
||||
@ -573,6 +579,8 @@ according to the "keep" directive. If a chunk is named in successive
|
||||
instances of png_set_keep_unknown_chunks(), the final instance will
|
||||
take precedence. The IHDR and IEND chunks should not be named in
|
||||
chunk_list; if they are, libpng will process them normally anyway.
|
||||
If you know that your application will never make use of some particular
|
||||
chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below.
|
||||
|
||||
Here is an example of the usage of png_set_keep_unknown_chunks(),
|
||||
where the private "vpAg" chunk will later be processed by a user chunk
|
||||
@ -669,7 +677,8 @@ called before the PNG file header had been read and png_set_alpha_mode() did not
|
||||
exist.
|
||||
|
||||
If you need to support versions prior to libpng-1.5.4 test the version number
|
||||
and follow the procedures described in the appropriate manual page.
|
||||
as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures
|
||||
described in the appropriate manual page.
|
||||
|
||||
You give libpng the encoding expected by your system expressed as a 'gamma'
|
||||
value. You can also specify a default encoding for the PNG file in
|
||||
@ -714,7 +723,9 @@ Libpng only supports composing onto a single color (using png_set_background;
|
||||
see below.) Otherwise you must do the composition yourself and, in this case,
|
||||
you may need to call png_set_alpha_mode:
|
||||
|
||||
#if PNG_LIBPNG_VER >= 10504
|
||||
png_set_alpha_mode(png_ptr, mode, screen_gamma);
|
||||
#endif
|
||||
|
||||
The screen_gamma value is the same as the argument to png_set_gamma, however how
|
||||
it affects the output depends on the mode. png_set_alpha_mode() sets the file
|
||||
@ -1229,6 +1240,8 @@ pointer into the info_ptr is returned for any complex types.
|
||||
Note that the itxt_length, lang, and lang_key
|
||||
members of the text_ptr structure only exist
|
||||
when the library is built with iTXt chunk support.
|
||||
Prior to libpng-1.4.0, the default build was
|
||||
was without iTXt chunk support.
|
||||
|
||||
num_text - number of comments (same as
|
||||
num_comments; you can put NULL here
|
||||
@ -1253,10 +1266,10 @@ pointer into the info_ptr is returned for any complex types.
|
||||
&unit_type);
|
||||
|
||||
offset_x - positive offset from the left edge
|
||||
of the screen
|
||||
of the screen (can be negative)
|
||||
|
||||
offset_y - positive offset from the top edge
|
||||
of the screen
|
||||
of the screen (can be negative)
|
||||
|
||||
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
|
||||
|
||||
@ -1288,6 +1301,7 @@ pointer into the info_ptr is returned for any complex types.
|
||||
unit - physical scale units (an integer)
|
||||
|
||||
width - width of a pixel in physical scale units
|
||||
(expressed as a string)
|
||||
|
||||
height - height of a pixel in physical scale units
|
||||
(width and height are strings like "2.54")
|
||||
@ -1310,6 +1324,12 @@ pointer into the info_ptr is returned for any complex types.
|
||||
chunks were read from the PNG file or inserted with the
|
||||
png_set_unknown_chunks() function.
|
||||
|
||||
The value of "location" is a bitwise "or" of
|
||||
|
||||
PNG_HAVE_IHDR (0x01)
|
||||
PNG_HAVE_PLTE (0x02)
|
||||
PNG_AFTER_IDAT (0x08)
|
||||
|
||||
The data from the pHYs chunk can be retrieved in several convenient
|
||||
forms:
|
||||
|
||||
@ -1454,7 +1474,7 @@ As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
|
||||
added. It expands the sample depth without changing tRNS to alpha.
|
||||
|
||||
As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as
|
||||
png_set_expand(), however, the resultant channels have 16 bits rather than 8.
|
||||
png_set_expand(); however, the resultant channels have 16 bits rather than 8.
|
||||
Use this when the output color or gray channels are made linear to avoid fairly
|
||||
severe accuracy loss.
|
||||
|
||||
@ -1465,7 +1485,14 @@ PNG can have files with 16 bits per channel. If you only can handle
|
||||
8 bits per channel, this will strip the pixels down to 8-bit.
|
||||
|
||||
if (bit_depth == 16)
|
||||
#if PNG_LIBPNG_VER >= 10504
|
||||
png_set_scale_16(png_ptr);
|
||||
#else
|
||||
png_set_strip_16(png_ptr);
|
||||
#endif
|
||||
|
||||
(The more accurate "png_set_scale_16()" API became available in libpng version
|
||||
1.5.4).
|
||||
|
||||
If you need to process the alpha channel on the image separately from the image
|
||||
data (for example if you convert it to a bitmap mask) it is possible to have
|
||||
@ -1643,7 +1670,7 @@ 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 for sBIT, regardless of the error_action setting.
|
||||
|
||||
The default values come from the PNG file cHRM chunk if present, otherwise the
|
||||
The default values come from the PNG file cHRM chunk if present; otherwise, the
|
||||
defaults correspond to the ITU-R recommendation 709, and also the sRGB color
|
||||
space, as recommended in the Charles Poynton's Colour FAQ,
|
||||
<http://www.poynton.com/>, in section 9:
|
||||
@ -1655,7 +1682,7 @@ space, as recommended in the Charles Poynton's Colour FAQ,
|
||||
The calculation is done in a linear colorspace, if the image gamma
|
||||
can be determined.
|
||||
|
||||
The png_set_background() function has been described already, it tells libpng to
|
||||
The png_set_background() function has been described already; it tells libpng to
|
||||
composite images with alpha or simple transparency against the supplied
|
||||
background color. For compatibility with versions of libpng earlier than
|
||||
libpng-1.5.4 it is recommended that you call the function after reading the file
|
||||
@ -1718,9 +1745,9 @@ file has more entries then will fit on your screen, png_set_quantize()
|
||||
will do that. Note that this is a simple match quantization that merely
|
||||
finds the closest color available. This should work fairly well with
|
||||
optimized palettes, but fairly badly with linear color cubes. If you
|
||||
pass a palette that is larger then maximum_colors, the file will
|
||||
pass a palette that is larger than maximum_colors, the file will
|
||||
reduce the number of colors in the palette so it will fit into
|
||||
maximum_colors. If there is a histogram, it will use it to make
|
||||
maximum_colors. If there is a histogram, libpng will use it to make
|
||||
more intelligent choices when reducing the palette. If there is no
|
||||
histogram, it may not do as good a job.
|
||||
|
||||
@ -1792,7 +1819,7 @@ after all of the other transformations have been processed. Take care with
|
||||
interlaced images if you do the interlace yourself - the width of the row is the
|
||||
width in 'row_info', not the overall image width.
|
||||
|
||||
If supported libpng provides two information routines that you can use to find
|
||||
If supported, libpng provides two information routines that you can use to find
|
||||
where you are in processing the image:
|
||||
|
||||
png_get_current_pass_number(png_structp png_ptr);
|
||||
@ -2716,14 +2743,14 @@ width, height, bit_depth, and color_type must be the same in each call.
|
||||
trans_alpha - array of alpha (transparency)
|
||||
entries for palette (PNG_INFO_tRNS)
|
||||
|
||||
num_trans - number of transparent entries
|
||||
(PNG_INFO_tRNS)
|
||||
|
||||
trans_color - graylevel or color sample values
|
||||
(in order red, green, blue) of the
|
||||
single transparent color for
|
||||
non-paletted images (PNG_INFO_tRNS)
|
||||
|
||||
num_trans - number of transparent entries
|
||||
(PNG_INFO_tRNS)
|
||||
|
||||
png_set_hIST(png_ptr, info_ptr, hist);
|
||||
|
||||
hist - histogram of palette (array of
|
||||
@ -2764,6 +2791,8 @@ width, height, bit_depth, and color_type must be the same in each call.
|
||||
Note that the itxt_length, lang, and lang_key
|
||||
members of the text_ptr structure only exist
|
||||
when the library is built with iTXt chunk support.
|
||||
Prior to libpng-1.4.0 the library was built by default
|
||||
without iTXt support.
|
||||
|
||||
num_text - number of comments
|
||||
|
||||
@ -2813,6 +2842,7 @@ width, height, bit_depth, and color_type must be the same in each call.
|
||||
unit - physical scale units (an integer)
|
||||
|
||||
width - width of a pixel in physical scale units
|
||||
expressed as a string
|
||||
|
||||
height - height of a pixel in physical scale units
|
||||
(width and height are strings like "2.54")
|
||||
@ -2854,7 +2884,7 @@ 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.
|
||||
Until text gets around a few hundred bytes, it is not worth compressing it.
|
||||
After the text has been written out to the file, the compression type
|
||||
is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
|
||||
so that it isn't written out again at the end (in case you are calling
|
||||
@ -3515,8 +3545,8 @@ defined, and FAR gets defined to far in pngconf.h, and you should be
|
||||
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 rows of data are defined as png_bytepp, which is an
|
||||
unsigned char far * far *.
|
||||
note that the rows of data are defined as png_bytepp, which is
|
||||
an "unsigned char far * far *".
|
||||
|
||||
Configuring for gui/windowing platforms:
|
||||
|
||||
@ -3534,7 +3564,10 @@ or delete an include, this is the place to do it.
|
||||
The includes that are not needed outside libpng are placed in pngpriv.h,
|
||||
which is only used by the routines inside libpng itself.
|
||||
The files in libpng proper only include pngpriv.h and png.h, which
|
||||
in turn includes pngconf.h.
|
||||
in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
|
||||
As of libpng-1.5.0, pngpriv.h also includes three other private header
|
||||
files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
|
||||
that previously appeared in the public headers.
|
||||
|
||||
Configuring zlib:
|
||||
|
||||
@ -3576,8 +3609,28 @@ zlib.h for more information on what these mean.
|
||||
window_bits);
|
||||
|
||||
png_set_compression_method(png_ptr, method);
|
||||
|
||||
png_set_compression_buffer_size(png_ptr, size);
|
||||
|
||||
As of libpng version 1.5.4, additional APIs became
|
||||
available to set these separately for non-IDAT
|
||||
compressed chunks such as zTXt, iTXt, and iCCP:
|
||||
|
||||
#include zlib.h
|
||||
#if PNG_LIBPNG_VER <= 10504
|
||||
png_set_text_compression_level(png_ptr, level);
|
||||
|
||||
png_set_text_compression_mem_level(png_ptr, level);
|
||||
|
||||
png_set_text_compression_strategy(png_ptr,
|
||||
strategy);
|
||||
|
||||
png_set_text_compression_window_bits(png_ptr,
|
||||
window_bits);
|
||||
|
||||
png_set_text_compression_method(png_ptr, method);
|
||||
#endif
|
||||
|
||||
Controlling row filtering
|
||||
|
||||
If you want to control whether libpng uses filtering or not, which
|
||||
@ -4447,7 +4500,7 @@ Other rules can be inferred by inspecting the libpng source.
|
||||
|
||||
XIV. Y2K Compliance in libpng
|
||||
|
||||
July 14, 2011
|
||||
July 26, 2011
|
||||
|
||||
Since the PNG Development group is an ad-hoc body, we can't make
|
||||
an official declaration.
|
||||
|
||||
130
libpng.3
130
libpng.3
@ -1,4 +1,4 @@
|
||||
.TH LIBPNG 3 "July 14, 2011"
|
||||
.TH LIBPNG 3 "July 26, 2011"
|
||||
.SH NAME
|
||||
libpng \- Portable Network Graphics (PNG) Reference Library 1.5.5beta03
|
||||
.SH SYNOPSIS
|
||||
@ -955,7 +955,7 @@ Following is a copy of the libpng-manual.txt file that accompanies libpng.
|
||||
.SH LIBPNG.TXT
|
||||
libpng-manual.txt - A description on how to use and modify libpng
|
||||
|
||||
libpng version 1.5.5beta03 - July 14, 2011
|
||||
libpng version 1.5.5beta03 - July 26, 2011
|
||||
Updated and distributed by Glenn Randers-Pehrson
|
||||
<glennrp at users.sourceforge.net>
|
||||
Copyright (c) 1998-2011 Glenn Randers-Pehrson
|
||||
@ -966,7 +966,7 @@ libpng-manual.txt - A description on how to use and modify libpng
|
||||
|
||||
Based on:
|
||||
|
||||
libpng versions 0.97, January 1998, through 1.5.5beta03 - July 14, 2011
|
||||
libpng versions 0.97, January 1998, through 1.5.5beta03 - July 26, 2011
|
||||
Updated and distributed by Glenn Randers-Pehrson
|
||||
Copyright (c) 1998-2011 Glenn Randers-Pehrson
|
||||
|
||||
@ -1062,7 +1062,8 @@ PNG file. At one time, the fields of png_info were intended to be
|
||||
directly accessible to the user. However, this tended to cause problems
|
||||
with applications using dynamically loaded libraries, and as a result
|
||||
a set of interface functions for png_info (the png_get_*() and png_set_*()
|
||||
functions) was developed.
|
||||
functions) was developed, and direct access to the png_info fields was
|
||||
deprecated..
|
||||
|
||||
The png_struct structure is the object used by the library to decode a
|
||||
single image. As of 1.5.0 this structure is also not exposed.
|
||||
@ -1101,9 +1102,9 @@ the value by multiplying by 100,000. As of libpng 1.5.0 a convenience
|
||||
macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
|
||||
which is simply (png_int_32).
|
||||
|
||||
All APIs that take (double) arguments also have an matching API that
|
||||
All APIs that take (double) arguments also have a matching API that
|
||||
takes the corresponding fixed point integer arguments. The fixed point
|
||||
API has the same name as the floating point one with _fixed appended.
|
||||
API has the same name as the floating point one with "_fixed" appended.
|
||||
The actual range of values permitted in the APIs is frequently less than
|
||||
the full range of (png_fixed_point) (-21474 to +21474). When APIs require
|
||||
a non-negative argument the type is recorded as png_uint_32 above. Consult
|
||||
@ -1121,6 +1122,10 @@ preprocessing directives of the form:
|
||||
#ifdef PNG_feature_SUPPORTED
|
||||
declare-function
|
||||
#endif
|
||||
...
|
||||
#ifdef PNG_feature_SUPPORTED
|
||||
use-function
|
||||
#endif
|
||||
|
||||
The library can be built without support for these APIs, although a
|
||||
standard build will have all implemented APIs. Application programs
|
||||
@ -1161,24 +1166,25 @@ A variety of methods exist to build libpng. Not all of these support
|
||||
reconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either be
|
||||
rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
|
||||
|
||||
Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt and changing
|
||||
the lines defining the supported features, paying very close attention to
|
||||
the 'option' information in scripts/pnglibconf.dfa that describes those
|
||||
features and their requirements. This is easy to get wrong.
|
||||
Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
|
||||
pnglibconf.h and changing the lines defining the supported features, paying
|
||||
very close attention to the 'option' information in scripts/pnglibconf.dfa
|
||||
that describes those features and their requirements. This is easy to get
|
||||
wrong.
|
||||
|
||||
B. Configuration using DFA_XTRA
|
||||
|
||||
Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
|
||||
variant such as 'nawk' or 'gawk', is available. The configure build will
|
||||
automatically find an appropriate awk and build pnglibconf.h.
|
||||
scripts/pnglibconf.mak contains a set of make rules for doing the same thing if
|
||||
configure is not used, and many of the makefiles in the scripts directory use
|
||||
this approach.
|
||||
The scripts/pnglibconf.mak file contains a set of make rules for doing the
|
||||
same thing if configure is not used, and many of the makefiles in the scripts
|
||||
directory use this approach.
|
||||
|
||||
When rebuilding simply write new file containing changed options and set
|
||||
When rebuilding simply write a new file containing changed options and set
|
||||
DFA_XTRA to the name of this file. This causes the build to append the new file
|
||||
to the end of scripts/pnglibconf.dfa. pngusr.dfa should contain lines of the
|
||||
following forms:
|
||||
to the end of scripts/pnglibconf.dfa. The pngusr.dfa file should contain lines
|
||||
of the following forms:
|
||||
|
||||
everything = off
|
||||
|
||||
@ -1210,8 +1216,8 @@ C. Configuration using PNG_USR_CONFIG
|
||||
|
||||
If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
|
||||
pngusr.h will automatically be included before the options in
|
||||
scripts/pnglibconf.dfa are processed. pngusr.h should contain only macro
|
||||
definitions turning features on or off or setting settings.
|
||||
scripts/pnglibconf.dfa are processed. Your pngusr.h file should contain only
|
||||
macro definitions turning features on or off or setting settings.
|
||||
|
||||
Apart from the global setting "everything = off" all the options listed above
|
||||
can be set using macros in pngusr.h:
|
||||
@ -1528,6 +1534,8 @@ according to the "keep" directive. If a chunk is named in successive
|
||||
instances of png_set_keep_unknown_chunks(), the final instance will
|
||||
take precedence. The IHDR and IEND chunks should not be named in
|
||||
chunk_list; if they are, libpng will process them normally anyway.
|
||||
If you know that your application will never make use of some particular
|
||||
chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below.
|
||||
|
||||
Here is an example of the usage of png_set_keep_unknown_chunks(),
|
||||
where the private "vpAg" chunk will later be processed by a user chunk
|
||||
@ -1624,7 +1632,8 @@ called before the PNG file header had been read and png_set_alpha_mode() did not
|
||||
exist.
|
||||
|
||||
If you need to support versions prior to libpng-1.5.4 test the version number
|
||||
and follow the procedures described in the appropriate manual page.
|
||||
as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures
|
||||
described in the appropriate manual page.
|
||||
|
||||
You give libpng the encoding expected by your system expressed as a 'gamma'
|
||||
value. You can also specify a default encoding for the PNG file in
|
||||
@ -1669,7 +1678,9 @@ Libpng only supports composing onto a single color (using png_set_background;
|
||||
see below.) Otherwise you must do the composition yourself and, in this case,
|
||||
you may need to call png_set_alpha_mode:
|
||||
|
||||
#if PNG_LIBPNG_VER >= 10504
|
||||
png_set_alpha_mode(png_ptr, mode, screen_gamma);
|
||||
#endif
|
||||
|
||||
The screen_gamma value is the same as the argument to png_set_gamma, however how
|
||||
it affects the output depends on the mode. png_set_alpha_mode() sets the file
|
||||
@ -2184,6 +2195,8 @@ pointer into the info_ptr is returned for any complex types.
|
||||
Note that the itxt_length, lang, and lang_key
|
||||
members of the text_ptr structure only exist
|
||||
when the library is built with iTXt chunk support.
|
||||
Prior to libpng-1.4.0, the default build was
|
||||
was without iTXt chunk support.
|
||||
|
||||
num_text - number of comments (same as
|
||||
num_comments; you can put NULL here
|
||||
@ -2208,10 +2221,10 @@ pointer into the info_ptr is returned for any complex types.
|
||||
&unit_type);
|
||||
|
||||
offset_x - positive offset from the left edge
|
||||
of the screen
|
||||
of the screen (can be negative)
|
||||
|
||||
offset_y - positive offset from the top edge
|
||||
of the screen
|
||||
of the screen (can be negative)
|
||||
|
||||
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
|
||||
|
||||
@ -2243,6 +2256,7 @@ pointer into the info_ptr is returned for any complex types.
|
||||
unit - physical scale units (an integer)
|
||||
|
||||
width - width of a pixel in physical scale units
|
||||
(expressed as a string)
|
||||
|
||||
height - height of a pixel in physical scale units
|
||||
(width and height are strings like "2.54")
|
||||
@ -2265,6 +2279,12 @@ pointer into the info_ptr is returned for any complex types.
|
||||
chunks were read from the PNG file or inserted with the
|
||||
png_set_unknown_chunks() function.
|
||||
|
||||
The value of "location" is a bitwise "or" of
|
||||
|
||||
PNG_HAVE_IHDR (0x01)
|
||||
PNG_HAVE_PLTE (0x02)
|
||||
PNG_AFTER_IDAT (0x08)
|
||||
|
||||
The data from the pHYs chunk can be retrieved in several convenient
|
||||
forms:
|
||||
|
||||
@ -2409,7 +2429,7 @@ As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
|
||||
added. It expands the sample depth without changing tRNS to alpha.
|
||||
|
||||
As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as
|
||||
png_set_expand(), however, the resultant channels have 16 bits rather than 8.
|
||||
png_set_expand(); however, the resultant channels have 16 bits rather than 8.
|
||||
Use this when the output color or gray channels are made linear to avoid fairly
|
||||
severe accuracy loss.
|
||||
|
||||
@ -2420,7 +2440,14 @@ PNG can have files with 16 bits per channel. If you only can handle
|
||||
8 bits per channel, this will strip the pixels down to 8-bit.
|
||||
|
||||
if (bit_depth == 16)
|
||||
#if PNG_LIBPNG_VER >= 10504
|
||||
png_set_scale_16(png_ptr);
|
||||
#else
|
||||
png_set_strip_16(png_ptr);
|
||||
#endif
|
||||
|
||||
(The more accurate "png_set_scale_16()" API became available in libpng version
|
||||
1.5.4).
|
||||
|
||||
If you need to process the alpha channel on the image separately from the image
|
||||
data (for example if you convert it to a bitmap mask) it is possible to have
|
||||
@ -2598,7 +2625,7 @@ 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 for sBIT, regardless of the error_action setting.
|
||||
|
||||
The default values come from the PNG file cHRM chunk if present, otherwise the
|
||||
The default values come from the PNG file cHRM chunk if present; otherwise, the
|
||||
defaults correspond to the ITU-R recommendation 709, and also the sRGB color
|
||||
space, as recommended in the Charles Poynton's Colour FAQ,
|
||||
<http://www.poynton.com/>, in section 9:
|
||||
@ -2610,7 +2637,7 @@ space, as recommended in the Charles Poynton's Colour FAQ,
|
||||
The calculation is done in a linear colorspace, if the image gamma
|
||||
can be determined.
|
||||
|
||||
The png_set_background() function has been described already, it tells libpng to
|
||||
The png_set_background() function has been described already; it tells libpng to
|
||||
composite images with alpha or simple transparency against the supplied
|
||||
background color. For compatibility with versions of libpng earlier than
|
||||
libpng-1.5.4 it is recommended that you call the function after reading the file
|
||||
@ -2673,9 +2700,9 @@ file has more entries then will fit on your screen, png_set_quantize()
|
||||
will do that. Note that this is a simple match quantization that merely
|
||||
finds the closest color available. This should work fairly well with
|
||||
optimized palettes, but fairly badly with linear color cubes. If you
|
||||
pass a palette that is larger then maximum_colors, the file will
|
||||
pass a palette that is larger than maximum_colors, the file will
|
||||
reduce the number of colors in the palette so it will fit into
|
||||
maximum_colors. If there is a histogram, it will use it to make
|
||||
maximum_colors. If there is a histogram, libpng will use it to make
|
||||
more intelligent choices when reducing the palette. If there is no
|
||||
histogram, it may not do as good a job.
|
||||
|
||||
@ -2747,7 +2774,7 @@ after all of the other transformations have been processed. Take care with
|
||||
interlaced images if you do the interlace yourself - the width of the row is the
|
||||
width in 'row_info', not the overall image width.
|
||||
|
||||
If supported libpng provides two information routines that you can use to find
|
||||
If supported, libpng provides two information routines that you can use to find
|
||||
where you are in processing the image:
|
||||
|
||||
png_get_current_pass_number(png_structp png_ptr);
|
||||
@ -3671,14 +3698,14 @@ width, height, bit_depth, and color_type must be the same in each call.
|
||||
trans_alpha - array of alpha (transparency)
|
||||
entries for palette (PNG_INFO_tRNS)
|
||||
|
||||
num_trans - number of transparent entries
|
||||
(PNG_INFO_tRNS)
|
||||
|
||||
trans_color - graylevel or color sample values
|
||||
(in order red, green, blue) of the
|
||||
single transparent color for
|
||||
non-paletted images (PNG_INFO_tRNS)
|
||||
|
||||
num_trans - number of transparent entries
|
||||
(PNG_INFO_tRNS)
|
||||
|
||||
png_set_hIST(png_ptr, info_ptr, hist);
|
||||
|
||||
hist - histogram of palette (array of
|
||||
@ -3719,6 +3746,8 @@ width, height, bit_depth, and color_type must be the same in each call.
|
||||
Note that the itxt_length, lang, and lang_key
|
||||
members of the text_ptr structure only exist
|
||||
when the library is built with iTXt chunk support.
|
||||
Prior to libpng-1.4.0 the library was built by default
|
||||
without iTXt support.
|
||||
|
||||
num_text - number of comments
|
||||
|
||||
@ -3768,6 +3797,7 @@ width, height, bit_depth, and color_type must be the same in each call.
|
||||
unit - physical scale units (an integer)
|
||||
|
||||
width - width of a pixel in physical scale units
|
||||
expressed as a string
|
||||
|
||||
height - height of a pixel in physical scale units
|
||||
(width and height are strings like "2.54")
|
||||
@ -3809,7 +3839,7 @@ 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.
|
||||
Until text gets around a few hundred bytes, it is not worth compressing it.
|
||||
After the text has been written out to the file, the compression type
|
||||
is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
|
||||
so that it isn't written out again at the end (in case you are calling
|
||||
@ -4470,8 +4500,8 @@ defined, and FAR gets defined to far in pngconf.h, and you should be
|
||||
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 rows of data are defined as png_bytepp, which is an
|
||||
unsigned char far * far *.
|
||||
note that the rows of data are defined as png_bytepp, which is
|
||||
an "unsigned char far * far *".
|
||||
|
||||
.SS Configuring for gui/windowing platforms:
|
||||
|
||||
@ -4489,7 +4519,11 @@ or delete an include, this is the place to do it.
|
||||
The includes that are not needed outside libpng are placed in pngpriv.h,
|
||||
which is only used by the routines inside libpng itself.
|
||||
The files in libpng proper only include pngpriv.h and png.h, which
|
||||
in turn includes pngconf.h.
|
||||
%14%in turn includes pngconf.h.
|
||||
in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
|
||||
As of libpng-1.5.0, pngpriv.h also includes three other private header
|
||||
files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
|
||||
that previously appeared in the public headers.
|
||||
|
||||
.SS Configuring zlib:
|
||||
|
||||
@ -4531,8 +4565,28 @@ zlib.h for more information on what these mean.
|
||||
window_bits);
|
||||
|
||||
png_set_compression_method(png_ptr, method);
|
||||
|
||||
png_set_compression_buffer_size(png_ptr, size);
|
||||
|
||||
As of libpng version 1.5.4, additional APIs became
|
||||
available to set these separately for non-IDAT
|
||||
compressed chunks such as zTXt, iTXt, and iCCP:
|
||||
|
||||
#include zlib.h
|
||||
#if PNG_LIBPNG_VER <= 10504
|
||||
png_set_text_compression_level(png_ptr, level);
|
||||
|
||||
png_set_text_compression_mem_level(png_ptr, level);
|
||||
|
||||
png_set_text_compression_strategy(png_ptr,
|
||||
strategy);
|
||||
|
||||
png_set_text_compression_window_bits(png_ptr,
|
||||
window_bits);
|
||||
|
||||
png_set_text_compression_method(png_ptr, method);
|
||||
#endif
|
||||
|
||||
.SS Controlling row filtering
|
||||
|
||||
If you want to control whether libpng uses filtering or not, which
|
||||
@ -5402,7 +5456,7 @@ Other rules can be inferred by inspecting the libpng source.
|
||||
|
||||
.SH XIV. Y2K Compliance in libpng
|
||||
|
||||
July 14, 2011
|
||||
July 26, 2011
|
||||
|
||||
Since the PNG Development group is an ad-hoc body, we can't make
|
||||
an official declaration.
|
||||
@ -5661,7 +5715,7 @@ possible without all of you.
|
||||
|
||||
Thanks to Frank J. T. Wojcik for helping with the documentation.
|
||||
|
||||
Libpng version 1.5.5beta03 - July 14, 2011:
|
||||
Libpng version 1.5.5beta03 - July 26, 2011:
|
||||
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
|
||||
Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
|
||||
|
||||
@ -5684,7 +5738,7 @@ this sentence.
|
||||
|
||||
This code is released under the libpng license.
|
||||
|
||||
libpng versions 1.2.6, August 15, 2004, through 1.5.5beta03, July 14, 2011, are
|
||||
libpng versions 1.2.6, August 15, 2004, through 1.5.5beta03, July 26, 2011, are
|
||||
Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
|
||||
distributed according to the same disclaimer and license as libpng-1.2.5
|
||||
with the following individual added to the list of Contributing Authors
|
||||
@ -5783,7 +5837,7 @@ certification mark of the Open Source Initiative.
|
||||
|
||||
Glenn Randers-Pehrson
|
||||
glennrp at users.sourceforge.net
|
||||
July 14, 2011
|
||||
July 26, 2011
|
||||
|
||||
.\" end of man page
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user