mewin/libpng
1
0
Fork 0
mirror of https://git.code.sf.net/p/libpng/code.git synced 2025-07-10 18:04:09 +02:00
Code Issues Projects Releases Wiki Activity

Imported from libpng-1.2.6rc1.tar

Browse Source
This commit is contained in:
Glenn Randers-Pehrson
2004-08-04 06:34:52 -05:00
parent 5fea36fb00
commit 272489dc69
73 changed files with 2230 additions and 2263 deletions
Download Patch File Download Diff File Expand all files Collapse all files

292
libpng.3
View File

@@ -1,6 +1,6 @@
.TH LIBPNG 3 "July 28, 2004"
.TH LIBPNG 3 "August 4, 2004"
.SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.2.6beta4
libpng \- Portable Network Graphics (PNG) Reference Library 1.2.6rc1
.SH SYNOPSIS
\fI\fB
@@ -266,10 +266,18 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.6beta4
\fI\fB
\fBpng_uint_32 png_get_user_height_max( png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
\fBpng_voidp png_get_user_transform_ptr (png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
\fBpng_uint_32 png_get_user_width_max (png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
\fBpng_uint_32 png_get_valid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP
\fI\fB
@@ -650,6 +658,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.6beta4
\fI\fB
\fBvoid png_set_user_limits (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIuser_width_max\fP\fB, png_uint_32 \fIuser_height_max\fP\fB);\fP
\fI\fB
\fBvoid png_set_user_transform_info (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_transform_ptr\fP\fB, int \fP\fIuser_transform_depth\fP\fB, int \fIuser_transform_channels\fP\fB);\fP
\fI\fB
@@ -761,7 +773,7 @@ Following is a copy of the libpng.txt file that accompanies libpng.
.SH LIBPNG.TXT
libpng.txt - A description on how to use and modify libpng
libpng version 1.2.6beta4 - July 28, 2004
libpng version 1.2.6rc1 - August 4, 2004
Updated and distributed by Glenn Randers-Pehrson
<glennrp@users.sourceforge.net>
Copyright (c) 1998-2004 Glenn Randers-Pehrson
@@ -1061,6 +1073,28 @@ To inform libpng about your function, use
png_set_read_status_fn(png_ptr, read_row_callback);
%-%.SS Width and height limits
%-%
%-%The PNG specification allows the width and height of an image to be as
%-%large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
%-%Since very few applications really need to process such large images,
%-%we have imposed an arbitrary 1-million limit on rows and columns.
%-%Larger images will be rejected immediately with a png_error() call. If
%-%you wish to override this limit, you can use
%-%
%-% png_set_user_limits(png_ptr, width_max, height_max);
%-%
%-%to set your own limits, or use width_max = height_max = 0x7fffffffL
%-%to allow all valid dimensions (libpng may reject some very large images
%-%anyway because of potential buffer overflow conditions).
%-%
%-%You should put this statement after you create the PNG structure and
%-%before calling png_read_info(), png_read_png(), or png_process_data().
%-%If you need to retrieve the limits that are being applied, use
%-%
%-% width_max = png_get_user_width_max(png_ptr);
%-% height_max = png_get_user_height_max(png_ptr);
%-%
.SS Unknown-chunk handling
Now you get to set the way the library processes unknown chunks in the
@@ -1069,7 +1103,7 @@ behavior is that known chunks will be parsed into information in
various info_ptr members; unknown chunks will be discarded. To change
this, you can call:
png_set_keep_unknown_chunks(png_ptr, info_ptr, keep,
png_set_keep_unknown_chunks(png_ptr, keep,
chunk_list, num_chunks);
keep - 0: do not keep
1: keep only if safe-to-copy
@@ -3420,125 +3454,125 @@ 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. Runtime optimization
A new feature in libpng 1.2.0 is the ability to dynamically switch between
standard and optimized versions of some routines. Currently these are
limited to three computationally intensive tasks when reading PNG files:
decoding row filters, expanding interlacing, and combining interlaced or
transparent row data with previous row data. Currently the optimized
versions are available only for x86 (Intel, AMD, etc.) platforms with
MMX support, though this may change in future versions. (For example,
the non-MMX assembler optimizations for zlib might become similarly
runtime-selectable in future releases, in which case libpng could be
extended to support them. Alternatively, the compile-time choice of
floating-point versus integer routines for gamma correction might become
runtime-selectable.)
Because such optimizations tend to be very platform- and compiler-dependent,
both in how they are written and in how they perform, the new runtime code
in libpng has been written to allow programs to query, enable, and disable
either specific optimizations or all such optimizations. For example, to
enable all possible optimizations (bearing in mind that some "optimizations"
may actually run more slowly in rare cases):
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
png_uint_32 mask, flags;
flags = png_get_asm_flags(png_ptr);
mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
png_set_asm_flags(png_ptr, flags | mask);
#endif
To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
by itself when calling png_get_asm_flagmask(); similarly for optimizing
only writing. To disable all optimizations:
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
flags = png_get_asm_flags(png_ptr);
mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
png_set_asm_flags(png_ptr, flags & ~mask);
#endif
To enable or disable only MMX-related features, use png_get_mmx_flagmask()
in place of png_get_asm_flagmask(). The mmx version takes one additional
parameter:
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
int compilerID;
mask = png_get_mmx_flagmask(selection, &compilerID);
#endif
On return, compilerID will indicate which version of the MMX assembler
optimizations was compiled. Currently two flavors exist: Microsoft
Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
On non-x86 platforms or on systems compiled without MMX optimizations, a
value of -1 is used.
Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
all valid, settable optimization bits for the version of the library that's
currently in use. In the case of shared (dynamically linked) libraries,
this may include optimizations that did not exist at the time the code was
written and compiled. It is also possible, of course, to enable only known,
specific optimizations; for example:
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
| PNG_ASM_FLAG_MMX_READ_INTERLACE \
| PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
| PNG_ASM_FLAG_MMX_READ_FILTER_UP \
| PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
| PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
png_set_asm_flags(png_ptr, flags);
#endif
This method would enable only the MMX read-optimizations available at the
time of libpng 1.2.0's release, regardless of whether a later version of
the DLL were actually being used. (Also note that these functions did not
exist in versions older than 1.2.0, so any attempt to run a dynamically
linked app on such an older version would fail.)
To determine whether the processor supports MMX instructions at all, use
the png_mmx_support() function:
#if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
mmxsupport = png_mmx_support();
#endif
It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
is compiled but MMX is not supported by the processor, or 1 if MMX support
is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
and png_get_asm_flagmask() all may be called without allocating and ini-
tializing any PNG structures (for example, as part of a usage screen or
"about" box).
The following code can be used to prevent an application from using the
thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
defined:
#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \
&& defined(PNG_THREAD_UNSAFE_OK)
/* Disable thread-unsafe features of pnggccrd */
if (png_access_version() >= 10200)
{
png_uint_32 mmx_disable_mask = 0;
png_uint_32 asm_flags;
mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
| PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
| PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
| PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
asm_flags = png_get_asm_flags(png_ptr);
png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
}
#endif
For more extensive examples of runtime querying, enabling and disabling
of optimized features, see contrib/gregbook/readpng2.c in the libpng
source-code distribution.
%-%.SH VI. Runtime optimization
%-%
%-%A new feature in libpng 1.2.0 is the ability to dynamically switch between
%-%standard and optimized versions of some routines. Currently these are
%-%limited to three computationally intensive tasks when reading PNG files:
%-%decoding row filters, expanding interlacing, and combining interlaced or
%-%transparent row data with previous row data. Currently the optimized
%-%versions are available only for x86 (Intel, AMD, etc.) platforms with
%-%MMX support, though this may change in future versions. (For example,
%-%the non-MMX assembler optimizations for zlib might become similarly
%-%runtime-selectable in future releases, in which case libpng could be
%-%extended to support them. Alternatively, the compile-time choice of
%-%floating-point versus integer routines for gamma correction might become
%-%runtime-selectable.)
%-%
%-%Because such optimizations tend to be very platform- and compiler-dependent,
%-%both in how they are written and in how they perform, the new runtime code
%-%in libpng has been written to allow programs to query, enable, and disable
%-%either specific optimizations or all such optimizations. For example, to
%-%enable all possible optimizations (bearing in mind that some "optimizations"
%-%may actually run more slowly in rare cases):
%-%
%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
%-% png_uint_32 mask, flags;
%-%
%-% flags = png_get_asm_flags(png_ptr);
%-% mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
%-% png_set_asm_flags(png_ptr, flags | mask);
%-% #endif
%-%
%-%To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
%-%by itself when calling png_get_asm_flagmask(); similarly for optimizing
%-%only writing. To disable all optimizations:
%-%
%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
%-% flags = png_get_asm_flags(png_ptr);
%-% mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
%-% png_set_asm_flags(png_ptr, flags & ~mask);
%-% #endif
%-%
%-%To enable or disable only MMX-related features, use png_get_mmx_flagmask()
%-%in place of png_get_asm_flagmask(). The mmx version takes one additional
%-%parameter:
%-%
%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
%-% int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
%-% int compilerID;
%-%
%-% mask = png_get_mmx_flagmask(selection, &compilerID);
%-% #endif
%-%
%-%On return, compilerID will indicate which version of the MMX assembler
%-%optimizations was compiled. Currently two flavors exist: Microsoft
%-%Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
%-%On non-x86 platforms or on systems compiled without MMX optimizations, a
%-%value of -1 is used.
%-%
%-%Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
%-%all valid, settable optimization bits for the version of the library that's
%-%currently in use. In the case of shared (dynamically linked) libraries,
%-%this may include optimizations that did not exist at the time the code was
%-%written and compiled. It is also possible, of course, to enable only known,
%-%specific optimizations; for example:
%-%
%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
%-% flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
%-% | PNG_ASM_FLAG_MMX_READ_INTERLACE \
%-% | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
%-% | PNG_ASM_FLAG_MMX_READ_FILTER_UP \
%-% | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
%-% | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
%-% png_set_asm_flags(png_ptr, flags);
%-% #endif
%-%
%-%This method would enable only the MMX read-optimizations available at the
%-%time of libpng 1.2.0's release, regardless of whether a later version of
%-%the DLL were actually being used. (Also note that these functions did not
%-%exist in versions older than 1.2.0, so any attempt to run a dynamically
%-%linked app on such an older version would fail.)
%-%
%-%To determine whether the processor supports MMX instructions at all, use
%-%the png_mmx_support() function:
%-%
%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
%-% mmxsupport = png_mmx_support();
%-% #endif
%-%
%-%It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
%-%is compiled but MMX is not supported by the processor, or 1 if MMX support
%-%is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
%-%and png_get_asm_flagmask() all may be called without allocating and ini-
%-%tializing any PNG structures (for example, as part of a usage screen or
%-%"about" box).
%-%
%-%The following code can be used to prevent an application from using the
%-%thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
%-%defined:
%-%
%-%#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \
%-% && defined(PNG_THREAD_UNSAFE_OK)
%-% /* Disable thread-unsafe features of pnggccrd */
%-% if (png_access_version() >= 10200)
%-% {
%-% png_uint_32 mmx_disable_mask = 0;
%-% png_uint_32 asm_flags;
%-%
%-% mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
%-% | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
%-% | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
%-% | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
%-% asm_flags = png_get_asm_flags(png_ptr);
%-% png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
%-% }
%-%#endif
%-%
%-%For more extensive examples of runtime querying, enabling and disabling
%-%of optimized features, see contrib/gregbook/readpng2.c in the libpng
%-%source-code distribution.
%-%
.SH VI. MNG support
The MNG specification (available at http://www.libpng.org/pub/mng) allows
@@ -3615,13 +3649,13 @@ application:
.SH VII. Y2K Compliance in libpng
July 28, 2004
August 4, 2004
Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.
This is your unofficial assurance that libpng from version 0.71 and
upward through 1.2.6beta4 are Y2K compliant. It is my belief that earlier
upward through 1.2.6rc1 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
@@ -3761,6 +3795,8 @@ the first widely used release:
1.0.15 10 10015 10.so.0.1.0.15
1.2.5 13 10205 12.so.0.1.2.5
1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4
1.0.16rc1-4 10 10016 10.so.0.1.0.16rc1-4
1.2.6rc1-4 13 10206 12.so.0.1.2.6rc1-4
Henceforth the source version will match the shared-library minor
and patch numbers; the shared-library major version number will be
@@ -3818,7 +3854,7 @@ possible without all of you.
Thanks to Frank J. T. Wojcik for helping with the documentation.
Libpng version 1.2.6beta4 - July 28, 2004:
Libpng version 1.2.6rc1 - August 4, 2004:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Currently maintained by Glenn Randers-Pehrson (glennrp@users.sourceforge.net).
@@ -3835,7 +3871,7 @@ included in the libpng distribution, the latter shall prevail.)
If you modify libpng you may insert additional notices immediately following
this sentence.
libpng version 1.2.6, July 28, 2004, is
libpng version 1.2.6, August 4, 2004, is
Copyright (c) 2004 Glenn Randers-Pehrson, and is
distributed according to the same disclaimer and license as libpng-1.2.5
with the following individuals added to the list of Contributing Authors
@@ -3935,7 +3971,7 @@ certification mark of the Open Source Initiative.
Glenn Randers-Pehrson
glennrp@users.sourceforge.net
July 28, 2004
August 4, 2004
.\" end of man page