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

Imported from libpng-1.0.5q.tar

Browse Source
This commit is contained in:
Glenn Randers-Pehrson 2000-02-04 23:40:16 -06:00
parent 166c5a397e
commit 61c32d9e66
49 changed files with 7587 additions and 1120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
ANNOUNCE
View File

@ -1,5 +1,5 @@
Libpng 1.0.5h - December 10, 1999
Libpng 1.0.5q - February 5, 2000
This is not intended to be a public release. It will be replaced
within a few weeks by a public version or by another test version.
@ -73,13 +73,72 @@ version libpng-1.0.5g December 7, 1999
Moved PNG_CHNK string macro definitions outside of PNG_NO_EXTERN block
Added "translated_key" to png_text structure and png_write_iTXt().
Added code in pngwrite.c to work around a newly discovered zlib bug.
version 1.0.5h [December 10, 1999]
NOTE: regarding the not for version 1.0.5e, the following must also
version libpng-1.0.5h December 10, 1999
NOTE: regarding the note for version 1.0.5e, the following must also
be included in your code:
png_text[i].translated_key = NULL;
Unknown chunk handling is now supported.
Option to eliminate all floating point support was added. Some new
fixed-point functions such as png_set_gAMA_fixed() were added.
version libpng-1.0.5i December 13, 1999
Added some type casts to silence compiler warnings.
Renamed "png_free_spalette" to "png_free_spalettes" for consistency.
Removed leading blanks from a #define in pngvcrd.c
Added some parameters to the new png_set_keep_unknown_chunks() function,
and relocated it in pngset.c
Added a test for up->location != 0 in the first instance of writing
unknown chunks in pngwrite.c
Changed "num" to "i" in png_free_spalettes() and png_free_unknowns() to
prevent recursion.
Added png_free_hIST() function.
Various patches to fix bugs in the sCAL and integer cHRM processing,
and to add some convenience macros for use with sCAL.
version libpng-1.0.5j December 21, 1999
Changed "unit" parameter of png_write_sCAL from png_byte to int, to work
around buggy compilers.
Added new type "png_fixed_point" for integers that hold float*100000 values
Restored backward compatibility of tEXt/zTXt chunk processing:
Added members "lang_key" and "itxt_length" to png_text struct. Set
text_length=0 when "text" contains iTXt data. Use the "compression"
member to distinguish among tEXt/zTXt/iTXt types. Restored the first
four members of png_text to the same order as v.1.0.5d. The "Note" above,
about backward incompatibility of libpng-1.0.5e, no longer applies.
Added PNG_ITXT_COMPRESSION_NONE (1) and PNG_ITXT_COMPRESSION_zTXt(2) macros.
Fixed png_read|write_iTXt() to read|write parameters in the right order.
and to write the iTXt chunk after IDAT if it appears in the end_ptr.
Added pnggccrd.c, version of pngvcrd.c Intel assembler for gcc (Greg Roelofs)
Reversed the order of trying to write floating-point and fixed-point gAMA.
version libpng-1.0.5k December 27, 1999
Added many parentheses, e.g., "if (a && b & c)" becomes "if (a && (b & c))"
Added png_handle_as_unknown()
Added png_free_chunk_list() function and chunk_list and num_chunk_list members
of png_ptr.
Eliminated erroneous warnings about multiple sPLT chunks and sPLT-after-PLTE.
Fixed a libpng-1.0.5h bug in pngrutil.c that was issuing erroneous warnings
about ignoring incorrect gAMA with sRGB (gAMA was in fact not ignored)
Added png_free_tRNS(); png_set_tRNS() now malloc's its own trans array (ESR).
Define png_get_int_32 when oFFs chunk is supported as well as when pCAL is.
Changed type of proflen from png_int_32 to png_uint_32 in png_get_iCCP().
version libpng-1.0.5l January 1, 2000
Added functions png_set_read_user_chunk_fn() and png_get_user_chunk_ptr()
for setting a callback function to handle unknown chunks and for
retrieving the associated user pointer (Glenn).
version 1.0.5m [January 7, 2000]
Added high-level functions png_read_png(), png_write_png(), png_free_pixels().
version 1.0.5n [January 9, 2000]
Added png_free_PLTE() function, and modified png_set_PLTE() to malloc its
own memory for info_ptr->palette. This makes it safe for the calling
application to free its copy of the palette any time after it calls
png_set_PLTE().
version 1.0.5o [January 20, 2000]
Cosmetic changes only (removed some trailing blanks and TABs)
version 1.0.5p [January 31, 2000]
Renamed pngdll.mak to makefile.bd32
Cosmetic changes in pngtest.c
version 1.0.5q [February 5, 2000]
Relocated the makefile.solaris warning about PATH problems.
Fixed pngvcrd.c bug by pushing/popping registers in mmxsupport (Bruce Oberg)
Revised makefile.gcmmx
Send comments/corrections/commendations to
png-implement@ccrc.wustl.edu or to randeg@alum.rpi.edu

65
CHANGES
View File

@ -517,7 +517,7 @@ version 1.0.5e [November 30, 1999]
with trailing compressed parts easier in the future, and added new functions
png_free_iCCP, png_free_pCAL, png_free_sPLT, png_free_text, png_get_iCCP,
png_get_spalettes, png_set_iCCP, png_set_spalettes (Eric S. Raymond).
NOTE: Applications that write text chunks MUST define png_text->lang and
NOTE: Applications that write text chunks MUST define png_text->lang
before calling png_set_text(). It must be set to NULL if you want to
write tEXt or zTXt chunks. If you want your application to be able to
run with older versions of libpng, use
@ -544,9 +544,70 @@ version 1.0.5g [December 7, 1999]
Added "translated_key" to png_text structure and png_write_iTXt().
Added code in pngwrite.c to work around a newly discovered zlib bug.
version 1.0.5h [December 10, 1999]
NOTE: regarding the not for version 1.0.5e, the following must also
NOTE: regarding the note for version 1.0.5e, the following must also
be included in your code:
png_text[i].translated_key = NULL;
Unknown chunk handling is now supported.
Option to eliminate all floating point support was added. Some new
fixed-point functions such as png_set_gAMA_fixed() were added.
Expanded tabs and removed trailing blanks in source files.
version 1.0.5i [December 13, 1999]
Added some type casts to silence compiler warnings.
Renamed "png_free_spalette" to "png_free_spalettes" for consistency.
Removed leading blanks from a #define in pngvcrd.c
Added some parameters to the new png_set_keep_unknown_chunks() function.
Added a test for up->location != 0 in the first instance of writing
unknown chunks in pngwrite.c
Changed "num" to "i" in png_free_spalettes() and png_free_unknowns() to
prevent recursion.
Added png_free_hIST() function.
Various patches to fix bugs in the sCAL and integer cHRM processing,
and to add some convenience macros for use with sCAL.
version 1.0.5j [December 21, 1999]
Changed "unit" parameter of png_write_sCAL from png_byte to int, to work
around buggy compilers.
Added new type "png_fixed_point" for integers that hold float*100000 values
Restored backward compatibility of tEXt/zTXt chunk processing:
Restored the first four members of png_text to the same order as v.1.0.5d.
Added members "lang_key" and "itxt_length" to png_text struct. Set
text_length=0 when "text" contains iTXt data. Use the "compression"
member to distinguish among tEXt/zTXt/iTXt types. Added
PNG_ITXT_COMPRESSION_NONE (1) and PNG_ITXT_COMPRESSION_zTXt(2) macros.
The "Note" above, about backward incompatibility of libpng-1.0.5e, no
longer applies.
Fixed png_read|write_iTXt() to read|write parameters in the right order,
and to write the iTXt chunk after IDAT if it appears in the end_ptr.
Added pnggccrd.c, version of pngvcrd.c Intel assembler for gcc (Greg Roelofs)
Reversed the order of trying to write floating-point and fixed-point gAMA.
version 1.0.5k [December 27, 1999]
Added many parentheses, e.g., "if (a && b & c)" becomes "if (a && (b & c))"
Added png_handle_as_unknown() function (Glenn)
Added png_free_chunk_list() function and chunk_list and num_chunk_list members
of png_ptr.
Eliminated erroneous warnings about multiple sPLT chunks and sPLT-after-PLTE.
Fixed a libpng-1.0.5h bug in pngrutil.c that was issuing erroneous warnings
about ignoring incorrect gAMA with sRGB (gAMA was in fact not ignored)
Added png_free_tRNS(); png_set_tRNS() now malloc's its own trans array (ESR).
Define png_get_int_32 when oFFs chunk is supported as well as when pCAL is.
Changed type of proflen from png_int_32 to png_uint_32 in png_get_iCCP().
version 1.0.5l [January 1, 2000]
Added functions png_set_read_user_chunk_fn() and png_get_user_chunk_ptr()
for setting a callback function to handle unknown chunks and for
retrieving the associated user pointer (Glenn).
version 1.0.5m [January 7, 2000]
Added high-level functions png_read_png(), png_write_png(), png_free_pixels().
version 1.0.5n [January 9, 2000]
Added png_free_PLTE() function, and modified png_set_PLTE() to malloc its
own memory for info_ptr->palette. This makes it safe for the calling
application to free its copy of the palette any time after it calls
png_set_PLTE().
version 1.0.5o [January 20, 2000]
Cosmetic changes only (removed some trailing blanks and TABs)
version 1.0.5p [January 31, 2000]
Renamed pngdll.mak to makefile.bd32
Cosmetic changes in pngtest.c
version 1.0.5q [February 5, 2000]
Relocated the makefile.solaris warning about PATH problems.
Fixed pngvcrd.c bug by pushing/popping registers in mmxsupport (Bruce Oberg)
Revised makefile.gcmmx
Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros

22
INSTALL
View File

@ -1,5 +1,5 @@
Installing libpng version 1.0.5h - December 10, 1999
Installing libpng version 1.0.5q - February 5, 2000
Before installing libpng, you must first install zlib. zlib
can usually be found wherever you got libpng. zlib can be
@ -10,7 +10,7 @@ zlib.h and zconf.h include files that correspond to the
version of zlib that's installed.
You can rename the directories that you downloaded (they
might be called "libpng-1.0.5h" or "lpng103" and "zlib-1.1.3"
might be called "libpng-1.0.5q" or "lpng103" and "zlib-1.1.3"
or "zlib113") so that you have directories called "zlib" and "libpng".
Your directory structure should look like this:
@ -36,6 +36,10 @@ Your directory structure should look like this:
contrib
etc.
If the line endings in the files look funny, you may wish to get the other
distribution of libpng. It is available in both tar.gz (UNIX style line
endings) and zip (DOS style line endings) formats.
First enter the zlib directory and follow the instructions
in zlib/README. Then come back here and choose the
appropriate makefile.sys in the scripts directory.
@ -51,8 +55,10 @@ include
makefile.hpux => HPUX (10.20 and 11.00) makefile
makefile.sgi => Silicon Graphics IRIX makefile
makefile.sunos => Sun makefile
makefile.solaris => Solaris 2.X makefile (gcc, creates libpng.so.2.1.0.5h)
makefile.linux => Linux/ELF makefile (gcc, creates libpng.so.2.1.0.5h)
makefile.solaris => Solaris 2.X makefile (gcc, creates libpng.so.2.1.0.5q)
makefile.linux => Linux/ELF makefile (gcc, creates libpng.so.2.1.0.5q)
makefile.gcmmx => Linux/ELF makefile (gcc, creates libpng.so.2.1.0.5q,
uses assembler code tuned for Intel MMX platform)
makefile.sco => For SCO OSr5 ELF and Unixware 7 with Native cc
makefile.mips => MIPS makefile
makefile.acorn => Acorn makefile
@ -61,20 +67,20 @@ include
(Requires SCOPTIONS, copied from scripts/SCOPTIONS.ppc)
makefile.atari => Atari makefile
makefile.beos => BEOS makefile for X86
makefile.borland => Borland makefile
makefile.borland => Borland makefile (uses bcc)
makefile.bd32 => To make a png32bd.dll with Borland C++ 4.5
makefile.turboc3 => Turbo C 3.0 makefile
build.bat => MS-DOS batch file for Borland compiler
makefile.dj2 => DJGPP 2 makefile
makefile.msc => Microsoft C makefile
makefile.vcawin32 => makefile for Microsoft Visual C++ 5.0 and later (uses
assembler code)
assembler code tuned for Intel MMX platform)
makefile.vcwin32 => makefile for Microsoft Visual C++ 4.0 and later (does
not use assembler code)
makefile.turboc3 => Turbo C 3.0 makefile
makefile.os2 => OS/2 Makefile (gcc and emx, requires pngos2.def)
pngos2.def => OS/2 module definition file used by makefile.os2
makefile.watcom => Watcom 10a+ Makefile, 32-bit flat memory model
makevms.com => VMS build script
pngdll.mak => To make a png32bd.dll with Borland C++ 4.5
pngdef.pas => Defines for a png32bd.dll with Borland C++ 4.5
SCOPTIONS.ppc => Used with smakefile.ppc

11
KNOWNBUG
View File

@ -38,6 +38,9 @@ Known bugs and suggested enhancements in libpng-1.0.5
for the png_set_gAMA(), png_set_cHRM(), and corresponding png_get_()
functions will be needed.
Much of this was completed in libpng-1.0.5h, but gamma compensation
is not yet done in fixed-point arithmetic.
4. October 1999 -- BUG
pngvcrd.c is failing for interlaced PNGs that have empty passes.
@ -64,4 +67,10 @@ Known bugs and suggested enhancements in libpng-1.0.5
is not backward compatible (the lang member was added, and the
translated_key member was added to libpng-1.0.5g)
STATUS: Will be fixed before the next public release.
STATUS: Fixed in libpng-1.0.5j/1.1.0
7. December 1999 -- BUG
The new pnggccrd.c has syntax errors when compiled with gcc.
STATUS: Under investigation.

8
LICENSE
View File

@ -4,8 +4,8 @@ Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
(libpng versions 0.5, May 1995, through 0.89c, May 1996)
Copyright (c) 1996, 1997 Andreas Dilger
(libpng versions 0.90, December 1996, through 0.96, May 1997)
Copyright (c) 1998, 1999 Glenn Randers-Pehrson
(libpng versions 0.97, January 1998, through 1.0.5h, December 10, 1999)
Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson
(libpng versions 0.97, January 1998, through 1.0.5q, February 5, 2000)
For the purposes of this copyright and license, "Contributing Authors"
is defined as the following set of individuals:
@ -63,9 +63,9 @@ boxes and the like:
Also, the PNG logo (in PNG format, of course) is supplied in the
file "pngnow.png".
Libpng is OSI Certified Open Source Software. OSI Certified is a
Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a
certification mark of the Open Source Initiative.
Glenn Randers-Pehrson
randeg@alum.rpi.edu
December 10, 1999
February 5, 2000

22
README
View File

@ -1,8 +1,12 @@
README for libpng 1.0.5h - December 10, 1999 (shared library 2.1)
README for libpng 1.0.5q - February 5, 2000 (shared library 2.1)
See the note about version numbers near the top of png.h
See INSTALL for instructions on how to install libpng.
Libpng comes in two distribution formats. Get libpng-*.tar.gz if you
want UNIX-style line endings in the text files, or lpng*.zip if you want
DOS-style line endings.
Version 0.89 was the first official release of libpng. Don't let the
fact that it's the first release fool you. The libpng library has been in
extensive use and testing since mid-1995. By late 1997 it had
@ -171,9 +175,12 @@ Files in this distribution:
makefile.sgi => Silicon Graphics IRIX makefile
makefile.sunos => Sun makefile
makefile.solaris => Solaris 2.X makefile
(gcc, creates libpng.so.2.1.0.5h)
(gcc, creates libpng.so.2.1.0.5q)
makefile.linux => Linux/ELF makefile
(gcc, creates libpng.so.2.1.0.5h)
(gcc, creates libpng.so.2.1.0.5q)
makefile.gcmmx => Linux/ELF makefile (gcc, creates
libpng.so.2.1.0.5q, uses assembler code
tuned for Intel MMX platform)
makefile.sco => For SCO OSr5 ELF and Unixware 7 with Native cc
makefile.mips => MIPS makefile
makefile.acorn => Acorn makefile
@ -183,20 +190,21 @@ Files in this distribution:
scripts/SCOPTIONS.ppc)
makefile.atari => Atari makefile
makefile.beos => BEOS makefile for X86
makefile.borland => Borland makefile
makefile.borland => Borland makefile (uses bcc)
makefile.bd32 => To make a png32bd.dll with Borland C++ 4.5
makefile.turboc3 => Turbo C 3.0 makefile
build.bat => MS-DOS batch file for Borland compiler
makefile.dj2 => DJGPP 2 makefile
makefile.msc => Microsoft C makefile
makefile.vcawin32 => makefile for Microsoft Visual C++ 5.0 and
later (uses assembler code)
later (uses assembler code tuned for Intel MMX
platform)
makefile.vcwin32 => makefile for Microsoft Visual C++ 4.0 and
later (does not use assembler code)
makefile.turboc3 => Turbo C 3.0 makefile
makefile.os2 => OS/2 Makefile (gcc and emx, requires pngos2.def)
pngos2.def => OS/2 module definition file used by makefile.os2
makefile.watcom => Watcom 10a+ Makefile, 32-bit flat memory model
makevms.com => VMS build script
pngdll.mak => To make a png32bd.dll with Borland C++ 4.5
pngdef.pas => Defines for a png32bd.dll with Borland C++ 4.5
SCOPTIONS.ppc => Used with smakefile.ppc

7
TODO
View File

@ -1,13 +1,11 @@
TODO - list of things to do for libpng:
Final bug fixes.
Fix problem with C++ and EXTERN "C".
Finish work on the no-floating-point version (including gamma compensation)
Better C++ wrapper/full C++ implementation?
Keep up with public chunks.
Fix problem with C++ and EXTERN "C".
cHRM transformation.
Support for application-defined chunk handlers.
Improve setjmp/longjmp usage or remove it in favor of returning error codes.
High-level API for reading images.
Add "grayscale->palette" transformation and "palette->grayscale" detection.
Improved dithering.
Multi-lingual error and warning message support.
@ -19,4 +17,3 @@ Better filter selection
Histogram creation.
Text conversion between different code pages (Latin-1 -> Mac and DOS).
Improve API by hiding the info_ptr.
Make a no-floating-point version.

30
Y2KINFO
View File

@ -1,29 +1,29 @@
Y2K compliance in libpng:
=========================
December 10, 1999
February 5, 2000
Since the PNG Development group is an ad-hoc body, we can't make
an official declaration.
This is your unofficial assurance that libpng from version 0.71 and
upward through 1.0.5h are Y2K compliant. It is my belief that earlier
upward through 1.0.5q are Y2K compliant. It is my belief that earlier
versions were also Y2K compliant.
Libpng only has three year fields. One is a 2-byte unsigned integer
that will hold years up to 65535. The other two hold the date in text
format, and will hold years up to 9999.
The integer is
"png_uint_16 year" in png_time_struct.
The strings are
"png_charp time_buffer" in png_struct and
"near_time_buffer", which is a local character string in png.c.
There are seven time-related functions:
png_convert_to_rfc_1123() in png.c
png_convert_to_rfc_1123() in png.c
(formerly png_convert_to_rfc_1152() in error)
png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c
png_convert_from_time_t() in pngwrite.c
@ -31,8 +31,8 @@
png_handle_tIME() in pngrutil.c, called in pngread.c
png_set_tIME() in pngset.c
png_write_tIME() in pngwutil.c, called in pngwrite.c
All appear to handle dates properly in a Y2K environment. The
All appear to handle dates properly in a Y2K environment. The
png_convert_from_time_t() function calls gmtime() to convert from system
clock time, which returns (year - 1900), which we properly convert to
the full 4-digit year. There is a possibility that applications using
@ -42,14 +42,14 @@
but this is not under our control. The libpng documentation has always
stated that it works with 4-digit years, and the APIs have been
documented as such.
The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
integer to hold the year, and can hold years as large as 65535.
zlib, upon which libpng depends, is also Y2K compliant. It contains
no date-related code.
Glenn Randers-Pehrson
libpng maintainer
PNG Development Group

52
contrib/pngminus/makefile Normal file
View File

@ -0,0 +1,52 @@
# Makefile for PngMinus (png2pnm and pnm2png)
# Linux / Unix
CC=cc -O -n32
LD=cc -O -n32
#CC=gcc -O
#LD=gcc -O
LB=ar
RM=rm
CP=cp
PNGPATH = /usr/local
PNGINC = $(PNGPATH)/include
PNGLIB = $(PNGPATH)/lib -lpng
# PNGLIB = $(PNGPATH)/libpng.a
ZPATH = /usr/local
ZINC = $(ZPATH)/include
ZLIB = $(ZPATH)/lib -lz
# ZLIB = $(ZPATH)/libz.a
CCFLAGS=-I$(PNGINC) -I$(ZINC)
LDFLAGS=-L$(PNGLIB) -L$(ZLIB) -lm
C=.c
O=.o
L=.a
E=
# dependencies
all: png2pnm$(E) pnm2png$(E)
png2pnm$(O): png2pnm$(C)
$(CC) -c $(CCFLAGS) png2pnm$(C)
png2pnm$(E): png2pnm$(O)
$(LD) -o png2pnm$(E) png2pnm$(O) $(LDFLAGS)
pnm2png$(O): pnm2png$(C)
$(CC) -c $(CCFLAGS) pnm2png$(C)
pnm2png$(E): pnm2png$(O)
$(LD) -o pnm2png$(E) pnm2png$(O) $(LDFLAGS)
clean:
$(RM) png2pnm$(O)
$(RM) pnm2png$(O)
$(RM) png2pnm$(E)
$(RM) pnm2png$(E)
# End of makefile for png2pnm / pnm2png

7
contrib/pngminus/pnm2png.c
View File

@ -77,7 +77,8 @@ int main(int argc, char *argv[])
if ((fp_al = fopen (argv[argi], "rb")) == NULL)
{
fprintf (stderr, "PNM2PNG\n");
fprintf (stderr, "Error: alpha-channel file %s does not exist\n", argv[argi]);
fprintf (stderr, "Error: alpha-channel file %s does not exist\n",
argv[argi]);
exit (1);
}
break;
@ -511,8 +512,8 @@ png_uint_32 get_value (FILE *pnm_file, int depth)
for (i = 0; i < depth; i++)
mask = (mask << 1) | 0x01;
get_token (pnm_file, token);
sscanf (token, "%lu", &ret_value);
get_token (pnm_file, (char *) token);
sscanf ((const char *) token, "%lu", &ret_value);
ret_value &= mask;

49
example.c
View File

@ -136,6 +136,19 @@ void read_png(FILE *fp, unsigned int sig_read) /* file is already open */
/* If we have already read some of the signature */
png_set_sig_bytes(png_ptr, sig_read);
#ifdef hilevel
/*
* If you have enough memory to read in the entire image at once,
* and you need to specify only transforms that can be controlled
* with one of the PNG_TRANSFORM_* bits (this presently excludes
* dithering, filling, setting background, and doing gamma
* adjustment), then you can read the entire image (including
* pixels) into the info structure with this call:
*/
png_read_png(png_ptr, info_ptr, png_transforms, NULL);
#else
/* OK, you're doing it the hard way, with the lower-level functions */
/* The call to png_read_info() gives us all of the information from the
* PNG file before the first IDAT (image data chunk). REQUIRED
*/
@ -275,7 +288,7 @@ void read_png(FILE *fp, unsigned int sig_read) /* file is already open */
*/
if (png_get_valid(png_ptr, info_ptr, PNG_INFO_sBIT))
{
png_color8p sig_bit;
png_color_8p sig_bit;
png_get_sBIT(png_ptr, info_ptr, &sig_bit);
png_set_shift(png_ptr, sig_bit);
@ -350,6 +363,9 @@ void read_png(FILE *fp, unsigned int sig_read) /* file is already open */
/* read rest of file, and get additional chunks in info_ptr - REQUIRED */
png_read_end(png_ptr, info_ptr);
#endif hilevel
/* At this point you have read the entire image */
/* clean up after the read, and free any memory allocated - REQUIRED */
png_destroy_read_struct(&png_ptr, &info_ptr, (png_infopp)NULL);
@ -530,7 +546,7 @@ void write_png(char *file_name /* , ... other image information ... */)
}
/* Set error handling. REQUIRED if you aren't supplying your own
* error hadnling functions in the png_create_write_struct() call.
* error handling functions in the png_create_write_struct() call.
*/
if (setjmp(png_ptr->jmpbuf))
{
@ -552,6 +568,15 @@ void write_png(char *file_name /* , ... other image information ... */)
/* where user_io_ptr is a structure you want available to the callbacks */
#endif no_streams /* only use one initialization method */
#ifdef hilevel
/* This is the easy way. Use it if you already have all the
* image info living info in the structure. You could "|" many
* PNG_TRANSFORM flags into the png_transforms integer here.
*/
png_write_png(png_ptr, info_ptr, png_transforms, NULL);
#else
/* This is the hard way */
/* Set the image information here. Width and height are up to 2^31,
* bit_depth is one of 1, 2, 4, 8, or 16, but valid values also depend on
* the color_type selected. color_type is one of PNG_COLOR_TYPE_GRAY,
@ -567,6 +592,11 @@ void write_png(char *file_name /* , ... other image information ... */)
palette = (png_colorp)png_malloc(png_ptr, 256 * sizeof (png_color));
/* ... set palette colors ... */
png_set_PLTE(png_ptr, info_ptr, palette, 256);
/* You can free the palette here if you like, since libpng has made its
own copy. In versions of libpng earlier than version 1.0.5n, it was
necessary to keep the palette until after png_write_end(), because
libpng was using the caller's copy. */
free(palette);
/* optional significant bit chunk */
/* if we are dealing with a grayscale image then */
@ -615,6 +645,9 @@ void write_png(char *file_name /* , ... other image information ... */)
* png_write_info_before_PLTE(write_ptr, write_info_ptr);
* write_my_chunk();
* png_write_info(png_ptr, info_ptr);
*
* However, given the level of known- and unknown-chunk support in 1.1.0
* and up, this should no longer be necessary.
*/
/* Once we write out the header, the compression type on the text
@ -695,14 +728,20 @@ void write_png(char *file_name /* , ... other image information ... */)
#endif no_entire /* use only one output method */
/* You can write optional chunks like tEXt, zTXt, and tIME at the end
* as well.
* as well. Shouldn't be necessary in 1.1.0 and up as all the public
* chunks are supported and you can use png_set_unknown_chunks() to
* register unknown chunks into the info structure to be written out.
*/
/* It is REQUIRED to call this to finish writing the rest of the file */
png_write_end(png_ptr, info_ptr);
#endif hilevel
/* if you malloced the palette, free it here */
free(info_ptr->palette);
/* if you malloced a palette and have not already freed it, free it
here (do *not* free libpng's copy of the palette in info_ptr->palette,
as recommended in versions 1.0.5m and earlier of this example; libpng
now takes care of that automatically). */
free(palette);
/* clean up after the write, and free any memory allocated */
png_destroy_write_struct(&png_ptr, (png_infopp)NULL);

470
libpng.3
View File

@ -1,6 +1,6 @@
.TH LIBPNG 3 "December 10, 1999"
.TH LIBPNG 3 "February 5, 2000"
.SH NAME
libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5q
.SH SYNOPSIS
\fI\fB
@ -84,10 +84,18 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBvoid png_free_chunk_list (png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
\fBvoid png_free_default(png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
\fI\fB
\fBvoid png_free_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fI\fP\fB);\fP
\fI\fB
\fBvoid png_free_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fI\fP\fB);\fP
\fI\fB
@ -96,11 +104,19 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBvoid png_free_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
\fBvoid png_free_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
\fBvoid png_free_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
\fBvoid png_free_spalette (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum_text\fP\fB);\fP
\fBvoid png_free_spalettes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum_text\fP\fB);\fP
\fI\fB
@ -112,6 +128,14 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBvoid png_free_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
\fBvoid png_free_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum_unknowns\fP\fB);\fP
\fI\fB
\fBpng_byte png_get_bit_depth (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
@ -172,7 +196,7 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBpng_uint_32 png_get_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_charpp \fP\fIprofile\fP\fB, int \fI*proflen\fP\fB);\fP
\fBpng_uint_32 png_get_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_charpp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP
\fI\fB
@ -270,6 +294,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBpng_voidp png_get_user_chunk_ptr (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
@ -362,6 +390,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBvoid png_read_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, voidp \fIparams\fP\fB);\fP
\fI\fB
\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
\fI\fB
@ -470,7 +502,7 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBvoid png_set_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_charp \fP\fIprofile\fP\fB, int \fIproflen\fP\fB);\fP
\fBvoid png_set_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_charp \fP\fIprofile\fP\fB, png_uint_32 \fIproflen\fP\fB);\fP
\fI\fB
@ -490,7 +522,7 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBvoid png_set_keep_unknown_chunks (png_structp \fIpng_ptr\fP\fB);\fP
\fBvoid png_set_keep_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIkeep\fP\fB, png_bytep \fP\fIchunk_list\fP\fB, int \fInum_chunks\fP\fB);\fP
\fI\fB
@ -606,7 +638,11 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBpng_uint_32 png_set_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkp \fP\fIunknowns\fP\fB, int \fInum\fP\fB);\fP
\fBpng_uint_32 png_set_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkp \fP\fIunknowns\fP\fB, int \fP\fInum\fP\fB, int \fIlocation\fP\fB);\fP
\fI\fB
\fBvoid png_set_read_user_chunk_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_chunk_ptr\fP\fB, png_user_chunk_ptr \fIread_user_chunk_fn\fP\fB);\fP
\fI\fB
@ -682,6 +718,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.0.5h
\fI\fB
\fBvoid png_write_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, voidp \fIparams\fP\fB);\fP
\fI\fB
\fBvoid png_write_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIrow\fP\fB);\fP
\fI\fB
@ -701,10 +741,10 @@ Following is a copy of the libpng.txt file that accompanies libpng.
.SH LIBPNG.TXT
libpng.txt - A description on how to use and modify libpng
libpng version 1.0.5h - December 10, 1999
libpng version 1.0.5q - February 5, 2000
Updated and distributed by Glenn Randers-Pehrson
<randeg@alum.rpi.edu>
Copyright (c) 1998, 1999 Glenn Randers-Pehrson
Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson
For conditions of distribution and use, see copyright
notice in png.h.
@ -720,10 +760,9 @@ libpng.txt - A description on how to use and modify libpng
Schalnat, Group 42, Inc.
Updated/rewritten per request in the libpng FAQ
Copyright (c) 1995 Frank J. T. Wojcik
December 18, 1995 && January 20, 1996
Copyright (c) 1995, 1996 Frank J. T. Wojcik
December 18, 1995 & January 20, 1996
*
.SH I. Introduction
This file describes how to use and modify the PNG reference library
@ -803,13 +842,14 @@ And while I'm on the topic, make sure you include the libpng header file:
.SH III. Reading
Reading PNG files:
We'll now walk you through the possible functions to call when reading
in a PNG file, briefly explaining the syntax and purpose of each one.
See example.c and png.h for more detail. While Progressive reading
is covered in the next section, you will still need some of the
functions discussed in this section to read a PNG file.
in a PNG file sequentially, briefly explaining the syntax and purpose
of each one. See example.c and png.h for more detail. While
progressive reading is covered in the next section, you will still
need some of the functions discussed in this section to read a PNG
file.
.SS Setup
You will want to do the I/O initialization(*) before you get into libpng,
so if it doesn't work, you don't have much to undo. Of course, you
@ -909,6 +949,10 @@ free any memory.
return;
}
If you would rather avoid the complexity of setjmp/longjmp issues,
you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
errors will result in a call to PNG_ABORT() which defaults to abort().
Now you need to set up the input code. The default for libpng is to
use the C function fread(). If you use this, you will need to pass a
valid FILE * in the function png_init_io(). Be sure that the file is
@ -925,6 +969,42 @@ libpng know that there are some bytes missing from the start of the file.
png_set_sig_bytes(png_ptr, number);
.SS Setting up callback code
You can set up a callback function to handle any unknown chunks in the
input stream. You must supply the function
read_chunk_callback(png_ptr ptr,
png_unknown_chunkp chunk);
{
/* The unknown chunk structure contains your
chunk data: */
png_byte name[5];
png_byte *data;
png_size_t size;
/* Note that libpng has already taken care of the
CRC handling */
/* put your code here. Return one of the following: */
return (-n); /* chunk had an error */
return (0); /* did not recognize */
return (n); /* success */
}
(You can give your function another name that you like instead of
"read_chunk_callback")
To inform libpng about your function, use
png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
read_chunk_callback);
This names not only the callback function, but also a user pointer that
you can retrieve with
png_get_user_chunk_ptr(png_ptr);
At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control
a progress meter or the like. It's demonstrated in pngtest.c.
@ -941,19 +1021,6 @@ To inform libpng about your function, use
png_set_read_status_fn(png_ptr, read_row_callback);
In PNG files, the alpha channel in an image is the level of opacity.
If you need the alpha channel in an image to be the level of transparency
instead of opacity, you can invert the alpha channel (or the tRNS chunk
data) after it's read, so that 0 is fully opaque and 255 (in 8-bit or
paletted images) or 65535 (in 16-bit images) is fully transparent, with
png_set_invert_alpha(png_ptr);
This has to appear here rather than later with the other transformations
because the tRNS chunk data must be modified in the case of paletted images.
If your image is not a paletted image, the tRNS data (which in such cases
represents a single color to be rendered as transparent) won't be changed.
Finally, you can write your own transformation function if none of
the existing ones meets your needs. This is done by setting a callback
with
@ -977,6 +1044,8 @@ function
png_set_user_transform_info(png_ptr, user_ptr,
user_depth, user_channels);
The user's application, not libpng, is responsible for allocating and
freeing any memory required for the user structure.
You can retrieve the pointer via the function
png_get_user_transform_ptr(). For example:
@ -984,23 +1053,100 @@ png_get_user_transform_ptr(). For example:
voidp read_user_transform_ptr =
png_get_user_transform_ptr(png_ptr);
You are now ready to read all the file information up to the actual
image data. You do this with a call to png_read_info().
.SS Unknown-chunk handling
Now you get to set the way the library processes unknown chunks in the
input PNG stream. Both known and unknown chunks will be read. Normal
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,
chunk_list, num_chunks);
keep - 0: do not keep
1: keep only if safe-to-copy
2: keep even if unsafe-to-copy
chunk_list - list of chunks affected (a byte string,
five bytes per chunk, NULL or '\0' if
num_chunks is 0)
num_chunks - number of chunks affected; if 0, all
unknown chunks are affected
Unknown chunks declared in this way will be saved as raw data onto a
list of png_unknown_chunk structures. If a chunk that is normally
known to libpng is named in the list, it will be handled as unknown,
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.
.SS The high-level read interface
At this point there are two ways to proceed; through the high-level
read interface, or through a sequence of low-level read operations.
You can use the high-level interface if (a) you are willing to read
the entire image into memory, and (b) the input transformations
you want to do are limited to the following set:
PNG_TRANSFORM_IDENTITY No transformation
PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to 8 bits
PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit samples to bytes
PNG_TRANSFORM_PACKSWAP Change order of packed pixels to LSB first
PNG_TRANSFORM_EXPAND Perform set_expand()
PNG_TRANSFORM_INVERT_MONO Invert monochrome images
PNG_TRANSFORM_SHIFT Normalize pixels to the sBIT depth
PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA to BGRA
PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA to AG
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity to transparency
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
(This excludes setting a background color, doing gamma transformation,
dithering, and setting filler.) If this is the case, simply do this:
png_read_png(png_ptr, info_ptr, png_transforms, NULL)
where png_transforms is an integer containing the logical-or of some set of
transformation flags. This call is equivalent to png_read_info(),
followed the set of transformations indicated by the transform mask,
followed by png_update_info(), followed by a read of the image bytes
to the info member `rowpointers', followed by png_read_end().
(The final parameter of this call is not yet used. Someday it
will point to transformation parameters.)
.SS The low-level read interface
If you are going the low-level route, you are now ready to read all
the file information up to the actual image data. You do this with a
call to png_read_info().
png_read_info(png_ptr, info_ptr);
This will read all chunks up to but not including the image data.
Both known and unknown chunks will be read. Known chunks will be
parsed into information in various info_ptr members; unknown chunks
will be discarded, unless you previously called
This will process all chunks up to but not including the image data.
png_set_keep_unknown_chunks();
There is one transformation you may need to set up before doing
png_read_info(), however. In PNG files, the alpha channel in an image
is the level of opacity. If you need the alpha channel in an image to
be the level of transparency instead of opacity, you can invert the
alpha channel (or the tRNS chunk data) after it's read, so that 0 is
fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
images) is fully transparent, with
in which case they will be saved as raw data onto a list of
png_unknown_chunk structures (and written out if you subsequently
call png_write_info and friends).
png_set_invert_alpha(png_ptr);
Functions are used to get the information from the info_ptr:
This must appear before png_write_info() instead of later with the
other transformations because in the case of paletted images the tRNS
chunk data has to be inverted before the tRNS chunk is written.
If your image is not a paletted image, the tRNS data (which in such cases
represents a single color to be rendered as transparent) won't need to
be changed, and you can safely do this transformation after your
png_read_info() call.
.SS Querying the info structure
Functions are used to get the information from the info_ptr once it
has been read. Note that these fields may not be completely filled
in until png_read_end() has read the chunk data following the image.
png_get_IHDR(png_ptr, info_ptr, &width, &height,
&bit_depth, &color_type, &interlace_type,
@ -1140,20 +1286,28 @@ into the info_ptr is returned for any complex types.
png_get_bKGD(png_ptr, info_ptr, &background);
background - background color (PNG_VALID_bKGD)
valid 16-bit red, green and blue
values, regardless of color_type
num_text = png_get_text(png_ptr, info_ptr, &text_ptr);
text_ptr - array of png_text holding image
comments
text_ptr[i]->lang - language of comment (NULL for unknown).
text_ptr[i]->compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
PNG_ITXT_COMPRESSION_NONE
PNG_ITXT_COMPRESSION_zTXt
text_ptr[i]->key - keyword for comment.
text_ptr[i]->translated_keyword - keyword in UTF-8 (NULL for unknown).
text_ptr[i]->text - text comments for current
keyword.
text_ptr[i]->compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
or PNG_TEXT_COMPRESSION_zTXt
text_ptr[i]->text_length - length of text string,
after decompression, 0 for iTXt
text_ptr[i]->itxt_length - length of itxt string,
after decompression, 0 for tEXt/zTXt
text_ptr[i]->lang - language of comment (NULL for unknown).
text_ptr[i]->translated_keyword - keyword in UTF-8 (NULL
for unknown).
num_text - number of comments
num_spalettes = png_get_spalettes(png_ptr, info_ptr, &palette_ptr);
palette_ptr - array of png_spalette structures holding contents
of one or more sPLT chunks read.
@ -1188,6 +1342,7 @@ into the info_ptr is returned for any complex types.
unknowns[i].name - name of unknown chunk
unknowns[i].data - data of unknown chunk
unknowns[i].size - size of unknown chunk
unknowns[i].location - position of chunk in file
The data from the pHYs chunk can be retrieved in several convenient
forms:
@ -1232,6 +1387,8 @@ make sure you have read all the text chunks, don't mess with these
until after you read the stuff after the image. This will be
mentioned again below in the discussion that goes with png_read_end().
.SS Input transformations
After you've read the header information, you can set up the library
to handle any special transformations of the image data. The various
ways to transform the data will be described in the order that they
@ -1566,6 +1723,8 @@ are allocating one large chunk, you will need to build an
array of pointers to each row, as it will be needed for some
of the functions below.
.SS Reading image data
After you've allocated memory, you can read the image data.
The simplest way to do this is in one function call. If you are
allocating enough memory to hold the whole image, you can just
@ -1674,12 +1833,14 @@ the second parameter NULL.
png_read_rows(png_ptr, NULL, row_pointers,
number_of_rows);
After you are finished reading the image, you can finish reading
the file. If you are interested in comments or time, which may be
stored either before or after the image data, you should pass the
separate png_info struct if you want to keep the comments from
before and after the image separate. If you are not interested, you
can pass NULL.
.SS Finishing a sequential read
After you are finished reading the image through either the high- or
low-level interfaces, you can finish reading the file. If you are
interested in comments or time, which may be stored either before or
after the image data, you should pass the separate png_info struct if
you want to keep the comments from before and after the image
separate. If you are not interested, you can pass NULL.
png_read_end(png_ptr, end_info);
@ -1694,16 +1855,20 @@ point to allocated storage with the following functions:
png_free_text(png_ptr, info_ptr, num)
num - number of text item to be freed (-1 for all items)
png_free_hIST(png_ptr, info_ptr)
png_free_iCCP(png_ptr, info_ptr)
png_free_pCAL(png_ptr, info_ptr)
png_free_sCAL(png_ptr, info_ptr)
png_free_spalette(png_ptr, info_ptr, num)
png_free_spalettes(png_ptr, info_ptr, num)
num - number of suggested-paletted entry to be freed
(-1 for all suggested palettes)
png_free_pixels(png_ptr, info_ptr)
png_free_unknown_chunk(png_ptr, info_ptr, num)
num - number of unknown chunk to be freed
(-1 for all suggested palettes)
@ -1714,8 +1879,7 @@ case do nothing.
For a more compact example of reading a PNG image, see the file example.c.
Reading PNG files progressively:
.SS Reading PNG files progressively
The progressive reader is slightly different then the non-progressive
reader. Instead of calling png_read_info(), png_read_rows(), and
@ -1892,6 +2056,8 @@ Much of this is very similar to reading. However, everything of
importance is repeated here, so you won't have to constantly look
back up in the reading section to understand writing.
.SS Setup
You will want to do the I/O initialization before you get into libpng,
so if it doesn't work, you don't have anything to undo. If you are not
using the standard I/O functions, you will need to replace them with
@ -1954,6 +2120,10 @@ section below for more information on the libpng error handling.
...
return;
If you would rather avoid the complexity of setjmp/longjmp issues,
you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
errors will result in a call to PNG_ABORT() which defaults to abort().
Now you need to set up the output code. The default for libpng is to
use the C function fwrite(). If you use this, you will need to pass a
valid FILE * in the function png_init_io(). Be sure that the file is
@ -1963,6 +2133,8 @@ Libpng section below.
png_init_io(png_ptr, fp);
.SS Write callbacks
At this point, you can set up a callback function that will be
called after each row has been written, which you can use to control
a progress meter or the like. It's demonstrated in pngtest.c.
@ -2017,6 +2189,8 @@ data. See the Compression Library for details on the compression levels.
png_set_compression_window_bits(png_ptr, 15);
png_set_compression_method(png_ptr, 8);
.SS Setting the contents of info for output
You now need to fill in the png_info structure with all the data you
wish to write before the actual image. Note that the only thing you
are allowed to write after the image is the text chunks and the time
@ -2146,15 +2320,22 @@ Some of the more important parts of the png_info are:
png_set_text(png_ptr, info_ptr, text_ptr, num_text);
text_ptr - array of png_text holding image
comments
text_ptr[i]->lang - language of comment (NULL for unknown).
text_ptr[i]->compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
PNG_ITXT_COMPRESSION_NONE
PNG_ITXT_COMPRESSION_zTXt
text_ptr[i]->key - keyword for comment.
text_ptr[i]->translated_keyword - keyword in UTF-8 (NULL for unknown).
text_ptr[i]->text - text comments for current
keyword.
text_ptr[i]->compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE or
PNG_TEXT_COMPRESSION_zTXt
num_text - number of comments in text_ptr
text_ptr[i]->text_length - length of text string,
after decompression, 0 for iTXt
text_ptr[i]->itxt_length - length of itxt string,
after decompression, 0 for tEXt/zTXt
text_ptr[i]->lang - language of comment (NULL for unknown).
text_ptr[i]->translated_keyword - keyword in UTF-8 (NULL
for unknown).
num_text - number of comments
png_set_spalettes(png_ptr, info_ptr, &palette_ptr, num_spalettes);
palette_ptr - array of png_spalette structures to be added to
@ -2189,20 +2370,15 @@ Some of the more important parts of the png_info are:
unknowns[i].name - name of unknown chunk
unknowns[i].data - data of unknown chunk
unknowns[i].size - size of unknown chunk
In PNG files, the alpha channel in an image is the level of opacity.
If your data is supplied as a level of transparency, you can invert the
alpha channel before you write it, so that 0 is fully transparent and 255
(in 8-bit or paletted images) or 65535 (in 16-bit images) is fully opaque,
with
png_set_invert_alpha(png_ptr);
This must appear here instead of later with the other transformations
because in the case of paletted images the tRNS chunk data has to
be inverted before the tRNS chunk is written. If your image is not a
paletted image, the tRNS data (which in such cases represents a single
color to be rendered as transparent) won't be changed.
unknowns[i].location - position to write chunk in file
0: do not write chunk
PNG_HAVE_IHDR: before PLTE
PNG_HAVE_PLTE: before IDAT
PNG_AFTER_IDAT: after IDAT
The "location" member is set automatically according to
what part of the output file has already been written.
You can change its value after calling png_set_unknown_chunks()
as demonstrated in pngtest.c.
A quick word about text and num_text. text is an array of png_text
structures. num_text is the number of valid structures in the array.
@ -2284,6 +2460,8 @@ by the software. To facilitate the use of RFC 1123 dates, a function
png_convert_to_rfc1123(png_timep) is provided to convert from PNG
time to an RFC 1123 format string.
.SS Writing unknown chunks
You can use the png_set_unknown_chunks function to queue up chunks
for writing. You give it a chunk name, raw data, and a size; that's
all there is to it. The chunks will be written by the next following
@ -2292,11 +2470,63 @@ Any chunks previously read into the info structure's unknown-chunk
list will also be written out in a sequence that satisfies the PNG
specification's ordering rules.
You are now ready to write all the file information up to the actual
image data. You do this with a call to png_write_info().
.SS The high-level write interface
At this point there are two ways to proceed; through the high-level
write interface, or through a sequence of low-level write operations.
You can use the high-level interface if your image data is present
on the rowpointers member of the info structure. All defined output
transformations are pernmitted, enabled by the following masks.
PNG_TRANSFORM_IDENTITY No transformation
PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
PNG_TRANSFORM_PACKSWAP Change order of packed pixels to LSB first
PNG_TRANSFORM_INVERT_MONO Invert monochrome images
PNG_TRANSFORM_SHIFT Normalize pixels to the sBIT depth
PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA to BGRA
PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA to AG
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity to transparency
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
PNG_TRANSFORM_STRIP_FILLER Strip out filler bytes.
If you have valid image data on the rowpointers member, simply do this:
png_write_png(png_ptr, info_ptr, png_transforms, NULL)
where png_transforms is an integer containing the logical-or of some set of
transformation flags. This call is equivalent to png_write_info(),
followed by the set of transformations indicated by the transform
mask, followed by followed by a write of the image bytes to the info
member `rowpointers', followed by png_write_end().
(The final parameter of this call is not yet used. Someday it
may point to output transformation parameters.)
.SS The low-level write interface
If you are going the low-level route instead, you are now ready to
write all the file information up to the actual image data. You do
this with a call to png_write_info().
png_write_info(png_ptr, info_ptr);
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
level of opacity. If your data is supplied as a level of
transparency, you can invert the alpha channel before you write it, so
that 0 is fully transparent and 255 (in 8-bit or paletted images) or
65535 (in 16-bit images) is fully opaque, with
png_set_invert_alpha(png_ptr);
This must appear before png_write_info() instead of later with the
other transformations because in the case of paletted images the tRNS
chunk data has to be inverted before the tRNS chunk is written. If
your image is not a paletted image, the tRNS data (which in such cases
represents a single color to be rendered as transparent) won't need to
be changed, and you can safely do this transformation after your
png_write_info() call.
If you need to write a private chunk that you want to appear before
the PLTE chunk when PLTE is present, you can write the PNG info in
two steps, and insert code to write your own chunk between them:
@ -2437,6 +2667,8 @@ may be acceptable for real-time applications). Infrequent flushing will
only degrade the compression performance by a few percent over images
that do not use flushing.
.SS Writing the image data
That's it for the transformations. Now you can write the image data.
The simplest way to do this is in one function call. If have the
whole image in memory, you can just call png_write_image() and libpng
@ -2470,7 +2702,7 @@ row_pointers:
png_write_row(png_ptr, &row_pointer);
When the file is interlaced, things can get a good deal more
complicated. The only currently (as of August 1999 -- PNG Specification
complicated. The only currently (as of January 2000 -- PNG Specification
version 1.2, dated July 1999) defined interlacing scheme for PNG files
is the "Adam7" interlace scheme, that breaks down an
image into seven smaller images of varying size. libpng will build
@ -2500,6 +2732,8 @@ As some of these rows are not used, and thus return immediately,
you may want to read about interlacing in the PNG specification,
and only update the rows that are actually used.
.SS Finishing a sequential write
After you are finished writing the image, you should finish writing
the file. If you are interested in writing comments or time, you should
pass an appropriately filled png_info pointer. If you are not interested,
@ -2517,16 +2751,20 @@ point to allocated storage with the following functions:
png_free_text(png_ptr, info_ptr, num)
num - number of text item to be freed (-1 for all items)
png_free_hIST(png_ptr, info_ptr)
png_free_iCCP(png_ptr, info_ptr)
png_free_pCAL(png_ptr, info_ptr)
png_free_sCAL(png_ptr, info_ptr)
png_free_spalette(png_ptr, info_ptr, num)
png_free_spalettes(png_ptr, info_ptr, num)
num - number of suggested-paletted entry to be freed
(-1 for all suggested palettes)
png_free_pixels(png_ptr, info_ptr)
png_free_unknown_chunk(png_ptr, info_ptr, num)
num - number of unknown chunk entry to be freed
(-1 for all suggested palettes)
@ -2535,8 +2773,7 @@ These functions may be safely called when the relevant storage has
already been freed, or has not yet been allocated, and will in that
case do nothing.
You must free any data you allocated for info_ptr, such as comments,
palette, or histogram, before the call to png_destroy_write_struct();
If you allocated palette data, you must free it before the call to png_destroy_write_struct();
For a more compact example of writing a PNG image, see the file example.c.
@ -2596,8 +2833,11 @@ a write stream, and vice versa.
Error handling in libpng is done through png_error() and png_warning().
Errors handled through png_error() are fatal, meaning that png_error()
should never return to its caller. Currently, this is handled via
setjmp() and longjmp(), but you could change this to do things like
exit() if you should wish. On non-fatal errors, png_warning() is called
setjmp() and longjmp() (unless you have compiled libpng with
PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
but you could change this to do things like exit() if you should wish.
On non-fatal errors, png_warning() is called
to print a warning message, and then control returns to the calling code.
By default png_error() and png_warning() print a message on stderr via
fprintf() unless the library is compiled with PNG_NO_STDIO defined. If
@ -2630,16 +2870,25 @@ after a longjmp, so the user may want to be careful about doing anything after
setjmp returns non-zero besides returning itself. Consult your compiler
documentation for more details.
If you need to read or write custom chunks, you will need to get deeper
into the libpng code, as a mechanism has not yet been supplied for user
callbacks with custom chunks. First, read the PNG specification, and have
a first level of understanding of how it works. Pay particular attention
to the sections that describe chunk names, and look at how other chunks
were designed, so you can do things similarly. Second, check out the
sections of libpng that read and write chunks. Try to find a chunk that
is similar to yours and use it as a template. More details can be found in the
comments inside the code. A way of handling unknown chunks in a generic
method, potentially via callback functions, would be best.
.SS Custom chunks
If you need to read or write custom chunks, you may need to get deeper
into the libpng code. The library now has mechanisms for storing
and writing chunks of unknown type; you can even declare callbacks
for custom chunks. Hoewver, this may not be good enough if the
library code itself needs to know about interactions between your
chunk and existing `intrinsic' chunks.
If you need to write a new intrinsic chunk, first read the PNG
specification. Acquire a first level of
understanding of how it works. Pay particular attention to the
sections that describe chunk names, and look at how other chunks were
designed, so you can do things similarly. Second, check out the
sections of libpng that read and write chunks. Try to find a chunk
that is similar to yours and use it as a template. More details can
be found in the comments inside the code. It is best to handle unknown
chunks in a generic method, via callback functions, instead of by
modifying libpng functions.
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
@ -2647,7 +2896,7 @@ the simpler ones to get an idea of how they work. Try to find a similar
transformation to the one you want to add and copy off of it. More details
can be found in the comments inside the code itself.
Configuring for 16 bit platforms:
.SS Configuring for 16 bit platforms
You may need to change the png_large_malloc() and png_large_free()
routines in pngmem.c, as these are required to allocate 64K, although
@ -2656,13 +2905,13 @@ you will want to look into zconf.h to tell zlib (and thus libpng) that
it cannot allocate more then 64K at a time. Even if you can, the memory
won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
Configuring for DOS:
.SS Configuring for DOS
For DOS users who only have access to the lower 640K, you will
have to limit zlib's memory usage via a png_set_compression_mem_level()
call. See zlib.h or zconf.h in the zlib library for more information.
Configuring for Medium Model:
.SS Configuring for Medium Model
Libpng's support for medium model has been tested on most of the popular
compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
@ -2670,10 +2919,10 @@ 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 row's of data are defined as png_bytepp, which is an
note that the rows of data are defined as png_bytepp, which is an
unsigned char far * far *.
Configuring for gui/windowing platforms:
.SS Configuring for gui/windowing platforms:
You will need to write new error and warning functions that use the GUI
interface, as described previously, and set them to be the error and
@ -2682,7 +2931,7 @@ in order to have them available during the structure initialization.
They can be changed later via png_set_error_fn(). On some compilers,
you may also have to change the memory allocators (png_malloc, etc.).
Configuring for compiler xxx:
.SS Configuring for compiler xxx:
All includes for libpng are in pngconf.h. If you need to add/change/delete
an include, this is the place to do it. The includes that are not
@ -2690,7 +2939,7 @@ needed outside libpng are protected by the PNG_INTERNAL definition,
which is only defined for those routines inside libpng itself. The
files in libpng proper only include png.h, which includes pngconf.h.
Configuring zlib:
.SS Configuring zlib:
There are special functions to configure the compression. Perhaps the
most useful one changes the compression level, which currently uses
@ -2722,7 +2971,7 @@ zlib.h for more information on what these mean.