From b1955840c58c667de6a95631d1f4b9b0a70202c3 Mon Sep 17 00:00:00 2001 From: cinap_lenrek Date: Wed, 4 May 2011 06:19:09 +0000 Subject: rename ape manpages so they dont get filtered out as object files --- sys/src/ape/cmd/patch/patch.1 | 1064 --------- sys/src/ape/cmd/patch/patch.1.man | 1064 +++++++++ sys/src/ape/cmd/pax/cpio.1 | 271 --- sys/src/ape/cmd/pax/cpio.1.man | 271 +++ sys/src/ape/cmd/pax/pax.1 | 579 ----- sys/src/ape/cmd/pax/pax.1.man | 579 +++++ sys/src/ape/cmd/pax/tar.1 | 195 -- sys/src/ape/cmd/pax/tar.1.man | 195 ++ sys/src/cmd/gs/jpeg/ansi2knr.1 | 36 - sys/src/cmd/gs/jpeg/ansi2knr.1.man | 36 + sys/src/cmd/gs/jpeg/cjpeg.1 | 292 --- sys/src/cmd/gs/jpeg/cjpeg.1.man | 292 +++ sys/src/cmd/gs/jpeg/djpeg.1 | 253 --- sys/src/cmd/gs/jpeg/djpeg.1.man | 253 +++ sys/src/cmd/gs/jpeg/jpegtran.1 | 238 -- sys/src/cmd/gs/jpeg/jpegtran.1.man | 238 ++ sys/src/cmd/gs/jpeg/rdjpgcom.1 | 54 - sys/src/cmd/gs/jpeg/rdjpgcom.1.man | 54 + sys/src/cmd/gs/jpeg/wrjpgcom.1 | 103 - sys/src/cmd/gs/jpeg/wrjpgcom.1.man | 103 + sys/src/cmd/gs/libpng/libpng.3 | 4022 ---------------------------------- sys/src/cmd/gs/libpng/libpng.3.man | 4022 ++++++++++++++++++++++++++++++++++ sys/src/cmd/gs/libpng/libpngpf.3 | 1096 --------- sys/src/cmd/gs/libpng/libpngpf.3.man | 1096 +++++++++ sys/src/cmd/gs/libpng/png.5 | 74 - sys/src/cmd/gs/libpng/png.5.man | 74 + sys/src/cmd/gs/man/dvipdf.1 | 29 - sys/src/cmd/gs/man/dvipdf.1.man | 29 + sys/src/cmd/gs/man/eps2eps.1 | 25 - sys/src/cmd/gs/man/eps2eps.1.man | 25 + sys/src/cmd/gs/man/font2c.1 | 25 - sys/src/cmd/gs/man/font2c.1.man | 25 + sys/src/cmd/gs/man/gs.1 | 404 ---- sys/src/cmd/gs/man/gs.1.man | 404 ++++ sys/src/cmd/gs/man/gslp.1 | 100 - sys/src/cmd/gs/man/gslp.1.man | 100 + sys/src/cmd/gs/man/gsnd.1 | 20 - sys/src/cmd/gs/man/gsnd.1.man | 20 + sys/src/cmd/gs/man/pdf2dsc.1 | 34 - sys/src/cmd/gs/man/pdf2dsc.1.man | 34 + sys/src/cmd/gs/man/pdf2ps.1 | 21 - sys/src/cmd/gs/man/pdf2ps.1.man | 21 + sys/src/cmd/gs/man/pdfopt.1 | 27 - sys/src/cmd/gs/man/pdfopt.1.man | 27 + sys/src/cmd/gs/man/pf2afm.1 | 23 - sys/src/cmd/gs/man/pf2afm.1.man | 23 + sys/src/cmd/gs/man/pfbtopfa.1 | 18 - sys/src/cmd/gs/man/pfbtopfa.1.man | 18 + sys/src/cmd/gs/man/printafm.1 | 19 - sys/src/cmd/gs/man/printafm.1.man | 19 + sys/src/cmd/gs/man/ps2ascii.1 | 31 - sys/src/cmd/gs/man/ps2ascii.1.man | 31 + sys/src/cmd/gs/man/ps2epsi.1 | 66 - sys/src/cmd/gs/man/ps2epsi.1.man | 66 + sys/src/cmd/gs/man/ps2pdf.1 | 53 - sys/src/cmd/gs/man/ps2pdf.1.man | 53 + sys/src/cmd/gs/man/ps2pdfwr.1 | 31 - sys/src/cmd/gs/man/ps2pdfwr.1.man | 31 + sys/src/cmd/gs/man/ps2ps.1 | 33 - sys/src/cmd/gs/man/ps2ps.1.man | 33 + sys/src/cmd/gs/man/wftopfa.1 | 20 - sys/src/cmd/gs/man/wftopfa.1.man | 20 + sys/src/cmd/gs/zlib/zlib.3 | 159 -- sys/src/cmd/gs/zlib/zlib.3.man | 159 ++ 64 files changed, 9415 insertions(+), 9415 deletions(-) delete mode 100644 sys/src/ape/cmd/patch/patch.1 create mode 100644 sys/src/ape/cmd/patch/patch.1.man delete mode 100644 sys/src/ape/cmd/pax/cpio.1 create mode 100644 sys/src/ape/cmd/pax/cpio.1.man delete mode 100644 sys/src/ape/cmd/pax/pax.1 create mode 100644 sys/src/ape/cmd/pax/pax.1.man delete mode 100644 sys/src/ape/cmd/pax/tar.1 create mode 100644 sys/src/ape/cmd/pax/tar.1.man delete mode 100644 sys/src/cmd/gs/jpeg/ansi2knr.1 create mode 100644 sys/src/cmd/gs/jpeg/ansi2knr.1.man delete mode 100644 sys/src/cmd/gs/jpeg/cjpeg.1 create mode 100644 sys/src/cmd/gs/jpeg/cjpeg.1.man delete mode 100644 sys/src/cmd/gs/jpeg/djpeg.1 create mode 100644 sys/src/cmd/gs/jpeg/djpeg.1.man delete mode 100644 sys/src/cmd/gs/jpeg/jpegtran.1 create mode 100644 sys/src/cmd/gs/jpeg/jpegtran.1.man delete mode 100644 sys/src/cmd/gs/jpeg/rdjpgcom.1 create mode 100644 sys/src/cmd/gs/jpeg/rdjpgcom.1.man delete mode 100644 sys/src/cmd/gs/jpeg/wrjpgcom.1 create mode 100644 sys/src/cmd/gs/jpeg/wrjpgcom.1.man delete mode 100644 sys/src/cmd/gs/libpng/libpng.3 create mode 100644 sys/src/cmd/gs/libpng/libpng.3.man delete mode 100644 sys/src/cmd/gs/libpng/libpngpf.3 create mode 100644 sys/src/cmd/gs/libpng/libpngpf.3.man delete mode 100644 sys/src/cmd/gs/libpng/png.5 create mode 100644 sys/src/cmd/gs/libpng/png.5.man delete mode 100644 sys/src/cmd/gs/man/dvipdf.1 create mode 100644 sys/src/cmd/gs/man/dvipdf.1.man delete mode 100644 sys/src/cmd/gs/man/eps2eps.1 create mode 100644 sys/src/cmd/gs/man/eps2eps.1.man delete mode 100644 sys/src/cmd/gs/man/font2c.1 create mode 100644 sys/src/cmd/gs/man/font2c.1.man delete mode 100644 sys/src/cmd/gs/man/gs.1 create mode 100644 sys/src/cmd/gs/man/gs.1.man delete mode 100644 sys/src/cmd/gs/man/gslp.1 create mode 100644 sys/src/cmd/gs/man/gslp.1.man delete mode 100644 sys/src/cmd/gs/man/gsnd.1 create mode 100644 sys/src/cmd/gs/man/gsnd.1.man delete mode 100644 sys/src/cmd/gs/man/pdf2dsc.1 create mode 100644 sys/src/cmd/gs/man/pdf2dsc.1.man delete mode 100644 sys/src/cmd/gs/man/pdf2ps.1 create mode 100644 sys/src/cmd/gs/man/pdf2ps.1.man delete mode 100644 sys/src/cmd/gs/man/pdfopt.1 create mode 100644 sys/src/cmd/gs/man/pdfopt.1.man delete mode 100644 sys/src/cmd/gs/man/pf2afm.1 create mode 100644 sys/src/cmd/gs/man/pf2afm.1.man delete mode 100644 sys/src/cmd/gs/man/pfbtopfa.1 create mode 100644 sys/src/cmd/gs/man/pfbtopfa.1.man delete mode 100644 sys/src/cmd/gs/man/printafm.1 create mode 100644 sys/src/cmd/gs/man/printafm.1.man delete mode 100644 sys/src/cmd/gs/man/ps2ascii.1 create mode 100644 sys/src/cmd/gs/man/ps2ascii.1.man delete mode 100644 sys/src/cmd/gs/man/ps2epsi.1 create mode 100644 sys/src/cmd/gs/man/ps2epsi.1.man delete mode 100644 sys/src/cmd/gs/man/ps2pdf.1 create mode 100644 sys/src/cmd/gs/man/ps2pdf.1.man delete mode 100644 sys/src/cmd/gs/man/ps2pdfwr.1 create mode 100644 sys/src/cmd/gs/man/ps2pdfwr.1.man delete mode 100644 sys/src/cmd/gs/man/ps2ps.1 create mode 100644 sys/src/cmd/gs/man/ps2ps.1.man delete mode 100644 sys/src/cmd/gs/man/wftopfa.1 create mode 100644 sys/src/cmd/gs/man/wftopfa.1.man delete mode 100644 sys/src/cmd/gs/zlib/zlib.3 create mode 100644 sys/src/cmd/gs/zlib/zlib.3.man (limited to 'sys/src') diff --git a/sys/src/ape/cmd/patch/patch.1 b/sys/src/ape/cmd/patch/patch.1 deleted file mode 100644 index e3589bae6..000000000 --- a/sys/src/ape/cmd/patch/patch.1 +++ /dev/null @@ -1,1064 +0,0 @@ -.\" patch man page -.de Id -.ds Dt \\$4 -.. -.Id $Id: patch.man,v 1.23 1997/07/16 12:26:36 eggert Exp $ -.ds = \-\^\- -.de Sp -.if t .sp .3 -.if n .sp -.. -.TH PATCH 1 \*(Dt GNU -.ta 3n -.SH NAME -patch \- apply a diff file to an original -.SH SYNOPSIS -.B patch -.RI [ options ] -.RI [ originalfile -.RI [ patchfile ]] -.Sp -but usually just -.Sp -.BI "patch \-p" "num" -.BI < patchfile -.SH DESCRIPTION -.B patch -takes a patch file -.I patchfile -containing a difference listing produced by the -.B diff -program and applies those differences to one or more original files, -producing patched versions. -Normally the patched versions are put in place of the originals. -Backups can be made; see the -.B \-b -or -.B \*=backup -option. -The names of the files to be patched are usually taken from the patch file, -but if there's just one file to be patched it can specified on the -command line as -.IR originalfile . -.PP -Upon startup, patch attempts to determine the type of the diff listing, -unless overruled by a -\fB\-c\fP (\fB\*=context\fP), -\fB\-e\fP (\fB\*=ed\fP), -\fB\-n\fP (\fB\*=normal\fP), -or -\fB\-u\fP (\fB\*=unified\fP) -option. -Context diffs (old-style, new-style, and unified) and -normal diffs are applied by the -.B patch -program itself, while -.B ed -diffs are simply fed to the -.BR ed (1) -editor via a pipe. -.PP -.B patch -tries to skip any leading garbage, apply the diff, -and then skip any trailing garbage. -Thus you could feed an article or message containing a -diff listing to -.BR patch , -and it should work. -If the entire diff is indented by a consistent amount, -or if a context diff is encapsulated one or more times by prepending -"\fB\- \fP" to lines starting with "\fB\-\fP" as specified by Internet RFC 934, -this is taken into account. -.PP -With context diffs, and to a lesser extent with normal diffs, -.B patch -can detect when the line numbers mentioned in the patch are incorrect, -and attempts to find the correct place to apply each hunk of the patch. -As a first guess, it takes the line number mentioned for the hunk, plus or -minus any offset used in applying the previous hunk. -If that is not the correct place, -.B patch -scans both forwards and backwards for a set of lines matching the context -given in the hunk. -First -.B patch -looks for a place where all lines of the context match. -If no such place is found, and it's a context diff, and the maximum fuzz factor -is set to 1 or more, then another scan takes place ignoring the first and last -line of context. -If that fails, and the maximum fuzz factor is set to 2 or more, -the first two and last two lines of context are ignored, -and another scan is made. -(The default maximum fuzz factor is 2.) -If -.B patch -cannot find a place to install that hunk of the patch, it puts the -hunk out to a reject file, which normally is the name of the output file -plus a -.B \&.rej -suffix, or -.B # -if -.B \&.rej -would generate a file name that is too long -(if even appending the single character -.B # -makes the file name too long, then -.B # -replaces the file name's last character). -(The rejected hunk comes out in ordinary context diff form regardless of -the input patch's form. -If the input was a normal diff, many of the contexts are simply null.) -The line numbers on the hunks in the reject file may be different than -in the patch file: they reflect the approximate location patch thinks the -failed hunks belong in the new file rather than the old one. -.PP -As each hunk is completed, you are told if the hunk -failed, and if so which line (in the new file) -.B patch -thought the hunk should go on. -If the hunk is installed at a different line -from the line number specified in the diff you -are told the offset. -A single large offset -.I may -indicate that a hunk was installed in the -wrong place. -You are also told if a fuzz factor was used to make the match, in which -case you should also be slightly suspicious. -If the -.B \*=verbose -option is given, you are also told about hunks that match exactly. -.PP -If no original file -.I origfile -is specified on the command line, -.B patch -tries to figure out from the leading garbage what the name of the file -to edit is, using the following rules. -.TP 3 -.B " \(bu" -If the header is that of a context diff, -.B patch -takes the old and new file names in the header. -Any -.B /dev/null -names are ignored. -.TP -.B " \(bu" -If there is an -.B Index:\& -line in the leading garbage -and if either the old and new names are both absent or the -.B POSIXLY_CORRECT -environment variable is set, -.B patch -takes the name in the -.B Index:\& -line. -.TP -.B " \(bu" -For the purpose of the following rules, -the names are considered to be in the order (old, new, index), -regardless of the order that they appear in the header. -.TP -.B " \(bu" -If some of the named files exist, -.B patch -uses the first name if the -.B POSIXLY_CORRECT -environment variable is set, and the best name otherwise. -.TP -.B " \(bu" -If -.B patch -is not ignoring \s-1RCS\s0 and \s-1SCCS\s0 (see the -.BI "\-g\ " num -or -.BI \*=get= num -option), and no named files exist -but an \s-1RCS\s0 or \s-1SCCS\s0 master is found, -.B patch -uses the first named file with an \s-1RCS\s0 or \s-1SCCS\s0 master. -.TP -.B " \(bu" -If no named files exist, no \s-1RCS\s0 or \s-1SCCS\s0 master was found, -some names are given, -.B POSIXLY_CORRECT -is not set, and the patch appears to create a file, -.B patch -uses the best name requiring the creation of the fewest directories. -.TP -.B " \(bu" -If no file name results from the above heuristics, you are asked -for the name of the file to patch. -.LP -To determine the -.I best -of a nonempty list of file names, -.B patch -first takes all the names with the fewest path name components; -of those, it then takes all the names with the shortest basename; -of those, it then takes all the shortest names; -finally, it takes the first remaining name. -.PP -Additionally, if the leading garbage contains a -.B Prereq:\& -line, -.B patch -takes the first word from the prerequisites line (normally a version -number) and checks the original file to see if that word can be found. -If not, -.B patch -asks for confirmation before proceeding. -.PP -The upshot of all this is that you should be able to say, while in a news -interface, something like the following: -.Sp - \fB| patch \-d /usr/src/local/blurfl\fP -.Sp -and patch a file in the -.B blurfl -directory directly from the article containing -the patch. -.PP -If the patch file contains more than one patch, -.B patch -tries to apply each of them as if they came from separate patch files. -This means, among other things, that it is assumed that the name of the file -to patch must be determined for each diff listing, -and that the garbage before each diff listing -contains interesting things such as file names and revision level, as -mentioned previously. -.SH OPTIONS -.TP 3 -\fB\-b\fP or \fB\*=backup\fP -Make backup files. -That is, when patching a file, -rename or copy the original instead of removing it. -When backing up a file that does not exist, -an empty, unreadable backup file is created -as a placeholder to represent the nonexistent file. -See the -.B \-V -or -.B \*=version\-control -option for details about how backup file names are determined. -.TP -.B \*=backup\-if\-mismatch -Back up a file if the patch does not match the file exactly -and if backups are not otherwise requested. -This is the default unless the -.B POSIXLY_CORRECT -environment variable is set. -.TP -.B \*=no\-backup\-if\-mismatch -Do not back up a file if the patch does not match the file exactly -and if backups are not otherwise requested. -This is the default if the -.B POSIXLY_CORRECT -environment variable is set. -.TP -\fB\-B\fP \fIpref\fP or \fB\*=prefix=\fP\fIpref\fP -Prefix -.I pref -to a file name when generating its simple backup file name. -For example, with -.B "\-B\ /junk/" -the simple backup file name for -.B src/patch/util.c -is -.BR /junk/src/patch/util.c . -.TP -\fB\*=binary\fP -Read and write all files in binary mode, -except for standard output and -.BR /dev/tty . -This option has no effect on \s-1POSIX\s0-compliant systems. -On systems like \s-1DOS\s0 where this option makes a difference, -the patch should be generated by -.BR "diff\ \-a\ \*=binary" . -.TP -\fB\-c\fP or \fB\*=context\fP -Interpret the patch file as a ordinary context diff. -.TP -\fB\-d\fP \fIdir\fP or \fB\*=directory=\fP\fIdir\fP -Change to the directory -.I dir -immediately, before doing -anything else. -.TP -\fB\-D\fP \fIdefine\fP or \fB\*=ifdef=\fP\fIdefine\fP -Use the -.BR #ifdef " .\|.\|. " #endif -construct to mark changes, with -.I define -as the differentiating symbol. -.TP -.B "\*=dry\-run" -Print the results of applying the patches without actually changing any files. -.TP -\fB\-e\fP or \fB\*=ed\fP -Interpret the patch file as an -.B ed -script. -.TP -\fB\-E\fP or \fB\*=remove\-empty\-files\fP -Remove output files that are empty after the patches have been applied. -Normally this option is unnecessary, since -.B patch -can examine the time stamps on the header to determine whether a file -should exist after patching. -However, if the input is not a context diff or if the -.B POSIXLY_CORRECT -environment variable is set, -.B patch -does not remove empty patched files unless this option is given. -When -.B patch -removes a file, it also attempts to remove any empty ancestor directories. -.TP -\fB\-f\fP or \fB\*=force\fP -Assume that the user knows exactly what he or she is doing, and do not -ask any questions. Skip patches whose headers -do not say which file is to be patched; patch files even though they have the -wrong version for the -.B Prereq:\& -line in the patch; and assume that -patches are not reversed even if they look like they are. -This option does not suppress commentary; use -.B \-s -for that. -.TP -\fB\-F\fP \fInum\fP or \fB\*=fuzz=\fP\fInum\fP -Set the maximum fuzz factor. -This option only applies to diffs that have context, and causes -.B patch -to ignore up to that many lines in looking for places to install a hunk. -Note that a larger fuzz factor increases the odds of a faulty patch. -The default fuzz factor is 2, and it may not be set to more than -the number of lines of context in the context diff, ordinarily 3. -.TP -\fB\-g\fP \fInum\fP or \fB\*=get=\fP\fInum\fP -This option controls -.BR patch 's -actions when a file is under \s-1RCS\s0 or \s-1SCCS\s0 control, -and does not exist or is read-only and matches the default version. -If -.I num -is positive, -.B patch -gets (or checks out) the file from the revision control system; if zero, -.B patch -ignores \s-1RCS\s0 and \s-1SCCS\s0 and does not get the file; and if negative, -.B patch -asks the user whether to get the file. -The default value of this option is given by the value of the -.B PATCH_GET -environment variable if it is set; if not, the default value is zero if -.B POSIXLY_CORRECT -is set, negative otherwise. -.TP -.B "\*=help" -Print a summary of options and exit. -.TP -\fB\-i\fP \fIpatchfile\fP or \fB\*=input=\fP\fIpatchfile\fP -Read the patch from -.IR patchfile . -If -.I patchfile -is -.BR \- , -read from standard input, the default. -.TP -\fB\-l\fP or \fB\*=ignore\-whitespace\fP -Match patterns loosely, in case tabs or spaces -have been munged in your files. -Any sequence of one or more blanks in the patch file matches any sequence -in the original file, and sequences of blanks at the ends of lines are ignored. -Normal characters must still match exactly. -Each line of the context must still match a line in the original file. -.TP -\fB\-n\fP or \fB\*=normal\fP -Interpret the patch file as a normal diff. -.TP -\fB\-N\fP or \fB\*=forward\fP -Ignore patches that seem to be reversed or already applied. -See also -.BR \-R . -.TP -\fB\-o\fP \fIoutfile\fP or \fB\*=output=\fP\fIoutfile\fP -Send output to -.I outfile -instead of patching files in place. -.TP -\fB\-p\fP\fInum\fP or \fB\*=strip\fP\fB=\fP\fInum\fP -Strip the smallest prefix containing -.I num -leading slashes from each file name found in the patch file. -A sequence of one or more adjacent slashes is counted as a single slash. -This controls how file names found in the patch file are treated, in case -you keep your files in a different directory than the person who sent -out the patch. -For example, supposing the file name in the patch file was -.Sp - \fB/u/howard/src/blurfl/blurfl.c\fP -.Sp -setting -.B \-p0 -gives the entire file name unmodified, -.B \-p1 -gives -.Sp - \fBu/howard/src/blurfl/blurfl.c\fP -.Sp -without the leading slash, -.B \-p4 -gives -.Sp - \fBblurfl/blurfl.c\fP -.Sp -and not specifying -.B \-p -at all just gives you \fBblurfl.c\fP. -Whatever you end up with is looked for either in the current directory, -or the directory specified by the -.B \-d -option. -.TP -\fB\-r\fP \fIrejectfile\fP or \fB\*=reject\-file=\fP\fIrejectfile\fP -Put rejects into -.I rejectfile -instead of the default -.B \&.rej -file. -.TP -\fB\-R\fP or \fB\*=reverse\fP -Assume that this patch was created with the old and new files swapped. -(Yes, I'm afraid that does happen occasionally, human nature being what it -is.) -.B patch -attempts to swap each hunk around before applying it. -Rejects come out in the swapped format. -The -.B \-R -option does not work with -.B ed -diff scripts because there is too little -information to reconstruct the reverse operation. -.Sp -If the first hunk of a patch fails, -.B patch -reverses the hunk to see if it can be applied that way. -If it can, you are asked if you want to have the -.B \-R -option set. -If it can't, the patch continues to be applied normally. -(Note: this method cannot detect a reversed patch if it is a normal diff -and if the first command is an append (i.e. it should have been a delete) -since appends always succeed, due to the fact that a null context matches -anywhere. -Luckily, most patches add or change lines rather than delete them, so most -reversed normal diffs begin with a delete, which fails, triggering -the heuristic.) -.TP -\fB\-s\fP or \fB\*=silent\fP or \fB\*=quiet\fP -Work silently, unless an error occurs. -.TP -\fB\-t\fP or \fB\*=batch\fP -Suppress questions like -.BR \-f , -but make some different assumptions: -skip patches whose headers do not contain file names (the same as \fB\-f\fP); -skip patches for which the file has the wrong version for the -.B Prereq:\& -line -in the patch; and assume that patches are reversed if they look like -they are. -.TP -\fB\-T\fP or \fB\*=set\-time\fP -Set the modification and access times of patched files from time stamps -given in context diff headers, assuming that the context diff headers -use local time. This option is not recommended, because patches using -local time cannot easily be used by people in other time zones, and -because local time stamps are ambiguous when local clocks move backwards -during daylight-saving time adjustments. Instead of using this option, -generate patches with \s-1UTC\s0 and use the -.B \-Z -or -.B \*=set\-utc -option instead. -.TP -\fB\-u\fP or \fB\*=unified\fP -Interpret the patch file as a unified context diff. -.TP -\fB\-v\fP or \fB\*=version\fP -Print out -.BR patch 's -revision header and patch level, and exit. -.TP -\fB\-V\fP \fImethod\fP or \fB\*=version\-control=\fP\fImethod\fP -Use -.I method -to determine -backup file names. The method can also be given by the -.B PATCH_VERSION_CONTROL -(or, if that's not set, the -.BR VERSION_CONTROL ) -environment variable, which is overridden by this option. -The method does not affect whether backup files are made; -it affects only the names of any backup files that are made. -.Sp -The value of -.I method -is like the \s-1GNU\s0 -Emacs `version-control' variable; -.B patch -also recognizes synonyms that -are more descriptive. The valid values for -.I method -are (unique abbreviations are -accepted): -.RS -.TP 3 -\fBexisting\fP or \fBnil\fP -Make numbered backups of files that already have them, -otherwise simple backups. -This is the default. -.TP -\fBnumbered\fP or \fBt\fP -Make numbered backups. The numbered backup file name for -.I F -is -.IB F .~ N ~ -where -.I N -is the version number. -.TP -\fBsimple\fP or \fBnever\fP -Make simple backups. -The -.B \-B -or -.BR \*=prefix , -.B \-Y -or -.BR \*=basename\-prefix , -and -.B \-z -or -.BR \*=suffix -options specify the simple backup file name. -If none of these options are given, then a simple backup suffix is used; -it is the value of the -.B SIMPLE_BACKUP_SUFFIX -environment variable if set, and is -.B \&.orig -otherwise. -.PP -With numbered or simple backups, -if the backup file name is too long, the backup suffix -.B ~ -is used instead; if even appending -.B ~ -would make the name too long, then -.B ~ -replaces the last character of the file name. -.RE -.TP -\fB\*=verbose\fP -Output extra information about the work being done. -.TP -\fB\-x\fP \fInum\fP or \fB\*=debug=\fP\fInum\fP -Set internal debugging flags of interest only to -.B patch -patchers. -.TP -\fB\-Y\fP \fIpref\fP or \fB\*=basename\-prefix=\fP\fIpref\fP -Prefix -.I pref -to the basename of a file name when generating its simple backup file name. -For example, with -.B "\-Y\ .del/" -the simple backup file name for -.B src/patch/util.c -is -.BR src/patch/.del/util.c . -.TP -\fB\-z\fP \fIsuffix\fP or \fB\*=suffix=\fP\fIsuffix\fP -Use -.I suffix -as the simple backup suffix. -For example, with -.B "\-z\ -" -the simple backup file name for -.B src/patch/util.c -is -.BR src/patch/util.c- . -The backup suffix may also be specified by the -.B SIMPLE_BACKUP_SUFFIX -environment variable, which is overridden by this option. -.TP -\fB\-Z\fP or \fB\*=set\-utc\fP -Set the modification and access times of patched files from time stamps -given in context diff headers, assuming that the context diff headers -use Coordinated Universal Time (\s-1UTC\s0, often known as \s-1GMT\s0). -Also see the -.B \-T -or -.B \*=set\-time -option. -.Sp -The -.B \-Z -or -.B \*=set\-utc -and -.B \-T -or -.B \*=set\-time -options normally refrain from setting a file's time if the file's original time -does not match the time given in the patch header, or if its -contents do not match the patch exactly. However, if the -.B \-f -or -.B \*=force -option is given, the file time is set regardless. -.Sp -Due to the limitations of -.B diff -output format, these options cannot update the times of files whose -contents have not changed. Also, if you use these options, you should remove -(e.g. with -.BR "make\ clean" ) -all files that depend on the patched files, so that later invocations of -.B make -do not get confused by the patched files' times. -.SH ENVIRONMENT -.TP 3 -\fBPATCH_GET\fP -This specifies whether -.B patch -gets missing or read-only files from \s-1RCS\s0 or \s-1SCCS\s0 -by default; see the -.B \-g -or -.B \*=get -option. -.TP -.B POSIXLY_CORRECT -If set, -.B patch -conforms more strictly to the \s-1POSIX\s0 standard: -it takes the first existing file from the list (old, new, index) -when intuiting file names from diff headers, -it does not remove files that are empty after patching, -it does not ask whether to get files from \s-1RCS\s0 or \s-1SCCS\s0, -it requires that all options precede the files in the command line, -and it does not backup files when there is a mismatch. -.TP -.B SIMPLE_BACKUP_SUFFIX -Extension to use for simple backup file names instead of -.BR \&.orig . -.TP -\fBTMPDIR\fP, \fBTMP\fP, \fBTEMP\fP -Directory to put temporary files in; -.B patch -uses the first environment variable in this list that is set. -If none are set, the default is system-dependent; -it is normally -.B /tmp -on Unix hosts. -.TP -\fBVERSION_CONTROL\fP or \fBPATCH_VERSION_CONTROL\fP -Selects version control style; see the -.B \-v -or -.B \*=version\-control -option. -.SH FILES -.TP 3 -.IB $TMPDIR "/p\(**" -temporary files -.TP -.B /dev/tty -controlling terminal; used to get answers to questions asked of the user -.SH "SEE ALSO" -.BR diff (1), -.BR ed (1) -.Sp -Marshall T. Rose and Einar A. Stefferud, -Proposed Standard for Message Encapsulation, -Internet RFC 934 (1985-01). -.SH "NOTES FOR PATCH SENDERS" -There are several things you should bear in mind if you are going to -be sending out patches. -.PP -Create your patch systematically. -A good method is the command -.BI "diff\ \-Naur\ " "old\ new" -where -.I old -and -.I new -identify the old and new directories. -The names -.I old -and -.I new -should not contain any slashes. -The -.B diff -command's headers should have dates -and times in Universal Time using traditional Unix format, -so that patch recipients can use the -.B \-Z -or -.B \*=set\-utc -option. -Here is an example command, using Bourne shell syntax: -.Sp - \fBLC_ALL=C TZ=UTC0 diff \-Naur gcc\-2.7 gcc\-2.8\fP -.PP -Tell your recipients how to apply the patch -by telling them which directory to -.B cd -to, and which -.B patch -options to use. The option string -.B "\-Np1" -is recommended. -Test your procedure by pretending to be a recipient and applying -your patch to a copy of the original files. -.PP -You can save people a lot of grief by keeping a -.B patchlevel.h -file which is patched to increment the patch level -as the first diff in the patch file you send out. -If you put a -.B Prereq:\& -line in with the patch, it won't let them apply -patches out of order without some warning. -.PP -You can create a file by sending out a diff that compares -.B /dev/null -or an empty file dated the Epoch (1970-01-01 00:00:00 \s-1UTC\s0) -to the file you want to create. -This only works if the file you want to create doesn't exist already in -the target directory. -Conversely, you can remove a file by sending out a context diff that compares -the file to be deleted with an empty file dated the Epoch. -The file will be removed unless the -.B POSIXLY_CORRECT -environment variable is set and the -.B \-E -or -.B \*=remove\-empty\-files -option is not given. -An easy way to generate patches that create and remove files -is to use \s-1GNU\s0 -.BR diff 's -.B \-N -or -.B \*=new\-file -option. -.PP -If the recipient is supposed to use the -.BI \-p N -option, do not send output that looks like this: -.Sp -.ft B -.ne 3 - diff \-Naur v2.0.29/prog/README prog/README -.br - \-\^\-\^\- v2.0.29/prog/README Mon Mar 10 15:13:12 1997 -.br - +\^+\^+ prog/README Mon Mar 17 14:58:22 1997 -.ft -.Sp -because the two file names have different numbers of slashes, -and different versions of -.B patch -interpret the file names differently. -To avoid confusion, send output that looks like this instead: -.Sp -.ft B -.ne 3 - diff \-Naur v2.0.29/prog/README v2.0.30/prog/README -.br - \-\^\-\^\- v2.0.29/prog/README Mon Mar 10 15:13:12 1997 -.br - +\^+\^+ v2.0.30/prog/README Mon Mar 17 14:58:22 1997 -.ft -.Sp -.PP -Avoid sending patches that compare backup file names like -.BR README.orig , -since this might confuse -.B patch -into patching a backup file instead of the real file. -Instead, send patches that compare the same base file names -in different directories, e.g.\& -.B old/README -and -.BR new/README . -.PP -Take care not to send out reversed patches, since it makes people wonder -whether they already applied the patch. -.PP -Try not to have your patch modify derived files -(e.g. the file -.B configure -where there is a line -.B "configure: configure.in" -in your makefile), since the recipient should be -able to regenerate the derived files anyway. -If you must send diffs of derived files, -generate the diffs using \s-1UTC\s0, -have the recipients apply the patch with the -.B \-Z -or -.B \*=set\-utc -option, and have them remove any unpatched files that depend on patched files -(e.g. with -.BR "make\ clean" ). -.PP -While you may be able to get away with putting 582 diff listings into -one file, it may be wiser to group related patches into separate files in -case something goes haywire. -.SH DIAGNOSTICS -Diagnostics generally indicate that -.B patch -couldn't parse your patch file. -.PP -If the -.B \*=verbose -option is given, the message -.B Hmm.\|.\|.\& -indicates that there is unprocessed text in -the patch file and that -.B patch -is attempting to intuit whether there is a patch in that text and, if so, -what kind of patch it is. -.PP -.BR patch 's -exit status is -0 if all hunks are applied successfully, -1 if some hunks cannot be applied, -and 2 if there is more serious trouble. -When applying a set of patches in a loop it behooves you to check this -exit status so you don't apply a later patch to a partially patched file. -.SH CAVEATS -Context diffs cannot reliably represent the creation or deletion of -empty files, empty directories, or special files such as symbolic links. -Nor can they represent changes to file metadata like ownership, permissions, -or whether one file is a hard link to another. -If changes like these are also required, separate instructions -(e.g. a shell script) to accomplish them should accompany the patch. -.PP -.B patch -cannot tell if the line numbers are off in an -.B ed -script, and can detect -bad line numbers in a normal diff only when it finds a change or deletion. -A context diff using fuzz factor 3 may have the same problem. -Until a suitable interactive interface is added, you should probably do -a context diff in these cases to see if the changes made sense. -Of course, compiling without errors is a pretty good indication that the patch -worked, but not always. -.PP -.B patch -usually produces the correct results, even when it has to do a lot of -guessing. -However, the results are guaranteed to be correct only when the patch is -applied to exactly the same version of the file that the patch was -generated from. -.SH "COMPATIBILITY ISSUES" -The \s-1POSIX\s0 standard specifies behavior that differs from -.BR patch 's -traditional behavior. -You should be aware of these differences if you must interoperate with -.B patch -versions 2.1 and earlier, which are not \s-1POSIX\s0-compliant. -.TP 3 -.B " \(bu" -In traditional -.BR patch , -the -.B \-p -option's operand was optional, and a bare -.B \-p -was equivalent to -.BR \-p0. -The -.B \-p -option now requires an operand, and -.B "\-p\ 0" -is now equivalent to -.BR \-p0 . -For maximum compatibility, use options like -.B \-p0 -and -.BR \-p1 . -.Sp -Also, -traditional -.B patch -simply counted slashes when stripping path prefixes; -.B patch -now counts pathname components. -That is, a sequence of one or more adjacent slashes -now counts as a single slash. -For maximum portability, avoid sending patches containing -.B // -in file names. -.TP -.B " \(bu" -In traditional -.BR patch , -backups were enabled by default. -This behavior is now enabled with the -.B \-b -or -.B \*=backup -option. -.Sp -Conversely, in \s-1POSIX\s0 -.BR patch , -backups are never made, even when there is a mismatch. -In \s-1GNU\s0 -.BR patch , -this behavior is enabled with the -.B \*=no\-backup\-if\-mismatch -option or by setting the -.B POSIXLY_CORRECT -environment variable. -.Sp -The -.BI \-b "\ suffix" -option -of traditional -.B patch -is equivalent to the -.BI "\-b\ \-z" "\ suffix" -options of \s-1GNU\s0 -.BR patch . -.TP -.B " \(bu" -Traditional -.B patch -used a complicated (and incompletely documented) method -to intuit the name of the file to be patched from the patch header. -This method was not \s-1POSIX\s0-compliant, and had a few gotchas. -Now -.B patch -uses a different, equally complicated (but better documented) method -that is optionally \s-1POSIX\s0-compliant; we hope it has -fewer gotchas. The two methods are compatible if the -file names in the context diff header and the -.B Index:\& -line are all identical after prefix-stripping. -Your patch is normally compatible if each header's file names -all contain the same number of slashes. -.TP -.B " \(bu" -When traditional -.B patch -asked the user a question, it sent the question to standard error -and looked for an answer from -the first file in the following list that was a terminal: -standard error, standard output, -.BR /dev/tty , -and standard input. -Now -.B patch -sends questions to standard output and gets answers from -.BR /dev/tty . -Defaults for some answers have been changed so that -.B patch -never goes into an infinite loop when using default answers. -.TP -.B " \(bu" -Traditional -.B patch -exited with a status value that counted the number of bad hunks, -or with status 1 if there was real trouble. -Now -.B patch -exits with status 1 if some hunks failed, -or with 2 if there was real trouble. -.TP -.B " \(bu" -Limit yourself to the following options when sending instructions -meant to be executed by anyone running \s-1GNU\s0 -.BR patch , -traditional -.BR patch , -or a \s-1POSIX\s0-compliant -.BR patch . -Spaces are significant in the following list, and operands are required. -.Sp -.nf -.in +3 -.ne 11 -.B \-c -.BI \-d " dir" -.BI \-D " define" -.B \-e -.B \-l -.B \-n -.B \-N -.BI \-o " outfile" -.BI \-p num -.B \-R -.BI \-r " rejectfile" -.in -.fi -.SH BUGS -.B patch -could be smarter about partial matches, excessively deviant offsets and -swapped code, but that would take an extra pass. -.PP -If code has been duplicated (for instance with -\fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP), -.B patch -is incapable of patching both versions, and, if it works at all, will likely -patch the wrong one, and tell you that it succeeded to boot. -.PP -If you apply a patch you've already applied, -.B patch -thinks it is a reversed patch, and offers to un-apply the patch. -This could be construed as a feature. -.SH COPYING -Copyright -.if t \(co -1984, 1985, 1986, 1988 Larry Wall. -.br -Copyright -.if t \(co -1997 Free Software Foundation, Inc. -.PP -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. -.PP -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. -.PP -Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be included in -translations approved by the copyright holders instead of in -the original English. -.SH AUTHORS -Larry Wall wrote the original version of -.BR patch . -Paul Eggert removed -.BR patch 's -arbitrary limits; added support for binary files, -setting file times, and deleting files; -and made it conform better to \s-1POSIX\s0. -Other contributors include Wayne Davison, who added unidiff support, -and David MacKenzie, who added configuration and backup support. diff --git a/sys/src/ape/cmd/patch/patch.1.man b/sys/src/ape/cmd/patch/patch.1.man new file mode 100644 index 000000000..e3589bae6 --- /dev/null +++ b/sys/src/ape/cmd/patch/patch.1.man @@ -0,0 +1,1064 @@ +.\" patch man page +.de Id +.ds Dt \\$4 +.. +.Id $Id: patch.man,v 1.23 1997/07/16 12:26:36 eggert Exp $ +.ds = \-\^\- +.de Sp +.if t .sp .3 +.if n .sp +.. +.TH PATCH 1 \*(Dt GNU +.ta 3n +.SH NAME +patch \- apply a diff file to an original +.SH SYNOPSIS +.B patch +.RI [ options ] +.RI [ originalfile +.RI [ patchfile ]] +.Sp +but usually just +.Sp +.BI "patch \-p" "num" +.BI < patchfile +.SH DESCRIPTION +.B patch +takes a patch file +.I patchfile +containing a difference listing produced by the +.B diff +program and applies those differences to one or more original files, +producing patched versions. +Normally the patched versions are put in place of the originals. +Backups can be made; see the +.B \-b +or +.B \*=backup +option. +The names of the files to be patched are usually taken from the patch file, +but if there's just one file to be patched it can specified on the +command line as +.IR originalfile . +.PP +Upon startup, patch attempts to determine the type of the diff listing, +unless overruled by a +\fB\-c\fP (\fB\*=context\fP), +\fB\-e\fP (\fB\*=ed\fP), +\fB\-n\fP (\fB\*=normal\fP), +or +\fB\-u\fP (\fB\*=unified\fP) +option. +Context diffs (old-style, new-style, and unified) and +normal diffs are applied by the +.B patch +program itself, while +.B ed +diffs are simply fed to the +.BR ed (1) +editor via a pipe. +.PP +.B patch +tries to skip any leading garbage, apply the diff, +and then skip any trailing garbage. +Thus you could feed an article or message containing a +diff listing to +.BR patch , +and it should work. +If the entire diff is indented by a consistent amount, +or if a context diff is encapsulated one or more times by prepending +"\fB\- \fP" to lines starting with "\fB\-\fP" as specified by Internet RFC 934, +this is taken into account. +.PP +With context diffs, and to a lesser extent with normal diffs, +.B patch +can detect when the line numbers mentioned in the patch are incorrect, +and attempts to find the correct place to apply each hunk of the patch. +As a first guess, it takes the line number mentioned for the hunk, plus or +minus any offset used in applying the previous hunk. +If that is not the correct place, +.B patch +scans both forwards and backwards for a set of lines matching the context +given in the hunk. +First +.B patch +looks for a place where all lines of the context match. +If no such place is found, and it's a context diff, and the maximum fuzz factor +is set to 1 or more, then another scan takes place ignoring the first and last +line of context. +If that fails, and the maximum fuzz factor is set to 2 or more, +the first two and last two lines of context are ignored, +and another scan is made. +(The default maximum fuzz factor is 2.) +If +.B patch +cannot find a place to install that hunk of the patch, it puts the +hunk out to a reject file, which normally is the name of the output file +plus a +.B \&.rej +suffix, or +.B # +if +.B \&.rej +would generate a file name that is too long +(if even appending the single character +.B # +makes the file name too long, then +.B # +replaces the file name's last character). +(The rejected hunk comes out in ordinary context diff form regardless of +the input patch's form. +If the input was a normal diff, many of the contexts are simply null.) +The line numbers on the hunks in the reject file may be different than +in the patch file: they reflect the approximate location patch thinks the +failed hunks belong in the new file rather than the old one. +.PP +As each hunk is completed, you are told if the hunk +failed, and if so which line (in the new file) +.B patch +thought the hunk should go on. +If the hunk is installed at a different line +from the line number specified in the diff you +are told the offset. +A single large offset +.I may +indicate that a hunk was installed in the +wrong place. +You are also told if a fuzz factor was used to make the match, in which +case you should also be slightly suspicious. +If the +.B \*=verbose +option is given, you are also told about hunks that match exactly. +.PP +If no original file +.I origfile +is specified on the command line, +.B patch +tries to figure out from the leading garbage what the name of the file +to edit is, using the following rules. +.TP 3 +.B " \(bu" +If the header is that of a context diff, +.B patch +takes the old and new file names in the header. +Any +.B /dev/null +names are ignored. +.TP +.B " \(bu" +If there is an +.B Index:\& +line in the leading garbage +and if either the old and new names are both absent or the +.B POSIXLY_CORRECT +environment variable is set, +.B patch +takes the name in the +.B Index:\& +line. +.TP +.B " \(bu" +For the purpose of the following rules, +the names are considered to be in the order (old, new, index), +regardless of the order that they appear in the header. +.TP +.B " \(bu" +If some of the named files exist, +.B patch +uses the first name if the +.B POSIXLY_CORRECT +environment variable is set, and the best name otherwise. +.TP +.B " \(bu" +If +.B patch +is not ignoring \s-1RCS\s0 and \s-1SCCS\s0 (see the +.BI "\-g\ " num +or +.BI \*=get= num +option), and no named files exist +but an \s-1RCS\s0 or \s-1SCCS\s0 master is found, +.B patch +uses the first named file with an \s-1RCS\s0 or \s-1SCCS\s0 master. +.TP +.B " \(bu" +If no named files exist, no \s-1RCS\s0 or \s-1SCCS\s0 master was found, +some names are given, +.B POSIXLY_CORRECT +is not set, and the patch appears to create a file, +.B patch +uses the best name requiring the creation of the fewest directories. +.TP +.B " \(bu" +If no file name results from the above heuristics, you are asked +for the name of the file to patch. +.LP +To determine the +.I best +of a nonempty list of file names, +.B patch +first takes all the names with the fewest path name components; +of those, it then takes all the names with the shortest basename; +of those, it then takes all the shortest names; +finally, it takes the first remaining name. +.PP +Additionally, if the leading garbage contains a +.B Prereq:\& +line, +.B patch +takes the first word from the prerequisites line (normally a version +number) and checks the original file to see if that word can be found. +If not, +.B patch +asks for confirmation before proceeding. +.PP +The upshot of all this is that you should be able to say, while in a news +interface, something like the following: +.Sp + \fB| patch \-d /usr/src/local/blurfl\fP +.Sp +and patch a file in the +.B blurfl +directory directly from the article containing +the patch. +.PP +If the patch file contains more than one patch, +.B patch +tries to apply each of them as if they came from separate patch files. +This means, among other things, that it is assumed that the name of the file +to patch must be determined for each diff listing, +and that the garbage before each diff listing +contains interesting things such as file names and revision level, as +mentioned previously. +.SH OPTIONS +.TP 3 +\fB\-b\fP or \fB\*=backup\fP +Make backup files. +That is, when patching a file, +rename or copy the original instead of removing it. +When backing up a file that does not exist, +an empty, unreadable backup file is created +as a placeholder to represent the nonexistent file. +See the +.B \-V +or +.B \*=version\-control +option for details about how backup file names are determined. +.TP +.B \*=backup\-if\-mismatch +Back up a file if the patch does not match the file exactly +and if backups are not otherwise requested. +This is the default unless the +.B POSIXLY_CORRECT +environment variable is set. +.TP +.B \*=no\-backup\-if\-mismatch +Do not back up a file if the patch does not match the file exactly +and if backups are not otherwise requested. +This is the default if the +.B POSIXLY_CORRECT +environment variable is set. +.TP +\fB\-B\fP \fIpref\fP or \fB\*=prefix=\fP\fIpref\fP +Prefix +.I pref +to a file name when generating its simple backup file name. +For example, with +.B "\-B\ /junk/" +the simple backup file name for +.B src/patch/util.c +is +.BR /junk/src/patch/util.c . +.TP +\fB\*=binary\fP +Read and write all files in binary mode, +except for standard output and +.BR /dev/tty . +This option has no effect on \s-1POSIX\s0-compliant systems. +On systems like \s-1DOS\s0 where this option makes a difference, +the patch should be generated by +.BR "diff\ \-a\ \*=binary" . +.TP +\fB\-c\fP or \fB\*=context\fP +Interpret the patch file as a ordinary context diff. +.TP +\fB\-d\fP \fIdir\fP or \fB\*=directory=\fP\fIdir\fP +Change to the directory +.I dir +immediately, before doing +anything else. +.TP +\fB\-D\fP \fIdefine\fP or \fB\*=ifdef=\fP\fIdefine\fP +Use the +.BR #ifdef " .\|.\|. " #endif +construct to mark changes, with +.I define +as the differentiating symbol. +.TP +.B "\*=dry\-run" +Print the results of applying the patches without actually changing any files. +.TP +\fB\-e\fP or \fB\*=ed\fP +Interpret the patch file as an +.B ed +script. +.TP +\fB\-E\fP or \fB\*=remove\-empty\-files\fP +Remove output files that are empty after the patches have been applied. +Normally this option is unnecessary, since +.B patch +can examine the time stamps on the header to determine whether a file +should exist after patching. +However, if the input is not a context diff or if the +.B POSIXLY_CORRECT +environment variable is set, +.B patch +does not remove empty patched files unless this option is given. +When +.B patch +removes a file, it also attempts to remove any empty ancestor directories. +.TP +\fB\-f\fP or \fB\*=force\fP +Assume that the user knows exactly what he or she is doing, and do not +ask any questions. Skip patches whose headers +do not say which file is to be patched; patch files even though they have the +wrong version for the +.B Prereq:\& +line in the patch; and assume that +patches are not reversed even if they look like they are. +This option does not suppress commentary; use +.B \-s +for that. +.TP +\fB\-F\fP \fInum\fP or \fB\*=fuzz=\fP\fInum\fP +Set the maximum fuzz factor. +This option only applies to diffs that have context, and causes +.B patch +to ignore up to that many lines in looking for places to install a hunk. +Note that a larger fuzz factor increases the odds of a faulty patch. +The default fuzz factor is 2, and it may not be set to more than +the number of lines of context in the context diff, ordinarily 3. +.TP +\fB\-g\fP \fInum\fP or \fB\*=get=\fP\fInum\fP +This option controls +.BR patch 's +actions when a file is under \s-1RCS\s0 or \s-1SCCS\s0 control, +and does not exist or is read-only and matches the default version. +If +.I num +is positive, +.B patch +gets (or checks out) the file from the revision control system; if zero, +.B patch +ignores \s-1RCS\s0 and \s-1SCCS\s0 and does not get the file; and if negative, +.B patch +asks the user whether to get the file. +The default value of this option is given by the value of the +.B PATCH_GET +environment variable if it is set; if not, the default value is zero if +.B POSIXLY_CORRECT +is set, negative otherwise. +.TP +.B "\*=help" +Print a summary of options and exit. +.TP +\fB\-i\fP \fIpatchfile\fP or \fB\*=input=\fP\fIpatchfile\fP +Read the patch from +.IR patchfile . +If +.I patchfile +is +.BR \- , +read from standard input, the default. +.TP +\fB\-l\fP or \fB\*=ignore\-whitespace\fP +Match patterns loosely, in case tabs or spaces +have been munged in your files. +Any sequence of one or more blanks in the patch file matches any sequence +in the original file, and sequences of blanks at the ends of lines are ignored. +Normal characters must still match exactly. +Each line of the context must still match a line in the original file. +.TP +\fB\-n\fP or \fB\*=normal\fP +Interpret the patch file as a normal diff. +.TP +\fB\-N\fP or \fB\*=forward\fP +Ignore patches that seem to be reversed or already applied. +See also +.BR \-R . +.TP +\fB\-o\fP \fIoutfile\fP or \fB\*=output=\fP\fIoutfile\fP +Send output to +.I outfile +instead of patching files in place. +.TP +\fB\-p\fP\fInum\fP or \fB\*=strip\fP\fB=\fP\fInum\fP +Strip the smallest prefix containing +.I num +leading slashes from each file name found in the patch file. +A sequence of one or more adjacent slashes is counted as a single slash. +This controls how file names found in the patch file are treated, in case +you keep your files in a different directory than the person who sent +out the patch. +For example, supposing the file name in the patch file was +.Sp + \fB/u/howard/src/blurfl/blurfl.c\fP +.Sp +setting +.B \-p0 +gives the entire file name unmodified, +.B \-p1 +gives +.Sp + \fBu/howard/src/blurfl/blurfl.c\fP +.Sp +without the leading slash, +.B \-p4 +gives +.Sp + \fBblurfl/blurfl.c\fP +.Sp +and not specifying +.B \-p +at all just gives you \fBblurfl.c\fP. +Whatever you end up with is looked for either in the current directory, +or the directory specified by the +.B \-d +option. +.TP +\fB\-r\fP \fIrejectfile\fP or \fB\*=reject\-file=\fP\fIrejectfile\fP +Put rejects into +.I rejectfile +instead of the default +.B \&.rej +file. +.TP +\fB\-R\fP or \fB\*=reverse\fP +Assume that this patch was created with the old and new files swapped. +(Yes, I'm afraid that does happen occasionally, human nature being what it +is.) +.B patch +attempts to swap each hunk around before applying it. +Rejects come out in the swapped format. +The +.B \-R +option does not work with +.B ed +diff scripts because there is too little +information to reconstruct the reverse operation. +.Sp +If the first hunk of a patch fails, +.B patch +reverses the hunk to see if it can be applied that way. +If it can, you are asked if you want to have the +.B \-R +option set. +If it can't, the patch continues to be applied normally. +(Note: this method cannot detect a reversed patch if it is a normal diff +and if the first command is an append (i.e. it should have been a delete) +since appends always succeed, due to the fact that a null context matches +anywhere. +Luckily, most patches add or change lines rather than delete them, so most +reversed normal diffs begin with a delete, which fails, triggering +the heuristic.) +.TP +\fB\-s\fP or \fB\*=silent\fP or \fB\*=quiet\fP +Work silently, unless an error occurs. +.TP +\fB\-t\fP or \fB\*=batch\fP +Suppress questions like +.BR \-f , +but make some different assumptions: +skip patches whose headers do not contain file names (the same as \fB\-f\fP); +skip patches for which the file has the wrong version for the +.B Prereq:\& +line +in the patch; and assume that patches are reversed if they look like +they are. +.TP +\fB\-T\fP or \fB\*=set\-time\fP +Set the modification and access times of patched files from time stamps +given in context diff headers, assuming that the context diff headers +use local time. This option is not recommended, because patches using +local time cannot easily be used by people in other time zones, and +because local time stamps are ambiguous when local clocks move backwards +during daylight-saving time adjustments. Instead of using this option, +generate patches with \s-1UTC\s0 and use the +.B \-Z +or +.B \*=set\-utc +option instead. +.TP +\fB\-u\fP or \fB\*=unified\fP +Interpret the patch file as a unified context diff. +.TP +\fB\-v\fP or \fB\*=version\fP +Print out +.BR patch 's +revision header and patch level, and exit. +.TP +\fB\-V\fP \fImethod\fP or \fB\*=version\-control=\fP\fImethod\fP +Use +.I method +to determine +backup file names. The method can also be given by the +.B PATCH_VERSION_CONTROL +(or, if that's not set, the +.BR VERSION_CONTROL ) +environment variable, which is overridden by this option. +The method does not affect whether backup files are made; +it affects only the names of any backup files that are made. +.Sp +The value of +.I method +is like the \s-1GNU\s0 +Emacs `version-control' variable; +.B patch +also recognizes synonyms that +are more descriptive. The valid values for +.I method +are (unique abbreviations are +accepted): +.RS +.TP 3 +\fBexisting\fP or \fBnil\fP +Make numbered backups of files that already have them, +otherwise simple backups. +This is the default. +.TP +\fBnumbered\fP or \fBt\fP +Make numbered backups. The numbered backup file name for +.I F +is +.IB F .~ N ~ +where +.I N +is the version number. +.TP +\fBsimple\fP or \fBnever\fP +Make simple backups. +The +.B \-B +or +.BR \*=prefix , +.B \-Y +or +.BR \*=basename\-prefix , +and +.B \-z +or +.BR \*=suffix +options specify the simple backup file name. +If none of these options are given, then a simple backup suffix is used; +it is the value of the +.B SIMPLE_BACKUP_SUFFIX +environment variable if set, and is +.B \&.orig +otherwise. +.PP +With numbered or simple backups, +if the backup file name is too long, the backup suffix +.B ~ +is used instead; if even appending +.B ~ +would make the name too long, then +.B ~ +replaces the last character of the file name. +.RE +.TP +\fB\*=verbose\fP +Output extra information about the work being done. +.TP +\fB\-x\fP \fInum\fP or \fB\*=debug=\fP\fInum\fP +Set internal debugging flags of interest only to +.B patch +patchers. +.TP +\fB\-Y\fP \fIpref\fP or \fB\*=basename\-prefix=\fP\fIpref\fP +Prefix +.I pref +to the basename of a file name when generating its simple backup file name. +For example, with +.B "\-Y\ .del/" +the simple backup file name for +.B src/patch/util.c +is +.BR src/patch/.del/util.c . +.TP +\fB\-z\fP \fIsuffix\fP or \fB\*=suffix=\fP\fIsuffix\fP +Use +.I suffix +as the simple backup suffix. +For example, with +.B "\-z\ -" +the simple backup file name for +.B src/patch/util.c +is +.BR src/patch/util.c- . +The backup suffix may also be specified by the +.B SIMPLE_BACKUP_SUFFIX +environment variable, which is overridden by this option. +.TP +\fB\-Z\fP or \fB\*=set\-utc\fP +Set the modification and access times of patched files from time stamps +given in context diff headers, assuming that the context diff headers +use Coordinated Universal Time (\s-1UTC\s0, often known as \s-1GMT\s0). +Also see the +.B \-T +or +.B \*=set\-time +option. +.Sp +The +.B \-Z +or +.B \*=set\-utc +and +.B \-T +or +.B \*=set\-time +options normally refrain from setting a file's time if the file's original time +does not match the time given in the patch header, or if its +contents do not match the patch exactly. However, if the +.B \-f +or +.B \*=force +option is given, the file time is set regardless. +.Sp +Due to the limitations of +.B diff +output format, these options cannot update the times of files whose +contents have not changed. Also, if you use these options, you should remove +(e.g. with +.BR "make\ clean" ) +all files that depend on the patched files, so that later invocations of +.B make +do not get confused by the patched files' times. +.SH ENVIRONMENT +.TP 3 +\fBPATCH_GET\fP +This specifies whether +.B patch +gets missing or read-only files from \s-1RCS\s0 or \s-1SCCS\s0 +by default; see the +.B \-g +or +.B \*=get +option. +.TP +.B POSIXLY_CORRECT +If set, +.B patch +conforms more strictly to the \s-1POSIX\s0 standard: +it takes the first existing file from the list (old, new, index) +when intuiting file names from diff headers, +it does not remove files that are empty after patching, +it does not ask whether to get files from \s-1RCS\s0 or \s-1SCCS\s0, +it requires that all options precede the files in the command line, +and it does not backup files when there is a mismatch. +.TP +.B SIMPLE_BACKUP_SUFFIX +Extension to use for simple backup file names instead of +.BR \&.orig . +.TP +\fBTMPDIR\fP, \fBTMP\fP, \fBTEMP\fP +Directory to put temporary files in; +.B patch +uses the first environment variable in this list that is set. +If none are set, the default is system-dependent; +it is normally +.B /tmp +on Unix hosts. +.TP +\fBVERSION_CONTROL\fP or \fBPATCH_VERSION_CONTROL\fP +Selects version control style; see the +.B \-v +or +.B \*=version\-control +option. +.SH FILES +.TP 3 +.IB $TMPDIR "/p\(**" +temporary files +.TP +.B /dev/tty +controlling terminal; used to get answers to questions asked of the user +.SH "SEE ALSO" +.BR diff (1), +.BR ed (1) +.Sp +Marshall T. Rose and Einar A. Stefferud, +Proposed Standard for Message Encapsulation, +Internet RFC 934 (1985-01). +.SH "NOTES FOR PATCH SENDERS" +There are several things you should bear in mind if you are going to +be sending out patches. +.PP +Create your patch systematically. +A good method is the command +.BI "diff\ \-Naur\ " "old\ new" +where +.I old +and +.I new +identify the old and new directories. +The names +.I old +and +.I new +should not contain any slashes. +The +.B diff +command's headers should have dates +and times in Universal Time using traditional Unix format, +so that patch recipients can use the +.B \-Z +or +.B \*=set\-utc +option. +Here is an example command, using Bourne shell syntax: +.Sp + \fBLC_ALL=C TZ=UTC0 diff \-Naur gcc\-2.7 gcc\-2.8\fP +.PP +Tell your recipients how to apply the patch +by telling them which directory to +.B cd +to, and which +.B patch +options to use. The option string +.B "\-Np1" +is recommended. +Test your procedure by pretending to be a recipient and applying +your patch to a copy of the original files. +.PP +You can save people a lot of grief by keeping a +.B patchlevel.h +file which is patched to increment the patch level +as the first diff in the patch file you send out. +If you put a +.B Prereq:\& +line in with the patch, it won't let them apply +patches out of order without some warning. +.PP +You can create a file by sending out a diff that compares +.B /dev/null +or an empty file dated the Epoch (1970-01-01 00:00:00 \s-1UTC\s0) +to the file you want to create. +This only works if the file you want to create doesn't exist already in +the target directory. +Conversely, you can remove a file by sending out a context diff that compares +the file to be deleted with an empty file dated the Epoch. +The file will be removed unless the +.B POSIXLY_CORRECT +environment variable is set and the +.B \-E +or +.B \*=remove\-empty\-files +option is not given. +An easy way to generate patches that create and remove files +is to use \s-1GNU\s0 +.BR diff 's +.B \-N +or +.B \*=new\-file +option. +.PP +If the recipient is supposed to use the +.BI \-p N +option, do not send output that looks like this: +.Sp +.ft B +.ne 3 + diff \-Naur v2.0.29/prog/README prog/README +.br + \-\^\-\^\- v2.0.29/prog/README Mon Mar 10 15:13:12 1997 +.br + +\^+\^+ prog/README Mon Mar 17 14:58:22 1997 +.ft +.Sp +because the two file names have different numbers of slashes, +and different versions of +.B patch +interpret the file names differently. +To avoid confusion, send output that looks like this instead: +.Sp +.ft B +.ne 3 + diff \-Naur v2.0.29/prog/README v2.0.30/prog/README +.br + \-\^\-\^\- v2.0.29/prog/README Mon Mar 10 15:13:12 1997 +.br + +\^+\^+ v2.0.30/prog/README Mon Mar 17 14:58:22 1997 +.ft +.Sp +.PP +Avoid sending patches that compare backup file names like +.BR README.orig , +since this might confuse +.B patch +into patching a backup file instead of the real file. +Instead, send patches that compare the same base file names +in different directories, e.g.\& +.B old/README +and +.BR new/README . +.PP +Take care not to send out reversed patches, since it makes people wonder +whether they already applied the patch. +.PP +Try not to have your patch modify derived files +(e.g. the file +.B configure +where there is a line +.B "configure: configure.in" +in your makefile), since the recipient should be +able to regenerate the derived files anyway. +If you must send diffs of derived files, +generate the diffs using \s-1UTC\s0, +have the recipients apply the patch with the +.B \-Z +or +.B \*=set\-utc +option, and have them remove any unpatched files that depend on patched files +(e.g. with +.BR "make\ clean" ). +.PP +While you may be able to get away with putting 582 diff listings into +one file, it may be wiser to group related patches into separate files in +case something goes haywire. +.SH DIAGNOSTICS +Diagnostics generally indicate that +.B patch +couldn't parse your patch file. +.PP +If the +.B \*=verbose +option is given, the message +.B Hmm.\|.\|.\& +indicates that there is unprocessed text in +the patch file and that +.B patch +is attempting to intuit whether there is a patch in that text and, if so, +what kind of patch it is. +.PP +.BR patch 's +exit status is +0 if all hunks are applied successfully, +1 if some hunks cannot be applied, +and 2 if there is more serious trouble. +When applying a set of patches in a loop it behooves you to check this +exit status so you don't apply a later patch to a partially patched file. +.SH CAVEATS +Context diffs cannot reliably represent the creation or deletion of +empty files, empty directories, or special files such as symbolic links. +Nor can they represent changes to file metadata like ownership, permissions, +or whether one file is a hard link to another. +If changes like these are also required, separate instructions +(e.g. a shell script) to accomplish them should accompany the patch. +.PP +.B patch +cannot tell if the line numbers are off in an +.B ed +script, and can detect +bad line numbers in a normal diff only when it finds a change or deletion. +A context diff using fuzz factor 3 may have the same problem. +Until a suitable interactive interface is added, you should probably do +a context diff in these cases to see if the changes made sense. +Of course, compiling without errors is a pretty good indication that the patch +worked, but not always. +.PP +.B patch +usually produces the correct results, even when it has to do a lot of +guessing. +However, the results are guaranteed to be correct only when the patch is +applied to exactly the same version of the file that the patch was +generated from. +.SH "COMPATIBILITY ISSUES" +The \s-1POSIX\s0 standard specifies behavior that differs from +.BR patch 's +traditional behavior. +You should be aware of these differences if you must interoperate with +.B patch +versions 2.1 and earlier, which are not \s-1POSIX\s0-compliant. +.TP 3 +.B " \(bu" +In traditional +.BR patch , +the +.B \-p +option's operand was optional, and a bare +.B \-p +was equivalent to +.BR \-p0. +The +.B \-p +option now requires an operand, and +.B "\-p\ 0" +is now equivalent to +.BR \-p0 . +For maximum compatibility, use options like +.B \-p0 +and +.BR \-p1 . +.Sp +Also, +traditional +.B patch +simply counted slashes when stripping path prefixes; +.B patch +now counts pathname components. +That is, a sequence of one or more adjacent slashes +now counts as a single slash. +For maximum portability, avoid sending patches containing +.B // +in file names. +.TP +.B " \(bu" +In traditional +.BR patch , +backups were enabled by default. +This behavior is now enabled with the +.B \-b +or +.B \*=backup +option. +.Sp +Conversely, in \s-1POSIX\s0 +.BR patch , +backups are never made, even when there is a mismatch. +In \s-1GNU\s0 +.BR patch , +this behavior is enabled with the +.B \*=no\-backup\-if\-mismatch +option or by setting the +.B POSIXLY_CORRECT +environment variable. +.Sp +The +.BI \-b "\ suffix" +option +of traditional +.B patch +is equivalent to the +.BI "\-b\ \-z" "\ suffix" +options of \s-1GNU\s0 +.BR patch . +.TP +.B " \(bu" +Traditional +.B patch +used a complicated (and incompletely documented) method +to intuit the name of the file to be patched from the patch header. +This method was not \s-1POSIX\s0-compliant, and had a few gotchas. +Now +.B patch +uses a different, equally complicated (but better documented) method +that is optionally \s-1POSIX\s0-compliant; we hope it has +fewer gotchas. The two methods are compatible if the +file names in the context diff header and the +.B Index:\& +line are all identical after prefix-stripping. +Your patch is normally compatible if each header's file names +all contain the same number of slashes. +.TP +.B " \(bu" +When traditional +.B patch +asked the user a question, it sent the question to standard error +and looked for an answer from +the first file in the following list that was a terminal: +standard error, standard output, +.BR /dev/tty , +and standard input. +Now +.B patch +sends questions to standard output and gets answers from +.BR /dev/tty . +Defaults for some answers have been changed so that +.B patch +never goes into an infinite loop when using default answers. +.TP +.B " \(bu" +Traditional +.B patch +exited with a status value that counted the number of bad hunks, +or with status 1 if there was real trouble. +Now +.B patch +exits with status 1 if some hunks failed, +or with 2 if there was real trouble. +.TP +.B " \(bu" +Limit yourself to the following options when sending instructions +meant to be executed by anyone running \s-1GNU\s0 +.BR patch , +traditional +.BR patch , +or a \s-1POSIX\s0-compliant +.BR patch . +Spaces are significant in the following list, and operands are required. +.Sp +.nf +.in +3 +.ne 11 +.B \-c +.BI \-d " dir" +.BI \-D " define" +.B \-e +.B \-l +.B \-n +.B \-N +.BI \-o " outfile" +.BI \-p num +.B \-R +.BI \-r " rejectfile" +.in +.fi +.SH BUGS +.B patch +could be smarter about partial matches, excessively deviant offsets and +swapped code, but that would take an extra pass. +.PP +If code has been duplicated (for instance with +\fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP), +.B patch +is incapable of patching both versions, and, if it works at all, will likely +patch the wrong one, and tell you that it succeeded to boot. +.PP +If you apply a patch you've already applied, +.B patch +thinks it is a reversed patch, and offers to un-apply the patch. +This could be construed as a feature. +.SH COPYING +Copyright +.if t \(co +1984, 1985, 1986, 1988 Larry Wall. +.br +Copyright +.if t \(co +1997 Free Software Foundation, Inc. +.PP +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. +.PP +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be included in +translations approved by the copyright holders instead of in +the original English. +.SH AUTHORS +Larry Wall wrote the original version of +.BR patch . +Paul Eggert removed +.BR patch 's +arbitrary limits; added support for binary files, +setting file times, and deleting files; +and made it conform better to \s-1POSIX\s0. +Other contributors include Wayne Davison, who added unidiff support, +and David MacKenzie, who added configuration and backup support. diff --git a/sys/src/ape/cmd/pax/cpio.1 b/sys/src/ape/cmd/pax/cpio.1 deleted file mode 100644 index 597682d19..000000000 --- a/sys/src/ape/cmd/pax/cpio.1 +++ /dev/null @@ -1,271 +0,0 @@ -.\" $Id: cpio.1,v 1.2 89/02/12 10:08:42 mark Exp $ -.TH CPIO 1 "USENIX Association" "" -.SH NAME -cpio \- copy file archives in and out -.SH SYNOPSIS -.B cpio -.BR \-o [ Bacv ] -.br -.B cpio -.BR \-i [ Bcdfmrtuv ] -.RI [ pattern... ] -.br -.B cpio -.BR \-p [ adlmruv ] -.I directory -.SH DESCRIPTION -The -.B cpio -utility produces and reads files in the format specified by the -.B cpio -.B "Archive/Interchange File Format" -specified in -.IR "IEEE Std. 1003.1-1988" . -.PP -The -.B "cpio -i" -(copy in) utility extracts files from the standard input, which is -assumed to be the product of a previous -.B "cpio -o" . -Only files with names that match -.I patterns -are selected. -Multiple -.I patterns -may be specified and if no -.I patterns -are specified, the default for -.I patterns -is \*, selecting all files. -The extracted files are conditionally created and copied into the -current directory, and possibly any levels below, based upon the -options described below and the permissions of the files will be those -of the previous -.B "cpio -o" . -The owner and group of the files will be that of the current user -unless the user has appropriate privileges, which causes -.B cpio -to retains the owner and group of the files of the previous -.B "cpio -o" . -.PP -The -.B "cpio -p" -(pass) utility reads the standard input to obtain a list of path names -of files that are conditionally created and copied into the -destination -.I directory -based upon the options described below. -.PP -If an error is detected, the cause is reported and the -.B cpio -utility will continue to copy other files. -.B cpio -will skip over any unrecognized files which it encounters in the archive. -.PP -The following restrictions apply to the -.B cpio -utility: -.IP 1 .25i -Pathnames are restricted to 256 characters. -.IP 2 .25i -Appropriate privileges are required to copy special files. -.IP 3 .25i -Blocks are reported in 512-byte quantities. -.SS Options -The following options are available: -.TP .5i -.B \-B -Input/output is to be blocked 5120 bytes to the record. -Can only be used with -.B "cpio -o" -or -.B "cpio -i" -for data that is directed to or from character special files. -.TP .5i -.B \-a -Reset access times of input files after they have been copied. -When the -.B \-l -option is also specified, the linked files do not have their access -times reset. -Can only be used with -.B "cpio -o" -or -.B "cpio -i" . -.TP .5i -.B \-c -Write header information in ASCII character for for portability. -Can only be used with -.B "cpio -i" -or -.B "cpio -o" . -Note that this option should always be used to write portable files. -.TP .5i -.B \-d -Creates directories as needed. -Can only be used with -.B "cpio -i" -or -.B "cpio -p" . -.TP .5i -.B \-f -Copy in all files except those in -.I patterns . -Can only be used with -.B "cpio -i" . -.TP .5i -.B \-l -Whenever possible, link files rather than copying them. -Can only be used with -.B "cpio -p" . -.TP .5i -.B \-m -Retain previous modification times. -This option is ineffective on directories that are being copied. -Can only be used with -.B "cpio -i" -or -.B "cpio -p" . -.TP .5i -.B \-r -Interactively rename files. -The user is asked whether to rename -.I pattern -each invocation. -Read and write permissions for -.B "/dev/tty" -are required for this option. -If the user types a null line, the file is skipped. -Should only be used with -.B "cpio -i" -or -.B "cpio -o" . -.TP .5i -.B \-t -Print a table of contents of the input. -No files are created. -Can only be used with -.B "cpio -i" . -.TP .5i -.B \-u -Copy files unconditionally; usually an older file will not replace a -new file with the same name. -Can only be used with -.B "cpio -i" -or -.B "cpio -p" . -.TP .5i -.B \-v -Verbose: cause the names of the affected files to be printed. -Can only be used with -.B "cpio -i" . -Provides a detailed listing when used with the -.B \-t -option. -.SS Operands -The following operands are available: -.TP 1i -.I patterns -Simple regular expressions given in the name-generating notation of the -shell. -.TP 1i -.I directory -The destination directory. -.SS "Exit Status" -The -.B cpio -utility exits with one of the following values: -.TP .5i -0 -All input files were copied. -.TP .5i -2 -The utility encountered errors in copying or accessing files or -directories. -An error will be reported for nonexistent files or directories, or -permissions that do not allow the user to access the source or target -files. -.SS -It is important to use the -.B "-depth" -option of the -.B find -utility to generate pathnames for -.B cpio . -This eliminates problems -.B cpio -could have trying to create files under read-only directories. -.PP -The following command: -.RS -ls | cpio -o > ../newfile -.RE -copies out the files listed by the -.B ls -utility and redirects them to the file -.B newfile . -.PP -The following command: -.RS -cat newfile | cpio -id "memo/al" "memo/b*" -.RE -uses the output file -.B newfile -from the -.B "cpio -o" -utility, takes those files that match the patterns -.B "memo/al" -and -.B "memo/b*" , -creates the directories below the current directory, and places the -files in the appropriate directories. -.PP -The command -.RS -find . -depth -print | cpio -pdlmv newdir -.RE -takes the file names piped to it from the -.B find -utility and copies or links those files to another directory -named -.B newdir , -while retaining the modification time. -.SH FILES -.TP 1i -/dev/tty -used to prompt the user for information when the -.B \-i -or -.B \-r -options are specified. -.SH "SEE ALSO" -find(1), pax(1), tar(1), cpio(5), tar(5) -.SH COPYRIGHT -Copyright (c) 1989 Mark H. Colburn. -.br -All rights reserved. -.PP -Redistribution and use in source and binary forms are permitted -provided that the above copyright notice is duplicated in all such -forms and that any documentation, advertising materials, and other -materials related to such distribution and use acknowledge that the -software was developed by Mark H. Colburn and sponsored by The -USENIX Association. -.PP -THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. -.SH AUTHOR -Mark H. Colburn -.br -NAPS International -.br -117 Mackubin Street, Suite 1 -.br -St. Paul, MN 55102 -.br -mark@jhereg.MN.ORG -.sp 2 -Sponsored by -.B "The USENIX Association" -for public distribution. diff --git a/sys/src/ape/cmd/pax/cpio.1.man b/sys/src/ape/cmd/pax/cpio.1.man new file mode 100644 index 000000000..597682d19 --- /dev/null +++ b/sys/src/ape/cmd/pax/cpio.1.man @@ -0,0 +1,271 @@ +.\" $Id: cpio.1,v 1.2 89/02/12 10:08:42 mark Exp $ +.TH CPIO 1 "USENIX Association" "" +.SH NAME +cpio \- copy file archives in and out +.SH SYNOPSIS +.B cpio +.BR \-o [ Bacv ] +.br +.B cpio +.BR \-i [ Bcdfmrtuv ] +.RI [ pattern... ] +.br +.B cpio +.BR \-p [ adlmruv ] +.I directory +.SH DESCRIPTION +The +.B cpio +utility produces and reads files in the format specified by the +.B cpio +.B "Archive/Interchange File Format" +specified in +.IR "IEEE Std. 1003.1-1988" . +.PP +The +.B "cpio -i" +(copy in) utility extracts files from the standard input, which is +assumed to be the product of a previous +.B "cpio -o" . +Only files with names that match +.I patterns +are selected. +Multiple +.I patterns +may be specified and if no +.I patterns +are specified, the default for +.I patterns +is \*, selecting all files. +The extracted files are conditionally created and copied into the +current directory, and possibly any levels below, based upon the +options described below and the permissions of the files will be those +of the previous +.B "cpio -o" . +The owner and group of the files will be that of the current user +unless the user has appropriate privileges, which causes +.B cpio +to retains the owner and group of the files of the previous +.B "cpio -o" . +.PP +The +.B "cpio -p" +(pass) utility reads the standard input to obtain a list of path names +of files that are conditionally created and copied into the +destination +.I directory +based upon the options described below. +.PP +If an error is detected, the cause is reported and the +.B cpio +utility will continue to copy other files. +.B cpio +will skip over any unrecognized files which it encounters in the archive. +.PP +The following restrictions apply to the +.B cpio +utility: +.IP 1 .25i +Pathnames are restricted to 256 characters. +.IP 2 .25i +Appropriate privileges are required to copy special files. +.IP 3 .25i +Blocks are reported in 512-byte quantities. +.SS Options +The following options are available: +.TP .5i +.B \-B +Input/output is to be blocked 5120 bytes to the record. +Can only be used with +.B "cpio -o" +or +.B "cpio -i" +for data that is directed to or from character special files. +.TP .5i +.B \-a +Reset access times of input files after they have been copied. +When the +.B \-l +option is also specified, the linked files do not have their access +times reset. +Can only be used with +.B "cpio -o" +or +.B "cpio -i" . +.TP .5i +.B \-c +Write header information in ASCII character for for portability. +Can only be used with +.B "cpio -i" +or +.B "cpio -o" . +Note that this option should always be used to write portable files. +.TP .5i +.B \-d +Creates directories as needed. +Can only be used with +.B "cpio -i" +or +.B "cpio -p" . +.TP .5i +.B \-f +Copy in all files except those in +.I patterns . +Can only be used with +.B "cpio -i" . +.TP .5i +.B \-l +Whenever possible, link files rather than copying them. +Can only be used with +.B "cpio -p" . +.TP .5i +.B \-m +Retain previous modification times. +This option is ineffective on directories that are being copied. +Can only be used with +.B "cpio -i" +or +.B "cpio -p" . +.TP .5i +.B \-r +Interactively rename files. +The user is asked whether to rename +.I pattern +each invocation. +Read and write permissions for +.B "/dev/tty" +are required for this option. +If the user types a null line, the file is skipped. +Should only be used with +.B "cpio -i" +or +.B "cpio -o" . +.TP .5i +.B \-t +Print a table of contents of the input. +No files are created. +Can only be used with +.B "cpio -i" . +.TP .5i +.B \-u +Copy files unconditionally; usually an older file will not replace a +new file with the same name. +Can only be used with +.B "cpio -i" +or +.B "cpio -p" . +.TP .5i +.B \-v +Verbose: cause the names of the affected files to be printed. +Can only be used with +.B "cpio -i" . +Provides a detailed listing when used with the +.B \-t +option. +.SS Operands +The following operands are available: +.TP 1i +.I patterns +Simple regular expressions given in the name-generating notation of the +shell. +.TP 1i +.I directory +The destination directory. +.SS "Exit Status" +The +.B cpio +utility exits with one of the following values: +.TP .5i +0 +All input files were copied. +.TP .5i +2 +The utility encountered errors in copying or accessing files or +directories. +An error will be reported for nonexistent files or directories, or +permissions that do not allow the user to access the source or target +files. +.SS +It is important to use the +.B "-depth" +option of the +.B find +utility to generate pathnames for +.B cpio . +This eliminates problems +.B cpio +could have trying to create files under read-only directories. +.PP +The following command: +.RS +ls | cpio -o > ../newfile +.RE +copies out the files listed by the +.B ls +utility and redirects them to the file +.B newfile . +.PP +The following command: +.RS +cat newfile | cpio -id "memo/al" "memo/b*" +.RE +uses the output file +.B newfile +from the +.B "cpio -o" +utility, takes those files that match the patterns +.B "memo/al" +and +.B "memo/b*" , +creates the directories below the current directory, and places the +files in the appropriate directories. +.PP +The command +.RS +find . -depth -print | cpio -pdlmv newdir +.RE +takes the file names piped to it from the +.B find +utility and copies or links those files to another directory +named +.B newdir , +while retaining the modification time. +.SH FILES +.TP 1i +/dev/tty +used to prompt the user for information when the +.B \-i +or +.B \-r +options are specified. +.SH "SEE ALSO" +find(1), pax(1), tar(1), cpio(5), tar(5) +.SH COPYRIGHT +Copyright (c) 1989 Mark H. Colburn. +.br +All rights reserved. +.PP +Redistribution and use in source and binary forms are permitted +provided that the above copyright notice is duplicated in all such +forms and that any documentation, advertising materials, and other +materials related to such distribution and use acknowledge that the +software was developed by Mark H. Colburn and sponsored by The +USENIX Association. +.PP +THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.SH AUTHOR +Mark H. Colburn +.br +NAPS International +.br +117 Mackubin Street, Suite 1 +.br +St. Paul, MN 55102 +.br +mark@jhereg.MN.ORG +.sp 2 +Sponsored by +.B "The USENIX Association" +for public distribution. diff --git a/sys/src/ape/cmd/pax/pax.1 b/sys/src/ape/cmd/pax/pax.1 deleted file mode 100644 index be3c8cfd6..000000000 --- a/sys/src/ape/cmd/pax/pax.1 +++ /dev/null @@ -1,579 +0,0 @@ -.\" $Id: pax.1,v 1.2 89/02/12 10:08:47 mark Exp $ -.TH PAX 1 "USENIX Association" "" -.SH NAME -pax \- portable archive exchange -.SH SYNOPSIS -.TP \w'\fBpax\fR\ 'u -.B pax -.RB [ \-cimopuvy ] -.RI "[\fB\-f\fR" " archive" ] -.RI "[\fB\-s\fR" " replstr" ] -.RI "[\fB\-t\fR" " device" ] -.RI [ pattern... ] -.TP \w'\fBpax\ \-r\fR\ 'u -.B "pax\ \-r" -.RB [ \-cimnopuvy ] -.RI "[\fB\-f\fR" " archive" ] -.RI "[\fB\-s\fR" " replstr" ] -.RI "[\fB\-t\fR" " device" ] -.RI [ pattern... ] -.TP \w'\fBpax\ \-w\fR\ 'u -.B "pax\ \-w" -.RB [ \-adimuvy ] -.RI "[\fB\-b\fR" " blocking" ] -.RI "[\fB\-f\fR" " archive" ] -.RI "[\fB\-s\fR" " replstr" ] -.RI "[\fB\-t\fR" " device" ] -.RI "[\fB\-x\fR" " format" ] -.RI [ pathname... ] -.TP \w'\fBpax\ \-rw\fR\ 'u -.B "pax\ \-rw" -.RB [ \-ilmopuvy ] -.RI "[\fB\-s\fR" " replstr" ] -.RI [ pathname... ] -directory -.SH DESCRIPTION -.I Pax -reads and writes archive files which conform to the -.B "Archive/Interchange File Format" -specified in -.IR "IEEE Std. 1003.1-1988" . -.I Pax -can also read, but not write, a number of other file formats -in addition to those specified in the -.B "Archive/Interchange File Format" -description. -Support for these traditional file formats, such as V7 -.I "tar" -and System V binary -.I "cpio" -format archives, -is provided for backward compatibility and to maximize portability. -.PP -.I Pax -will also support traditional -.I cpio -and -System V -.I tar -interfaces if invoked with the name -"cpio" or "tar" respectively. -See the -.I cpio(1) -or -.I tar(1) -manual pages for more details. -.PP -Combinations of the -.B \-r -and -.B \-w -command line arguments specify whether -.I pax -will read, write or list the contents of the specified archive, -or move the specified files to another directory. -.PP -The command line arguments are: -.TP .5i -.B \-w -writes the files and directories specified by -.I pathname -operands to the standard output together with the pathname and status -information prescribed by the archive format used. -A directory -.I pathname -operand refers to the files and (recursively) subdirectories of that -directory. -If no -.I pathname -operands are given, then the standard input is read to get a -list of pathnames to copy, one pathname per line. -In this case, only those pathnames appearing on the standard input are -copied. -.TP .5i -.B \-r -.I Pax -reads an archive file from the standard input. -Only files with names that match any of the -.I pattern -operands are selected for extraction. -The selected files are conditionally created and copied relative to the -current directory tree, subject to the options described below. -By default, the owner and group of selected files will be that of the -invoking process, and the permissions and modification times will be the -sames as those in the archive. -.RS .5i -.PP -The supported archive formats are automatically detected on input. -The default output format is -.IR ustar , -but may be overridden by the -.B \-x -.I format -option described below. -.RE -.TP .5i -.B \-rw -.I Pax -reads the files and directories named in the -.I pathname -operands and copies them to the destination -.IR directory . -A directory -.I pathname -operand refers to the files and (recursively) subdirectories of that -directory. -If no -.I pathname -operands are given, the standard input is read to get a list of pathnames -to copy, one pathname per line. -In this case, only those pathnames appearing on the standard input are -copied. -The directory named by the -.I directory -operand must exist and have the proper permissions before the copy can -occur. -.PP -If neither the -.BR \-r " or " \-w -options are given, then -.I pax -will list the contents of the specified archive. -In this mode, -.I pax -lists normal files one per line, hard link pathnames as -.sp -.RS 1i -.IR pathname " == " linkname -.RE -.sp -and symbolic link pathnames (if supported by the implementation) as -.sp -.RS 1i -.IR pathname " -> " linkname -.RE -.sp -where -.I pathname -is the name of the file being extracted, and -.I linkname -is the name of a file which appeared earlier in the archive. -.PP -If the -.B \-v -option is specified, then -.I pax -list normal pathnames in the same format used by the -.I ls -utility with the -.B \-l -option. -Hard links are shown as -.sp -.RS 1i -.IR "" " == " linkname -.RE -.sp -and symbolic links (if supported) are shown as -.sp -.RS 1i -.IR "" " -> " linkname -.RE -.sp -.PP -.I Pax -is capable of reading and writing archives which span multiple physical -volumes. -Upon detecting an end of medium on an archive which is not yet completed, -.I pax -will prompt the user for the next volume of the archive and will allow the -user to specify the location of the next volume. -.SS Options -The following options are available: -.TP 1i -.B \-a -The files specified by -.I pathname -are appended to the specified archive. -.TP 1i -.BI \-b " blocking" -Block the output at -.I blocking -bytes per write to the archive file. -A -.B k -suffix multiplies -.I blocking -by 1024, a -.B b -suffix multiplies -.I blocking -by 512 and a -.B m -suffix multiplies -.I blocking -by 1048576 (1 megabyte). -For machines with 16-bit int's (VAXen, XENIX-286, etc.), -the maximum buffer size is 32k-1. -If not specified, -.I blocking -is automatically determined on input and is ignored for -.B \-rw. -.TP 1i -.B \-c -Complement the match sense of the -.I pattern -operands. -.TP 1i -.B \-d -Intermediate directories not explicitly listed in the archive are not -created. -This option is ignored unless -the -.B \-r -option is specified. -.TP 1i -.BI \-f " archive" -The -.I archive -option specifies the pathname of the input or output archive, -overriding the default of standard input for -.B \-r -or standard output for -.BR \-w . -.TP 1i -.B \-i -Interactively rename files. -Substitutions specified by -.B \-s -options (described below) -are performed before requesting the new file name from the user. -A file is skipped if an empty line is entered and -.I pax -exits with an exit status of 0 if -.B EOF -is encountered. -.TP 1i -.B \-l -Files are linked rather than copied when possible. -.TP 1i -.B \-m -File modification times are not retained. -.TP 1i -.B \-n -When -.B \-r -is specified, but -.B \-w -is not, the -.I pattern -arguments are treated as ordinary file names. -Only the first occurrence of each of these files in the input archive -is read. -The -.B pax -utility exits with a zero exit status after all files in the list have been -read. -If one or more files in the list is not found, -.B pax -writes a diagnostic to standard error for each of the files and exits with -a non-zero exit status. -the file names are compared before any of the -.BR \-i , -.BR \-s , -or -.B \-y -options are applied. -.TP 1i -.B \-o -Restore file ownership as specified in the archive. -The invoking process must have appropriate privileges to accomplish this. -.TP 1i -.B \-p -Preserve the access time of the input files after they have been copied. -.TP 1i -.BI \-s " replstr" -File names are modified according to the substitution expression using the -syntax of -.I "ed(1)" -as shown: -.sp -.RS 2i --s /\fIold\fR/\fInew\fR/\fB[\fRgp\fB]\fR -.RE -.RS 1i -.PP -Any non null character may be used as a delimiter (a / is used here as an -example). -Multiple -.B \-s -expressions may be specified; the expressions are applied in the order -specified terminating with the first successful substitution. -The optional trailing -.B p -causes successful mappings to be listed on standard error. -The optional trailing -.B g -causes the -.I old -expression to be replaced each time it occurs in the source string. -Files that substitute to an empty string are ignored both on input and -output. -.RE -.TP 1i -.BI \-t " device" -The -.I device -option argument is an implementation-defined identifier that names the input -or output archive device, overriding the default of standard input for -.B \-r -and standard output for -.BR \-w . -.TP 1i -.B \-u -Copy each file only if it is newer than a pre-existing file with the same -name. -This implies -.BR \-a . -.TP 1i -.B \-v -List file names as they are encountered. -Produces a verbose table of contents listing on the standard output when both -.B \-r -and -.B \-w -are omitted, -otherwise the file names are printed to standard error as they are -encountered in the archive. -.TP 1i -.BI \-x " format" -Specifies the output archive -.IR format . -The input format, which must be one of the following, is automatically -determined when the -.B \-r -option is used. -The supported formats are: -.RS 1i -.TP 0.75i -.I cpio -The extended -.I CPIO -interchange format specified in -.B "Extended CPIO Format" in -.I "IEEE Std. 1003.1-1988." -.TP 0.75i -.I ustar -The extended -.I TAR -interchange format specified in -.B "Extended TAR Format" in -.I "IEEE Std. 1003.1-1988." -This is the default archive format. -.RE -.TP 1i -.B \-y -Interactively prompt for the disposition of each file. -Substitutions specified by -.B \-s -options (described above) -are performed before prompting the user for disposition. -.B EOF -or an input line starting with the character -.B q -caused -.I pax -to exit. -Otherwise, an input line starting with anything other than -.B y -causes the file to be ignored. -This option cannot be used in conjunction with the -.B \-i -option. -.PP -Only the last of multiple -.B \-f -or -.B \-t -options take effect. -.PP -When writing to an archive, the -standard input is used as a list of pathnames if no -.I pathname -operands are specified. -The format is one pathname per line. -Otherwise, the standard input is the archive file, -which is formatted according to one of the specifications in -.B "Archive/Interchange File format" -in -.IR "IEEE Std. 1003.1-1988" , -or some other implementation-defined format. -.PP -The user ID and group ID of the process, together with the appropriate -privileges, affect the ability of -.I pax -to restore ownership and permissions attributes of the archived files. -(See -.I "format-reading utility" -in -.B "Archive/Interchange File Format" -in -.IR "IEEE Std. 1003.1-1988" ".)" -.PP -The options -.BR \-a , -.BR \-c , -.BR \-d , -.BR \-i , -.BR \-l , -.BR \-p , -.BR \-t , -.BR \-u , -and -.BR \-y -are provided for functional compatibility with the historical -.I cpio -and -.I tar -utilities. -The option defaults were chosen based on the most common usage of these -options, therefore, some of the options have meanings different than -those of the historical commands. -.SS Operands -The following operands are available: -.TP 1i -.I directory -The destination directory pathname for copies when both the -.B \-r -and -.B \-w -options are specified. -The directory must exist and be writable before the copy or and error -results. -.TP 1i -.I pathname -A file whose contents are used instead of the files named on the standard -input. -When a directory is named, all of its files and (recursively) -subdirectories -are copied as well. -.TP 1i -.IR pattern -A -.I pattern -is given in the standard shell pattern matching notation. -The default if no -.I pattern -is specified is -.BR * \, -which selects all files. -.SH EXAMPLES -The following command -.sp -.RS 1i -pax \-w \-f /dev/rmt0 \. -.RE -.sp -copies the contents of the current directory to tape drive 0. -.PP -The commands -.sp -.RS 1i -.RI mkdir " newdir" -.br -.RI cd " olddir" -.br -.RI "pax -rw . " newdir -.RE -.sp -copies the contents of -.I olddir -to -.I newdir . -.PP -The command -.sp -.RS 1i -pax \-r \-s ',//*usr//*,,' -f pax.out -.RE -.sp -reads the archive -.B pax.out -with all files rooted in "/usr" in the archive extracted -relative to the current directory. -.SH FILES -.TP 1i -/dev/tty -used to prompt the user for information when the -.BR \-i " or " \-y -options are specified. -.SH "SEE ALSO" -cpio(1), find(1), tar(1), cpio(5), tar(5) -.SH DIAGNOSTICS -.I Pax -will terminate immediately, without processing any -additional files on the command line or in the archive. -.SH "EXIT CODES" -.I Pax -will exit with one of the following values: -.IP 0 .5i -All files in the archive were processed successfully. -.IP ">0" .5i -.I Pax -aborted due to errors encountered during operation. -.SH BUGS -Special permissions may be required to copy or extract special files. -.PP -Device, user ID, and group ID numbers larger than 65535 cause additional -header records to be output. -These records are ignored by some historical version of -.I "cpio(1)" -and -.IR "tar(1)" . -.PP -The archive formats described in -.B "Archive/Interchange File Format" -have certain restrictions that have -been carried over from historical usage. -For example, there are restrictions on the length of pathnames stored in -the archive. -.PP -When getting an "ls -l" style listing on -.I tar -format archives, link counts are listed as zero since the -.I ustar -archive format does not keep link count information. -.PP -On 16 bit architectures, the largest buffer size is 32k-1. -This is due, in part, to using integers in the buffer allocation schemes, -however, on many of these machines, it is not possible to allocate blocks -of memory larger than 32k. -.SH COPYRIGHT -Copyright (c) 1989 Mark H. Colburn. -.br -All rights reserved. -.PP -Redistribution and use in source and binary forms are permitted -provided that the above copyright notice is duplicated in all such -forms and that any documentation, advertising materials, and other -materials related to such distribution and use acknowledge that the -software was developed by Mark H. Colburn and sponsored by The -USENIX Association. -.PP -THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. -.SH AUTHOR -Mark H. Colburn -.br -Minnetech Consulting, Inc. -.br -117 Mackubin Street, Suite 1 -.br -St. Paul, MN 55102 -.br -mark@jhereg.MN.ORG -.sp 2 -Sponsored by -.B "The USENIX Association" -for public distribution. diff --git a/sys/src/ape/cmd/pax/pax.1.man b/sys/src/ape/cmd/pax/pax.1.man new file mode 100644 index 000000000..be3c8cfd6 --- /dev/null +++ b/sys/src/ape/cmd/pax/pax.1.man @@ -0,0 +1,579 @@ +.\" $Id: pax.1,v 1.2 89/02/12 10:08:47 mark Exp $ +.TH PAX 1 "USENIX Association" "" +.SH NAME +pax \- portable archive exchange +.SH SYNOPSIS +.TP \w'\fBpax\fR\ 'u +.B pax +.RB [ \-cimopuvy ] +.RI "[\fB\-f\fR" " archive" ] +.RI "[\fB\-s\fR" " replstr" ] +.RI "[\fB\-t\fR" " device" ] +.RI [ pattern... ] +.TP \w'\fBpax\ \-r\fR\ 'u +.B "pax\ \-r" +.RB [ \-cimnopuvy ] +.RI "[\fB\-f\fR" " archive" ] +.RI "[\fB\-s\fR" " replstr" ] +.RI "[\fB\-t\fR" " device" ] +.RI [ pattern... ] +.TP \w'\fBpax\ \-w\fR\ 'u +.B "pax\ \-w" +.RB [ \-adimuvy ] +.RI "[\fB\-b\fR" " blocking" ] +.RI "[\fB\-f\fR" " archive" ] +.RI "[\fB\-s\fR" " replstr" ] +.RI "[\fB\-t\fR" " device" ] +.RI "[\fB\-x\fR" " format" ] +.RI [ pathname... ] +.TP \w'\fBpax\ \-rw\fR\ 'u +.B "pax\ \-rw" +.RB [ \-ilmopuvy ] +.RI "[\fB\-s\fR" " replstr" ] +.RI [ pathname... ] +directory +.SH DESCRIPTION +.I Pax +reads and writes archive files which conform to the +.B "Archive/Interchange File Format" +specified in +.IR "IEEE Std. 1003.1-1988" . +.I Pax +can also read, but not write, a number of other file formats +in addition to those specified in the +.B "Archive/Interchange File Format" +description. +Support for these traditional file formats, such as V7 +.I "tar" +and System V binary +.I "cpio" +format archives, +is provided for backward compatibility and to maximize portability. +.PP +.I Pax +will also support traditional +.I cpio +and +System V +.I tar +interfaces if invoked with the name +"cpio" or "tar" respectively. +See the +.I cpio(1) +or +.I tar(1) +manual pages for more details. +.PP +Combinations of the +.B \-r +and +.B \-w +command line arguments specify whether +.I pax +will read, write or list the contents of the specified archive, +or move the specified files to another directory. +.PP +The command line arguments are: +.TP .5i +.B \-w +writes the files and directories specified by +.I pathname +operands to the standard output together with the pathname and status +information prescribed by the archive format used. +A directory +.I pathname +operand refers to the files and (recursively) subdirectories of that +directory. +If no +.I pathname +operands are given, then the standard input is read to get a +list of pathnames to copy, one pathname per line. +In this case, only those pathnames appearing on the standard input are +copied. +.TP .5i +.B \-r +.I Pax +reads an archive file from the standard input. +Only files with names that match any of the +.I pattern +operands are selected for extraction. +The selected files are conditionally created and copied relative to the +current directory tree, subject to the options described below. +By default, the owner and group of selected files will be that of the +invoking process, and the permissions and modification times will be the +sames as those in the archive. +.RS .5i +.PP +The supported archive formats are automatically detected on input. +The default output format is +.IR ustar , +but may be overridden by the +.B \-x +.I format +option described below. +.RE +.TP .5i +.B \-rw +.I Pax +reads the files and directories named in the +.I pathname +operands and copies them to the destination +.IR directory . +A directory +.I pathname +operand refers to the files and (recursively) subdirectories of that +directory. +If no +.I pathname +operands are given, the standard input is read to get a list of pathnames +to copy, one pathname per line. +In this case, only those pathnames appearing on the standard input are +copied. +The directory named by the +.I directory +operand must exist and have the proper permissions before the copy can +occur. +.PP +If neither the +.BR \-r " or " \-w +options are given, then +.I pax +will list the contents of the specified archive. +In this mode, +.I pax +lists normal files one per line, hard link pathnames as +.sp +.RS 1i +.IR pathname " == " linkname +.RE +.sp +and symbolic link pathnames (if supported by the implementation) as +.sp +.RS 1i +.IR pathname " -> " linkname +.RE +.sp +where +.I pathname +is the name of the file being extracted, and +.I linkname +is the name of a file which appeared earlier in the archive. +.PP +If the +.B \-v +option is specified, then +.I pax +list normal pathnames in the same format used by the +.I ls +utility with the +.B \-l +option. +Hard links are shown as +.sp +.RS 1i +.IR "" " == " linkname +.RE +.sp +and symbolic links (if supported) are shown as +.sp +.RS 1i +.IR "" " -> " linkname +.RE +.sp +.PP +.I Pax +is capable of reading and writing archives which span multiple physical +volumes. +Upon detecting an end of medium on an archive which is not yet completed, +.I pax +will prompt the user for the next volume of the archive and will allow the +user to specify the location of the next volume. +.SS Options +The following options are available: +.TP 1i +.B \-a +The files specified by +.I pathname +are appended to the specified archive. +.TP 1i +.BI \-b " blocking" +Block the output at +.I blocking +bytes per write to the archive file. +A +.B k +suffix multiplies +.I blocking +by 1024, a +.B b +suffix multiplies +.I blocking +by 512 and a +.B m +suffix multiplies +.I blocking +by 1048576 (1 megabyte). +For machines with 16-bit int's (VAXen, XENIX-286, etc.), +the maximum buffer size is 32k-1. +If not specified, +.I blocking +is automatically determined on input and is ignored for +.B \-rw. +.TP 1i +.B \-c +Complement the match sense of the +.I pattern +operands. +.TP 1i +.B \-d +Intermediate directories not explicitly listed in the archive are not +created. +This option is ignored unless +the +.B \-r +option is specified. +.TP 1i +.BI \-f " archive" +The +.I archive +option specifies the pathname of the input or output archive, +overriding the default of standard input for +.B \-r +or standard output for +.BR \-w . +.TP 1i +.B \-i +Interactively rename files. +Substitutions specified by +.B \-s +options (described below) +are performed before requesting the new file name from the user. +A file is skipped if an empty line is entered and +.I pax +exits with an exit status of 0 if +.B EOF +is encountered. +.TP 1i +.B \-l +Files are linked rather than copied when possible. +.TP 1i +.B \-m +File modification times are not retained. +.TP 1i +.B \-n +When +.B \-r +is specified, but +.B \-w +is not, the +.I pattern +arguments are treated as ordinary file names. +Only the first occurrence of each of these files in the input archive +is read. +The +.B pax +utility exits with a zero exit status after all files in the list have been +read. +If one or more files in the list is not found, +.B pax +writes a diagnostic to standard error for each of the files and exits with +a non-zero exit status. +the file names are compared before any of the +.BR \-i , +.BR \-s , +or +.B \-y +options are applied. +.TP 1i +.B \-o +Restore file ownership as specified in the archive. +The invoking process must have appropriate privileges to accomplish this. +.TP 1i +.B \-p +Preserve the access time of the input files after they have been copied. +.TP 1i +.BI \-s " replstr" +File names are modified according to the substitution expression using the +syntax of +.I "ed(1)" +as shown: +.sp +.RS 2i +-s /\fIold\fR/\fInew\fR/\fB[\fRgp\fB]\fR +.RE +.RS 1i +.PP +Any non null character may be used as a delimiter (a / is used here as an +example). +Multiple +.B \-s +expressions may be specified; the expressions are applied in the order +specified terminating with the first successful substitution. +The optional trailing +.B p +causes successful mappings to be listed on standard error. +The optional trailing +.B g +causes the +.I old +expression to be replaced each time it occurs in the source string. +Files that substitute to an empty string are ignored both on input and +output. +.RE +.TP 1i +.BI \-t " device" +The +.I device +option argument is an implementation-defined identifier that names the input +or output archive device, overriding the default of standard input for +.B \-r +and standard output for +.BR \-w . +.TP 1i +.B \-u +Copy each file only if it is newer than a pre-existing file with the same +name. +This implies +.BR \-a . +.TP 1i +.B \-v +List file names as they are encountered. +Produces a verbose table of contents listing on the standard output when both +.B \-r +and +.B \-w +are omitted, +otherwise the file names are printed to standard error as they are +encountered in the archive. +.TP 1i +.BI \-x " format" +Specifies the output archive +.IR format . +The input format, which must be one of the following, is automatically +determined when the +.B \-r +option is used. +The supported formats are: +.RS 1i +.TP 0.75i +.I cpio +The extended +.I CPIO +interchange format specified in +.B "Extended CPIO Format" in +.I "IEEE Std. 1003.1-1988." +.TP 0.75i +.I ustar +The extended +.I TAR +interchange format specified in +.B "Extended TAR Format" in +.I "IEEE Std. 1003.1-1988." +This is the default archive format. +.RE +.TP 1i +.B \-y +Interactively prompt for the disposition of each file. +Substitutions specified by +.B \-s +options (described above) +are performed before prompting the user for disposition. +.B EOF +or an input line starting with the character +.B q +caused +.I pax +to exit. +Otherwise, an input line starting with anything other than +.B y +causes the file to be ignored. +This option cannot be used in conjunction with the +.B \-i +option. +.PP +Only the last of multiple +.B \-f +or +.B \-t +options take effect. +.PP +When writing to an archive, the +standard input is used as a list of pathnames if no +.I pathname +operands are specified. +The format is one pathname per line. +Otherwise, the standard input is the archive file, +which is formatted according to one of the specifications in +.B "Archive/Interchange File format" +in +.IR "IEEE Std. 1003.1-1988" , +or some other implementation-defined format. +.PP +The user ID and group ID of the process, together with the appropriate +privileges, affect the ability of +.I pax +to restore ownership and permissions attributes of the archived files. +(See +.I "format-reading utility" +in +.B "Archive/Interchange File Format" +in +.IR "IEEE Std. 1003.1-1988" ".)" +.PP +The options +.BR \-a , +.BR \-c , +.BR \-d , +.BR \-i , +.BR \-l , +.BR \-p , +.BR \-t , +.BR \-u , +and +.BR \-y +are provided for functional compatibility with the historical +.I cpio +and +.I tar +utilities. +The option defaults were chosen based on the most common usage of these +options, therefore, some of the options have meanings different than +those of the historical commands. +.SS Operands +The following operands are available: +.TP 1i +.I directory +The destination directory pathname for copies when both the +.B \-r +and +.B \-w +options are specified. +The directory must exist and be writable before the copy or and error +results. +.TP 1i +.I pathname +A file whose contents are used instead of the files named on the standard +input. +When a directory is named, all of its files and (recursively) +subdirectories +are copied as well. +.TP 1i +.IR pattern +A +.I pattern +is given in the standard shell pattern matching notation. +The default if no +.I pattern +is specified is +.BR * \, +which selects all files. +.SH EXAMPLES +The following command +.sp +.RS 1i +pax \-w \-f /dev/rmt0 \. +.RE +.sp +copies the contents of the current directory to tape drive 0. +.PP +The commands +.sp +.RS 1i +.RI mkdir " newdir" +.br +.RI cd " olddir" +.br +.RI "pax -rw . " newdir +.RE +.sp +copies the contents of +.I olddir +to +.I newdir . +.PP +The command +.sp +.RS 1i +pax \-r \-s ',//*usr//*,,' -f pax.out +.RE +.sp +reads the archive +.B pax.out +with all files rooted in "/usr" in the archive extracted +relative to the current directory. +.SH FILES +.TP 1i +/dev/tty +used to prompt the user for information when the +.BR \-i " or " \-y +options are specified. +.SH "SEE ALSO" +cpio(1), find(1), tar(1), cpio(5), tar(5) +.SH DIAGNOSTICS +.I Pax +will terminate immediately, without processing any +additional files on the command line or in the archive. +.SH "EXIT CODES" +.I Pax +will exit with one of the following values: +.IP 0 .5i +All files in the archive were processed successfully. +.IP ">0" .5i +.I Pax +aborted due to errors encountered during operation. +.SH BUGS +Special permissions may be required to copy or extract special files. +.PP +Device, user ID, and group ID numbers larger than 65535 cause additional +header records to be output. +These records are ignored by some historical version of +.I "cpio(1)" +and +.IR "tar(1)" . +.PP +The archive formats described in +.B "Archive/Interchange File Format" +have certain restrictions that have +been carried over from historical usage. +For example, there are restrictions on the length of pathnames stored in +the archive. +.PP +When getting an "ls -l" style listing on +.I tar +format archives, link counts are listed as zero since the +.I ustar +archive format does not keep link count information. +.PP +On 16 bit architectures, the largest buffer size is 32k-1. +This is due, in part, to using integers in the buffer allocation schemes, +however, on many of these machines, it is not possible to allocate blocks +of memory larger than 32k. +.SH COPYRIGHT +Copyright (c) 1989 Mark H. Colburn. +.br +All rights reserved. +.PP +Redistribution and use in source and binary forms are permitted +provided that the above copyright notice is duplicated in all such +forms and that any documentation, advertising materials, and other +materials related to such distribution and use acknowledge that the +software was developed by Mark H. Colburn and sponsored by The +USENIX Association. +.PP +THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.SH AUTHOR +Mark H. Colburn +.br +Minnetech Consulting, Inc. +.br +117 Mackubin Street, Suite 1 +.br +St. Paul, MN 55102 +.br +mark@jhereg.MN.ORG +.sp 2 +Sponsored by +.B "The USENIX Association" +for public distribution. diff --git a/sys/src/ape/cmd/pax/tar.1 b/sys/src/ape/cmd/pax/tar.1 deleted file mode 100644 index 539f59024..000000000 --- a/sys/src/ape/cmd/pax/tar.1 +++ /dev/null @@ -1,195 +0,0 @@ -.\" $Id: tar.1,v 1.2 89/02/12 10:08:55 mark Exp $ -.TH TAR 1 "USENIX Association" "" -.SH NAME -tar \- process tape archives -.SH SYNOPSIS -.B tar -.BR \-c [ bfvw ] -.I device -.I block -.I filename... -.br -.B tar -.BR \-r [ bvw ] -.I device -.I block -.RI [ filename... ] -.br -.B tar -.BR \-t [ fv ] -.I device -.br -.B tar -.BR \-u [ bvw ] -.I device -.I block -.br -.B tar -.BR \-x [ flmovw ] -.I device -.RI [ filename... ] -.SH DESCRIPTION -.I Tar -reads and writes archive files which conform to the -.B "Archive/Interchange File Format" -specified in -.IR "IEEE Std. 1003.1-1988" . -.SS Options -The following options are available: -.TP 1i -.B \-c -Creates a new archive; writing begins at the beginning of the archive, -instead of after the last file. -.TP 1i -.B \-r -Writes names files to the end of the archive. -.TP 1i -.B \-t -Lists the names of all of the files in the archive. -.TP 1i -.B \-u -Causes named files to be -added to the archive if they are not already there, or have been -modified since last written into the archive. -This implies the -.B \-r -option. -.TP 1i -.B \-x -Extracts named files -from the archive. -If a named file matches a directory whose contents had been written onto -the archive, that directory is recursively extracted. -If a named file in the archive does not exist on the system, the file is -create with the same mode as the one in the archive, except that the -set-user-id and get-group-id modes are not set unless the user has -appropriate privileges. -.PP -If the files exist, their modes are not changed except as described above. -The owner, group and modification time are restored if possible. -If no -.I filename -argument is given, the entire contents of the archive is extracted. -Note that if several files with the same name are in the archive, -the last one will overwrite all earlier ones. -.TP 1i -.B \-b -Causes -.I tar -to use the next argument on the command line as the blocking factor for -tape records. -The default is 1; the maximum is 20. -This option should only be used with raw magnetic tape archives. -Normally, the block size is determined automatically when reading tapes. -.TP 1i -.B \-f -Causes -.I tar -to use the next argument on the command line as the name of the archive -instead of the default, which is usually a tape drive. -If -.B - -is specified as a filename -.I tar -writes to the standard output or reads from the standard input, whichever -is appropriate for the options given. -Thus, -.I tar -can be used as the head or tail of a pipeline. -.TP 1i -.B \-l -Tells -.I tar -to report if it cannot resolve all of the links to the files being -archived. -If -.B \-l -is not specified, no error messages are written to the standard output. -This modifier is only valid with the -.BR \-c , -.B \-r -and -.BR \-u -options. -.TP 1i -.B \-m -Tells -.I tar -not to restore the modification times. -The modification time of the file will be the time of extraction. -This modifier is invalid with th -.B \-t -option. -.TP 1i -.B \-o -Causes extracted files to take on the user and group identifier of the user -running the program rather than those on the archive. -This modifier is only valid with the -.B \-x -option. -.TP 1i -.B \-v -Causes -.I tar -to operate verbosely. Usually, -.I tar -does its work silently, but -the -.B v -modifier causes it to print the name of each file it processes, -preceded by the option letter. -With the -.B \-t -option, -.B v -gives more information about the archive entries than just the name. -.TP 1i -.B \-w -Causes -.I tar -to print the action to be taken, followed by the name of the file, and then -wait for the user's confirmation. -If a word beginning with -.B y -is given, the action is performed. -Any other input means "no". -This modifier is invalid with the -.B \-t -option. -.SH FILES -.TP 1i -/dev/tty -used to prompt the user for information when the -.BR \-i " or " \-y -options are specified. -.SH "SEE ALSO" -cpio(1), dd(1), find(1), pax(1), cpio(5), tar(5) -.SH COPYRIGHT -Copyright (c) 1989 Mark H. Colburn. -.br -All rights reserved. -.PP -Redistribution and use in source and binary forms are permitted -provided that the above copyright notice is duplicated in all such -forms and that any documentation, advertising materials, and other -materials related to such distribution and use acknowledge that the -software was developed by Mark H. Colburn and sponsored by The -USENIX Association. -.PP -THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. -.SH AUTHOR -Mark H. Colburn -.br -NAPS International -.br -117 Mackubin Street, Suite 1 -.br -St. Paul, MN 55102 -.br -mark@jhereg.MN.ORG -.sp 2 -Sponsored by -.B "The USENIX Association" -for public distribution. diff --git a/sys/src/ape/cmd/pax/tar.1.man b/sys/src/ape/cmd/pax/tar.1.man new file mode 100644 index 000000000..539f59024 --- /dev/null +++ b/sys/src/ape/cmd/pax/tar.1.man @@ -0,0 +1,195 @@ +.\" $Id: tar.1,v 1.2 89/02/12 10:08:55 mark Exp $ +.TH TAR 1 "USENIX Association" "" +.SH NAME +tar \- process tape archives +.SH SYNOPSIS +.B tar +.BR \-c [ bfvw ] +.I device +.I block +.I filename... +.br +.B tar +.BR \-r [ bvw ] +.I device +.I block +.RI [ filename... ] +.br +.B tar +.BR \-t [ fv ] +.I device +.br +.B tar +.BR \-u [ bvw ] +.I device +.I block +.br +.B tar +.BR \-x [ flmovw ] +.I device +.RI [ filename... ] +.SH DESCRIPTION +.I Tar +reads and writes archive files which conform to the +.B "Archive/Interchange File Format" +specified in +.IR "IEEE Std. 1003.1-1988" . +.SS Options +The following options are available: +.TP 1i +.B \-c +Creates a new archive; writing begins at the beginning of the archive, +instead of after the last file. +.TP 1i +.B \-r +Writes names files to the end of the archive. +.TP 1i +.B \-t +Lists the names of all of the files in the archive. +.TP 1i +.B \-u +Causes named files to be +added to the archive if they are not already there, or have been +modified since last written into the archive. +This implies the +.B \-r +option. +.TP 1i +.B \-x +Extracts named files +from the archive. +If a named file matches a directory whose contents had been written onto +the archive, that directory is recursively extracted. +If a named file in the archive does not exist on the system, the file is +create with the same mode as the one in the archive, except that the +set-user-id and get-group-id modes are not set unless the user has +appropriate privileges. +.PP +If the files exist, their modes are not changed except as described above. +The owner, group and modification time are restored if possible. +If no +.I filename +argument is given, the entire contents of the archive is extracted. +Note that if several files with the same name are in the archive, +the last one will overwrite all earlier ones. +.TP 1i +.B \-b +Causes +.I tar +to use the next argument on the command line as the blocking factor for +tape records. +The default is 1; the maximum is 20. +This option should only be used with raw magnetic tape archives. +Normally, the block size is determined automatically when reading tapes. +.TP 1i +.B \-f +Causes +.I tar +to use the next argument on the command line as the name of the archive +instead of the default, which is usually a tape drive. +If +.B - +is specified as a filename +.I tar +writes to the standard output or reads from the standard input, whichever +is appropriate for the options given. +Thus, +.I tar +can be used as the head or tail of a pipeline. +.TP 1i +.B \-l +Tells +.I tar +to report if it cannot resolve all of the links to the files being +archived. +If +.B \-l +is not specified, no error messages are written to the standard output. +This modifier is only valid with the +.BR \-c , +.B \-r +and +.BR \-u +options. +.TP 1i +.B \-m +Tells +.I tar +not to restore the modification times. +The modification time of the file will be the time of extraction. +This modifier is invalid with th +.B \-t +option. +.TP 1i +.B \-o +Causes extracted files to take on the user and group identifier of the user +running the program rather than those on the archive. +This modifier is only valid with the +.B \-x +option. +.TP 1i +.B \-v +Causes +.I tar +to operate verbosely. Usually, +.I tar +does its work silently, but +the +.B v +modifier causes it to print the name of each file it processes, +preceded by the option letter. +With the +.B \-t +option, +.B v +gives more information about the archive entries than just the name. +.TP 1i +.B \-w +Causes +.I tar +to print the action to be taken, followed by the name of the file, and then +wait for the user's confirmation. +If a word beginning with +.B y +is given, the action is performed. +Any other input means "no". +This modifier is invalid with the +.B \-t +option. +.SH FILES +.TP 1i +/dev/tty +used to prompt the user for information when the +.BR \-i " or " \-y +options are specified. +.SH "SEE ALSO" +cpio(1), dd(1), find(1), pax(1), cpio(5), tar(5) +.SH COPYRIGHT +Copyright (c) 1989 Mark H. Colburn. +.br +All rights reserved. +.PP +Redistribution and use in source and binary forms are permitted +provided that the above copyright notice is duplicated in all such +forms and that any documentation, advertising materials, and other +materials related to such distribution and use acknowledge that the +software was developed by Mark H. Colburn and sponsored by The +USENIX Association. +.PP +THE SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. +.SH AUTHOR +Mark H. Colburn +.br +NAPS International +.br +117 Mackubin Street, Suite 1 +.br +St. Paul, MN 55102 +.br +mark@jhereg.MN.ORG +.sp 2 +Sponsored by +.B "The USENIX Association" +for public distribution. diff --git a/sys/src/cmd/gs/jpeg/ansi2knr.1 b/sys/src/cmd/gs/jpeg/ansi2knr.1 deleted file mode 100644 index f9ee5a631..000000000 --- a/sys/src/cmd/gs/jpeg/ansi2knr.1 +++ /dev/null @@ -1,36 +0,0 @@ -.TH ANSI2KNR 1 "19 Jan 1996" -.SH NAME -ansi2knr \- convert ANSI C to Kernighan & Ritchie C -.SH SYNOPSIS -.I ansi2knr -[--varargs] input_file [output_file] -.SH DESCRIPTION -If no output_file is supplied, output goes to stdout. -.br -There are no error messages. -.sp -.I ansi2knr -recognizes function definitions by seeing a non-keyword identifier at the left -margin, followed by a left parenthesis, with a right parenthesis as the last -character on the line, and with a left brace as the first token on the -following line (ignoring possible intervening comments). It will recognize a -multi-line header provided that no intervening line ends with a left or right -brace or a semicolon. These algorithms ignore whitespace and comments, except -that the function name must be the first thing on the line. -.sp -The following constructs will confuse it: -.br - - Any other construct that starts at the left margin and follows the -above syntax (such as a macro or function call). -.br - - Some macros that tinker with the syntax of the function header. -.sp -The --varargs switch is obsolete, and is recognized only for -backwards compatibility. The present version of -.I ansi2knr -will always attempt to convert a ... argument to va_alist and va_dcl. -.SH AUTHOR -L. Peter Deutsch wrote the original ansi2knr and -continues to maintain the current version; most of the code in the current -version is his work. ansi2knr also includes contributions by Francois -Pinard and Jim Avera . diff --git a/sys/src/cmd/gs/jpeg/ansi2knr.1.man b/sys/src/cmd/gs/jpeg/ansi2knr.1.man new file mode 100644 index 000000000..f9ee5a631 --- /dev/null +++ b/sys/src/cmd/gs/jpeg/ansi2knr.1.man @@ -0,0 +1,36 @@ +.TH ANSI2KNR 1 "19 Jan 1996" +.SH NAME +ansi2knr \- convert ANSI C to Kernighan & Ritchie C +.SH SYNOPSIS +.I ansi2knr +[--varargs] input_file [output_file] +.SH DESCRIPTION +If no output_file is supplied, output goes to stdout. +.br +There are no error messages. +.sp +.I ansi2knr +recognizes function definitions by seeing a non-keyword identifier at the left +margin, followed by a left parenthesis, with a right parenthesis as the last +character on the line, and with a left brace as the first token on the +following line (ignoring possible intervening comments). It will recognize a +multi-line header provided that no intervening line ends with a left or right +brace or a semicolon. These algorithms ignore whitespace and comments, except +that the function name must be the first thing on the line. +.sp +The following constructs will confuse it: +.br + - Any other construct that starts at the left margin and follows the +above syntax (such as a macro or function call). +.br + - Some macros that tinker with the syntax of the function header. +.sp +The --varargs switch is obsolete, and is recognized only for +backwards compatibility. The present version of +.I ansi2knr +will always attempt to convert a ... argument to va_alist and va_dcl. +.SH AUTHOR +L. Peter Deutsch wrote the original ansi2knr and +continues to maintain the current version; most of the code in the current +version is his work. ansi2knr also includes contributions by Francois +Pinard and Jim Avera . diff --git a/sys/src/cmd/gs/jpeg/cjpeg.1 b/sys/src/cmd/gs/jpeg/cjpeg.1 deleted file mode 100644 index d175a961c..000000000 --- a/sys/src/cmd/gs/jpeg/cjpeg.1 +++ /dev/null @@ -1,292 +0,0 @@ -.TH CJPEG 1 "20 March 1998" -.SH NAME -cjpeg \- compress an image file to a JPEG file -.SH SYNOPSIS -.B cjpeg -[ -.I options -] -[ -.I filename -] -.LP -.SH DESCRIPTION -.LP -.B cjpeg -compresses the named image file, or the standard input if no file is -named, and produces a JPEG/JFIF file on the standard output. -The currently supported input file formats are: PPM (PBMPLUS color -format), PGM (PBMPLUS gray-scale format), BMP, Targa, and RLE (Utah Raster -Toolkit format). (RLE is supported only if the URT library is available.) -.SH OPTIONS -All switch names may be abbreviated; for example, -.B \-grayscale -may be written -.B \-gray -or -.BR \-gr . -Most of the "basic" switches can be abbreviated to as little as one letter. -Upper and lower case are equivalent (thus -.B \-BMP -is the same as -.BR \-bmp ). -British spellings are also accepted (e.g., -.BR \-greyscale ), -though for brevity these are not mentioned below. -.PP -The basic switches are: -.TP -.BI \-quality " N" -Scale quantization tables to adjust image quality. Quality is 0 (worst) to -100 (best); default is 75. (See below for more info.) -.TP -.B \-grayscale -Create monochrome JPEG file from color input. Be sure to use this switch when -compressing a grayscale BMP file, because -.B cjpeg -isn't bright enough to notice whether a BMP file uses only shades of gray. -By saying -.BR \-grayscale , -you'll get a smaller JPEG file that takes less time to process. -.TP -.B \-optimize -Perform optimization of entropy encoding parameters. Without this, default -encoding parameters are used. -.B \-optimize -usually makes the JPEG file a little smaller, but -.B cjpeg -runs somewhat slower and needs much more memory. Image quality and speed of -decompression are unaffected by -.BR \-optimize . -.TP -.B \-progressive -Create progressive JPEG file (see below). -.TP -.B \-targa -Input file is Targa format. Targa files that contain an "identification" -field will not be automatically recognized by -.BR cjpeg ; -for such files you must specify -.B \-targa -to make -.B cjpeg -treat the input as Targa format. -For most Targa files, you won't need this switch. -.PP -The -.B \-quality -switch lets you trade off compressed file size against quality of the -reconstructed image: the higher the quality setting, the larger the JPEG file, -and the closer the output image will be to the original input. Normally you -want to use the lowest quality setting (smallest file) that decompresses into -something visually indistinguishable from the original image. For this -purpose the quality setting should be between 50 and 95; the default of 75 is -often about right. If you see defects at -.B \-quality -75, then go up 5 or 10 counts at a time until you are happy with the output -image. (The optimal setting will vary from one image to another.) -.PP -.B \-quality -100 will generate a quantization table of all 1's, minimizing loss in the -quantization step (but there is still information loss in subsampling, as well -as roundoff error). This setting is mainly of interest for experimental -purposes. Quality values above about 95 are -.B not -recommended for normal use; the compressed file size goes up dramatically for -hardly any gain in output image quality. -.PP -In the other direction, quality values below 50 will produce very small files -of low image quality. Settings around 5 to 10 might be useful in preparing an -index of a large image library, for example. Try -.B \-quality -2 (or so) for some amusing Cubist effects. (Note: quality -values below about 25 generate 2-byte quantization tables, which are -considered optional in the JPEG standard. -.B cjpeg -emits a warning message when you give such a quality value, because some -other JPEG programs may be unable to decode the resulting file. Use -.B \-baseline -if you need to ensure compatibility at low quality values.) -.PP -The -.B \-progressive -switch creates a "progressive JPEG" file. In this type of JPEG file, the data -is stored in multiple scans of increasing quality. If the file is being -transmitted over a slow communications link, the decoder can use the first -scan to display a low-quality image very quickly, and can then improve the -display with each subsequent scan. The final image is exactly equivalent to a -standard JPEG file of the same quality setting, and the total file size is -about the same --- often a little smaller. -.B Caution: -progressive JPEG is not yet widely implemented, so many decoders will be -unable to view a progressive JPEG file at all. -.PP -Switches for advanced users: -.TP -.B \-dct int -Use integer DCT method (default). -.TP -.B \-dct fast -Use fast integer DCT (less accurate). -.TP -.B \-dct float -Use floating-point DCT method. -The float method is very slightly more accurate than the int method, but is -much slower unless your machine has very fast floating-point hardware. Also -note that results of the floating-point method may vary slightly across -machines, while the integer methods should give the same results everywhere. -The fast integer method is much less accurate than the other two. -.TP -.BI \-restart " N" -Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is -attached to the number. -.B \-restart 0 -(the default) means no restart markers. -.TP -.BI \-smooth " N" -Smooth the input image to eliminate dithering noise. N, ranging from 1 to -100, indicates the strength of smoothing. 0 (the default) means no smoothing. -.TP -.BI \-maxmemory " N" -Set limit for amount of memory to use in processing large images. Value is -in thousands of bytes, or millions of bytes if "M" is attached to the -number. For example, -.B \-max 4m -selects 4000000 bytes. If more space is needed, temporary files will be used. -.TP -.BI \-outfile " name" -Send output image to the named file, not to standard output. -.TP -.B \-verbose -Enable debug printout. More -.BR \-v 's -give more output. Also, version information is printed at startup. -.TP -.B \-debug -Same as -.BR \-verbose . -.PP -The -.B \-restart -option inserts extra markers that allow a JPEG decoder to resynchronize after -a transmission error. Without restart markers, any damage to a compressed -file will usually ruin the image from the point of the error to the end of the -image; with restart markers, the damage is usually confined to the portion of -the image up to the next restart marker. Of course, the restart markers -occupy extra space. We recommend -.B \-restart 1 -for images that will be transmitted across unreliable networks such as Usenet. -.PP -The -.B \-smooth -option filters the input to eliminate fine-scale noise. This is often useful -when converting dithered images to JPEG: a moderate smoothing factor of 10 to -50 gets rid of dithering patterns in the input file, resulting in a smaller -JPEG file and a better-looking image. Too large a smoothing factor will -visibly blur the image, however. -.PP -Switches for wizards: -.TP -.B \-baseline -Force baseline-compatible quantization tables to be generated. This clamps -quantization values to 8 bits even at low quality settings. (This switch is -poorly named, since it does not ensure that the output is actually baseline -JPEG. For example, you can use -.B \-baseline -and -.B \-progressive -together.) -.TP -.BI \-qtables " file" -Use the quantization tables given in the specified text file. -.TP -.BI \-qslots " N[,...]" -Select which quantization table to use for each color component. -.TP -.BI \-sample " HxV[,...]" -Set JPEG sampling factors for each color component. -.TP -.BI \-scans " file" -Use the scan script given in the specified text file. -.PP -The "wizard" switches are intended for experimentation with JPEG. If you -don't know what you are doing, \fBdon't use them\fR. These switches are -documented further in the file wizard.doc. -.SH EXAMPLES -.LP -This example compresses the PPM file foo.ppm with a quality factor of -60 and saves the output as foo.jpg: -.IP -.B cjpeg \-quality -.I 60 foo.ppm -.B > -.I foo.jpg -.SH HINTS -Color GIF files are not the ideal input for JPEG; JPEG is really intended for -compressing full-color (24-bit) images. In particular, don't try to convert -cartoons, line drawings, and other images that have only a few distinct -colors. GIF works great on these, JPEG does not. If you want to convert a -GIF to JPEG, you should experiment with -.BR cjpeg 's -.B \-quality -and -.B \-smooth -options to get a satisfactory conversion. -.B \-smooth 10 -or so is often helpful. -.PP -Avoid running an image through a series of JPEG compression/decompression -cycles. Image quality loss will accumulate; after ten or so cycles the image -may be noticeably worse than it was after one cycle. It's best to use a -lossless format while manipulating an image, then convert to JPEG format when -you are ready to file the image away. -.PP -The -.B \-optimize -option to -.B cjpeg -is worth using when you are making a "final" version for posting or archiving. -It's also a win when you are using low quality settings to make very small -JPEG files; the percentage improvement is often a lot more than it is on -larger files. (At present, -.B \-optimize -mode is always selected when generating progressive JPEG files.) -.SH ENVIRONMENT -.TP -.B JPEGMEM -If this environment variable is set, its value is the default memory limit. -The value is specified as described for the -.B \-maxmemory -switch. -.B JPEGMEM -overrides the default value specified when the program was compiled, and -itself is overridden by an explicit -.BR \-maxmemory . -.SH SEE ALSO -.BR djpeg (1), -.BR jpegtran (1), -.BR rdjpgcom (1), -.BR wrjpgcom (1) -.br -.BR ppm (5), -.BR pgm (5) -.br -Wallace, Gregory K. "The JPEG Still Picture Compression Standard", -Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. -.SH AUTHOR -Independent JPEG Group -.SH BUGS -Arithmetic coding is not supported for legal reasons. -.PP -GIF input files are no longer supported, to avoid the Unisys LZW patent. -Use a Unisys-licensed program if you need to read a GIF file. (Conversion -of GIF files to JPEG is usually a bad idea anyway.) -.PP -Not all variants of BMP and Targa file formats are supported. -.PP -The -.B \-targa -switch is not a bug, it's a feature. (It would be a bug if the Targa format -designers had not been clueless.) -.PP -Still not as fast as we'd like. diff --git a/sys/src/cmd/gs/jpeg/cjpeg.1.man b/sys/src/cmd/gs/jpeg/cjpeg.1.man new file mode 100644 index 000000000..d175a961c --- /dev/null +++ b/sys/src/cmd/gs/jpeg/cjpeg.1.man @@ -0,0 +1,292 @@ +.TH CJPEG 1 "20 March 1998" +.SH NAME +cjpeg \- compress an image file to a JPEG file +.SH SYNOPSIS +.B cjpeg +[ +.I options +] +[ +.I filename +] +.LP +.SH DESCRIPTION +.LP +.B cjpeg +compresses the named image file, or the standard input if no file is +named, and produces a JPEG/JFIF file on the standard output. +The currently supported input file formats are: PPM (PBMPLUS color +format), PGM (PBMPLUS gray-scale format), BMP, Targa, and RLE (Utah Raster +Toolkit format). (RLE is supported only if the URT library is available.) +.SH OPTIONS +All switch names may be abbreviated; for example, +.B \-grayscale +may be written +.B \-gray +or +.BR \-gr . +Most of the "basic" switches can be abbreviated to as little as one letter. +Upper and lower case are equivalent (thus +.B \-BMP +is the same as +.BR \-bmp ). +British spellings are also accepted (e.g., +.BR \-greyscale ), +though for brevity these are not mentioned below. +.PP +The basic switches are: +.TP +.BI \-quality " N" +Scale quantization tables to adjust image quality. Quality is 0 (worst) to +100 (best); default is 75. (See below for more info.) +.TP +.B \-grayscale +Create monochrome JPEG file from color input. Be sure to use this switch when +compressing a grayscale BMP file, because +.B cjpeg +isn't bright enough to notice whether a BMP file uses only shades of gray. +By saying +.BR \-grayscale , +you'll get a smaller JPEG file that takes less time to process. +.TP +.B \-optimize +Perform optimization of entropy encoding parameters. Without this, default +encoding parameters are used. +.B \-optimize +usually makes the JPEG file a little smaller, but +.B cjpeg +runs somewhat slower and needs much more memory. Image quality and speed of +decompression are unaffected by +.BR \-optimize . +.TP +.B \-progressive +Create progressive JPEG file (see below). +.TP +.B \-targa +Input file is Targa format. Targa files that contain an "identification" +field will not be automatically recognized by +.BR cjpeg ; +for such files you must specify +.B \-targa +to make +.B cjpeg +treat the input as Targa format. +For most Targa files, you won't need this switch. +.PP +The +.B \-quality +switch lets you trade off compressed file size against quality of the +reconstructed image: the higher the quality setting, the larger the JPEG file, +and the closer the output image will be to the original input. Normally you +want to use the lowest quality setting (smallest file) that decompresses into +something visually indistinguishable from the original image. For this +purpose the quality setting should be between 50 and 95; the default of 75 is +often about right. If you see defects at +.B \-quality +75, then go up 5 or 10 counts at a time until you are happy with the output +image. (The optimal setting will vary from one image to another.) +.PP +.B \-quality +100 will generate a quantization table of all 1's, minimizing loss in the +quantization step (but there is still information loss in subsampling, as well +as roundoff error). This setting is mainly of interest for experimental +purposes. Quality values above about 95 are +.B not +recommended for normal use; the compressed file size goes up dramatically for +hardly any gain in output image quality. +.PP +In the other direction, quality values below 50 will produce very small files +of low image quality. Settings around 5 to 10 might be useful in preparing an +index of a large image library, for example. Try +.B \-quality +2 (or so) for some amusing Cubist effects. (Note: quality +values below about 25 generate 2-byte quantization tables, which are +considered optional in the JPEG standard. +.B cjpeg +emits a warning message when you give such a quality value, because some +other JPEG programs may be unable to decode the resulting file. Use +.B \-baseline +if you need to ensure compatibility at low quality values.) +.PP +The +.B \-progressive +switch creates a "progressive JPEG" file. In this type of JPEG file, the data +is stored in multiple scans of increasing quality. If the file is being +transmitted over a slow communications link, the decoder can use the first +scan to display a low-quality image very quickly, and can then improve the +display with each subsequent scan. The final image is exactly equivalent to a +standard JPEG file of the same quality setting, and the total file size is +about the same --- often a little smaller. +.B Caution: +progressive JPEG is not yet widely implemented, so many decoders will be +unable to view a progressive JPEG file at all. +.PP +Switches for advanced users: +.TP +.B \-dct int +Use integer DCT method (default). +.TP +.B \-dct fast +Use fast integer DCT (less accurate). +.TP +.B \-dct float +Use floating-point DCT method. +The float method is very slightly more accurate than the int method, but is +much slower unless your machine has very fast floating-point hardware. Also +note that results of the floating-point method may vary slightly across +machines, while the integer methods should give the same results everywhere. +The fast integer method is much less accurate than the other two. +.TP +.BI \-restart " N" +Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is +attached to the number. +.B \-restart 0 +(the default) means no restart markers. +.TP +.BI \-smooth " N" +Smooth the input image to eliminate dithering noise. N, ranging from 1 to +100, indicates the strength of smoothing. 0 (the default) means no smoothing. +.TP +.BI \-maxmemory " N" +Set limit for amount of memory to use in processing large images. Value is +in thousands of bytes, or millions of bytes if "M" is attached to the +number. For example, +.B \-max 4m +selects 4000000 bytes. If more space is needed, temporary files will be used. +.TP +.BI \-outfile " name" +Send output image to the named file, not to standard output. +.TP +.B \-verbose +Enable debug printout. More +.BR \-v 's +give more output. Also, version information is printed at startup. +.TP +.B \-debug +Same as +.BR \-verbose . +.PP +The +.B \-restart +option inserts extra markers that allow a JPEG decoder to resynchronize after +a transmission error. Without restart markers, any damage to a compressed +file will usually ruin the image from the point of the error to the end of the +image; with restart markers, the damage is usually confined to the portion of +the image up to the next restart marker. Of course, the restart markers +occupy extra space. We recommend +.B \-restart 1 +for images that will be transmitted across unreliable networks such as Usenet. +.PP +The +.B \-smooth +option filters the input to eliminate fine-scale noise. This is often useful +when converting dithered images to JPEG: a moderate smoothing factor of 10 to +50 gets rid of dithering patterns in the input file, resulting in a smaller +JPEG file and a better-looking image. Too large a smoothing factor will +visibly blur the image, however. +.PP +Switches for wizards: +.TP +.B \-baseline +Force baseline-compatible quantization tables to be generated. This clamps +quantization values to 8 bits even at low quality settings. (This switch is +poorly named, since it does not ensure that the output is actually baseline +JPEG. For example, you can use +.B \-baseline +and +.B \-progressive +together.) +.TP +.BI \-qtables " file" +Use the quantization tables given in the specified text file. +.TP +.BI \-qslots " N[,...]" +Select which quantization table to use for each color component. +.TP +.BI \-sample " HxV[,...]" +Set JPEG sampling factors for each color component. +.TP +.BI \-scans " file" +Use the scan script given in the specified text file. +.PP +The "wizard" switches are intended for experimentation with JPEG. If you +don't know what you are doing, \fBdon't use them\fR. These switches are +documented further in the file wizard.doc. +.SH EXAMPLES +.LP +This example compresses the PPM file foo.ppm with a quality factor of +60 and saves the output as foo.jpg: +.IP +.B cjpeg \-quality +.I 60 foo.ppm +.B > +.I foo.jpg +.SH HINTS +Color GIF files are not the ideal input for JPEG; JPEG is really intended for +compressing full-color (24-bit) images. In particular, don't try to convert +cartoons, line drawings, and other images that have only a few distinct +colors. GIF works great on these, JPEG does not. If you want to convert a +GIF to JPEG, you should experiment with +.BR cjpeg 's +.B \-quality +and +.B \-smooth +options to get a satisfactory conversion. +.B \-smooth 10 +or so is often helpful. +.PP +Avoid running an image through a series of JPEG compression/decompression +cycles. Image quality loss will accumulate; after ten or so cycles the image +may be noticeably worse than it was after one cycle. It's best to use a +lossless format while manipulating an image, then convert to JPEG format when +you are ready to file the image away. +.PP +The +.B \-optimize +option to +.B cjpeg +is worth using when you are making a "final" version for posting or archiving. +It's also a win when you are using low quality settings to make very small +JPEG files; the percentage improvement is often a lot more than it is on +larger files. (At present, +.B \-optimize +mode is always selected when generating progressive JPEG files.) +.SH ENVIRONMENT +.TP +.B JPEGMEM +If this environment variable is set, its value is the default memory limit. +The value is specified as described for the +.B \-maxmemory +switch. +.B JPEGMEM +overrides the default value specified when the program was compiled, and +itself is overridden by an explicit +.BR \-maxmemory . +.SH SEE ALSO +.BR djpeg (1), +.BR jpegtran (1), +.BR rdjpgcom (1), +.BR wrjpgcom (1) +.br +.BR ppm (5), +.BR pgm (5) +.br +Wallace, Gregory K. "The JPEG Still Picture Compression Standard", +Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. +.SH AUTHOR +Independent JPEG Group +.SH BUGS +Arithmetic coding is not supported for legal reasons. +.PP +GIF input files are no longer supported, to avoid the Unisys LZW patent. +Use a Unisys-licensed program if you need to read a GIF file. (Conversion +of GIF files to JPEG is usually a bad idea anyway.) +.PP +Not all variants of BMP and Targa file formats are supported. +.PP +The +.B \-targa +switch is not a bug, it's a feature. (It would be a bug if the Targa format +designers had not been clueless.) +.PP +Still not as fast as we'd like. diff --git a/sys/src/cmd/gs/jpeg/djpeg.1 b/sys/src/cmd/gs/jpeg/djpeg.1 deleted file mode 100644 index 11beb6a51..000000000 --- a/sys/src/cmd/gs/jpeg/djpeg.1 +++ /dev/null @@ -1,253 +0,0 @@ -.TH DJPEG 1 "22 August 1997" -.SH NAME -djpeg \- decompress a JPEG file to an image file -.SH SYNOPSIS -.B djpeg -[ -.I options -] -[ -.I filename -] -.LP -.SH DESCRIPTION -.LP -.B djpeg -decompresses the named JPEG file, or the standard input if no file is named, -and produces an image file on the standard output. PBMPLUS (PPM/PGM), BMP, -GIF, Targa, or RLE (Utah Raster Toolkit) output format can be selected. -(RLE is supported only if the URT library is available.) -.SH OPTIONS -All switch names may be abbreviated; for example, -.B \-grayscale -may be written -.B \-gray -or -.BR \-gr . -Most of the "basic" switches can be abbreviated to as little as one letter. -Upper and lower case are equivalent (thus -.B \-BMP -is the same as -.BR \-bmp ). -British spellings are also accepted (e.g., -.BR \-greyscale ), -though for brevity these are not mentioned below. -.PP -The basic switches are: -.TP -.BI \-colors " N" -Reduce image to at most N colors. This reduces the number of colors used in -the output image, so that it can be displayed on a colormapped display or -stored in a colormapped file format. For example, if you have an 8-bit -display, you'd need to reduce to 256 or fewer colors. -.TP -.BI \-quantize " N" -Same as -.BR \-colors . -.B \-colors -is the recommended name, -.B \-quantize -is provided only for backwards compatibility. -.TP -.B \-fast -Select recommended processing options for fast, low quality output. (The -default options are chosen for highest quality output.) Currently, this is -equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR. -.TP -.B \-grayscale -Force gray-scale output even if JPEG file is color. Useful for viewing on -monochrome displays; also, -.B djpeg -runs noticeably faster in this mode. -.TP -.BI \-scale " M/N" -Scale the output image by a factor M/N. Currently the scale factor must be -1/1, 1/2, 1/4, or 1/8. Scaling is handy if the image is larger than your -screen; also, -.B djpeg -runs much faster when scaling down the output. -.TP -.B \-bmp -Select BMP output format (Windows flavor). 8-bit colormapped format is -emitted if -.B \-colors -or -.B \-grayscale -is specified, or if the JPEG file is gray-scale; otherwise, 24-bit full-color -format is emitted. -.TP -.B \-gif -Select GIF output format. Since GIF does not support more than 256 colors, -.B \-colors 256 -is assumed (unless you specify a smaller number of colors). -.TP -.B \-os2 -Select BMP output format (OS/2 1.x flavor). 8-bit colormapped format is -emitted if -.B \-colors -or -.B \-grayscale -is specified, or if the JPEG file is gray-scale; otherwise, 24-bit full-color -format is emitted. -.TP -.B \-pnm -Select PBMPLUS (PPM/PGM) output format (this is the default format). -PGM is emitted if the JPEG file is gray-scale or if -.B \-grayscale -is specified; otherwise PPM is emitted. -.TP -.B \-rle -Select RLE output format. (Requires URT library.) -.TP -.B \-targa -Select Targa output format. Gray-scale format is emitted if the JPEG file is -gray-scale or if -.B \-grayscale -is specified; otherwise, colormapped format is emitted if -.B \-colors -is specified; otherwise, 24-bit full-color format is emitted. -.PP -Switches for advanced users: -.TP -.B \-dct int -Use integer DCT method (default). -.TP -.B \-dct fast -Use fast integer DCT (less accurate). -.TP -.B \-dct float -Use floating-point DCT method. -The float method is very slightly more accurate than the int method, but is -much slower unless your machine has very fast floating-point hardware. Also -note that results of the floating-point method may vary slightly across -machines, while the integer methods should give the same results everywhere. -The fast integer method is much less accurate than the other two. -.TP -.B \-dither fs -Use Floyd-Steinberg dithering in color quantization. -.TP -.B \-dither ordered -Use ordered dithering in color quantization. -.TP -.B \-dither none -Do not use dithering in color quantization. -By default, Floyd-Steinberg dithering is applied when quantizing colors; this -is slow but usually produces the best results. Ordered dither is a compromise -between speed and quality; no dithering is fast but usually looks awful. Note -that these switches have no effect unless color quantization is being done. -Ordered dither is only available in -.B \-onepass -mode. -.TP -.BI \-map " file" -Quantize to the colors used in the specified image file. This is useful for -producing multiple files with identical color maps, or for forcing a -predefined set of colors to be used. The -.I file -must be a GIF or PPM file. This option overrides -.B \-colors -and -.BR \-onepass . -.TP -.B \-nosmooth -Use a faster, lower-quality upsampling routine. -.TP -.B \-onepass -Use one-pass instead of two-pass color quantization. The one-pass method is -faster and needs less memory, but it produces a lower-quality image. -.B \-onepass -is ignored unless you also say -.B \-colors -.IR N . -Also, the one-pass method is always used for gray-scale output (the two-pass -method is no improvement then). -.TP -.BI \-maxmemory " N" -Set limit for amount of memory to use in processing large images. Value is -in thousands of bytes, or millions of bytes if "M" is attached to the -number. For example, -.B \-max 4m -selects 4000000 bytes. If more space is needed, temporary files will be used. -.TP -.BI \-outfile " name" -Send output image to the named file, not to standard output. -.TP -.B \-verbose -Enable debug printout. More -.BR \-v 's -give more output. Also, version information is printed at startup. -.TP -.B \-debug -Same as -.BR \-verbose . -.SH EXAMPLES -.LP -This example decompresses the JPEG file foo.jpg, quantizes it to -256 colors, and saves the output in 8-bit BMP format in foo.bmp: -.IP -.B djpeg \-colors 256 \-bmp -.I foo.jpg -.B > -.I foo.bmp -.SH HINTS -To get a quick preview of an image, use the -.B \-grayscale -and/or -.B \-scale -switches. -.B \-grayscale \-scale 1/8 -is the fastest case. -.PP -Several options are available that trade off image quality to gain speed. -.B \-fast -turns on the recommended settings. -.PP -.B \-dct fast -and/or -.B \-nosmooth -gain speed at a small sacrifice in quality. -When producing a color-quantized image, -.B \-onepass \-dither ordered -is fast but much lower quality than the default behavior. -.B \-dither none -may give acceptable results in two-pass mode, but is seldom tolerable in -one-pass mode. -.PP -If you are fortunate enough to have very fast floating point hardware, -\fB\-dct float\fR may be even faster than \fB\-dct fast\fR. But on most -machines \fB\-dct float\fR is slower than \fB\-dct int\fR; in this case it is -not worth using, because its theoretical accuracy advantage is too small to be -significant in practice. -.SH ENVIRONMENT -.TP -.B JPEGMEM -If this environment variable is set, its value is the default memory limit. -The value is specified as described for the -.B \-maxmemory -switch. -.B JPEGMEM -overrides the default value specified when the program was compiled, and -itself is overridden by an explicit -.BR \-maxmemory . -.SH SEE ALSO -.BR cjpeg (1), -.BR jpegtran (1), -.BR rdjpgcom (1), -.BR wrjpgcom (1) -.br -.BR ppm (5), -.BR pgm (5) -.br -Wallace, Gregory K. "The JPEG Still Picture Compression Standard", -Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. -.SH AUTHOR -Independent JPEG Group -.SH BUGS -Arithmetic coding is not supported for legal reasons. -.PP -To avoid the Unisys LZW patent, -.B djpeg -produces uncompressed GIF files. These are larger than they should be, but -are readable by standard GIF decoders. -.PP -Still not as fast as we'd like. diff --git a/sys/src/cmd/gs/jpeg/djpeg.1.man b/sys/src/cmd/gs/jpeg/djpeg.1.man new file mode 100644 index 000000000..11beb6a51 --- /dev/null +++ b/sys/src/cmd/gs/jpeg/djpeg.1.man @@ -0,0 +1,253 @@ +.TH DJPEG 1 "22 August 1997" +.SH NAME +djpeg \- decompress a JPEG file to an image file +.SH SYNOPSIS +.B djpeg +[ +.I options +] +[ +.I filename +] +.LP +.SH DESCRIPTION +.LP +.B djpeg +decompresses the named JPEG file, or the standard input if no file is named, +and produces an image file on the standard output. PBMPLUS (PPM/PGM), BMP, +GIF, Targa, or RLE (Utah Raster Toolkit) output format can be selected. +(RLE is supported only if the URT library is available.) +.SH OPTIONS +All switch names may be abbreviated; for example, +.B \-grayscale +may be written +.B \-gray +or +.BR \-gr . +Most of the "basic" switches can be abbreviated to as little as one letter. +Upper and lower case are equivalent (thus +.B \-BMP +is the same as +.BR \-bmp ). +British spellings are also accepted (e.g., +.BR \-greyscale ), +though for brevity these are not mentioned below. +.PP +The basic switches are: +.TP +.BI \-colors " N" +Reduce image to at most N colors. This reduces the number of colors used in +the output image, so that it can be displayed on a colormapped display or +stored in a colormapped file format. For example, if you have an 8-bit +display, you'd need to reduce to 256 or fewer colors. +.TP +.BI \-quantize " N" +Same as +.BR \-colors . +.B \-colors +is the recommended name, +.B \-quantize +is provided only for backwards compatibility. +.TP +.B \-fast +Select recommended processing options for fast, low quality output. (The +default options are chosen for highest quality output.) Currently, this is +equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR. +.TP +.B \-grayscale +Force gray-scale output even if JPEG file is color. Useful for viewing on +monochrome displays; also, +.B djpeg +runs noticeably faster in this mode. +.TP +.BI \-scale " M/N" +Scale the output image by a factor M/N. Currently the scale factor must be +1/1, 1/2, 1/4, or 1/8. Scaling is handy if the image is larger than your +screen; also, +.B djpeg +runs much faster when scaling down the output. +.TP +.B \-bmp +Select BMP output format (Windows flavor). 8-bit colormapped format is +emitted if +.B \-colors +or +.B \-grayscale +is specified, or if the JPEG file is gray-scale; otherwise, 24-bit full-color +format is emitted. +.TP +.B \-gif +Select GIF output format. Since GIF does not support more than 256 colors, +.B \-colors 256 +is assumed (unless you specify a smaller number of colors). +.TP +.B \-os2 +Select BMP output format (OS/2 1.x flavor). 8-bit colormapped format is +emitted if +.B \-colors +or +.B \-grayscale +is specified, or if the JPEG file is gray-scale; otherwise, 24-bit full-color +format is emitted. +.TP +.B \-pnm +Select PBMPLUS (PPM/PGM) output format (this is the default format). +PGM is emitted if the JPEG file is gray-scale or if +.B \-grayscale +is specified; otherwise PPM is emitted. +.TP +.B \-rle +Select RLE output format. (Requires URT library.) +.TP +.B \-targa +Select Targa output format. Gray-scale format is emitted if the JPEG file is +gray-scale or if +.B \-grayscale +is specified; otherwise, colormapped format is emitted if +.B \-colors +is specified; otherwise, 24-bit full-color format is emitted. +.PP +Switches for advanced users: +.TP +.B \-dct int +Use integer DCT method (default). +.TP +.B \-dct fast +Use fast integer DCT (less accurate). +.TP +.B \-dct float +Use floating-point DCT method. +The float method is very slightly more accurate than the int method, but is +much slower unless your machine has very fast floating-point hardware. Also +note that results of the floating-point method may vary slightly across +machines, while the integer methods should give the same results everywhere. +The fast integer method is much less accurate than the other two. +.TP +.B \-dither fs +Use Floyd-Steinberg dithering in color quantization. +.TP +.B \-dither ordered +Use ordered dithering in color quantization. +.TP +.B \-dither none +Do not use dithering in color quantization. +By default, Floyd-Steinberg dithering is applied when quantizing colors; this +is slow but usually produces the best results. Ordered dither is a compromise +between speed and quality; no dithering is fast but usually looks awful. Note +that these switches have no effect unless color quantization is being done. +Ordered dither is only available in +.B \-onepass +mode. +.TP +.BI \-map " file" +Quantize to the colors used in the specified image file. This is useful for +producing multiple files with identical color maps, or for forcing a +predefined set of colors to be used. The +.I file +must be a GIF or PPM file. This option overrides +.B \-colors +and +.BR \-onepass . +.TP +.B \-nosmooth +Use a faster, lower-quality upsampling routine. +.TP +.B \-onepass +Use one-pass instead of two-pass color quantization. The one-pass method is +faster and needs less memory, but it produces a lower-quality image. +.B \-onepass +is ignored unless you also say +.B \-colors +.IR N . +Also, the one-pass method is always used for gray-scale output (the two-pass +method is no improvement then). +.TP +.BI \-maxmemory " N" +Set limit for amount of memory to use in processing large images. Value is +in thousands of bytes, or millions of bytes if "M" is attached to the +number. For example, +.B \-max 4m +selects 4000000 bytes. If more space is needed, temporary files will be used. +.TP +.BI \-outfile " name" +Send output image to the named file, not to standard output. +.TP +.B \-verbose +Enable debug printout. More +.BR \-v 's +give more output. Also, version information is printed at startup. +.TP +.B \-debug +Same as +.BR \-verbose . +.SH EXAMPLES +.LP +This example decompresses the JPEG file foo.jpg, quantizes it to +256 colors, and saves the output in 8-bit BMP format in foo.bmp: +.IP +.B djpeg \-colors 256 \-bmp +.I foo.jpg +.B > +.I foo.bmp +.SH HINTS +To get a quick preview of an image, use the +.B \-grayscale +and/or +.B \-scale +switches. +.B \-grayscale \-scale 1/8 +is the fastest case. +.PP +Several options are available that trade off image quality to gain speed. +.B \-fast +turns on the recommended settings. +.PP +.B \-dct fast +and/or +.B \-nosmooth +gain speed at a small sacrifice in quality. +When producing a color-quantized image, +.B \-onepass \-dither ordered +is fast but much lower quality than the default behavior. +.B \-dither none +may give acceptable results in two-pass mode, but is seldom tolerable in +one-pass mode. +.PP +If you are fortunate enough to have very fast floating point hardware, +\fB\-dct float\fR may be even faster than \fB\-dct fast\fR. But on most +machines \fB\-dct float\fR is slower than \fB\-dct int\fR; in this case it is +not worth using, because its theoretical accuracy advantage is too small to be +significant in practice. +.SH ENVIRONMENT +.TP +.B JPEGMEM +If this environment variable is set, its value is the default memory limit. +The value is specified as described for the +.B \-maxmemory +switch. +.B JPEGMEM +overrides the default value specified when the program was compiled, and +itself is overridden by an explicit +.BR \-maxmemory . +.SH SEE ALSO +.BR cjpeg (1), +.BR jpegtran (1), +.BR rdjpgcom (1), +.BR wrjpgcom (1) +.br +.BR ppm (5), +.BR pgm (5) +.br +Wallace, Gregory K. "The JPEG Still Picture Compression Standard", +Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. +.SH AUTHOR +Independent JPEG Group +.SH BUGS +Arithmetic coding is not supported for legal reasons. +.PP +To avoid the Unisys LZW patent, +.B djpeg +produces uncompressed GIF files. These are larger than they should be, but +are readable by standard GIF decoders. +.PP +Still not as fast as we'd like. diff --git a/sys/src/cmd/gs/jpeg/jpegtran.1 b/sys/src/cmd/gs/jpeg/jpegtran.1 deleted file mode 100644 index 6de18e2af..000000000 --- a/sys/src/cmd/gs/jpeg/jpegtran.1 +++ /dev/null @@ -1,238 +0,0 @@ -.TH JPEGTRAN 1 "3 August 1997" -.SH NAME -jpegtran \- lossless transformation of JPEG files -.SH SYNOPSIS -.B jpegtran -[ -.I options -] -[ -.I filename -] -.LP -.SH DESCRIPTION -.LP -.B jpegtran -performs various useful transformations of JPEG files. -It can translate the coded representation from one variant of JPEG to another, -for example from baseline JPEG to progressive JPEG or vice versa. It can also -perform some rearrangements of the image data, for example turning an image -from landscape to portrait format by rotation. -.PP -.B jpegtran -works by rearranging the compressed data (DCT coefficients), without -ever fully decoding the image. Therefore, its transformations are lossless: -there is no image degradation at all, which would not be true if you used -.B djpeg -followed by -.B cjpeg -to accomplish the same conversion. But by the same token, -.B jpegtran -cannot perform lossy operations such as changing the image quality. -.PP -.B jpegtran -reads the named JPEG/JFIF file, or the standard input if no file is -named, and produces a JPEG/JFIF file on the standard output. -.SH OPTIONS -All switch names may be abbreviated; for example, -.B \-optimize -may be written -.B \-opt -or -.BR \-o . -Upper and lower case are equivalent. -British spellings are also accepted (e.g., -.BR \-optimise ), -though for brevity these are not mentioned below. -.PP -To specify the coded JPEG representation used in the output file, -.B jpegtran -accepts a subset of the switches recognized by -.BR cjpeg : -.TP -.B \-optimize -Perform optimization of entropy encoding parameters. -.TP -.B \-progressive -Create progressive JPEG file. -.TP -.BI \-restart " N" -Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is -attached to the number. -.TP -.BI \-scans " file" -Use the scan script given in the specified text file. -.PP -See -.BR cjpeg (1) -for more details about these switches. -If you specify none of these switches, you get a plain baseline-JPEG output -file. The quality setting and so forth are determined by the input file. -.PP -The image can be losslessly transformed by giving one of these switches: -.TP -.B \-flip horizontal -Mirror image horizontally (left-right). -.TP -.B \-flip vertical -Mirror image vertically (top-bottom). -.TP -.B \-rotate 90 -Rotate image 90 degrees clockwise. -.TP -.B \-rotate 180 -Rotate image 180 degrees. -.TP -.B \-rotate 270 -Rotate image 270 degrees clockwise (or 90 ccw). -.TP -.B \-transpose -Transpose image (across UL-to-LR axis). -.TP -.B \-transverse -Transverse transpose (across UR-to-LL axis). -.PP -The transpose transformation has no restrictions regarding image dimensions. -The other transformations operate rather oddly if the image dimensions are not -a multiple of the iMCU size (usually 8 or 16 pixels), because they can only -transform complete blocks of DCT coefficient data in the desired way. -.PP -.BR jpegtran 's -default behavior when transforming an odd-size image is designed -to preserve exact reversibility and mathematical consistency of the -transformation set. As stated, transpose is able to flip the entire image -area. Horizontal mirroring leaves any partial iMCU column at the right edge -untouched, but is able to flip all rows of the image. Similarly, vertical -mirroring leaves any partial iMCU row at the bottom edge untouched, but is -able to flip all columns. The other transforms can be built up as sequences -of transpose and flip operations; for consistency, their actions on edge -pixels are defined to be the same as the end result of the corresponding -transpose-and-flip sequence. -.PP -For practical use, you may prefer to discard any untransformable edge pixels -rather than having a strange-looking strip along the right and/or bottom edges -of a transformed image. To do this, add the -.B \-trim -switch: -.TP -.B \-trim -Drop non-transformable edge blocks. -.PP -Obviously, a transformation with -.B \-trim -is not reversible, so strictly speaking -.B jpegtran -with this switch is not lossless. Also, the expected mathematical -equivalences between the transformations no longer hold. For example, -.B \-rot 270 -trim -trims only the bottom edge, but -.B \-rot 90 -trim -followed by -.B \-rot 180 -trim -trims both edges. -.PP -Another not-strictly-lossless transformation switch is: -.TP -.B \-grayscale -Force grayscale output. -.PP -This option discards the chrominance channels if the input image is YCbCr -(ie, a standard color JPEG), resulting in a grayscale JPEG file. The -luminance channel is preserved exactly, so this is a better method of reducing -to grayscale than decompression, conversion, and recompression. This switch -is particularly handy for fixing a monochrome picture that was mistakenly -encoded as a color JPEG. (In such a case, the space savings from getting rid -of the near-empty chroma channels won't be large; but the decoding time for -a grayscale JPEG is substantially less than that for a color JPEG.) -.PP -.B jpegtran -also recognizes these switches that control what to do with "extra" markers, -such as comment blocks: -.TP -.B \-copy none -Copy no extra markers from source file. This setting suppresses all -comments and other excess baggage present in the source file. -.TP -.B \-copy comments -Copy only comment markers. This setting copies comments from the source file, -but discards any other inessential data. -.TP -.B \-copy all -Copy all extra markers. This setting preserves miscellaneous markers -found in the source file, such as JFIF thumbnails and Photoshop settings. -In some files these extra markers can be sizable. -.PP -The default behavior is -.BR "\-copy comments" . -(Note: in IJG releases v6 and v6a, -.B jpegtran -always did the equivalent of -.BR "\-copy none" .) -.PP -Additional switches recognized by jpegtran are: -.TP -.BI \-maxmemory " N" -Set limit for amount of memory to use in processing large images. Value is -in thousands of bytes, or millions of bytes if "M" is attached to the -number. For example, -.B \-max 4m -selects 4000000 bytes. If more space is needed, temporary files will be used. -.TP -.BI \-outfile " name" -Send output image to the named file, not to standard output. -.TP -.B \-verbose -Enable debug printout. More -.BR \-v 's -give more output. Also, version information is printed at startup. -.TP -.B \-debug -Same as -.BR \-verbose . -.SH EXAMPLES -.LP -This example converts a baseline JPEG file to progressive form: -.IP -.B jpegtran \-progressive -.I foo.jpg -.B > -.I fooprog.jpg -.PP -This example rotates an image 90 degrees clockwise, discarding any -unrotatable edge pixels: -.IP -.B jpegtran \-rot 90 -trim -.I foo.jpg -.B > -.I foo90.jpg -.SH ENVIRONMENT -.TP -.B JPEGMEM -If this environment variable is set, its value is the default memory limit. -The value is specified as described for the -.B \-maxmemory -switch. -.B JPEGMEM -overrides the default value specified when the program was compiled, and -itself is overridden by an explicit -.BR \-maxmemory . -.SH SEE ALSO -.BR cjpeg (1), -.BR djpeg (1), -.BR rdjpgcom (1), -.BR wrjpgcom (1) -.br -Wallace, Gregory K. "The JPEG Still Picture Compression Standard", -Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. -.SH AUTHOR -Independent JPEG Group -.SH BUGS -Arithmetic coding is not supported for legal reasons. -.PP -The transform options can't transform odd-size images perfectly. Use -.B \-trim -if you don't like the results without it. -.PP -The entire image is read into memory and then written out again, even in -cases where this isn't really necessary. Expect swapping on large images, -especially when using the more complex transform options. diff --git a/sys/src/cmd/gs/jpeg/jpegtran.1.man b/sys/src/cmd/gs/jpeg/jpegtran.1.man new file mode 100644 index 000000000..6de18e2af --- /dev/null +++ b/sys/src/cmd/gs/jpeg/jpegtran.1.man @@ -0,0 +1,238 @@ +.TH JPEGTRAN 1 "3 August 1997" +.SH NAME +jpegtran \- lossless transformation of JPEG files +.SH SYNOPSIS +.B jpegtran +[ +.I options +] +[ +.I filename +] +.LP +.SH DESCRIPTION +.LP +.B jpegtran +performs various useful transformations of JPEG files. +It can translate the coded representation from one variant of JPEG to another, +for example from baseline JPEG to progressive JPEG or vice versa. It can also +perform some rearrangements of the image data, for example turning an image +from landscape to portrait format by rotation. +.PP +.B jpegtran +works by rearranging the compressed data (DCT coefficients), without +ever fully decoding the image. Therefore, its transformations are lossless: +there is no image degradation at all, which would not be true if you used +.B djpeg +followed by +.B cjpeg +to accomplish the same conversion. But by the same token, +.B jpegtran +cannot perform lossy operations such as changing the image quality. +.PP +.B jpegtran +reads the named JPEG/JFIF file, or the standard input if no file is +named, and produces a JPEG/JFIF file on the standard output. +.SH OPTIONS +All switch names may be abbreviated; for example, +.B \-optimize +may be written +.B \-opt +or +.BR \-o . +Upper and lower case are equivalent. +British spellings are also accepted (e.g., +.BR \-optimise ), +though for brevity these are not mentioned below. +.PP +To specify the coded JPEG representation used in the output file, +.B jpegtran +accepts a subset of the switches recognized by +.BR cjpeg : +.TP +.B \-optimize +Perform optimization of entropy encoding parameters. +.TP +.B \-progressive +Create progressive JPEG file. +.TP +.BI \-restart " N" +Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is +attached to the number. +.TP +.BI \-scans " file" +Use the scan script given in the specified text file. +.PP +See +.BR cjpeg (1) +for more details about these switches. +If you specify none of these switches, you get a plain baseline-JPEG output +file. The quality setting and so forth are determined by the input file. +.PP +The image can be losslessly transformed by giving one of these switches: +.TP +.B \-flip horizontal +Mirror image horizontally (left-right). +.TP +.B \-flip vertical +Mirror image vertically (top-bottom). +.TP +.B \-rotate 90 +Rotate image 90 degrees clockwise. +.TP +.B \-rotate 180 +Rotate image 180 degrees. +.TP +.B \-rotate 270 +Rotate image 270 degrees clockwise (or 90 ccw). +.TP +.B \-transpose +Transpose image (across UL-to-LR axis). +.TP +.B \-transverse +Transverse transpose (across UR-to-LL axis). +.PP +The transpose transformation has no restrictions regarding image dimensions. +The other transformations operate rather oddly if the image dimensions are not +a multiple of the iMCU size (usually 8 or 16 pixels), because they can only +transform complete blocks of DCT coefficient data in the desired way. +.PP +.BR jpegtran 's +default behavior when transforming an odd-size image is designed +to preserve exact reversibility and mathematical consistency of the +transformation set. As stated, transpose is able to flip the entire image +area. Horizontal mirroring leaves any partial iMCU column at the right edge +untouched, but is able to flip all rows of the image. Similarly, vertical +mirroring leaves any partial iMCU row at the bottom edge untouched, but is +able to flip all columns. The other transforms can be built up as sequences +of transpose and flip operations; for consistency, their actions on edge +pixels are defined to be the same as the end result of the corresponding +transpose-and-flip sequence. +.PP +For practical use, you may prefer to discard any untransformable edge pixels +rather than having a strange-looking strip along the right and/or bottom edges +of a transformed image. To do this, add the +.B \-trim +switch: +.TP +.B \-trim +Drop non-transformable edge blocks. +.PP +Obviously, a transformation with +.B \-trim +is not reversible, so strictly speaking +.B jpegtran +with this switch is not lossless. Also, the expected mathematical +equivalences between the transformations no longer hold. For example, +.B \-rot 270 -trim +trims only the bottom edge, but +.B \-rot 90 -trim +followed by +.B \-rot 180 -trim +trims both edges. +.PP +Another not-strictly-lossless transformation switch is: +.TP +.B \-grayscale +Force grayscale output. +.PP +This option discards the chrominance channels if the input image is YCbCr +(ie, a standard color JPEG), resulting in a grayscale JPEG file. The +luminance channel is preserved exactly, so this is a better method of reducing +to grayscale than decompression, conversion, and recompression. This switch +is particularly handy for fixing a monochrome picture that was mistakenly +encoded as a color JPEG. (In such a case, the space savings from getting rid +of the near-empty chroma channels won't be large; but the decoding time for +a grayscale JPEG is substantially less than that for a color JPEG.) +.PP +.B jpegtran +also recognizes these switches that control what to do with "extra" markers, +such as comment blocks: +.TP +.B \-copy none +Copy no extra markers from source file. This setting suppresses all +comments and other excess baggage present in the source file. +.TP +.B \-copy comments +Copy only comment markers. This setting copies comments from the source file, +but discards any other inessential data. +.TP +.B \-copy all +Copy all extra markers. This setting preserves miscellaneous markers +found in the source file, such as JFIF thumbnails and Photoshop settings. +In some files these extra markers can be sizable. +.PP +The default behavior is +.BR "\-copy comments" . +(Note: in IJG releases v6 and v6a, +.B jpegtran +always did the equivalent of +.BR "\-copy none" .) +.PP +Additional switches recognized by jpegtran are: +.TP +.BI \-maxmemory " N" +Set limit for amount of memory to use in processing large images. Value is +in thousands of bytes, or millions of bytes if "M" is attached to the +number. For example, +.B \-max 4m +selects 4000000 bytes. If more space is needed, temporary files will be used. +.TP +.BI \-outfile " name" +Send output image to the named file, not to standard output. +.TP +.B \-verbose +Enable debug printout. More +.BR \-v 's +give more output. Also, version information is printed at startup. +.TP +.B \-debug +Same as +.BR \-verbose . +.SH EXAMPLES +.LP +This example converts a baseline JPEG file to progressive form: +.IP +.B jpegtran \-progressive +.I foo.jpg +.B > +.I fooprog.jpg +.PP +This example rotates an image 90 degrees clockwise, discarding any +unrotatable edge pixels: +.IP +.B jpegtran \-rot 90 -trim +.I foo.jpg +.B > +.I foo90.jpg +.SH ENVIRONMENT +.TP +.B JPEGMEM +If this environment variable is set, its value is the default memory limit. +The value is specified as described for the +.B \-maxmemory +switch. +.B JPEGMEM +overrides the default value specified when the program was compiled, and +itself is overridden by an explicit +.BR \-maxmemory . +.SH SEE ALSO +.BR cjpeg (1), +.BR djpeg (1), +.BR rdjpgcom (1), +.BR wrjpgcom (1) +.br +Wallace, Gregory K. "The JPEG Still Picture Compression Standard", +Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. +.SH AUTHOR +Independent JPEG Group +.SH BUGS +Arithmetic coding is not supported for legal reasons. +.PP +The transform options can't transform odd-size images perfectly. Use +.B \-trim +if you don't like the results without it. +.PP +The entire image is read into memory and then written out again, even in +cases where this isn't really necessary. Expect swapping on large images, +especially when using the more complex transform options. diff --git a/sys/src/cmd/gs/jpeg/rdjpgcom.1 b/sys/src/cmd/gs/jpeg/rdjpgcom.1 deleted file mode 100644 index 2bba04e1a..000000000 --- a/sys/src/cmd/gs/jpeg/rdjpgcom.1 +++ /dev/null @@ -1,54 +0,0 @@ -.TH RDJPGCOM 1 "11 October 1997" -.SH NAME -rdjpgcom \- display text comments from a JPEG file -.SH SYNOPSIS -.B rdjpgcom -[ -.B \-verbose -] -[ -.I filename -] -.LP -.SH DESCRIPTION -.LP -.B rdjpgcom -reads the named JPEG/JFIF file, or the standard input if no file is named, -and prints any text comments found in the file on the standard output. -.PP -The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. -Although the standard doesn't actually define what COM blocks are for, they -are widely used to hold user-supplied text strings. This lets you add -annotations, titles, index terms, etc to your JPEG files, and later retrieve -them as text. COM blocks do not interfere with the image stored in the JPEG -file. The maximum size of a COM block is 64K, but you can have as many of -them as you like in one JPEG file. -.SH OPTIONS -.TP -.B \-verbose -Causes -.B rdjpgcom -to also display the JPEG image dimensions. -.PP -Switch names may be abbreviated, and are not case sensitive. -.SH HINTS -.B rdjpgcom -does not depend on the IJG JPEG library. Its source code is intended as an -illustration of the minimum amount of code required to parse a JPEG file -header correctly. -.PP -In -.B \-verbose -mode, -.B rdjpgcom -will also attempt to print the contents of any "APP12" markers as text. -Some digital cameras produce APP12 markers containing useful textual -information. If you like, you can modify the source code to print -other APPn marker types as well. -.SH SEE ALSO -.BR cjpeg (1), -.BR djpeg (1), -.BR jpegtran (1), -.BR wrjpgcom (1) -.SH AUTHOR -Independent JPEG Group diff --git a/sys/src/cmd/gs/jpeg/rdjpgcom.1.man b/sys/src/cmd/gs/jpeg/rdjpgcom.1.man new file mode 100644 index 000000000..2bba04e1a --- /dev/null +++ b/sys/src/cmd/gs/jpeg/rdjpgcom.1.man @@ -0,0 +1,54 @@ +.TH RDJPGCOM 1 "11 October 1997" +.SH NAME +rdjpgcom \- display text comments from a JPEG file +.SH SYNOPSIS +.B rdjpgcom +[ +.B \-verbose +] +[ +.I filename +] +.LP +.SH DESCRIPTION +.LP +.B rdjpgcom +reads the named JPEG/JFIF file, or the standard input if no file is named, +and prints any text comments found in the file on the standard output. +.PP +The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. +Although the standard doesn't actually define what COM blocks are for, they +are widely used to hold user-supplied text strings. This lets you add +annotations, titles, index terms, etc to your JPEG files, and later retrieve +them as text. COM blocks do not interfere with the image stored in the JPEG +file. The maximum size of a COM block is 64K, but you can have as many of +them as you like in one JPEG file. +.SH OPTIONS +.TP +.B \-verbose +Causes +.B rdjpgcom +to also display the JPEG image dimensions. +.PP +Switch names may be abbreviated, and are not case sensitive. +.SH HINTS +.B rdjpgcom +does not depend on the IJG JPEG library. Its source code is intended as an +illustration of the minimum amount of code required to parse a JPEG file +header correctly. +.PP +In +.B \-verbose +mode, +.B rdjpgcom +will also attempt to print the contents of any "APP12" markers as text. +Some digital cameras produce APP12 markers containing useful textual +information. If you like, you can modify the source code to print +other APPn marker types as well. +.SH SEE ALSO +.BR cjpeg (1), +.BR djpeg (1), +.BR jpegtran (1), +.BR wrjpgcom (1) +.SH AUTHOR +Independent JPEG Group diff --git a/sys/src/cmd/gs/jpeg/wrjpgcom.1 b/sys/src/cmd/gs/jpeg/wrjpgcom.1 deleted file mode 100644 index d419a9999..000000000 --- a/sys/src/cmd/gs/jpeg/wrjpgcom.1 +++ /dev/null @@ -1,103 +0,0 @@ -.TH WRJPGCOM 1 "15 June 1995" -.SH NAME -wrjpgcom \- insert text comments into a JPEG file -.SH SYNOPSIS -.B wrjpgcom -[ -.B \-replace -] -[ -.BI \-comment " text" -] -[ -.BI \-cfile " name" -] -[ -.I filename -] -.LP -.SH DESCRIPTION -.LP -.B wrjpgcom -reads the named JPEG/JFIF file, or the standard input if no file is named, -and generates a new JPEG/JFIF file on standard output. A comment block is -added to the file. -.PP -The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. -Although the standard doesn't actually define what COM blocks are for, they -are widely used to hold user-supplied text strings. This lets you add -annotations, titles, index terms, etc to your JPEG files, and later retrieve -them as text. COM blocks do not interfere with the image stored in the JPEG -file. The maximum size of a COM block is 64K, but you can have as many of -them as you like in one JPEG file. -.PP -.B wrjpgcom -adds a COM block, containing text you provide, to a JPEG file. -Ordinarily, the COM block is added after any existing COM blocks; but you -can delete the old COM blocks if you wish. -.SH OPTIONS -Switch names may be abbreviated, and are not case sensitive. -.TP -.B \-replace -Delete any existing COM blocks from the file. -.TP -.BI \-comment " text" -Supply text for new COM block on command line. -.TP -.BI \-cfile " name" -Read text for new COM block from named file. -.PP -If you have only one line of comment text to add, you can provide it on the -command line with -.BR \-comment . -The comment text must be surrounded with quotes so that it is treated as a -single argument. Longer comments can be read from a text file. -.PP -If you give neither -.B \-comment -nor -.BR \-cfile , -then -.B wrjpgcom -will read the comment text from standard input. (In this case an input image -file name MUST be supplied, so that the source JPEG file comes from somewhere -else.) You can enter multiple lines, up to 64KB worth. Type an end-of-file -indicator (usually control-D) to terminate the comment text entry. -.PP -.B wrjpgcom -will not add a COM block if the provided comment string is empty. Therefore -\fB\-replace \-comment ""\fR can be used to delete all COM blocks from a file. -.SH EXAMPLES -.LP -Add a short comment to in.jpg, producing out.jpg: -.IP -.B wrjpgcom \-c -\fI"View of my back yard" in.jpg -.B > -.I out.jpg -.PP -Attach a long comment previously stored in comment.txt: -.IP -.B wrjpgcom -.I in.jpg -.B < -.I comment.txt -.B > -.I out.jpg -.PP -or equivalently -.IP -.B wrjpgcom -.B -cfile -.I comment.txt -.B < -.I in.jpg -.B > -.I out.jpg -.SH SEE ALSO -.BR cjpeg (1), -.BR djpeg (1), -.BR jpegtran (1), -.BR rdjpgcom (1) -.SH AUTHOR -Independent JPEG Group diff --git a/sys/src/cmd/gs/jpeg/wrjpgcom.1.man b/sys/src/cmd/gs/jpeg/wrjpgcom.1.man new file mode 100644 index 000000000..d419a9999 --- /dev/null +++ b/sys/src/cmd/gs/jpeg/wrjpgcom.1.man @@ -0,0 +1,103 @@ +.TH WRJPGCOM 1 "15 June 1995" +.SH NAME +wrjpgcom \- insert text comments into a JPEG file +.SH SYNOPSIS +.B wrjpgcom +[ +.B \-replace +] +[ +.BI \-comment " text" +] +[ +.BI \-cfile " name" +] +[ +.I filename +] +.LP +.SH DESCRIPTION +.LP +.B wrjpgcom +reads the named JPEG/JFIF file, or the standard input if no file is named, +and generates a new JPEG/JFIF file on standard output. A comment block is +added to the file. +.PP +The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. +Although the standard doesn't actually define what COM blocks are for, they +are widely used to hold user-supplied text strings. This lets you add +annotations, titles, index terms, etc to your JPEG files, and later retrieve +them as text. COM blocks do not interfere with the image stored in the JPEG +file. The maximum size of a COM block is 64K, but you can have as many of +them as you like in one JPEG file. +.PP +.B wrjpgcom +adds a COM block, containing text you provide, to a JPEG file. +Ordinarily, the COM block is added after any existing COM blocks; but you +can delete the old COM blocks if you wish. +.SH OPTIONS +Switch names may be abbreviated, and are not case sensitive. +.TP +.B \-replace +Delete any existing COM blocks from the file. +.TP +.BI \-comment " text" +Supply text for new COM block on command line. +.TP +.BI \-cfile " name" +Read text for new COM block from named file. +.PP +If you have only one line of comment text to add, you can provide it on the +command line with +.BR \-comment . +The comment text must be surrounded with quotes so that it is treated as a +single argument. Longer comments can be read from a text file. +.PP +If you give neither +.B \-comment +nor +.BR \-cfile , +then +.B wrjpgcom +will read the comment text from standard input. (In this case an input image +file name MUST be supplied, so that the source JPEG file comes from somewhere +else.) You can enter multiple lines, up to 64KB worth. Type an end-of-file +indicator (usually control-D) to terminate the comment text entry. +.PP +.B wrjpgcom +will not add a COM block if the provided comment string is empty. Therefore +\fB\-replace \-comment ""\fR can be used to delete all COM blocks from a file. +.SH EXAMPLES +.LP +Add a short comment to in.jpg, producing out.jpg: +.IP +.B wrjpgcom \-c +\fI"View of my back yard" in.jpg +.B > +.I out.jpg +.PP +Attach a long comment previously stored in comment.txt: +.IP +.B wrjpgcom +.I in.jpg +.B < +.I comment.txt +.B > +.I out.jpg +.PP +or equivalently +.IP +.B wrjpgcom +.B -cfile +.I comment.txt +.B < +.I in.jpg +.B > +.I out.jpg +.SH SEE ALSO +.BR cjpeg (1), +.BR djpeg (1), +.BR jpegtran (1), +.BR rdjpgcom (1) +.SH AUTHOR +Independent JPEG Group diff --git a/sys/src/cmd/gs/libpng/libpng.3 b/sys/src/cmd/gs/libpng/libpng.3 deleted file mode 100644 index 1feceee38..000000000 --- a/sys/src/cmd/gs/libpng/libpng.3 +++ /dev/null @@ -1,4022 +0,0 @@ -.TH LIBPNG 3 "December 3, 2004" -.SH NAME -libpng \- Portable Network Graphics (PNG) Reference Library 1.2.8 -.SH SYNOPSIS -\fI\fB - -\fB#include \fP - -\fI\fB - -\fBpng_uint_32 png_access_version_number \fI(void\fP\fB);\fP - -\fI\fB - -\fBint png_check_sig (png_bytep \fP\fIsig\fP\fB, int \fInum\fP\fB);\fP - -\fI\fB - -\fBvoid png_chunk_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP - -\fI\fB - -\fBvoid png_chunk_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP - -\fI\fB - -\fBvoid png_convert_from_struct_tm (png_timep \fP\fIptime\fP\fB, struct tm FAR * \fIttime\fP\fB);\fP - -\fI\fB - -\fBvoid png_convert_from_time_t (png_timep \fP\fIptime\fP\fB, time_t \fIttime\fP\fB);\fP - -\fI\fB - -\fBpng_charp png_convert_to_rfc1123 (png_structp \fP\fIpng_ptr\fP\fB, png_timep \fIptime\fP\fB);\fP - -\fI\fB - -\fBpng_infop png_create_info_struct (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_structp png_create_read_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP - -\fI\fB - -\fBpng_structp png_create_read_struct_2(png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP - -\fI\fB - -\fBpng_structp png_create_write_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP - -\fI\fB - -\fBpng_structp png_create_write_struct_2(png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP - -\fI\fB - -\fBint png_debug(int \fP\fIlevel\fP\fB, png_const_charp \fImessage\fP\fB);\fP - -\fI\fB - -\fBint png_debug1(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fIp1\fP\fB);\fP - -\fI\fB - -\fBint png_debug2(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fP\fIp1\fP\fB, \fIp2\fP\fB);\fP - -\fI\fB - -\fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_destroy_read_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fP\fIinfo_ptr_ptr\fP\fB, png_infopp \fIend_info_ptr_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_destroy_write_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP - -\fI\fB - -\fBvoid png_free (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP - -\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_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum\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 - -\fBpng_uint_32 png_get_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_channels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_copyright (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_error_ptr (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_filter_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_header_ver (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_header_version (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP - -\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, png_uint_32 \fI*proflen\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*width\fP\fB, png_uint_32 \fP\fI*height\fP\fB, int \fP\fI*bit_depth\fP\fB, int \fP\fI*color_type\fP\fB, int \fP\fI*interlace_type\fP\fB, int \fP\fI*compression_type\fP\fB, int \fI*filter_type\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_image_height (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_image_width (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_libpng_ver (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP - -\fI\fB - -\fBfloat png_get_pixel_aspect_ratio (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_progressive_ptr (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP - -\fI\fB - -\fBpng_byte png_get_rgb_to_gray_status (png_structp \fIpng_ptr) - -\fBpng_uint_32 png_get_rowbytes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_bytepp png_get_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP - -\fI\fB - -\fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fI*intent\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_values\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_get_user_chunk_ptr (png_structp \fIpng_ptr\fP\fB);\fP - -\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 - -\fBpng_int_32 png_get_x_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_int_32 png_get_x_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_x_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_int_32 png_get_y_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_y_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP - -\fI\fB - -\fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP - -\fI\fB - -\fBDEPRECATED: void png_info_init (png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBDEPRECATED: void png_info_init_2 (png_infopp \fP\fIptr_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP - -\fI\fB - -\fBvoidp png_memcpy (png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_size_t \fIsize\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_memcpy_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_uint_32 \fIsize\fP\fB);\fP - -\fI\fB - -\fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP - -\fI\fB - -\fBpng_voidp png_memset_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_uint_32 \fIsize\fP\fB);\fP - -\fI\fB - -\fBDEPRECATED: void png_permit_empty_plte (png_structp \fP\fIpng_ptr\fP\fB, int \fIempty_plte_permitted\fP\fB);\fP - -\fI\fB - -\fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP - -\fI\fB - -\fBvoid png_progressive_combine_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIold_row\fP\fB, png_bytep \fInew_row\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_destroy (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_infop \fIend_info_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP - -\fI\fB - -\fBDEPRECATED: void png_read_init (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBDEPRECATED: void png_read_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\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, png_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 - -\fBvoid png_read_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_bytepp \fP\fIdisplay_row\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP - -\fI\fB - -\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fB#if \fI!defined(PNG_1_0_X) - -\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP - -\fI\fB#endif - -\fI\fB - -\fBvoid png_set_background (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, double \fIbackground_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fIbackground\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIwhite_x\fP\fB, double \fP\fIwhite_y\fP\fB, double \fP\fIred_x\fP\fB, double \fP\fIred_y\fP\fB, double \fP\fIgreen_x\fP\fB, double \fP\fIgreen_y\fP\fB, double \fP\fIblue_x\fP\fB, double \fIblue_y\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwhite_x\fP\fB, png_uint_32 \fP\fIwhite_y\fP\fB, png_uint_32 \fP\fIred_x\fP\fB, png_uint_32 \fP\fIred_y\fP\fB, png_uint_32 \fP\fIgreen_x\fP\fB, png_uint_32 \fP\fIgreen_y\fP\fB, png_uint_32 \fP\fIblue_x\fP\fB, png_uint_32 \fIblue_y\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_crc_action (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIcrit_action\fP\fB, int \fIancil_action\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_dither (png_structp \fP\fIpng_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fP\fInum_palette\fP\fB, int \fP\fImaximum_colors\fP\fB, png_uint_16p \fP\fIhistogram\fP\fB, int \fIfull_dither\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_error_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarning_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_filler (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_filter (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImethod\fP\fB, int \fIfilters\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_filter_heuristics (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_doublep \fP\fIfilter_weights\fP\fB, png_doublep \fIfilter_costs\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gamma (png_structp \fP\fIpng_ptr\fP\fB, double \fP\fIscreen_gamma\fP\fB, double \fIdefault_file_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIfile_gamma\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gray_1_2_4_to_8(png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fIhist\fP\fB);\fP - -\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, png_uint_32 \fIproflen\fP\fB);\fP - -\fI\fB - -\fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwidth\fP\fB, png_uint_32 \fP\fIheight\fP\fB, int \fP\fIbit_depth\fP\fB, int \fP\fIcolor_type\fP\fB, int \fP\fIinterlace_type\fP\fB, int \fP\fIcompression_type\fP\fB, int \fIfilter_type\fP\fB);\fP - -\fI\fB - -\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 - -\fBvoid png_set_mem_fn(png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIoffset_x\fP\fB, png_uint_32 \fP\fIoffset_y\fP\fB, int \fIunit_type\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_palette_to_rgb(png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIpurpose\fP\fB, png_int_32 \fP\fIX0\fP\fB, png_int_32 \fP\fIX1\fP\fB, int \fP\fItype\fP\fB, int \fP\fInparams\fP\fB, png_charp \fP\fIunits\fP\fB, png_charpp \fIparams\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIres_x\fP\fB, png_uint_32 \fP\fIres_y\fP\fB, int \fIunit_type\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_progressive_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIprogressive_ptr\fP\fB, png_progressive_info_ptr \fP\fIinfo_fn\fP\fB, png_progressive_row_ptr \fP\fIrow_fn\fP\fB, png_progressive_end_ptr \fIend_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fInum_palette\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fIread_data_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_read_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_read_status_ptr \fIread_row_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_read_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIread_user_transform_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_rgb_to_gray (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIerror_action\fP\fB, double \fP\fIred\fP\fB, double \fIgreen\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_fixed_point \fP\fIred\fP\fB, png_fixed_point \fIgreen\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytepp \fIrow_pointers\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fIsig_bit\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_shift (png_structp \fP\fIpng_ptr\fP\fB, png_color_8p \fItrue_bits\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sig_bytes (png_structp \fP\fIpng_ptr\fP\fB, int \fInum_bytes\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fP\fIsplt_ptr\fP\fB, int \fInum_spalettes\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_sRGB_gAMA_and_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_strip_16 (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_strip_alpha (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_swap (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_swap_alpha (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fItext_ptr\fP\fB, int \fInum_text\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fImod_time\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fItrans\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_values\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_tRNS_to_alpha(png_structp \fIpng_ptr\fP\fB);\fP - -\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 \fP\fInum\fP\fB, int \fIlocation\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_unknown_chunk_location(png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIchunk\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 - -\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 - -\fBvoid png_set_write_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fP\fIwrite_data_fn\fP\fB, png_flush_ptr \fIoutput_flush_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_write_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_write_status_ptr \fIwrite_row_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_write_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIwrite_user_transform_fn\fP\fB);\fP - -\fI\fB - -\fBvoid png_set_compression_buffer_size(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP - -\fI\fB - -\fBint png_sig_cmp (png_bytep \fP\fIsig\fP\fB, png_size_t \fP\fIstart\fP\fB, png_size_t \fInum_to_check\fP\fB);\fP - -\fI\fB - -\fBvoid png_start_read_image (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_chunk (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_chunk_data (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_chunk_end (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_chunk_start (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_uint_32 \fIlength\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_destroy (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_flush (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP - -\fI\fB - -\fBDEPRECATED: void png_write_init (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBDEPRECATED: void png_write_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\fI\fB - -\fBvoid png_write_info_before_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP - -\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, png_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 - -\fBvoid png_write_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP - -\fI\fB - -\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\fP\fB);\fP - -\fI\fB - -\fBvoid png_zfree (voidpf \fP\fIpng_ptr\fP\fB, voidpf \fIptr\fP\fB);\fP - -\fI\fB - -.SH DESCRIPTION -The -.I libpng -library supports encoding, decoding, and various manipulations of -the Portable Network Graphics (PNG) format image files. It uses the -.IR zlib(3) -compression library. -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.8 - December 3, 2004 - Updated and distributed by Glenn Randers-Pehrson - - Copyright (c) 1998-2004 Glenn Randers-Pehrson - For conditions of distribution and use, see copyright - notice in png.h. - - based on: - - libpng 1.0 beta 6 version 0.96 May 28, 1997 - Updated and distributed by Andreas Dilger - Copyright (c) 1996, 1997 Andreas Dilger - - libpng 1.0 beta 2 - version 0.88 January 26, 1996 - For conditions of distribution and use, see copyright - notice in png.h. Copyright (c) 1995, 1996 Guy Eric - Schalnat, Group 42, Inc. - - Updated/rewritten per request in the libpng FAQ - 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 -(known as libpng) for your own use. There are five sections to this -file: introduction, structures, reading, writing, and modification and -configuration notes for various special platforms. In addition to this -file, example.c is a good starting point for using the library, as -it is heavily commented and should include everything most people -will need. We assume that libpng is already installed; see the -INSTALL file for instructions on how to install libpng. - -Libpng was written as a companion to the PNG specification, as a way -of reducing the amount of time and effort it takes to support the PNG -file format in application programs. - -The PNG specification (second edition), November 2003, is available as -a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at - - -The PNG-1.0 specification is available -as RFC 2083 and as a -W3C Recommendation . Some -additional chunks are described in the special-purpose public chunks -documents at . - -Other information -about PNG, and the latest version of libpng, can be found at the PNG home -page, . - -Most users will not have to modify the library significantly; advanced -users may want to modify it more. All attempts were made to make it as -complete as possible, while keeping the code easy to understand. -Currently, this library only supports C. Support for other languages -is being considered. - -Libpng has been designed to handle multiple sessions at one time, -to be easily modifiable, to be portable to the vast majority of -machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy -to use. The ultimate goal of libpng is to promote the acceptance of -the PNG file format in whatever way possible. While there is still -work to be done (see the TODO file), libpng should cover the -majority of the needs of its users. - -Libpng uses zlib for its compression and decompression of PNG files. -Further information about zlib, and the latest version of zlib, can -be found at the zlib home page, . -The zlib compression utility is a general purpose utility that is -useful for more than PNG files, and can be used without libpng. -See the documentation delivered with zlib for more details. -You can usually find the source files for the zlib utility wherever you -find the libpng source files. - -Libpng is thread safe, provided the threads are using different -instances of the structures. Each thread should have its own -png_struct and png_info instances, and thus its own image. -Libpng does not protect itself against two threads using the -same instance of a structure. Note: thread safety may be defeated -by use of some of the MMX assembler code in pnggccrd.c, which is only -compiled when the user defines PNG_THREAD_UNSAFE_OK. - -.SH II. Structures - -There are two main structures that are important to libpng, png_struct -and png_info. The first, png_struct, is an internal structure that -will not, for the most part, be used by a user except as the first -variable passed to every libpng function call. - -The png_info structure is designed to provide information about the -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. The fields of png_info are still available for -older applications, but it is suggested that applications use the new -interfaces if at all possible. - -Applications that do make direct access to the members of png_struct (except -for png_ptr->jmpbuf) must be recompiled whenever the library is updated, -and applications that make direct access to the members of png_info must -be recompiled if they were compiled or loaded with libpng version 1.0.6, -in which the members were in a different order. In version 1.0.7, the -members of the png_info structure reverted to the old order, as they were -in versions 0.97c through 1.0.5. Starting with version 2.0.0, both -structures are going to be hidden, and the contents of the structures will -only be accessible through the png_get/png_set functions. - -The png.h header file is an invaluable reference for programming with libpng. -And while I'm on the topic, make sure you include the libpng header file: - -#include - -.SH III. Reading - -We'll now walk you through the possible functions to call when reading -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 -will also want to insure that you are, in fact, dealing with a PNG -file. Libpng provides a simple check to see if a file is a PNG file. -To use it, pass in the first 1 to 8 bytes of the file to the function -png_sig_cmp(), and it will return 0 if the bytes match the corresponding -bytes of the PNG signature, or nonzero otherwise. Of course, the more bytes -you pass in, the greater the accuracy of the prediction. - -If you are intending to keep the file pointer open for use in libpng, -you must ensure you don't read more than 8 bytes from the beginning -of the file, and you also have to make a call to png_set_sig_bytes_read() -with the number of bytes you read from the beginning. Libpng will -then only check the bytes (if any) that your program didn't read. - -(*): If you are not using the standard I/O functions, you will need -to replace them with custom functions. See the discussion under -Customizing libpng. - - - FILE *fp = fopen(file_name, "rb"); - if (!fp) - { - return (ERROR); - } - fread(header, 1, number, fp); - is_png = !png_sig_cmp(header, 0, number); - if (!is_png) - { - return (NOT_PNG); - } - - -Next, png_struct and png_info need to be allocated and initialized. In -order to ensure that the size of these structures is correct even with a -dynamically linked libpng, there are functions to initialize and -allocate the structures. We also pass the library version, optional -pointers to error handling functions, and a pointer to a data struct for -use by the error functions, if necessary (the pointer and functions can -be NULL if the default error handlers are to be used). See the section -on Changes to Libpng below regarding the old initialization functions. -The structure allocation functions quietly return NULL if they fail to -create the structure, so your application should check for that. - - png_structp png_ptr = png_create_read_struct - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - if (!png_ptr) - return (ERROR); - - png_infop info_ptr = png_create_info_struct(png_ptr); - if (!info_ptr) - { - png_destroy_read_struct(&png_ptr, - (png_infopp)NULL, (png_infopp)NULL); - return (ERROR); - } - - png_infop end_info = png_create_info_struct(png_ptr); - if (!end_info) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - -If you want to use your own memory allocation routines, -define PNG_USER_MEM_SUPPORTED and use -png_create_read_struct_2() instead of png_create_read_struct(): - - png_structp png_ptr = png_create_read_struct_2 - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn, (png_voidp) - user_mem_ptr, user_malloc_fn, user_free_fn); - -The error handling routines passed to png_create_read_struct() -and the memory alloc/free routines passed to png_create_struct_2() -are only necessary if you are not using the libpng supplied error -handling and memory alloc/free functions. - -When libpng encounters an error, it expects to longjmp back -to your routine. Therefore, you will need to call setjmp and pass -your png_jmpbuf(png_ptr). If you read the file from different -routines, you will need to update the jmpbuf field every time you enter -a new routine that will call a png_*() function. - -See your documentation of setjmp/longjmp for your compiler for more -information on setjmp/longjmp. See the discussion on libpng error -handling in the Customizing Libpng section below for more information -on the libpng error handling. If an error occurs, and libpng longjmp's -back to your setjmp, you will want to call png_destroy_read_struct() to -free any memory. - - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - &end_info); - fclose(fp); - return (ERROR); - } - -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 -opened in binary mode. If you wish to handle reading data in another -way, you need not call the png_init_io() function, but you must then -implement the libpng I/O methods discussed in the Customizing Libpng -section below. - - png_init_io(png_ptr, fp); - -If you had previously opened the file and read any of the signature from -the beginning in order to see if this was a PNG file, you need to let -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. -You must supply a function - - void read_row_callback(png_ptr ptr, png_uint_32 row, - int pass); - { - /* put your code here */ - } - -(You can give it another name that you like instead of "read_row_callback") - -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 -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, keep, - chunk_list, num_chunks); - keep - 0: do not handle as unknown - 1: do not keep - 2: keep only if safe-to-copy - 3: keep even if unsafe-to-copy - You can use these definitions: - PNG_HANDLE_CHUNK_AS_DEFAULT 0 - PNG_HANDLE_CHUNK_NEVER 1 - PNG_HANDLE_CHUNK_IF_SAFE 2 - PNG_HANDLE_CHUNK_ALWAYS 3 - 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. If nonzero, - only the chunks in the list 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. The IHDR and IEND chunks should not be named in -chunk_list; if they are, libpng will process them normally anyway. - -.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, -then png_read_image(), and finally png_read_end(). - -(The final parameter of this call is not yet used. Someday it might point -to transformation parameters required by some future input transform.) - -You must use png_transforms and not call any png_set_transform() functions -when you use png_read_png(). - -After you have called png_read_png(), you can retrieve the image data -with - - row_pointers = png_get_rows(png_ptr, info_ptr); - -where row_pointers is an array of pointers to the pixel data for each row: - - png_bytep row_pointers[height]; - -If you know your image size and pixel size ahead of time, you can allocate -row_pointers prior to calling png_read_png() with - - if (height > PNG_UINT_32_MAX/png_sizeof(png_byte)) - png_error (png_ptr, - "Image is too tall to process in memory"); - if (width > PNG_UINT_32_MAX/pixel_size) - png_error (png_ptr, - "Image is too wide to process in memory"); - row_pointers = png_malloc(png_ptr, - height*png_sizeof(png_bytep)); - for (int i=0; i) and -png_get_(png_ptr, info_ptr, ...) functions return non-zero if the -data has been read, or zero if it is missing. The parameters to the -png_get_ are set directly if they are simple data types, or a pointer -into the info_ptr is returned for any complex types. - - png_get_PLTE(png_ptr, info_ptr, &palette, - &num_palette); - palette - the palette for the file - (array of png_color) - num_palette - number of entries in the palette - - png_get_gAMA(png_ptr, info_ptr, &gamma); - gamma - the gamma the file is written - at (PNG_INFO_gAMA) - - png_get_sRGB(png_ptr, info_ptr, &srgb_intent); - srgb_intent - the rendering intent (PNG_INFO_sRGB) - The presence of the sRGB chunk - means that the pixel data is in the - sRGB color space. This chunk also - implies specific values of gAMA and - cHRM. - - png_get_iCCP(png_ptr, info_ptr, &name, - &compression_type, &profile, &proflen); - name - The profile name. - compression - The compression type; always - PNG_COMPRESSION_TYPE_BASE for PNG 1.0. - You may give NULL to this argument to - ignore it. - profile - International Color Consortium color - profile data. May contain NULs. - proflen - length of profile data in bytes. - - png_get_sBIT(png_ptr, info_ptr, &sig_bit); - sig_bit - the number of significant bits for - (PNG_INFO_sBIT) each of the gray, - red, green, and blue channels, - whichever are appropriate for the - given color type (png_color_16) - - png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans, - &trans_values); - trans - array of transparent entries for - palette (PNG_INFO_tRNS) - trans_values - graylevel or color sample values of - the single transparent color for - non-paletted images (PNG_INFO_tRNS) - num_trans - number of transparent entries - (PNG_INFO_tRNS) - - png_get_hIST(png_ptr, info_ptr, &hist); - (PNG_INFO_hIST) - hist - histogram of palette (array of - png_uint_16) - - png_get_tIME(png_ptr, info_ptr, &mod_time); - mod_time - time image was last modified - (PNG_VALID_tIME) - - 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_comments = png_get_text(png_ptr, info_ptr, - &text_ptr, &num_text); - num_comments - number of comments - text_ptr - array of png_text holding image - comments - 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. Must contain - 1-79 characters. - text_ptr[i].text - text comments for current - keyword. Can be empty. - 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 (empty - string for unknown). - text_ptr[i].lang_key - keyword in UTF-8 - (empty string for unknown). - num_text - number of comments (same as - num_comments; you can put NULL here - to avoid the duplication) - Note while png_set_text() will accept text, language, - and translated keywords that can be NULL pointers, the - structure returned by png_get_text will always contain - regular zero-terminated C strings. They might be - empty strings but they will never be NULL pointers. - - num_spalettes = png_get_sPLT(png_ptr, info_ptr, - &palette_ptr); - palette_ptr - array of palette structures holding - contents of one or more sPLT chunks - read. - num_spalettes - number of sPLT chunks read. - - png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y, - &unit_type); - offset_x - positive offset from the left edge - of the screen - offset_y - positive offset from the top edge - of the screen - unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER - - png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y, - &unit_type); - res_x - pixels/unit physical resolution in - x direction - res_y - pixels/unit physical resolution in - x direction - unit_type - PNG_RESOLUTION_UNKNOWN, - PNG_RESOLUTION_METER - - png_get_sCAL(png_ptr, info_ptr, &unit, &width, - &height) - unit - physical scale units (an integer) - width - width of a pixel in physical scale units - height - height of a pixel in physical scale units - (width and height are doubles) - - png_get_sCAL_s(png_ptr, info_ptr, &unit, &width, - &height) - unit - physical scale units (an integer) - width - width of a pixel in physical scale units - height - height of a pixel in physical scale units - (width and height are strings like "2.54") - - num_unknown_chunks = png_get_unknown_chunks(png_ptr, - info_ptr, &unknowns) - unknowns - array of png_unknown_chunk - structures holding unknown chunks - unknowns[i].name - name of unknown chunk - unknowns[i].data - data of unknown chunk - unknowns[i].size - size of unknown chunk's data - unknowns[i].location - position of chunk in file - - The value of "i" corresponds to the order in which the - chunks were read from the PNG file or inserted with the - png_set_unknown_chunks() function. - -The data from the pHYs chunk can be retrieved in several convenient -forms: - - res_x = png_get_x_pixels_per_meter(png_ptr, - info_ptr) - res_y = png_get_y_pixels_per_meter(png_ptr, - info_ptr) - res_x_and_y = png_get_pixels_per_meter(png_ptr, - info_ptr) - res_x = png_get_x_pixels_per_inch(png_ptr, - info_ptr) - res_y = png_get_y_pixels_per_inch(png_ptr, - info_ptr) - res_x_and_y = png_get_pixels_per_inch(png_ptr, - info_ptr) - aspect_ratio = png_get_pixel_aspect_ratio(png_ptr, - info_ptr) - - (Each of these returns 0 [signifying "unknown"] if - the data is not present or if res_x is 0; - res_x_and_y is 0 if res_x != res_y) - -The data from the oFFs chunk can be retrieved in several convenient -forms: - - x_offset = png_get_x_offset_microns(png_ptr, info_ptr); - y_offset = png_get_y_offset_microns(png_ptr, info_ptr); - x_offset = png_get_x_offset_inches(png_ptr, info_ptr); - y_offset = png_get_y_offset_inches(png_ptr, info_ptr); - - (Each of these returns 0 [signifying "unknown" if both - x and y are 0] if the data is not present or if the - chunk is present but the unit is the pixel) - -For more information, see the png_info definition in png.h and the -PNG specification for chunk contents. Be careful with trusting -rowbytes, as some of the transformations could increase the space -needed to hold a row (expand, filler, gray_to_rgb, etc.). -See png_read_update_info(), below. - -A quick word about text_ptr and num_text. PNG stores comments in -keyword/text pairs, one pair per chunk, with no limit on the number -of text chunks, and a 2^31 byte limit on their size. While there are -suggested keywords, there is no requirement to restrict the use to these -strings. It is strongly suggested that keywords and text be sensible -to humans (that's the point), so don't use abbreviations. Non-printing -symbols are not allowed. See the PNG specification for more details. -There is also no requirement to have text after the keyword. - -Keywords should be limited to 79 Latin-1 characters without leading or -trailing spaces, but non-consecutive spaces are allowed within the -keyword. It is possible to have the same keyword any number of times. -The text_ptr is an array of png_text structures, each holding a -pointer to a language string, a pointer to a keyword and a pointer to -a text string. The text string, language code, and translated -keyword may be empty or NULL pointers. The keyword/text -pairs are put into the array in the order that they are received. -However, some or all of the text chunks may be after the image, so, to -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 -should occur. This is important, as some of these change the color -type and/or bit depth of the data, and some others only work on -certain color types and bit depths. Even though each transformation -checks to see if it has data that it can do something with, you should -make sure to only enable a transformation if it will be valid for the -data. For example, don't swap red and blue on grayscale data. - -The colors used for the background and transparency values should be -supplied in the same format/depth as the current image data. They -are stored in the same format/depth as the image data in a bKGD or tRNS -chunk, so this is what libpng expects for this data. The colors are -transformed to keep in sync with the image data when an application -calls the png_read_update_info() routine (see below). - -Data will be decoded into the supplied row buffers packed into bytes -unless the library has been told to transform it into another format. -For example, 4 bit/pixel paletted or grayscale data will be returned -2 pixels/byte with the leftmost pixel in the high-order bits of the -byte, unless png_set_packing() is called. 8-bit RGB data will be stored -in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha() -is called to insert filler bytes, either before or after each RGB triplet. -16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant -byte of the color value first, unless png_set_strip_16() is called to -transform it to regular RGB RGB triplets, or png_set_filler() or -png_set_add alpha() is called to insert filler bytes, either before or -after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can -be modified with -png_set_filler(), png_set_add_alpha(), or png_set_strip_16(). - -The following code transforms grayscale images of less than 8 to 8 bits, -changes paletted images to RGB, and adds a full alpha channel if there is -transparency information in a tRNS chunk. This is most useful on -grayscale images with bit depths of 2 or 4 or if there is a multiple-image -viewing application that wishes to treat all images in the same way. - - if (color_type == PNG_COLOR_TYPE_PALETTE) - png_set_palette_to_rgb(png_ptr); - - if (color_type == PNG_COLOR_TYPE_GRAY && - bit_depth < 8) png_set_gray_1_2_4_to_8(png_ptr); - - if (png_get_valid(png_ptr, info_ptr, - PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr); - -These three functions are actually aliases for png_set_expand(), added -in libpng version 1.0.4, with the function names expanded to improve code -readability. In some future version they may actually do different -things. - -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) - png_set_strip_16(png_ptr); - -If, for some reason, you don't need the alpha channel on an image, -and you want to remove it rather than combining it with the background -(but the image author certainly had in mind that you *would* combine -it with the background, so that's what you should probably do): - - if (color_type & PNG_COLOR_MASK_ALPHA) - png_set_strip_alpha(png_ptr); - -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); - -PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as -they can, resulting in, for example, 8 pixels per byte for 1 bit -files. This code expands to 1 pixel per byte without changing the -values of the pixels: - - if (bit_depth < 8) - png_set_packing(png_ptr); - -PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels -stored in a PNG image have been "scaled" or "shifted" up to the next -higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to -8 bits/sample in the range [0, 255]). However, it is also possible to -convert the PNG pixel data back to the original bit depth of the image. -This call reduces the pixels back down to the original bit depth: - - png_color_8p sig_bit; - - if (png_get_sBIT(png_ptr, info_ptr, &sig_bit)) - png_set_shift(png_ptr, sig_bit); - -PNG files store 3-color pixels in red, green, blue order. This code -changes the storage of the pixels to blue, green, red: - - if (color_type == PNG_COLOR_TYPE_RGB || - color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_bgr(png_ptr); - -PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them -into 4 or 8 bytes for windowing systems that need them in this format: - - if (color_type == PNG_COLOR_TYPE_RGB) - png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE); - -where "filler" is the 8 or 16-bit number to fill with, and the location is -either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether -you want the filler before the RGB or after. This transformation -does not affect images that already have full alpha channels. To add an -opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which -will generate RGBA pixels. - -Note that png_set_filler() does not change the color type. If you want -to do that, you can add a true alpha channel with - - if (color_type == PNG_COLOR_TYPE_RGB || - color_type == PNG_COLOR_TYPE_GRAY) - png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER); - -where "filler" contains the alpha value to assign to each pixel. -This function was added in libpng-1.2.7. - -If you are reading an image with an alpha channel, and you need the -data as ARGB instead of the normal PNG format RGBA: - - if (color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_swap_alpha(png_ptr); - -For some uses, you may want a grayscale image to be represented as -RGB. This code will do that conversion: - - if (color_type == PNG_COLOR_TYPE_GRAY || - color_type == PNG_COLOR_TYPE_GRAY_ALPHA) - png_set_gray_to_rgb(png_ptr); - -Conversely, you can convert an RGB or RGBA image to grayscale or grayscale -with alpha. - - if (color_type == PNG_COLOR_TYPE_RGB || - color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_rgb_to_gray_fixed(png_ptr, error_action, - int red_weight, int green_weight); - - error_action = 1: silently do the conversion - error_action = 2: issue a warning if the original - image has any pixel where - red != green or red != blue - error_action = 3: issue an error and abort the - conversion if the original - image has any pixel where - red != green or red != blue - - red_weight: weight of red component times 100000 - green_weight: weight of green component times 100000 - If either weight is negative, default - weights (21268, 71514) are used. - -If you have set error_action = 1 or 2, you can -later check whether the image really was gray, after processing -the image rows, with the png_get_rgb_to_gray_status(png_ptr) function. -It will return a png_byte that is zero if the image was gray or -1 if there were any non-gray pixels. bKGD and sBIT data -will be silently converted to grayscale, using the green channel -data, regardless of the error_action setting. - -With red_weight+green_weight<=100000, -the normalized graylevel is computed: - - int rw = red_weight * 65536; - int gw = green_weight * 65536; - int bw = 65536 - (rw + gw); - gray = (rw*red + gw*green + bw*blue)/65536; - -The default values approximate those recommended in the Charles -Poynton's Color FAQ, -Copyright (c) 1998-01-04 Charles Poynton - - Y = 0.212671 * R + 0.715160 * G + 0.072169 * B - -Libpng approximates this with - - Y = 0.21268 * R + 0.7151 * G + 0.07217 * B - -which can be expressed with integers as - - Y = (6969 * R + 23434 * G + 2365 * B)/32768 - -The calculation is done in a linear colorspace, if the image gamma -is known. - -If you have a grayscale and you are using png_set_expand_depth(), -png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to -a higher bit-depth, you must either supply the background color as a gray -value at the original file bit-depth (need_expand = 1) or else supply the -background color as an RGB triplet at the final, expanded bit depth -(need_expand = 0). Similarly, if you are reading a paletted image, you -must either supply the background color as a palette index (need_expand = 1) -or as an RGB triplet that may or may not be in the palette (need_expand = 0). - - png_color_16 my_background; - png_color_16p image_background; - - if (png_get_bKGD(png_ptr, info_ptr, &image_background)) - png_set_background(png_ptr, image_background, - PNG_BACKGROUND_GAMMA_FILE, 1, 1.0); - else - png_set_background(png_ptr, &my_background, - PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0); - -The png_set_background() function tells libpng to composite images -with alpha or simple transparency against the supplied background -color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), -you may use this color, or supply another color more suitable for -the current display (e.g., the background color from a web page). You -need to tell libpng whether the color is in the gamma space of the -display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file -(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one -that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't -know why anyone would use this, but it's here). - -To properly display PNG images on any kind of system, the application needs -to know what the display gamma is. Ideally, the user will know this, and -the application will allow them to set it. One method of allowing the user -to set the display gamma separately for each system is to check for a -SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be -correctly set. - -Note that display_gamma is the overall gamma correction required to produce -pleasing results, which depends on the lighting conditions in the surrounding -environment. In a dim or brightly lit room, no compensation other than -the physical gamma exponent of the monitor is needed, while in a dark room -a slightly smaller exponent is better. - - double gamma, screen_gamma; - - if (/* We have a user-defined screen - gamma value */) - { - screen_gamma = user_defined_screen_gamma; - } - /* One way that applications can share the same - screen gamma value */ - else if ((gamma_str = getenv("SCREEN_GAMMA")) - != NULL) - { - screen_gamma = (double)atof(gamma_str); - } - /* If we don't have another value */ - else - { - screen_gamma = 2.2; /* A good guess for a - PC monitor in a bright office or a dim room */ - screen_gamma = 2.0; /* A good guess for a - PC monitor in a dark room */ - screen_gamma = 1.7 or 1.0; /* A good - guess for Mac systems */ - } - -The png_set_gamma() function handles gamma transformations of the data. -Pass both the file gamma and the current screen_gamma. If the file does -not have a gamma value, you can pass one anyway if you have an idea what -it is (usually 0.45455 is a good guess for GIF images on PCs). Note -that file gammas are inverted from screen gammas. See the discussions -on gamma in the PNG specification for an excellent description of what -gamma is, and why all applications should support it. It is strongly -recommended that PNG viewers support gamma correction. - - if (png_get_gAMA(png_ptr, info_ptr, &gamma)) - png_set_gamma(png_ptr, screen_gamma, gamma); - else - png_set_gamma(png_ptr, screen_gamma, 0.45455); - -If you need to reduce an RGB file to a paletted file, or if a paletted -file has more entries then will fit on your screen, png_set_dither() -will do that. Note that this is a simple match dither that merely -finds the closest color available. This should work fairly well with -optimized palettes, and fairly badly with linear color cubes. If you -pass a palette that is larger then 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 -more intelligent choices when reducing the palette. If there is no -histogram, it may not do as good a job. - - if (color_type & PNG_COLOR_MASK_COLOR) - { - if (png_get_valid(png_ptr, info_ptr, - PNG_INFO_PLTE)) - { - png_uint_16p histogram = NULL; - - png_get_hIST(png_ptr, info_ptr, - &histogram); - png_set_dither(png_ptr, palette, num_palette, - max_screen_colors, histogram, 1); - } - else - { - png_color std_color_cube[MAX_SCREEN_COLORS] = - { ... colors ... }; - - png_set_dither(png_ptr, std_color_cube, - MAX_SCREEN_COLORS, MAX_SCREEN_COLORS, - NULL,0); - } - } - -PNG files describe monochrome as black being zero and white being one. -The following code will reverse this (make black be one and white be -zero): - - if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY) - png_set_invert_mono(png_ptr); - -This function can also be used to invert grayscale and gray-alpha images: - - if (color_type == PNG_COLOR_TYPE_GRAY || - color_type == PNG_COLOR_TYPE_GRAY_ALPHA) - png_set_invert_mono(png_ptr); - -PNG files store 16 bit pixels in network byte order (big-endian, -ie. most significant bits first). This code changes the storage to the -other way (little-endian, i.e. least significant bits first, the -way PCs store them): - - if (bit_depth == 16) - png_set_swap(png_ptr); - -If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you -need to change the order the pixels are packed into bytes, you can use: - - if (bit_depth < 8) - png_set_packswap(png_ptr); - -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 - - png_set_read_user_transform_fn(png_ptr, - read_transform_fn); - -You must supply the function - - void read_transform_fn(png_ptr ptr, row_info_ptr - row_info, png_bytep data) - -See pngtest.c for a working example. Your function will be called -after all of the other transformations have been processed. - -You can also set up a pointer to a user structure for use by your -callback function, and you can inform libpng that your transform -function will change the number of channels or bit depth with the -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: - - voidp read_user_transform_ptr = - png_get_user_transform_ptr(png_ptr); - -The last thing to handle is interlacing; this is covered in detail below, -but you must call the function here if you want libpng to handle expansion -of the interlaced image. - - number_of_passes = png_set_interlace_handling(png_ptr); - -After setting the transformations, libpng can update your png_info -structure to reflect any transformations you've requested with this -call. This is most useful to update the info structure's rowbytes -field so you can use it to allocate your image memory. This function -will also update your palette with the correct screen_gamma and -background if these have been given with the calls above. - - png_read_update_info(png_ptr, info_ptr); - -After you call png_read_update_info(), you can allocate any -memory you need to hold the image. The row data is simply -raw byte data for all forms of images. As the actual allocation -varies among applications, no example will be given. If you -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 -call png_read_image() and libpng will read in all the image data -and put it in the memory area supplied. You will need to pass in -an array of pointers to each row. - -This function automatically handles interlacing, so you don't need -to call png_set_interlace_handling() or call this function multiple -times, or any of that other stuff necessary with png_read_rows(). - - png_read_image(png_ptr, row_pointers); - -where row_pointers is: - - png_bytep row_pointers[height]; - -You can point to void or char or whatever you use for pixels. - -If you don't want to read in the whole image at once, you can -use png_read_rows() instead. If there is no interlacing (check -interlace_type == PNG_INTERLACE_NONE), this is simple: - - png_read_rows(png_ptr, row_pointers, NULL, - number_of_rows); - -where row_pointers is the same as in the png_read_image() call. - -If you are doing this just one row at a time, you can do this with -a single row_pointer instead of an array of row_pointers: - - png_bytep row_pointer = row; - png_read_row(png_ptr, row_pointer, NULL); - -If the file is interlaced (interlace_type != 0 in the IHDR chunk), things -get somewhat harder. The only current (PNG Specification version 1.2) -interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7) -is a somewhat complicated 2D interlace scheme, known as Adam7, that -breaks down an image into seven smaller images of varying size, based -on an 8x8 grid. - -libpng can fill out those images or it can give them to you "as is". -If you want them filled out, there are two ways to do that. The one -mentioned in the PNG specification is to expand each pixel to cover -those pixels that have not been read yet (the "rectangle" method). -This results in a blocky image for the first pass, which gradually -smooths out as more pixels are read. The other method is the "sparkle" -method, where pixels are drawn only in their final locations, with the -rest of the image remaining whatever colors they were initialized to -before the start of the read. The first method usually looks better, -but tends to be slower, as there are more pixels to put in the rows. - -If you don't want libpng to handle the interlacing details, just call -png_read_rows() seven times to read in all seven images. Each of the -images is a valid image by itself, or they can all be combined on an -8x8 grid to form a single image (although if you intend to combine them -you would be far better off using the libpng interlace handling). - -The first pass will return an image 1/8 as wide as the entire image -(every 8th column starting in column 0) and 1/8 as high as the original -(every 8th row starting in row 0), the second will be 1/8 as wide -(starting in column 4) and 1/8 as high (also starting in row 0). The -third pass will be 1/4 as wide (every 4th pixel starting in column 0) and -1/8 as high (every 8th row starting in row 4), and the fourth pass will -be 1/4 as wide and 1/4 as high (every 4th column starting in column 2, -and every 4th row starting in row 0). The fifth pass will return an -image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2), -while the sixth pass will be 1/2 as wide and 1/2 as high as the original -(starting in column 1 and row 0). The seventh and final pass will be as -wide as the original, and 1/2 as high, containing all of the odd -numbered scanlines. Phew! - -If you want libpng to expand the images, call this before calling -png_start_read_image() or png_read_update_info(): - - if (interlace_type == PNG_INTERLACE_ADAM7) - number_of_passes - = png_set_interlace_handling(png_ptr); - -This will return the number of passes needed. Currently, this -is seven, but may change if another interlace type is added. -This function can be called even if the file is not interlaced, -where it will return one pass. - -If you are not going to display the image after each pass, but are -going to wait until the entire image is read in, use the sparkle -effect. This effect is faster and the end result of either method -is exactly the same. If you are planning on displaying the image -after each pass, the "rectangle" effect is generally considered the -better looking one. - -If you only want the "sparkle" effect, just call png_read_rows() as -normal, with the third parameter NULL. Make sure you make pass over -the image number_of_passes times, and you don't change the data in the -rows between calls. You can change the locations of the data, just -not the data. Each pass only writes the pixels appropriate for that -pass, and assumes the data from previous passes is still valid. - - png_read_rows(png_ptr, row_pointers, NULL, - number_of_rows); - -If you only want the first effect (the rectangles), do the same as -before except pass the row buffer in the third parameter, and leave -the second parameter NULL. - - png_read_rows(png_ptr, NULL, row_pointers, - number_of_rows); - -.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); - -When you are done, you can free all memory allocated by libpng like this: - - png_destroy_read_struct(&png_ptr, &info_ptr, - &end_info); - -It is also possible to individually free the info_ptr members that -point to libpng-allocated storage with the following function: - - png_free_data(png_ptr, info_ptr, mask, seq) - mask - identifies data to be freed, a mask - containing the logical OR of one or - more of - PNG_FREE_PLTE, PNG_FREE_TRNS, - PNG_FREE_HIST, PNG_FREE_ICCP, - PNG_FREE_PCAL, PNG_FREE_ROWS, - PNG_FREE_SCAL, PNG_FREE_SPLT, - PNG_FREE_TEXT, PNG_FREE_UNKN, - or simply PNG_FREE_ALL - seq - sequence number of item to be freed - (-1 for all items) - -This function may be safely called when the relevant storage has -already been freed, or has not yet been allocated, or was allocated -by the user and not by libpng, and will in those -cases do nothing. The "seq" parameter is ignored if only one item -of the selected data type, such as PLTE, is allowed. If "seq" is not --1, and multiple items are allowed for the data type identified in -the mask, such as text or sPLT, only the n'th item in the structure -is freed, where n is "seq". - -The default behavior is only to free data that was allocated internally -by libpng. This can be changed, so that libpng will not free the data, -or so that it will free data that was allocated by the user with png_malloc() -or png_zalloc() and passed in via a png_set_*() function, with - - png_data_freer(png_ptr, info_ptr, freer, mask) - mask - which data elements are affected - same choices as in png_free_data() - freer - one of - PNG_DESTROY_WILL_FREE_DATA - PNG_SET_WILL_FREE_DATA - PNG_USER_WILL_FREE_DATA - -This function only affects data that has already been allocated. -You can call this function after reading the PNG data but before calling -any png_set_*() functions, to control whether the user or the png_set_*() -function is responsible for freeing any existing data that might be present, -and again after the png_set_*() functions to control whether the user -or png_destroy_*() is supposed to free the data. When the user assumes -responsibility for libpng-allocated data, the application must use -png_free() to free it, and when the user transfers responsibility to libpng -for data that the user has allocated, the user must have used png_malloc() -or png_zalloc() to allocate it. - -If you allocated your row_pointers in a single block, as suggested above in -the description of the high level read interface, you must not transfer -responsibility for freeing it to the png_set_rows or png_read_destroy function, -because they would also try to free the individual row_pointers[i]. - -If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword -separately, do not transfer responsibility for freeing text_ptr to libpng, -because when libpng fills a png_text structure it combines these members with -the key member, and png_free_data() will free only text_ptr.key. Similarly, -if you transfer responsibility for free'ing text_ptr from libpng to your -application, your application must not separately free those members. - -The png_free_data() function will turn off the "valid" flag for anything -it frees. If you need to turn the flag off for a chunk that was freed by your -application instead of by libpng, you can use - - png_set_invalid(png_ptr, info_ptr, mask); - mask - identifies the chunks to be made invalid, - containing the logical OR of one or - more of - PNG_INFO_gAMA, PNG_INFO_sBIT, - PNG_INFO_cHRM, PNG_INFO_PLTE, - PNG_INFO_tRNS, PNG_INFO_bKGD, - PNG_INFO_hIST, PNG_INFO_pHYs, - PNG_INFO_oFFs, PNG_INFO_tIME, - PNG_INFO_pCAL, PNG_INFO_sRGB, - PNG_INFO_iCCP, PNG_INFO_sPLT, - PNG_INFO_sCAL, PNG_INFO_IDAT - -For a more compact example of reading a PNG image, see the file example.c. - -.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 -png_read_end(), you make one call to png_process_data(), which calls -callbacks when it has the info, a row, or the end of the image. You -set up these callbacks with png_set_progressive_read_fn(). You don't -have to worry about the input/output functions of libpng, as you are -giving the library the data directly in png_process_data(). I will -assume that you have read the section on reading PNG files above, -so I will only highlight the differences (although I will show -all of the code). - -png_structp png_ptr; -png_infop info_ptr; - - /* An example code fragment of how you would - initialize the progressive reader in your - application. */ - int - initialize_png_reader() - { - png_ptr = png_create_read_struct - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - if (!png_ptr) - return (ERROR); - info_ptr = png_create_info_struct(png_ptr); - if (!info_ptr) - { - png_destroy_read_struct(&png_ptr, (png_infopp)NULL, - (png_infopp)NULL); - return (ERROR); - } - - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - - /* This one's new. You can provide functions - to be called when the header info is valid, - when each row is completed, and when the image - is finished. If you aren't using all functions, - you can specify NULL parameters. Even when all - three functions are NULL, you need to call - png_set_progressive_read_fn(). You can use - any struct as the user_ptr (cast to a void pointer - for the function call), and retrieve the pointer - from inside the callbacks using the function - - png_get_progressive_ptr(png_ptr); - - which will return a void pointer, which you have - to cast appropriately. - */ - png_set_progressive_read_fn(png_ptr, (void *)user_ptr, - info_callback, row_callback, end_callback); - - return 0; - } - - /* A code fragment that you call as you receive blocks - of data */ - int - process_data(png_bytep buffer, png_uint_32 length) - { - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - - /* This one's new also. Simply give it a chunk - of data from the file stream (in order, of - course). On machines with segmented memory - models machines, don't give it any more than - 64K. The library seems to run fine with sizes - of 4K. Although you can give it much less if - necessary (I assume you can give it chunks of - 1 byte, I haven't tried less then 256 bytes - yet). When this function returns, you may - want to display any rows that were generated - in the row callback if you don't already do - so there. - */ - png_process_data(png_ptr, info_ptr, buffer, length); - return 0; - } - - /* This function is called (as set by - png_set_progressive_read_fn() above) when enough data - has been supplied so all of the header has been - read. - */ - void - info_callback(png_structp png_ptr, png_infop info) - { - /* Do any setup here, including setting any of - the transformations mentioned in the Reading - PNG files section. For now, you _must_ call - either png_start_read_image() or - png_read_update_info() after all the - transformations are set (even if you don't set - any). You may start getting rows before - png_process_data() returns, so this is your - last chance to prepare for that. - */ - } - - /* This function is called when each row of image - data is complete */ - void - row_callback(png_structp png_ptr, png_bytep new_row, - png_uint_32 row_num, int pass) - { - /* If the image is interlaced, and you turned - on the interlace handler, this function will - be called for every row in every pass. Some - of these rows will not be changed from the - previous pass. When the row is not changed, - the new_row variable will be NULL. The rows - and passes are called in order, so you don't - really need the row_num and pass, but I'm - supplying them because it may make your life - easier. - - For the non-NULL rows of interlaced images, - you must call png_progressive_combine_row() - passing in the row and the old row. You can - call this function for NULL rows (it will just - return) and for non-interlaced images (it just - does the memcpy for you) if it will make the - code easier. Thus, you can just do this for - all cases: - */ - - png_progressive_combine_row(png_ptr, old_row, - new_row); - - /* where old_row is what was displayed for - previously for the row. Note that the first - pass (pass == 0, really) will completely cover - the old row, so the rows do not have to be - initialized. After the first pass (and only - for interlaced images), you will have to pass - the current row, and the function will combine - the old row and the new row. - */ - } - - void - end_callback(png_structp png_ptr, png_infop info) - { - /* This function is called after the whole image - has been read, including any chunks after the - image (up to and including the IEND). You - will usually have the same info chunk as you - had in the header, although some data may have - been added to the comments and time fields. - - Most people won't do much here, perhaps setting - a flag that marks the image as finished. - */ - } - - - -.SH IV. Writing - -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 -custom writing functions. See the discussion under Customizing libpng. - - FILE *fp = fopen(file_name, "wb"); - if (!fp) - { - return (ERROR); - } - -Next, png_struct and png_info need to be allocated and initialized. -As these can be both relatively large, you may not want to store these -on the stack, unless you have stack space to spare. Of course, you -will want to check if they return NULL. If you are also reading, -you won't want to name your read structure and your write structure -both "png_ptr"; you can call them anything you like, such as -"read_ptr" and "write_ptr". Look at pngtest.c, for example. - - png_structp png_ptr = png_create_write_struct - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - if (!png_ptr) - return (ERROR); - - png_infop info_ptr = png_create_info_struct(png_ptr); - if (!info_ptr) - { - png_destroy_write_struct(&png_ptr, - (png_infopp)NULL); - return (ERROR); - } - -If you want to use your own memory allocation routines, -define PNG_USER_MEM_SUPPORTED and use -png_create_write_struct_2() instead of png_create_write_struct(): - - png_structp png_ptr = png_create_write_struct_2 - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn, (png_voidp) - user_mem_ptr, user_malloc_fn, user_free_fn); - -After you have these structures, you will need to set up the -error handling. When libpng encounters an error, it expects to -longjmp() back to your routine. Therefore, you will need to call -setjmp() and pass the png_jmpbuf(png_ptr). If you -write the file from different routines, you will need to update -the png_jmpbuf(png_ptr) every time you enter a new routine that will -call a png_*() function. See your documentation of setjmp/longjmp -for your compiler for more information on setjmp/longjmp. See -the discussion on libpng error handling in the Customizing Libpng -section below for more information on the libpng error handling. - - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_write_struct(&png_ptr, &info_ptr); - fclose(fp); - return (ERROR); - } - ... - 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 -opened in binary mode. Again, if you wish to handle writing data in -another way, see the discussion on libpng I/O handling in the Customizing -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. -You must supply a function - - void write_row_callback(png_ptr, png_uint_32 row, - int pass); - { - /* put your code here */ - } - -(You can give it another name that you like instead of "write_row_callback") - -To inform libpng about your function, use - - png_set_write_status_fn(png_ptr, write_row_callback); - -You now have the option of modifying how the compression library will -run. The following functions are mainly for testing, but may be useful -in some cases, like if you need to write PNG files extremely fast and -are willing to give up some compression, or if you want to get the -maximum possible compression at the expense of slower writing. If you -have no special needs in this area, let the library do what it wants by -not calling this function at all, as it has been tuned to deliver a good -speed/compression ratio. The second parameter to png_set_filter() is -the filter method, for which the only valid values are 0 (as of the -July 1999 PNG specification, version 1.2) or 64 (if you are writing -a PNG datastream that is to be embedded in a MNG datastream). The third -parameter is a flag that indicates which filter type(s) are to be tested -for each scanline. See the PNG specification for details on the specific filter -types. - - - /* turn on or off filtering, and/or choose - specific filters. You can use either a single - PNG_FILTER_VALUE_NAME or the logical OR of one - or more PNG_FILTER_NAME masks. */ - png_set_filter(png_ptr, 0, - PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE | - PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB | - PNG_FILTER_UP | PNG_FILTER_VALUE_UP | - PNG_FILTER_AVE | PNG_FILTER_VALUE_AVE | - PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH| - PNG_ALL_FILTERS); - -If an application -wants to start and stop using particular filters during compression, -it should start out with all of the filters (to ensure that the previous -row of pixels will be stored in case it's needed later), and then add -and remove them after the start of compression. - -If you are writing a PNG datastream that is to be embedded in a MNG -datastream, the second parameter can be either 0 or 64. - -The png_set_compression_*() functions interface to the zlib compression -library, and should mostly be ignored unless you really know what you are -doing. The only generally useful call is png_set_compression_level() -which changes how much time zlib spends on trying to compress the image -data. See the Compression Library (zlib.h and algorithm.txt, distributed -with zlib) for details on the compression levels. - - /* set the zlib compression level */ - png_set_compression_level(png_ptr, - Z_BEST_COMPRESSION); - - /* set other zlib parameters */ - png_set_compression_mem_level(png_ptr, 8); - png_set_compression_strategy(png_ptr, - Z_DEFAULT_STRATEGY); - png_set_compression_window_bits(png_ptr, 15); - png_set_compression_method(png_ptr, 8); - png_set_compression_buffer_size(png_ptr, 8192) - -extern PNG_EXPORT(void,png_set_zbuf_size) - -.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 -chunk (as of PNG Specification 1.2, anyway). See png_write_end() and -the latest PNG specification for more information on that. If you -wish to write them before the image, fill them in now, and flag that -data as being valid. If you want to wait until after the data, don't -fill them until png_write_end(). For all the fields in png_info and -their data types, see png.h. For explanations of what the fields -contain, see the PNG specification. - -Some of the more important parts of the png_info are: - - png_set_IHDR(png_ptr, info_ptr, width, height, - bit_depth, color_type, interlace_type, - compression_type, filter_method) - width - holds the width of the image - in pixels (up to 2^31). - height - holds the height of the image - in pixels (up to 2^31). - bit_depth - holds the bit depth of one of the - image channels. - (valid values are 1, 2, 4, 8, 16 - and depend also on the - color_type. See also significant - bits (sBIT) below). - color_type - describes which color/alpha - channels are present. - PNG_COLOR_TYPE_GRAY - (bit depths 1, 2, 4, 8, 16) - PNG_COLOR_TYPE_GRAY_ALPHA - (bit depths 8, 16) - PNG_COLOR_TYPE_PALETTE - (bit depths 1, 2, 4, 8) - PNG_COLOR_TYPE_RGB - (bit_depths 8, 16) - PNG_COLOR_TYPE_RGB_ALPHA - (bit_depths 8, 16) - - PNG_COLOR_MASK_PALETTE - PNG_COLOR_MASK_COLOR - PNG_COLOR_MASK_ALPHA - - interlace_type - PNG_INTERLACE_NONE or - PNG_INTERLACE_ADAM7 - compression_type - (must be - PNG_COMPRESSION_TYPE_DEFAULT) - filter_method - (must be PNG_FILTER_TYPE_DEFAULT - or, if you are writing a PNG to - be embedded in a MNG datastream, - can also be - PNG_INTRAPIXEL_DIFFERENCING) - - png_set_PLTE(png_ptr, info_ptr, palette, - num_palette); - palette - the palette for the file - (array of png_color) - num_palette - number of entries in the palette - - png_set_gAMA(png_ptr, info_ptr, gamma); - gamma - the gamma the image was created - at (PNG_INFO_gAMA) - - png_set_sRGB(png_ptr, info_ptr, srgb_intent); - srgb_intent - the rendering intent - (PNG_INFO_sRGB) The presence of - the sRGB chunk means that the pixel - data is in the sRGB color space. - This chunk also implies specific - values of gAMA and cHRM. Rendering - intent is the CSS-1 property that - has been defined by the International - Color Consortium - (http://www.color.org). - It can be one of - PNG_sRGB_INTENT_SATURATION, - PNG_sRGB_INTENT_PERCEPTUAL, - PNG_sRGB_INTENT_ABSOLUTE, or - PNG_sRGB_INTENT_RELATIVE. - - - png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr, - srgb_intent); - srgb_intent - the rendering intent - (PNG_INFO_sRGB) The presence of the - sRGB chunk means that the pixel - data is in the sRGB color space. - This function also causes gAMA and - cHRM chunks with the specific values - that are consistent with sRGB to be - written. - - png_set_iCCP(png_ptr, info_ptr, name, compression_type, - profile, proflen); - name - The profile name. - compression - The compression type; always - PNG_COMPRESSION_TYPE_BASE for PNG 1.0. - You may give NULL to this argument to - ignore it. - profile - International Color Consortium color - profile data. May contain NULs. - proflen - length of profile data in bytes. - - png_set_sBIT(png_ptr, info_ptr, sig_bit); - sig_bit - the number of significant bits for - (PNG_INFO_sBIT) each of the gray, red, - green, and blue channels, whichever are - appropriate for the given color type - (png_color_16) - - png_set_tRNS(png_ptr, info_ptr, trans, num_trans, - trans_values); - trans - array of transparent entries for - palette (PNG_INFO_tRNS) - trans_values - graylevel or color sample values 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); - (PNG_INFO_hIST) - hist - histogram of palette (array of - png_uint_16) - - png_set_tIME(png_ptr, info_ptr, mod_time); - mod_time - time image was last modified - (PNG_VALID_tIME) - - png_set_bKGD(png_ptr, info_ptr, background); - background - background color (PNG_VALID_bKGD) - - png_set_text(png_ptr, info_ptr, text_ptr, num_text); - text_ptr - array of png_text holding image - comments - 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. Must contain - 1-79 characters. - text_ptr[i].text - text comments for current - keyword. Can be NULL or empty. - 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 or - empty for unknown). - text_ptr[i].translated_keyword - keyword in UTF-8 (NULL - or empty for unknown). - num_text - number of comments - - png_set_sPLT(png_ptr, info_ptr, &palette_ptr, - num_spalettes); - palette_ptr - array of png_sPLT_struct structures - to be added to the list of palettes - in the info structure. - num_spalettes - number of palette structures to be - added. - - png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y, - unit_type); - offset_x - positive offset from the left - edge of the screen - offset_y - positive offset from the top - edge of the screen - unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER - - png_set_pHYs(png_ptr, info_ptr, res_x, res_y, - unit_type); - res_x - pixels/unit physical resolution - in x direction - res_y - pixels/unit physical resolution - in y direction - unit_type - PNG_RESOLUTION_UNKNOWN, - PNG_RESOLUTION_METER - - png_set_sCAL(png_ptr, info_ptr, unit, width, height) - unit - physical scale units (an integer) - width - width of a pixel in physical scale units - height - height of a pixel in physical scale units - (width and height are doubles) - - png_set_sCAL_s(png_ptr, info_ptr, unit, width, height) - unit - physical scale units (an integer) - width - width of a pixel in physical scale units - height - height of a pixel in physical scale units - (width and height are strings like "2.54") - - png_set_unknown_chunks(png_ptr, info_ptr, &unknowns, - num_unknowns) - unknowns - array of png_unknown_chunk - structures holding unknown chunks - unknowns[i].name - name of unknown chunk - unknowns[i].data - data of unknown chunk - unknowns[i].size - size of unknown chunk's data - 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. Within each of the "locations", -the chunks are sequenced according to their position in the -structure (that is, the value of "i", which is the order in which -the chunk was either read from the input file or defined with -png_set_unknown_chunks). - -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. -Each png_text structure holds a language code, a keyword, a text value, -and a compression type. - -The compression types have the same valid numbers as the compression -types of the image data. Currently, the only valid number is zero. -However, you can store text either compressed or uncompressed, unlike -images, which always have to be compressed. So if you don't want the -text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE. -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. -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 -png_write_end() with the same struct. - -The keywords that are given in the PNG Specification are: - - Title Short (one line) title or - caption for image - Author Name of image's creator - Description Description of image (possibly long) - Copyright Copyright notice - Creation Time Time of original image creation - (usually RFC 1123 format, see below) - Software Software used to create the image - Disclaimer Legal disclaimer - Warning Warning of nature of content - Source Device used to create the image - Comment Miscellaneous comment; conversion - from other image format - -The keyword-text pairs work like this. Keywords should be short -simple descriptions of what the comment is about. Some typical -keywords are found in the PNG specification, as is some recommendations -on keywords. You can repeat keywords in a file. You can even write -some text before the image and some after. For example, you may want -to put a description of the image before the image, but leave the -disclaimer until after, so viewers working over modem connections -don't have to wait for the disclaimer to go over the modem before -they start seeing the image. Finally, keywords should be full -words, not abbreviations. Keywords and text are in the ISO 8859-1 -(Latin-1) character set (a superset of regular ASCII) and can not -contain NUL characters, and should not contain control or other -unprintable characters. To make the comments widely readable, stick -with basic ASCII, and avoid machine specific character set extensions -like the IBM-PC character set. The keyword must be present, but -you can leave off the text string on non-compressed pairs. -Compressed pairs must have a text string, as only the text string -is compressed anyway, so the compression would be meaningless. - -PNG supports modification time via the png_time structure. Two -conversion routines are provided, png_convert_from_time_t() for -time_t and png_convert_from_struct_tm() for struct tm. The -time_t routine uses gmtime(). You don't have to use either of -these, but if you wish to fill in the png_time structure directly, -you should provide the time in universal time (GMT) if possible -instead of your local time. Note that the year number is the full -year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and -that months start with 1. - -If you want to store the time of the original image creation, you should -use a plain tEXt chunk with the "Creation Time" keyword. This is -necessary because the "creation time" of a PNG image is somewhat vague, -depending on whether you mean the PNG file, the time the image was -created in a non-PNG format, a still photo from which the image was -scanned, or possibly the subject matter itself. In order to facilitate -machine-readable dates, it is recommended that the "Creation Time" -tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"), -although this isn't a requirement. Unlike the tIME chunk, the -"Creation Time" tEXt chunk is not expected to be automatically changed -by the software. To facilitate the use of RFC 1123 dates, a function -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 -png_write_info_before_PLTE, png_write_info, or png_write_end function. -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. - -.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 -in the info structure. All defined output -transformations are permitted, 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 in the info structure (you can use -png_set_rows() to put image data in the info structure), 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 the set of transformations indicated by the transform mask, -then png_write_image(), and finally png_write_end(). - -(The final parameter of this call is not yet used. Someday it might point -to transformation parameters required by some future output transform.) - -You must use png_transforms and not call any png_set_transform() functions -when you use png_write_png(). - -.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: - - png_write_info_before_PLTE(png_ptr, info_ptr); - png_set_unknown_chunks(png_ptr, info_ptr, ...); - png_write_info(png_ptr, info_ptr); - -After you've written the file 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 -should occur. This is important, as some of these change the color -type and/or bit depth of the data, and some others only work on -certain color types and bit depths. Even though each transformation -checks to see if it has data that it can do something with, you should -make sure to only enable a transformation if it will be valid for the -data. For example, don't swap red and blue on grayscale data. - -PNG files store RGB pixels packed into 3 or 6 bytes. This code tells -the library to strip input data that has 4 or 8 bytes per pixel down -to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2 -bytes per pixel). - - png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE); - -where the 0 is unused, and the location is either PNG_FILLER_BEFORE or -PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel -is stored XRGB or RGBX. - -PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as -they can, resulting in, for example, 8 pixels per byte for 1 bit files. -If the data is supplied at 1 pixel per byte, use this code, which will -correctly pack the pixels into a single byte: - - png_set_packing(png_ptr); - -PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your -data is of another bit depth, you can write an sBIT chunk into the -file so that decoders can recover the original data if desired. - - /* Set the true bit depth of the image data */ - if (color_type & PNG_COLOR_MASK_COLOR) - { - sig_bit.red = true_bit_depth; - sig_bit.green = true_bit_depth; - sig_bit.blue = true_bit_depth; - } - else - { - sig_bit.gray = true_bit_depth; - } - if (color_type & PNG_COLOR_MASK_ALPHA) - { - sig_bit.alpha = true_bit_depth; - } - - png_set_sBIT(png_ptr, info_ptr, &sig_bit); - -If the data is stored in the row buffer in a bit depth other than -one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG), -this will scale the values to appear to be the correct bit depth as -is required by PNG. - - png_set_shift(png_ptr, &sig_bit); - -PNG files store 16 bit pixels in network byte order (big-endian, -ie. most significant bits first). This code would be used if they are -supplied the other way (little-endian, i.e. least significant bits -first, the way PCs store them): - - if (bit_depth > 8) - png_set_swap(png_ptr); - -If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you -need to change the order the pixels are packed into bytes, you can use: - - if (bit_depth < 8) - png_set_packswap(png_ptr); - -PNG files store 3 color pixels in red, green, blue order. This code -would be used if they are supplied as blue, green, red: - - png_set_bgr(png_ptr); - -PNG files describe monochrome as black being zero and white being -one. This code would be used if the pixels are supplied with this reversed -(black being one and white being zero): - - png_set_invert_mono(png_ptr); - -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 - - png_set_write_user_transform_fn(png_ptr, - write_transform_fn); - -You must supply the function - - void write_transform_fn(png_ptr ptr, row_info_ptr - row_info, png_bytep data) - -See pngtest.c for a working example. Your function will be called -before any of the other transformations are processed. - -You can also set up a pointer to a user structure for use by your -callback function. - - png_set_user_transform_info(png_ptr, user_ptr, 0, 0); - -The user_channels and user_depth parameters of this function are ignored -when writing; you can set them to zero as shown. - -You can retrieve the pointer via the function png_get_user_transform_ptr(). -For example: - - voidp write_user_transform_ptr = - png_get_user_transform_ptr(png_ptr); - -It is possible to have libpng flush any pending output, either manually, -or automatically after a certain number of lines have been written. To -flush the output stream a single time call: - - png_write_flush(png_ptr); - -and to have libpng flush the output stream periodically after a certain -number of scanlines have been written, call: - - png_set_flush(png_ptr, nrows); - -Note that the distance between rows is from the last time png_write_flush() -was called, or the first row of the image if it has never been called. -So if you write 50 lines, and then png_set_flush 25, it will flush the -output on the next scanline, and every 25 lines thereafter, unless -png_write_flush() is called before 25 more lines have been written. -If nrows is too small (less than about 10 lines for a 640 pixel wide -RGB image) the image compression may decrease noticeably (although this -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 you have the -whole image in memory, you can just call png_write_image() and libpng -will write the image. You will need to pass in an array of pointers to -each row. This function automatically handles interlacing, so you don't -need to call png_set_interlace_handling() or call this function multiple -times, or any of that other stuff necessary with png_write_rows(). - - png_write_image(png_ptr, row_pointers); - -where row_pointers is: - - png_byte *row_pointers[height]; - -You can point to void or char or whatever you use for pixels. - -If you don't want to write the whole image at once, you can -use png_write_rows() instead. If the file is not interlaced, -this is simple: - - png_write_rows(png_ptr, row_pointers, - number_of_rows); - -row_pointers is the same as in the png_write_image() call. - -If you are just writing one row at a time, you can do this with -a single row_pointer instead of an array of row_pointers: - - png_bytep row_pointer = row; - - 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 the 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 -these images for you, or you can do them yourself. If you want to -build them yourself, see the PNG specification for details of which -pixels to write when. - -If you don't want libpng to handle the interlacing details, just -use png_set_interlace_handling() and call png_write_rows() the -correct number of times to write all seven sub-images. - -If you want libpng to build the sub-images, call this before you start -writing any rows: - - number_of_passes = - png_set_interlace_handling(png_ptr); - -This will return the number of passes needed. Currently, this -is seven, but may change if another interlace type is added. - -Then write the complete image number_of_passes times. - - png_write_rows(png_ptr, row_pointers, - number_of_rows); - -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, -you can pass NULL. - - png_write_end(png_ptr, info_ptr); - -When you are done, you can free all memory used by libpng like this: - - png_destroy_write_struct(&png_ptr, &info_ptr); - -It is also possible to individually free the info_ptr members that -point to libpng-allocated storage with the following function: - - png_free_data(png_ptr, info_ptr, mask, seq) - mask - identifies data to be freed, a mask - containing the logical OR of one or - more of - PNG_FREE_PLTE, PNG_FREE_TRNS, - PNG_FREE_HIST, PNG_FREE_ICCP, - PNG_FREE_PCAL, PNG_FREE_ROWS, - PNG_FREE_SCAL, PNG_FREE_SPLT, - PNG_FREE_TEXT, PNG_FREE_UNKN, - or simply PNG_FREE_ALL - seq - sequence number of item to be freed - (-1 for all items) - -This function may be safely called when the relevant storage has -already been freed, or has not yet been allocated, or was allocated -by the user and not by libpng, and will in those -cases do nothing. The "seq" parameter is ignored if only one item -of the selected data type, such as PLTE, is allowed. If "seq" is not --1, and multiple items are allowed for the data type identified in -the mask, such as text or sPLT, only the n'th item in the structure -is freed, where n is "seq". - -If you allocated data such as a palette that you passed -in to libpng with png_set_*, you must not free it until just before the call to -png_destroy_write_struct(). - -The default behavior is only to free data that was allocated internally -by libpng. This can be changed, so that libpng will not free the data, -or so that it will free data that was allocated by the user with png_malloc() -or png_zalloc() and passed in via a png_set_*() function, with - - png_data_freer(png_ptr, info_ptr, freer, mask) - mask - which data elements are affected - same choices as in png_free_data() - freer - one of - PNG_DESTROY_WILL_FREE_DATA - PNG_SET_WILL_FREE_DATA - PNG_USER_WILL_FREE_DATA - -For example, to transfer responsibility for some data from a read structure -to a write structure, you could use - - png_data_freer(read_ptr, read_info_ptr, - PNG_USER_WILL_FREE_DATA, - PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST) - png_data_freer(write_ptr, write_info_ptr, - PNG_DESTROY_WILL_FREE_DATA, - PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST) - -thereby briefly reassigning responsibility for freeing to the user but -immediately afterwards reassigning it once more to the write_destroy -function. Having done this, it would then be safe to destroy the read -structure and continue to use the PLTE, tRNS, and hIST data in the write -structure. - -This function only affects data that has already been allocated. -You can call this function before calling after the png_set_*() functions -to control whether the user or png_destroy_*() is supposed to free the data. -When the user assumes responsibility for libpng-allocated data, the -application must use -png_free() to free it, and when the user transfers responsibility to libpng -for data that the user has allocated, the user must have used png_malloc() -or png_zalloc() to allocate it. - -If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword -separately, do not transfer responsibility for freeing text_ptr to libpng, -because when libpng fills a png_text structure it combines these members with -the key member, and png_free_data() will free only text_ptr.key. Similarly, -if you transfer responsibility for free'ing text_ptr from libpng to your -application, your application must not separately free those members. -For a more compact example of writing a PNG image, see the file example.c. - -.SH V. Modifying/Customizing libpng: - -There are three issues here. The first is changing how libpng does -standard things like memory allocation, input/output, and error handling. -The second deals with more complicated things like adding new chunks, -adding new transformations, and generally changing how libpng works. -Both of those are compile-time issues; that is, they are generally -determined at the time the code is written, and there is rarely a need -to provide the user with a means of changing them. The third is a -run-time issue: choosing between and/or tuning one or more alternate -versions of computationally intensive routines; specifically, optimized -assembly-language (and therefore compiler- and platform-dependent) -versions. - -Memory allocation, input/output, and error handling - -All of the memory allocation, input/output, and error handling in libpng -goes through callbacks that are user-settable. The default routines are -in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change -these functions, call the appropriate png_set_*_fn() function. - -Memory allocation is done through the functions png_malloc() -and png_free(). These currently just call the standard C functions. If -your pointers can't access more then 64K at a time, you will want to set -MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling -memory allocation on a platform will change between applications, these -functions must be modified in the library at compile time. If you prefer -to use a different method of allocating and freeing data, you can use -png_create_read_struct_2() or png_create_write_struct_2() to register -your own functions as described above. -These functions also provide a void pointer that can be retrieved via - - mem_ptr=png_get_mem_ptr(png_ptr); - -Your replacement memory functions must have prototypes as follows: - - png_voidp malloc_fn(png_structp png_ptr, - png_size_t size); - void free_fn(png_structp png_ptr, png_voidp ptr); - -Your malloc_fn() must return NULL in case of failure. The png_malloc() -function will normally call png_error() if it receives a NULL from the -system memory allocator or from your replacement malloc_fn(). - -Input/Output in libpng is done through png_read() and png_write(), -which currently just call fread() and fwrite(). The FILE * is stored in -png_struct and is initialized via png_init_io(). If you wish to change -the method of I/O, the library supplies callbacks that you can set -through the function png_set_read_fn() and png_set_write_fn() at run -time, instead of calling the png_init_io() function. These functions -also provide a void pointer that can be retrieved via the function -png_get_io_ptr(). For example: - - png_set_read_fn(png_structp read_ptr, - voidp read_io_ptr, png_rw_ptr read_data_fn) - - png_set_write_fn(png_structp write_ptr, - voidp write_io_ptr, png_rw_ptr write_data_fn, - png_flush_ptr output_flush_fn); - - voidp read_io_ptr = png_get_io_ptr(read_ptr); - voidp write_io_ptr = png_get_io_ptr(write_ptr); - -The replacement I/O functions must have prototypes as follows: - - void user_read_data(png_structp png_ptr, - png_bytep data, png_size_t length); - void user_write_data(png_structp png_ptr, - png_bytep data, png_size_t length); - void user_flush_data(png_structp png_ptr); - -Supplying NULL for the read, write, or flush functions sets them back -to using the default C stream functions. It is an error to read from -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() (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_CONSOLE_IO defined -(because you don't want the messages) or PNG_NO_STDIO defined (because -fprintf() isn't available). If you wish to change the behavior of the error -functions, you will need to set up your own message callbacks. These -functions are normally supplied at the time that the png_struct is created. -It is also possible to redirect errors and warnings to your own replacement -functions after png_create_*_struct() has been called by calling: - - png_set_error_fn(png_structp png_ptr, - png_voidp error_ptr, png_error_ptr error_fn, - png_error_ptr warning_fn); - - png_voidp error_ptr = png_get_error_ptr(png_ptr); - -If NULL is supplied for either error_fn or warning_fn, then the libpng -default function will be used, calling fprintf() and/or longjmp() if a -problem is encountered. The replacement error functions should have -parameters as follows: - - void user_error_fn(png_structp png_ptr, - png_const_charp error_msg); - void user_warning_fn(png_structp png_ptr, - png_const_charp warning_msg); - -The motivation behind using setjmp() and longjmp() is the C++ throw and -catch exception handling methods. This makes the code much easier to write, -as there is no need to check every return code of every function call. -However, there are some uncertainties about the status of local variables -after a longjmp, so the user may want to be careful about doing anything after -setjmp returns non-zero besides returning itself. Consult your compiler -documentation for more details. For an alternative approach, you may wish -to use the "cexcept" facility (see http://cexcept.sourceforge.net). - -.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 -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. - -.SS Configuring for 16 bit platforms - -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. - -.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. - -.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 -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 *. - -.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 -warning functions at the time that png_create_*_struct() is called, -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.). - -.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 -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. - -.SS Configuring zlib: - -There are special functions to configure the compression. Perhaps the -most useful one changes the compression level, which currently uses -input compression values in the range 0 - 9. The library normally -uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests -have shown that for a large majority of images, compression values in -the range 3-6 compress nearly as well as higher levels, and do so much -faster. For online applications it may be desirable to have maximum speed -(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also -specify no compression (Z_NO_COMPRESSION = 0), but this would create -files larger than just storing the raw bitmap. You can specify the -compression level by calling: - - png_set_compression_level(png_ptr, level); - -Another useful one is to reduce the memory level used by the library. -The memory level defaults to 8, but it can be lowered if you are -short on memory (running DOS, for example, where you only have 640K). -Note that the memory level does have an effect on compression; among -other things, lower levels will result in sections of incompressible -data being emitted in smaller stored blocks, with a correspondingly -larger relative overhead of up to 15% in the worst case. - - png_set_compression_mem_level(png_ptr, level); - -The other functions are for configuring zlib. They are not recommended -for normal use and may result in writing an invalid PNG file. See -zlib.h for more information on what these mean. - - png_set_compression_strategy(png_ptr, - strategy); - png_set_compression_window_bits(png_ptr, - window_bits); - png_set_compression_method(png_ptr, method); - png_set_compression_buffer_size(png_ptr, size); - -.SS Controlling row filtering - -If you want to control whether libpng uses filtering or not, which -filters are used, and how it goes about picking row filters, you -can call one of these functions. The selection and configuration -of row filters can have a significant impact on the size and -encoding speed and a somewhat lesser impact on the decoding speed -of an image. Filtering is enabled by default for RGB and grayscale -images (with and without alpha), but not for paletted images nor -for any images with bit depths less than 8 bits/pixel. - -The 'method' parameter sets the main filtering method, which is -currently only '0' in the PNG 1.2 specification. The 'filters' -parameter sets which filter(s), if any, should be used for each -scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS -to turn filtering on and off, respectively. - -Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB, -PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise -ORed together with '|' to specify one or more filters to use. -These filters are described in more detail in the PNG specification. -If you intend to change the filter type during the course of writing -the image, you should start with flags set for all of the filters -you intend to use so that libpng can initialize its internal -structures appropriately for all of the filter types. (Note that this -means the first row must always be adaptively filtered, because libpng -currently does not allocate the filter buffers until png_write_row() -is called for the first time.) - - filters = PNG_FILTER_NONE | PNG_FILTER_SUB - PNG_FILTER_UP | PNG_FILTER_AVE | - PNG_FILTER_PAETH | PNG_ALL_FILTERS; - - png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE, - filters); - The second parameter can also be - PNG_INTRAPIXEL_DIFFERENCING if you are - writing a PNG to be embedded in a MNG - datastream. This parameter must be the - same as the value of filter_method used - in png_set_IHDR(). - -It is also possible to influence how libpng chooses from among the -available filters. This is done in one or both of two ways - by -telling it how important it is to keep the same filter for successive -rows, and by telling it the relative computational costs of the filters. - - double weights[3] = {1.5, 1.3, 1.1}, - costs[PNG_FILTER_VALUE_LAST] = - {1.0, 1.3, 1.3, 1.5, 1.7}; - - png_set_filter_heuristics(png_ptr, - PNG_FILTER_HEURISTIC_WEIGHTED, 3, - weights, costs); - -The weights are multiplying factors that indicate to libpng that the -row filter should be the same for successive rows unless another row filter -is that many times better than the previous filter. In the above example, -if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a -"sum of absolute differences" 1.5 x 1.3 times higher than other filters -and still be chosen, while the NONE filter could have a sum 1.1 times -higher than other filters and still be chosen. Unspecified weights are -taken to be 1.0, and the specified weights should probably be declining -like those above in order to emphasize recent filters over older filters. - -The filter costs specify for each filter type a relative decoding cost -to be considered when selecting row filters. This means that filters -with higher costs are less likely to be chosen over filters with lower -costs, unless their "sum of absolute differences" is that much smaller. -The costs do not necessarily reflect the exact computational speeds of -the various filters, since this would unduly influence the final image -size. - -Note that the numbers above were invented purely for this example and -are given only to help explain the function usage. Little testing has -been done to find optimum values for either the costs or the weights. - -.SS Removing unwanted object code - -There are a bunch of #define's in pngconf.h that control what parts of -libpng are compiled. All the defines end in _SUPPORTED. If you are -never going to use a capability, you can change the #define to #undef -before recompiling libpng and save yourself code and data space, or -you can turn off individual capabilities with defines that begin with -PNG_NO_. - -You can also turn all of the transforms and ancillary chunk capabilities -off en masse with compiler directives that define -PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, -or all four, -along with directives to turn on any of the capabilities that you do -want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable -the extra transformations but still leave the library fully capable of reading -and writing PNG files with all known public chunks -Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive -produces a library that is incapable of reading or writing ancillary chunks. -If you are not using the progressive reading capability, you can -turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse -this with the INTERLACING capability, which you'll still have). - -All the reading and writing specific code are in separate files, so the -linker should only grab the files it needs. However, if you want to -make sure, or if you are building a stand alone library, all the -reading files start with pngr and all the writing files start with -pngw. The files that don't match either (like png.c, pngtrans.c, etc.) -are used for both reading and writing, and always need to be included. -The progressive reader is in pngpread.c - -If you are creating or distributing a dynamically linked library (a .so -or DLL file), you should not remove or disable any parts of the library, -as this will cause applications linked with different versions of the -library to fail if they call functions not available in your library. -The size of the library itself should not be an issue, because only -those sections that are actually used will be loaded into memory. - -.SS Requesting debug printout - -The macro definition PNG_DEBUG can be used to request debugging -printout. Set it to an integer value in the range 0 to 3. Higher -numbers result in increasing amounts of debugging information. The -information is printed to the "stderr" file, unless another file -name is specified in the PNG_DEBUG_FILE macro definition. - -When PNG_DEBUG > 0, the following functions (macros) become available: - - png_debug(level, message) - png_debug1(level, message, p1) - png_debug2(level, message, p1, p2) - -in which "level" is compared to PNG_DEBUG to decide whether to print -the message, "message" is the formatted string to be printed, -and p1 and p2 are parameters that are to be embedded in the string -according to printf-style formatting directives. For example, - - png_debug1(2, "foo=%d\n", foo); - -is expanded to - - if(PNG_DEBUG > 2) - fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo); - -When PNG_DEBUG is defined but is zero, the macros aren't defined, but you -can still use PNG_DEBUG to control your own debugging: - - #ifdef PNG_DEBUG - fprintf(stderr, ... - #endif - -When PNG_DEBUG = 1, the macros are defined, but only png_debug statements -having level = 0 will be printed. There aren't any such statements in -this version of libpng, but if you insert some they will be printed. - -.SH VI. 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 VII. MNG support - -The MNG specification (available at http://www.libpng.org/pub/mng) allows -certain extensions to PNG for PNG images that are embedded in MNG datastreams. -Libpng can support some of these extensions. To enable them, use the -png_permit_mng_features() function: - - feature_set = png_permit_mng_features(png_ptr, mask) - mask is a png_uint_32 containing the logical OR of the - features you want to enable. These include - PNG_FLAG_MNG_EMPTY_PLTE - PNG_FLAG_MNG_FILTER_64 - PNG_ALL_MNG_FEATURES - feature_set is a png_uint_32 that is the logical AND of - your mask with the set of MNG features that is - supported by the version of libpng that you are using. - -It is an error to use this function when reading or writing a standalone -PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped -in a MNG datastream. As a minimum, it must have the MNG 8-byte signature -and the MHDR and MEND chunks. Libpng does not provide support for these -or any other MNG chunks; your application must provide its own support for -them. You may wish to consider using libmng (available at -http://www.libmng.com) instead. - -.SH VIII. Changes to Libpng from version 0.88 - -It should be noted that versions of libpng later than 0.96 are not -distributed by the original libpng author, Guy Schalnat, nor by -Andreas Dilger, who had taken over from Guy during 1996 and 1997, and -distributed versions 0.89 through 0.96, but rather by another member -of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are -still alive and well, but they have moved on to other things. - -The old libpng functions png_read_init(), png_write_init(), -png_info_init(), png_read_destroy(), and png_write_destroy() have been -moved to PNG_INTERNAL in version 0.95 to discourage their use. These -functions will be removed from libpng version 2.0.0. - -The preferred method of creating and initializing the libpng structures is -via the png_create_read_struct(), png_create_write_struct(), and -png_create_info_struct() because they isolate the size of the structures -from the application, allow version error checking, and also allow the -use of custom error handling routines during the initialization, which -the old functions do not. The functions png_read_destroy() and -png_write_destroy() do not actually free the memory that libpng -allocated for these structs, but just reset the data structures, so they -can be used instead of png_destroy_read_struct() and -png_destroy_write_struct() if you feel there is too much system overhead -allocating and freeing the png_struct for each image read. - -Setting the error callbacks via png_set_message_fn() before -png_read_init() as was suggested in libpng-0.88 is no longer supported -because this caused applications that do not use custom error functions -to fail if the png_ptr was not initialized to zero. It is still possible -to set the error callbacks AFTER png_read_init(), or to change them with -png_set_error_fn(), which is essentially the same function, but with a new -name to force compilation errors with applications that try to use the old -method. - -Starting with version 1.0.7, you can find out which version of the library -you are using at run-time: - - png_uint_32 libpng_vn = png_access_version_number(); - -The number libpng_vn is constructed from the major version, minor -version with leading zero, and release number with leading zero, -(e.g., libpng_vn for version 1.0.7 is 10007). - -You can also check which version of png.h you used when compiling your -application: - - png_uint_32 application_vn = PNG_LIBPNG_VER; - -.SH IX. Y2K Compliance in libpng - -December 3, 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.8 are Y2K compliant. It is my belief that earlier -versions were also Y2K compliant. - -Libpng only has three year fields. One is a 2-byte unsigned integer that -will hold years up to 65535. The other two hold the date in text -format, and will hold years up to 9999. - -The integer is - "png_uint_16 year" in png_time_struct. - -The strings are - "png_charp time_buffer" in png_struct and - "near_time_buffer", which is a local character string in png.c. - -There are seven time-related functions: - - png_convert_to_rfc_1123() in png.c - (formerly png_convert_to_rfc_1152() in error) - png_convert_from_struct_tm() in pngwrite.c, called - in pngwrite.c - png_convert_from_time_t() in pngwrite.c - png_get_tIME() in pngget.c - png_handle_tIME() in pngrutil.c, called in pngread.c - png_set_tIME() in pngset.c - png_write_tIME() in pngwutil.c, called in pngwrite.c - -All appear to handle dates properly in a Y2K environment. The -png_convert_from_time_t() function calls gmtime() to convert from system -clock time, which returns (year - 1900), which we properly convert to -the full 4-digit year. There is a possibility that applications using -libpng are not passing 4-digit years into the png_convert_to_rfc_1123() -function, or that they are incorrectly passing only a 2-digit year -instead of "year - 1900" into the png_convert_from_struct_tm() function, -but this is not under our control. The libpng documentation has always -stated that it works with 4-digit years, and the APIs have been -documented as such. - -The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned -integer to hold the year, and can hold years as large as 65535. - -zlib, upon which libpng depends, is also Y2K compliant. It contains -no date-related code. - - - Glenn Randers-Pehrson - libpng maintainer - PNG Development Group - -.SH NOTE - -Note about libpng version numbers: - -Due to various miscommunications, unforeseen code incompatibilities -and occasional factors outside the authors' control, version numbering -on the library has not always been consistent and straightforward. -The following table summarizes matters since version 0.89c, which was -the first widely used release: - - source png.h png.h shared-lib - version string int version - ------- ------ ----- ---------- - 0.89c ("beta 3") 0.89 89 1.0.89 - 0.90 ("beta 4") 0.90 90 0.90 - 0.95 ("beta 5") 0.95 95 0.95 - 0.96 ("beta 6") 0.96 96 0.96 - 0.97b ("beta 7") 1.00.97 97 1.0.1 - 0.97c 0.97 97 2.0.97 - 0.98 0.98 98 2.0.98 - 0.99 0.99 98 2.0.99 - 0.99a-m 0.99 99 2.0.99 - 1.00 1.00 100 2.1.0 - 1.0.0 1.0.0 100 2.1.0 - 1.0.0 (from here on, the 100 2.1.0 - 1.0.1 png.h string is 10001 2.1.0 - 1.0.1a-e identical to the 10002 from here on, the - 1.0.2 source version) 10002 shared library is 2.V - 1.0.2a-b 10003 where V is the source - 1.0.1 10001 code version except as - 1.0.1a-e 10002 2.1.0.1a-e noted. - 1.0.2 10002 2.1.0.2 - 1.0.2a-b 10003 2.1.0.2a-b - 1.0.3 10003 2.1.0.3 - 1.0.3a-d 10004 2.1.0.3a-d - 1.0.4 10004 2.1.0.4 - 1.0.4a-f 10005 2.1.0.4a-f - 1.0.5 (+ 2 patches) 10005 2.1.0.5 - 1.0.5a-d 10006 2.1.0.5a-d - 1.0.5e-r 10100 2.1.0.5e-r - 1.0.5s-v 10006 2.1.0.5s-v - 1.0.6 (+ 3 patches) 10006 2.1.0.6 - 1.0.6d-g 10007 2.1.0.6d-g - 1.0.6h 10007 10.6h - 1.0.6i 10007 10.6i - 1.0.6j 10007 2.1.0.6j - 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14 - 1.0.7beta15-18 1 10007 2.1.0.7beta15-18 - 1.0.7rc1-2 1 10007 2.1.0.7rc1-2 - 1.0.7 1 10007 2.1.0.7 - 1.0.8beta1-4 1 10008 2.1.0.8beta1-4 - 1.0.8rc1 1 10008 2.1.0.8rc1 - 1.0.8 1 10008 2.1.0.8 - 1.0.9beta1-6 1 10009 2.1.0.9beta1-6 - 1.0.9rc1 1 10009 2.1.0.9rc1 - 1.0.9beta7-10 1 10009 2.1.0.9beta7-10 - 1.0.9rc2 1 10009 2.1.0.9rc2 - 1.0.9 1 10009 2.1.0.9 - 1.0.10beta1 1 10010 2.1.0.10beta1 - 1.0.10rc1 1 10010 2.1.0.10rc1 - 1.0.10 1 10010 2.1.0.10 - 1.0.11beta1-3 1 10011 2.1.0.11beta1-3 - 1.0.11rc1 1 10011 2.1.0.11rc1 - 1.0.11 1 10011 2.1.0.11 - 1.0.12beta1-2 2 10012 2.1.0.12beta1-2 - 1.0.12rc1 2 10012 2.1.0.12rc1 - 1.0.12 2 10012 2.1.0.12 - 1.1.0a-f - 10100 2.1.1.0a-f abandoned - 1.2.0beta1-2 2 10200 2.1.2.0beta1-2 - 1.2.0beta3-5 3 10200 3.1.2.0beta3-5 - 1.2.0rc1 3 10200 3.1.2.0rc1 - 1.2.0 3 10200 3.1.2.0 - 1.2.1beta-4 3 10201 3.1.2.1beta1-4 - 1.2.1rc1-2 3 10201 3.1.2.1rc1-2 - 1.2.1 3 10201 3.1.2.1 - 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6 - 1.0.13beta1 10 10013 10.so.0.1.0.13beta1 - 1.0.13rc1 10 10013 10.so.0.1.0.13rc1 - 1.2.2rc1 12 10202 12.so.0.1.2.2rc1 - 1.0.13 10 10013 10.so.0.1.0.13 - 1.2.2 12 10202 12.so.0.1.2.2 - 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6 - 1.2.3 12 10203 12.so.0.1.2.3 - 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3 - 1.2.4rc1 13 10204 12.so.0.1.2.4rc1 - 1.0.14 10 10014 10.so.0.1.0.14 - 1.2.4 13 10204 12.so.0.1.2.4 - 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2 - 1.0.15rc1 10 10015 10.so.0.1.0.15rc1 - 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.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5 - 1.0.16 10 10016 10.so.0.1.0.16 - 1.2.6 13 10206 12.so.0.1.2.6 - 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2 - 1.0.17rc1 10 10017 12.so.0.1.0.17rc1 - 1.2.7rc1 13 10207 12.so.0.1.2.7rc1 - 1.0.17 10 10017 12.so.0.1.0.17 - 1.2.7 13 10207 12.so.0.1.2.7 - 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5 - 1.0.18rc1-5 10 10018 12.so.0.1.0.18rc1-5 - 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5 - 1.0.18 10 10018 12.so.0.1.0.18 - 1.2.8 13 10208 12.so.0.1.2.8 - -Henceforth the source version will match the shared-library minor -and patch numbers; the shared-library major version number will be -used for changes in backward compatibility, as it is intended. The -PNG_PNGLIB_VER macro, which is not used within libpng but is available -for applications, is an unsigned integer of the form xyyzz corresponding -to the source version x.y.z (leading zeros in y and z). Beta versions -were given the previous public release number plus a letter, until -version 1.0.6j; from then on they were given the upcoming public -release number plus "betaNN" or "rcN". - -.SH "SEE ALSO" -libpngpf(3), png(5) -.LP -.IR libpng : -.IP -http://libpng.sourceforge.net (follow the [DOWNLOAD] link) -http://www.libpng.org/pub/png - -.LP -.IR zlib : -.IP -(generally) at the same location as -.I libpng -or at -.br -ftp://ftp.info-zip.org/pub/infozip/zlib - -.LP -.IR PNG specification: RFC 2083 -.IP -(generally) at the same location as -.I libpng -or at -.br -ftp://ds.internic.net/rfc/rfc2083.txt -.br -or (as a W3C Recommendation) at -.br -http://www.w3.org/TR/REC-png.html - -.LP -In the case of any inconsistency between the PNG specification -and this library, the specification takes precedence. - -.SH AUTHORS -This man page: Glenn Randers-Pehrson - - -The contributing authors would like to thank all those who helped -with testing, bug fixes, and patience. This wouldn't have been -possible without all of you. - -Thanks to Frank J. T. Wojcik for helping with the documentation. - -Libpng version 1.2.8 - December 3, 2004: -Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. -Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). - -Supported by the PNG development group -.br -png-implement at ccrc.wustl.edu (subscription required; write to -majordomo at ccrc.wustl.edu with "subscribe png-implement" in the message). - -.SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE: - -(This copy of the libpng notices is provided for your convenience. In case of -any discrepancy between this copy and the notices in the file png.h that is -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, December 3, 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 individual added to the list of Contributing Authors - - Cosmin Truta - -libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002, are -Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are -distributed according to the same disclaimer and license as libpng-1.0.6 -with the following individuals added to the list of Contributing Authors - - Simon-Pierre Cadieux - Eric S. Raymond - Gilles Vollant - -and with the following additions to the disclaimer: - - There is no warranty against interference with your - enjoyment of the library or against infringement. - There is no warranty that our efforts or the library - will fulfill any of your particular purposes or needs. - This library is provided with all faults, and the entire - risk of satisfactory quality, performance, accuracy, and - effort is with the user. - -libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are -Copyright (c) 1998, 1999 Glenn Randers-Pehrson -Distributed according to the same disclaimer and license as libpng-0.96, -with the following individuals added to the list of Contributing Authors: - - Tom Lane - Glenn Randers-Pehrson - Willem van Schaik - -libpng versions 0.89, June 1996, through 0.96, May 1997, are -Copyright (c) 1996, 1997 Andreas Dilger -Distributed according to the same disclaimer and license as libpng-0.88, -with the following individuals added to the list of Contributing Authors: - - John Bowler - Kevin Bracey - Sam Bushell - Magnus Holmgren - Greg Roelofs - Tom Tanner - -libpng versions 0.5, May 1995, through 0.88, January 1996, are -Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc. - -For the purposes of this copyright and license, "Contributing Authors" -is defined as the following set of individuals: - - Andreas Dilger - Dave Martindale - Guy Eric Schalnat - Paul Schmidt - Tim Wegner - -The PNG Reference Library is supplied "AS IS". The Contributing Authors -and Group 42, Inc. disclaim all warranties, expressed or implied, -including, without limitation, the warranties of merchantability and of -fitness for any purpose. The Contributing Authors and Group 42, Inc. -assume no liability for direct, indirect, incidental, special, exemplary, -or consequential damages, which may result from the use of the PNG -Reference Library, even if advised of the possibility of such damage. - -Permission is hereby granted to use, copy, modify, and distribute this -source code, or portions hereof, for any purpose, without fee, subject -to the following restrictions: - -1. The origin of this source code must not be misrepresented. - -2. Altered versions must be plainly marked as such and - must not be misrepresented as being the original source. - -3. This Copyright notice may not be removed or altered from - any source or altered source distribution. - -The Contributing Authors and Group 42, Inc. specifically permit, without -fee, and encourage the use of this source code as a component to -supporting the PNG file format in commercial products. If you use this -source code in a product, acknowledgment is not required but would be -appreciated. - - -A "png_get_copyright" function is available, for convenient use in "about" -boxes and the like: - - printf("%s",png_get_copyright(NULL)); - -Also, the PNG logo (in PNG format, of course) is supplied in the -files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31). - -Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a -certification mark of the Open Source Initiative. - -Glenn Randers-Pehrson -glennrp at users.sourceforge.net -December 3, 2004 - -.\" end of man page - diff --git a/sys/src/cmd/gs/libpng/libpng.3.man b/sys/src/cmd/gs/libpng/libpng.3.man new file mode 100644 index 000000000..1feceee38 --- /dev/null +++ b/sys/src/cmd/gs/libpng/libpng.3.man @@ -0,0 +1,4022 @@ +.TH LIBPNG 3 "December 3, 2004" +.SH NAME +libpng \- Portable Network Graphics (PNG) Reference Library 1.2.8 +.SH SYNOPSIS +\fI\fB + +\fB#include \fP + +\fI\fB + +\fBpng_uint_32 png_access_version_number \fI(void\fP\fB);\fP + +\fI\fB + +\fBint png_check_sig (png_bytep \fP\fIsig\fP\fB, int \fInum\fP\fB);\fP + +\fI\fB + +\fBvoid png_chunk_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP + +\fI\fB + +\fBvoid png_chunk_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP + +\fI\fB + +\fBvoid png_convert_from_struct_tm (png_timep \fP\fIptime\fP\fB, struct tm FAR * \fIttime\fP\fB);\fP + +\fI\fB + +\fBvoid png_convert_from_time_t (png_timep \fP\fIptime\fP\fB, time_t \fIttime\fP\fB);\fP + +\fI\fB + +\fBpng_charp png_convert_to_rfc1123 (png_structp \fP\fIpng_ptr\fP\fB, png_timep \fIptime\fP\fB);\fP + +\fI\fB + +\fBpng_infop png_create_info_struct (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_structp png_create_read_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP + +\fI\fB + +\fBpng_structp png_create_read_struct_2(png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP + +\fI\fB + +\fBpng_structp png_create_write_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP + +\fI\fB + +\fBpng_structp png_create_write_struct_2(png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP + +\fI\fB + +\fBint png_debug(int \fP\fIlevel\fP\fB, png_const_charp \fImessage\fP\fB);\fP + +\fI\fB + +\fBint png_debug1(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fIp1\fP\fB);\fP + +\fI\fB + +\fBint png_debug2(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fP\fIp1\fP\fB, \fIp2\fP\fB);\fP + +\fI\fB + +\fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_destroy_read_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fP\fIinfo_ptr_ptr\fP\fB, png_infopp \fIend_info_ptr_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_destroy_write_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP + +\fI\fB + +\fBvoid png_free (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP + +\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_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum\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 + +\fBpng_uint_32 png_get_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_channels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_copyright (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_get_error_ptr (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_filter_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_header_ver (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_header_version (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP + +\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, png_uint_32 \fI*proflen\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*width\fP\fB, png_uint_32 \fP\fI*height\fP\fB, int \fP\fI*bit_depth\fP\fB, int \fP\fI*color_type\fP\fB, int \fP\fI*interlace_type\fP\fB, int \fP\fI*compression_type\fP\fB, int \fI*filter_type\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_image_height (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_image_width (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_libpng_ver (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP + +\fI\fB + +\fBfloat png_get_pixel_aspect_ratio (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_get_progressive_ptr (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP + +\fI\fB + +\fBpng_byte png_get_rgb_to_gray_status (png_structp \fIpng_ptr) + +\fBpng_uint_32 png_get_rowbytes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_bytepp png_get_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP + +\fI\fB + +\fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fI*intent\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_values\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_get_user_chunk_ptr (png_structp \fIpng_ptr\fP\fB);\fP + +\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 + +\fBpng_int_32 png_get_x_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_int_32 png_get_x_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_x_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_int_32 png_get_y_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_y_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP + +\fI\fB + +\fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP + +\fI\fB + +\fBDEPRECATED: void png_info_init (png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBDEPRECATED: void png_info_init_2 (png_infopp \fP\fIptr_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP + +\fI\fB + +\fBvoidp png_memcpy (png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_size_t \fIsize\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_memcpy_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_uint_32 \fIsize\fP\fB);\fP + +\fI\fB + +\fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP + +\fI\fB + +\fBpng_voidp png_memset_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_uint_32 \fIsize\fP\fB);\fP + +\fI\fB + +\fBDEPRECATED: void png_permit_empty_plte (png_structp \fP\fIpng_ptr\fP\fB, int \fIempty_plte_permitted\fP\fB);\fP + +\fI\fB + +\fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP + +\fI\fB + +\fBvoid png_progressive_combine_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIold_row\fP\fB, png_bytep \fInew_row\fP\fB);\fP + +\fI\fB + +\fBvoid png_read_destroy (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_infop \fIend_info_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP + +\fI\fB + +\fBDEPRECATED: void png_read_init (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBDEPRECATED: void png_read_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\fP\fB);\fP + +\fI\fB + +\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\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, png_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 + +\fBvoid png_read_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_bytepp \fP\fIdisplay_row\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP + +\fI\fB + +\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fB#if \fI!defined(PNG_1_0_X) + +\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP + +\fI\fB#endif + +\fI\fB + +\fBvoid png_set_background (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, double \fIbackground_gamma\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fIbackground\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIwhite_x\fP\fB, double \fP\fIwhite_y\fP\fB, double \fP\fIred_x\fP\fB, double \fP\fIred_y\fP\fB, double \fP\fIgreen_x\fP\fB, double \fP\fIgreen_y\fP\fB, double \fP\fIblue_x\fP\fB, double \fIblue_y\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwhite_x\fP\fB, png_uint_32 \fP\fIwhite_y\fP\fB, png_uint_32 \fP\fIred_x\fP\fB, png_uint_32 \fP\fIred_y\fP\fB, png_uint_32 \fP\fIgreen_x\fP\fB, png_uint_32 \fP\fIgreen_y\fP\fB, png_uint_32 \fP\fIblue_x\fP\fB, png_uint_32 \fIblue_y\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_crc_action (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIcrit_action\fP\fB, int \fIancil_action\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_dither (png_structp \fP\fIpng_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fP\fInum_palette\fP\fB, int \fP\fImaximum_colors\fP\fB, png_uint_16p \fP\fIhistogram\fP\fB, int \fIfull_dither\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_error_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarning_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_filler (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_filter (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImethod\fP\fB, int \fIfilters\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_filter_heuristics (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_doublep \fP\fIfilter_weights\fP\fB, png_doublep \fIfilter_costs\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_gamma (png_structp \fP\fIpng_ptr\fP\fB, double \fP\fIscreen_gamma\fP\fB, double \fIdefault_file_gamma\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIfile_gamma\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_gray_1_2_4_to_8(png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fIhist\fP\fB);\fP + +\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, png_uint_32 \fIproflen\fP\fB);\fP + +\fI\fB + +\fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwidth\fP\fB, png_uint_32 \fP\fIheight\fP\fB, int \fP\fIbit_depth\fP\fB, int \fP\fIcolor_type\fP\fB, int \fP\fIinterlace_type\fP\fB, int \fP\fIcompression_type\fP\fB, int \fIfilter_type\fP\fB);\fP + +\fI\fB + +\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 + +\fBvoid png_set_mem_fn(png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIoffset_x\fP\fB, png_uint_32 \fP\fIoffset_y\fP\fB, int \fIunit_type\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_palette_to_rgb(png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIpurpose\fP\fB, png_int_32 \fP\fIX0\fP\fB, png_int_32 \fP\fIX1\fP\fB, int \fP\fItype\fP\fB, int \fP\fInparams\fP\fB, png_charp \fP\fIunits\fP\fB, png_charpp \fIparams\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIres_x\fP\fB, png_uint_32 \fP\fIres_y\fP\fB, int \fIunit_type\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_progressive_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIprogressive_ptr\fP\fB, png_progressive_info_ptr \fP\fIinfo_fn\fP\fB, png_progressive_row_ptr \fP\fIrow_fn\fP\fB, png_progressive_end_ptr \fIend_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fInum_palette\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fIread_data_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_read_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_read_status_ptr \fIread_row_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_read_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIread_user_transform_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_rgb_to_gray (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIerror_action\fP\fB, double \fP\fIred\fP\fB, double \fIgreen\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_fixed_point \fP\fIred\fP\fB, png_fixed_point \fIgreen\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytepp \fIrow_pointers\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fIsig_bit\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_shift (png_structp \fP\fIpng_ptr\fP\fB, png_color_8p \fItrue_bits\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_sig_bytes (png_structp \fP\fIpng_ptr\fP\fB, int \fInum_bytes\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fP\fIsplt_ptr\fP\fB, int \fInum_spalettes\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_sRGB_gAMA_and_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_strip_16 (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_strip_alpha (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_swap (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_swap_alpha (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fItext_ptr\fP\fB, int \fInum_text\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fImod_time\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fItrans\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_values\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_tRNS_to_alpha(png_structp \fIpng_ptr\fP\fB);\fP + +\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 \fP\fInum\fP\fB, int \fIlocation\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_unknown_chunk_location(png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIchunk\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 + +\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 + +\fBvoid png_set_write_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fP\fIwrite_data_fn\fP\fB, png_flush_ptr \fIoutput_flush_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_write_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_write_status_ptr \fIwrite_row_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_write_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIwrite_user_transform_fn\fP\fB);\fP + +\fI\fB + +\fBvoid png_set_compression_buffer_size(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP + +\fI\fB + +\fBint png_sig_cmp (png_bytep \fP\fIsig\fP\fB, png_size_t \fP\fIstart\fP\fB, png_size_t \fInum_to_check\fP\fB);\fP + +\fI\fB + +\fBvoid png_start_read_image (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_chunk (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_chunk_data (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_chunk_end (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_chunk_start (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_uint_32 \fIlength\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_destroy (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_flush (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP + +\fI\fB + +\fBDEPRECATED: void png_write_init (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + +\fBDEPRECATED: void png_write_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\fI\fB + +\fBvoid png_write_info_before_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP + +\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, png_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 + +\fBvoid png_write_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP + +\fI\fB + +\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\fP\fB);\fP + +\fI\fB + +\fBvoid png_zfree (voidpf \fP\fIpng_ptr\fP\fB, voidpf \fIptr\fP\fB);\fP + +\fI\fB + +.SH DESCRIPTION +The +.I libpng +library supports encoding, decoding, and various manipulations of +the Portable Network Graphics (PNG) format image files. It uses the +.IR zlib(3) +compression library. +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.8 - December 3, 2004 + Updated and distributed by Glenn Randers-Pehrson + + Copyright (c) 1998-2004 Glenn Randers-Pehrson + For conditions of distribution and use, see copyright + notice in png.h. + + based on: + + libpng 1.0 beta 6 version 0.96 May 28, 1997 + Updated and distributed by Andreas Dilger + Copyright (c) 1996, 1997 Andreas Dilger + + libpng 1.0 beta 2 - version 0.88 January 26, 1996 + For conditions of distribution and use, see copyright + notice in png.h. Copyright (c) 1995, 1996 Guy Eric + Schalnat, Group 42, Inc. + + Updated/rewritten per request in the libpng FAQ + 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 +(known as libpng) for your own use. There are five sections to this +file: introduction, structures, reading, writing, and modification and +configuration notes for various special platforms. In addition to this +file, example.c is a good starting point for using the library, as +it is heavily commented and should include everything most people +will need. We assume that libpng is already installed; see the +INSTALL file for instructions on how to install libpng. + +Libpng was written as a companion to the PNG specification, as a way +of reducing the amount of time and effort it takes to support the PNG +file format in application programs. + +The PNG specification (second edition), November 2003, is available as +a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at + + +The PNG-1.0 specification is available +as RFC 2083 and as a +W3C Recommendation . Some +additional chunks are described in the special-purpose public chunks +documents at . + +Other information +about PNG, and the latest version of libpng, can be found at the PNG home +page, . + +Most users will not have to modify the library significantly; advanced +users may want to modify it more. All attempts were made to make it as +complete as possible, while keeping the code easy to understand. +Currently, this library only supports C. Support for other languages +is being considered. + +Libpng has been designed to handle multiple sessions at one time, +to be easily modifiable, to be portable to the vast majority of +machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy +to use. The ultimate goal of libpng is to promote the acceptance of +the PNG file format in whatever way possible. While there is still +work to be done (see the TODO file), libpng should cover the +majority of the needs of its users. + +Libpng uses zlib for its compression and decompression of PNG files. +Further information about zlib, and the latest version of zlib, can +be found at the zlib home page, . +The zlib compression utility is a general purpose utility that is +useful for more than PNG files, and can be used without libpng. +See the documentation delivered with zlib for more details. +You can usually find the source files for the zlib utility wherever you +find the libpng source files. + +Libpng is thread safe, provided the threads are using different +instances of the structures. Each thread should have its own +png_struct and png_info instances, and thus its own image. +Libpng does not protect itself against two threads using the +same instance of a structure. Note: thread safety may be defeated +by use of some of the MMX assembler code in pnggccrd.c, which is only +compiled when the user defines PNG_THREAD_UNSAFE_OK. + +.SH II. Structures + +There are two main structures that are important to libpng, png_struct +and png_info. The first, png_struct, is an internal structure that +will not, for the most part, be used by a user except as the first +variable passed to every libpng function call. + +The png_info structure is designed to provide information about the +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. The fields of png_info are still available for +older applications, but it is suggested that applications use the new +interfaces if at all possible. + +Applications that do make direct access to the members of png_struct (except +for png_ptr->jmpbuf) must be recompiled whenever the library is updated, +and applications that make direct access to the members of png_info must +be recompiled if they were compiled or loaded with libpng version 1.0.6, +in which the members were in a different order. In version 1.0.7, the +members of the png_info structure reverted to the old order, as they were +in versions 0.97c through 1.0.5. Starting with version 2.0.0, both +structures are going to be hidden, and the contents of the structures will +only be accessible through the png_get/png_set functions. + +The png.h header file is an invaluable reference for programming with libpng. +And while I'm on the topic, make sure you include the libpng header file: + +#include + +.SH III. Reading + +We'll now walk you through the possible functions to call when reading +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 +will also want to insure that you are, in fact, dealing with a PNG +file. Libpng provides a simple check to see if a file is a PNG file. +To use it, pass in the first 1 to 8 bytes of the file to the function +png_sig_cmp(), and it will return 0 if the bytes match the corresponding +bytes of the PNG signature, or nonzero otherwise. Of course, the more bytes +you pass in, the greater the accuracy of the prediction. + +If you are intending to keep the file pointer open for use in libpng, +you must ensure you don't read more than 8 bytes from the beginning +of the file, and you also have to make a call to png_set_sig_bytes_read() +with the number of bytes you read from the beginning. Libpng will +then only check the bytes (if any) that your program didn't read. + +(*): If you are not using the standard I/O functions, you will need +to replace them with custom functions. See the discussion under +Customizing libpng. + + + FILE *fp = fopen(file_name, "rb"); + if (!fp) + { + return (ERROR); + } + fread(header, 1, number, fp); + is_png = !png_sig_cmp(header, 0, number); + if (!is_png) + { + return (NOT_PNG); + } + + +Next, png_struct and png_info need to be allocated and initialized. In +order to ensure that the size of these structures is correct even with a +dynamically linked libpng, there are functions to initialize and +allocate the structures. We also pass the library version, optional +pointers to error handling functions, and a pointer to a data struct for +use by the error functions, if necessary (the pointer and functions can +be NULL if the default error handlers are to be used). See the section +on Changes to Libpng below regarding the old initialization functions. +The structure allocation functions quietly return NULL if they fail to +create the structure, so your application should check for that. + + png_structp png_ptr = png_create_read_struct + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, + user_error_fn, user_warning_fn); + if (!png_ptr) + return (ERROR); + + png_infop info_ptr = png_create_info_struct(png_ptr); + if (!info_ptr) + { + png_destroy_read_struct(&png_ptr, + (png_infopp)NULL, (png_infopp)NULL); + return (ERROR); + } + + png_infop end_info = png_create_info_struct(png_ptr); + if (!end_info) + { + png_destroy_read_struct(&png_ptr, &info_ptr, + (png_infopp)NULL); + return (ERROR); + } + +If you want to use your own memory allocation routines, +define PNG_USER_MEM_SUPPORTED and use +png_create_read_struct_2() instead of png_create_read_struct(): + + png_structp png_ptr = png_create_read_struct_2 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, + user_error_fn, user_warning_fn, (png_voidp) + user_mem_ptr, user_malloc_fn, user_free_fn); + +The error handling routines passed to png_create_read_struct() +and the memory alloc/free routines passed to png_create_struct_2() +are only necessary if you are not using the libpng supplied error +handling and memory alloc/free functions. + +When libpng encounters an error, it expects to longjmp back +to your routine. Therefore, you will need to call setjmp and pass +your png_jmpbuf(png_ptr). If you read the file from different +routines, you will need to update the jmpbuf field every time you enter +a new routine that will call a png_*() function. + +See your documentation of setjmp/longjmp for your compiler for more +information on setjmp/longjmp. See the discussion on libpng error +handling in the Customizing Libpng section below for more information +on the libpng error handling. If an error occurs, and libpng longjmp's +back to your setjmp, you will want to call png_destroy_read_struct() to +free any memory. + + if (setjmp(png_jmpbuf(png_ptr))) + { + png_destroy_read_struct(&png_ptr, &info_ptr, + &end_info); + fclose(fp); + return (ERROR); + } + +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 +opened in binary mode. If you wish to handle reading data in another +way, you need not call the png_init_io() function, but you must then +implement the libpng I/O methods discussed in the Customizing Libpng +section below. + + png_init_io(png_ptr, fp); + +If you had previously opened the file and read any of the signature from +the beginning in order to see if this was a PNG file, you need to let +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. +You must supply a function + + void read_row_callback(png_ptr ptr, png_uint_32 row, + int pass); + { + /* put your code here */ + } + +(You can give it another name that you like instead of "read_row_callback") + +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 +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, keep, + chunk_list, num_chunks); + keep - 0: do not handle as unknown + 1: do not keep + 2: keep only if safe-to-copy + 3: keep even if unsafe-to-copy + You can use these definitions: + PNG_HANDLE_CHUNK_AS_DEFAULT 0 + PNG_HANDLE_CHUNK_NEVER 1 + PNG_HANDLE_CHUNK_IF_SAFE 2 + PNG_HANDLE_CHUNK_ALWAYS 3 + 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. If nonzero, + only the chunks in the list 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. The IHDR and IEND chunks should not be named in +chunk_list; if they are, libpng will process them normally anyway. + +.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, +then png_read_image(), and finally png_read_end(). + +(The final parameter of this call is not yet used. Someday it might point +to transformation parameters required by some future input transform.) + +You must use png_transforms and not call any png_set_transform() functions +when you use png_read_png(). + +After you have called png_read_png(), you can retrieve the image data +with + + row_pointers = png_get_rows(png_ptr, info_ptr); + +where row_pointers is an array of pointers to the pixel data for each row: + + png_bytep row_pointers[height]; + +If you know your image size and pixel size ahead of time, you can allocate +row_pointers prior to calling png_read_png() with + + if (height > PNG_UINT_32_MAX/png_sizeof(png_byte)) + png_error (png_ptr, + "Image is too tall to process in memory"); + if (width > PNG_UINT_32_MAX/pixel_size) + png_error (png_ptr, + "Image is too wide to process in memory"); + row_pointers = png_malloc(png_ptr, + height*png_sizeof(png_bytep)); + for (int i=0; i) and +png_get_(png_ptr, info_ptr, ...) functions return non-zero if the +data has been read, or zero if it is missing. The parameters to the +png_get_ are set directly if they are simple data types, or a pointer +into the info_ptr is returned for any complex types. + + png_get_PLTE(png_ptr, info_ptr, &palette, + &num_palette); + palette - the palette for the file + (array of png_color) + num_palette - number of entries in the palette + + png_get_gAMA(png_ptr, info_ptr, &gamma); + gamma - the gamma the file is written + at (PNG_INFO_gAMA) + + png_get_sRGB(png_ptr, info_ptr, &srgb_intent); + srgb_intent - the rendering intent (PNG_INFO_sRGB) + The presence of the sRGB chunk + means that the pixel data is in the + sRGB color space. This chunk also + implies specific values of gAMA and + cHRM. + + png_get_iCCP(png_ptr, info_ptr, &name, + &compression_type, &profile, &proflen); + name - The profile name. + compression - The compression type; always + PNG_COMPRESSION_TYPE_BASE for PNG 1.0. + You may give NULL to this argument to + ignore it. + profile - International Color Consortium color + profile data. May contain NULs. + proflen - length of profile data in bytes. + + png_get_sBIT(png_ptr, info_ptr, &sig_bit); + sig_bit - the number of significant bits for + (PNG_INFO_sBIT) each of the gray, + red, green, and blue channels, + whichever are appropriate for the + given color type (png_color_16) + + png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans, + &trans_values); + trans - array of transparent entries for + palette (PNG_INFO_tRNS) + trans_values - graylevel or color sample values of + the single transparent color for + non-paletted images (PNG_INFO_tRNS) + num_trans - number of transparent entries + (PNG_INFO_tRNS) + + png_get_hIST(png_ptr, info_ptr, &hist); + (PNG_INFO_hIST) + hist - histogram of palette (array of + png_uint_16) + + png_get_tIME(png_ptr, info_ptr, &mod_time); + mod_time - time image was last modified + (PNG_VALID_tIME) + + 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_comments = png_get_text(png_ptr, info_ptr, + &text_ptr, &num_text); + num_comments - number of comments + text_ptr - array of png_text holding image + comments + 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. Must contain + 1-79 characters. + text_ptr[i].text - text comments for current + keyword. Can be empty. + 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 (empty + string for unknown). + text_ptr[i].lang_key - keyword in UTF-8 + (empty string for unknown). + num_text - number of comments (same as + num_comments; you can put NULL here + to avoid the duplication) + Note while png_set_text() will accept text, language, + and translated keywords that can be NULL pointers, the + structure returned by png_get_text will always contain + regular zero-terminated C strings. They might be + empty strings but they will never be NULL pointers. + + num_spalettes = png_get_sPLT(png_ptr, info_ptr, + &palette_ptr); + palette_ptr - array of palette structures holding + contents of one or more sPLT chunks + read. + num_spalettes - number of sPLT chunks read. + + png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y, + &unit_type); + offset_x - positive offset from the left edge + of the screen + offset_y - positive offset from the top edge + of the screen + unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER + + png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y, + &unit_type); + res_x - pixels/unit physical resolution in + x direction + res_y - pixels/unit physical resolution in + x direction + unit_type - PNG_RESOLUTION_UNKNOWN, + PNG_RESOLUTION_METER + + png_get_sCAL(png_ptr, info_ptr, &unit, &width, + &height) + unit - physical scale units (an integer) + width - width of a pixel in physical scale units + height - height of a pixel in physical scale units + (width and height are doubles) + + png_get_sCAL_s(png_ptr, info_ptr, &unit, &width, + &height) + unit - physical scale units (an integer) + width - width of a pixel in physical scale units + height - height of a pixel in physical scale units + (width and height are strings like "2.54") + + num_unknown_chunks = png_get_unknown_chunks(png_ptr, + info_ptr, &unknowns) + unknowns - array of png_unknown_chunk + structures holding unknown chunks + unknowns[i].name - name of unknown chunk + unknowns[i].data - data of unknown chunk + unknowns[i].size - size of unknown chunk's data + unknowns[i].location - position of chunk in file + + The value of "i" corresponds to the order in which the + chunks were read from the PNG file or inserted with the + png_set_unknown_chunks() function. + +The data from the pHYs chunk can be retrieved in several convenient +forms: + + res_x = png_get_x_pixels_per_meter(png_ptr, + info_ptr) + res_y = png_get_y_pixels_per_meter(png_ptr, + info_ptr) + res_x_and_y = png_get_pixels_per_meter(png_ptr, + info_ptr) + res_x = png_get_x_pixels_per_inch(png_ptr, + info_ptr) + res_y = png_get_y_pixels_per_inch(png_ptr, + info_ptr) + res_x_and_y = png_get_pixels_per_inch(png_ptr, + info_ptr) + aspect_ratio = png_get_pixel_aspect_ratio(png_ptr, + info_ptr) + + (Each of these returns 0 [signifying "unknown"] if + the data is not present or if res_x is 0; + res_x_and_y is 0 if res_x != res_y) + +The data from the oFFs chunk can be retrieved in several convenient +forms: + + x_offset = png_get_x_offset_microns(png_ptr, info_ptr); + y_offset = png_get_y_offset_microns(png_ptr, info_ptr); + x_offset = png_get_x_offset_inches(png_ptr, info_ptr); + y_offset = png_get_y_offset_inches(png_ptr, info_ptr); + + (Each of these returns 0 [signifying "unknown" if both + x and y are 0] if the data is not present or if the + chunk is present but the unit is the pixel) + +For more information, see the png_info definition in png.h and the +PNG specification for chunk contents. Be careful with trusting +rowbytes, as some of the transformations could increase the space +needed to hold a row (expand, filler, gray_to_rgb, etc.). +See png_read_update_info(), below. + +A quick word about text_ptr and num_text. PNG stores comments in +keyword/text pairs, one pair per chunk, with no limit on the number +of text chunks, and a 2^31 byte limit on their size. While there are +suggested keywords, there is no requirement to restrict the use to these +strings. It is strongly suggested that keywords and text be sensible +to humans (that's the point), so don't use abbreviations. Non-printing +symbols are not allowed. See the PNG specification for more details. +There is also no requirement to have text after the keyword. + +Keywords should be limited to 79 Latin-1 characters without leading or +trailing spaces, but non-consecutive spaces are allowed within the +keyword. It is possible to have the same keyword any number of times. +The text_ptr is an array of png_text structures, each holding a +pointer to a language string, a pointer to a keyword and a pointer to +a text string. The text string, language code, and translated +keyword may be empty or NULL pointers. The keyword/text +pairs are put into the array in the order that they are received. +However, some or all of the text chunks may be after the image, so, to +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 +should occur. This is important, as some of these change the color +type and/or bit depth of the data, and some others only work on +certain color types and bit depths. Even though each transformation +checks to see if it has data that it can do something with, you should +make sure to only enable a transformation if it will be valid for the +data. For example, don't swap red and blue on grayscale data. + +The colors used for the background and transparency values should be +supplied in the same format/depth as the current image data. They +are stored in the same format/depth as the image data in a bKGD or tRNS +chunk, so this is what libpng expects for this data. The colors are +transformed to keep in sync with the image data when an application +calls the png_read_update_info() routine (see below). + +Data will be decoded into the supplied row buffers packed into bytes +unless the library has been told to transform it into another format. +For example, 4 bit/pixel paletted or grayscale data will be returned +2 pixels/byte with the leftmost pixel in the high-order bits of the +byte, unless png_set_packing() is called. 8-bit RGB data will be stored +in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha() +is called to insert filler bytes, either before or after each RGB triplet. +16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant +byte of the color value first, unless png_set_strip_16() is called to +transform it to regular RGB RGB triplets, or png_set_filler() or +png_set_add alpha() is called to insert filler bytes, either before or +after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can +be modified with +png_set_filler(), png_set_add_alpha(), or png_set_strip_16(). + +The following code transforms grayscale images of less than 8 to 8 bits, +changes paletted images to RGB, and adds a full alpha channel if there is +transparency information in a tRNS chunk. This is most useful on +grayscale images with bit depths of 2 or 4 or if there is a multiple-image +viewing application that wishes to treat all images in the same way. + + if (color_type == PNG_COLOR_TYPE_PALETTE) + png_set_palette_to_rgb(png_ptr); + + if (color_type == PNG_COLOR_TYPE_GRAY && + bit_depth < 8) png_set_gray_1_2_4_to_8(png_ptr); + + if (png_get_valid(png_ptr, info_ptr, + PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr); + +These three functions are actually aliases for png_set_expand(), added +in libpng version 1.0.4, with the function names expanded to improve code +readability. In some future version they may actually do different +things. + +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) + png_set_strip_16(png_ptr); + +If, for some reason, you don't need the alpha channel on an image, +and you want to remove it rather than combining it with the background +(but the image author certainly had in mind that you *would* combine +it with the background, so that's what you should probably do): + + if (color_type & PNG_COLOR_MASK_ALPHA) + png_set_strip_alpha(png_ptr); + +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); + +PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as +they can, resulting in, for example, 8 pixels per byte for 1 bit +files. This code expands to 1 pixel per byte without changing the +values of the pixels: + + if (bit_depth < 8) + png_set_packing(png_ptr); + +PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels +stored in a PNG image have been "scaled" or "shifted" up to the next +higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to +8 bits/sample in the range [0, 255]). However, it is also possible to +convert the PNG pixel data back to the original bit depth of the image. +This call reduces the pixels back down to the original bit depth: + + png_color_8p sig_bit; + + if (png_get_sBIT(png_ptr, info_ptr, &sig_bit)) + png_set_shift(png_ptr, sig_bit); + +PNG files store 3-color pixels in red, green, blue order. This code +changes the storage of the pixels to blue, green, red: + + if (color_type == PNG_COLOR_TYPE_RGB || + color_type == PNG_COLOR_TYPE_RGB_ALPHA) + png_set_bgr(png_ptr); + +PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them +into 4 or 8 bytes for windowing systems that need them in this format: + + if (color_type == PNG_COLOR_TYPE_RGB) + png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE); + +where "filler" is the 8 or 16-bit number to fill with, and the location is +either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether +you want the filler before the RGB or after. This transformation +does not affect images that already have full alpha channels. To add an +opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which +will generate RGBA pixels. + +Note that png_set_filler() does not change the color type. If you want +to do that, you can add a true alpha channel with + + if (color_type == PNG_COLOR_TYPE_RGB || + color_type == PNG_COLOR_TYPE_GRAY) + png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER); + +where "filler" contains the alpha value to assign to each pixel. +This function was added in libpng-1.2.7. + +If you are reading an image with an alpha channel, and you need the +data as ARGB instead of the normal PNG format RGBA: + + if (color_type == PNG_COLOR_TYPE_RGB_ALPHA) + png_set_swap_alpha(png_ptr); + +For some uses, you may want a grayscale image to be represented as +RGB. This code will do that conversion: + + if (color_type == PNG_COLOR_TYPE_GRAY || + color_type == PNG_COLOR_TYPE_GRAY_ALPHA) + png_set_gray_to_rgb(png_ptr); + +Conversely, you can convert an RGB or RGBA image to grayscale or grayscale +with alpha. + + if (color_type == PNG_COLOR_TYPE_RGB || + color_type == PNG_COLOR_TYPE_RGB_ALPHA) + png_set_rgb_to_gray_fixed(png_ptr, error_action, + int red_weight, int green_weight); + + error_action = 1: silently do the conversion + error_action = 2: issue a warning if the original + image has any pixel where + red != green or red != blue + error_action = 3: issue an error and abort the + conversion if the original + image has any pixel where + red != green or red != blue + + red_weight: weight of red component times 100000 + green_weight: weight of green component times 100000 + If either weight is negative, default + weights (21268, 71514) are used. + +If you have set error_action = 1 or 2, you can +later check whether the image really was gray, after processing +the image rows, with the png_get_rgb_to_gray_status(png_ptr) function. +It will return a png_byte that is zero if the image was gray or +1 if there were any non-gray pixels. bKGD and sBIT data +will be silently converted to grayscale, using the green channel +data, regardless of the error_action setting. + +With red_weight+green_weight<=100000, +the normalized graylevel is computed: + + int rw = red_weight * 65536; + int gw = green_weight * 65536; + int bw = 65536 - (rw + gw); + gray = (rw*red + gw*green + bw*blue)/65536; + +The default values approximate those recommended in the Charles +Poynton's Color FAQ, +Copyright (c) 1998-01-04 Charles Poynton + + Y = 0.212671 * R + 0.715160 * G + 0.072169 * B + +Libpng approximates this with + + Y = 0.21268 * R + 0.7151 * G + 0.07217 * B + +which can be expressed with integers as + + Y = (6969 * R + 23434 * G + 2365 * B)/32768 + +The calculation is done in a linear colorspace, if the image gamma +is known. + +If you have a grayscale and you are using png_set_expand_depth(), +png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to +a higher bit-depth, you must either supply the background color as a gray +value at the original file bit-depth (need_expand = 1) or else supply the +background color as an RGB triplet at the final, expanded bit depth +(need_expand = 0). Similarly, if you are reading a paletted image, you +must either supply the background color as a palette index (need_expand = 1) +or as an RGB triplet that may or may not be in the palette (need_expand = 0). + + png_color_16 my_background; + png_color_16p image_background; + + if (png_get_bKGD(png_ptr, info_ptr, &image_background)) + png_set_background(png_ptr, image_background, + PNG_BACKGROUND_GAMMA_FILE, 1, 1.0); + else + png_set_background(png_ptr, &my_background, + PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0); + +The png_set_background() function tells libpng to composite images +with alpha or simple transparency against the supplied background +color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), +you may use this color, or supply another color more suitable for +the current display (e.g., the background color from a web page). You +need to tell libpng whether the color is in the gamma space of the +display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file +(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one +that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't +know why anyone would use this, but it's here). + +To properly display PNG images on any kind of system, the application needs +to know what the display gamma is. Ideally, the user will know this, and +the application will allow them to set it. One method of allowing the user +to set the display gamma separately for each system is to check for a +SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be +correctly set. + +Note that display_gamma is the overall gamma correction required to produce +pleasing results, which depends on the lighting conditions in the surrounding +environment. In a dim or brightly lit room, no compensation other than +the physical gamma exponent of the monitor is needed, while in a dark room +a slightly smaller exponent is better. + + double gamma, screen_gamma; + + if (/* We have a user-defined screen + gamma value */) + { + screen_gamma = user_defined_screen_gamma; + } + /* One way that applications can share the same + screen gamma value */ + else if ((gamma_str = getenv("SCREEN_GAMMA")) + != NULL) + { + screen_gamma = (double)atof(gamma_str); + } + /* If we don't have another value */ + else + { + screen_gamma = 2.2; /* A good guess for a + PC monitor in a bright office or a dim room */ + screen_gamma = 2.0; /* A good guess for a + PC monitor in a dark room */ + screen_gamma = 1.7 or 1.0; /* A good + guess for Mac systems */ + } + +The png_set_gamma() function handles gamma transformations of the data. +Pass both the file gamma and the current screen_gamma. If the file does +not have a gamma value, you can pass one anyway if you have an idea what +it is (usually 0.45455 is a good guess for GIF images on PCs). Note +that file gammas are inverted from screen gammas. See the discussions +on gamma in the PNG specification for an excellent description of what +gamma is, and why all applications should support it. It is strongly +recommended that PNG viewers support gamma correction. + + if (png_get_gAMA(png_ptr, info_ptr, &gamma)) + png_set_gamma(png_ptr, screen_gamma, gamma); + else + png_set_gamma(png_ptr, screen_gamma, 0.45455); + +If you need to reduce an RGB file to a paletted file, or if a paletted +file has more entries then will fit on your screen, png_set_dither() +will do that. Note that this is a simple match dither that merely +finds the closest color available. This should work fairly well with +optimized palettes, and fairly badly with linear color cubes. If you +pass a palette that is larger then 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 +more intelligent choices when reducing the palette. If there is no +histogram, it may not do as good a job. + + if (color_type & PNG_COLOR_MASK_COLOR) + { + if (png_get_valid(png_ptr, info_ptr, + PNG_INFO_PLTE)) + { + png_uint_16p histogram = NULL; + + png_get_hIST(png_ptr, info_ptr, + &histogram); + png_set_dither(png_ptr, palette, num_palette, + max_screen_colors, histogram, 1); + } + else + { + png_color std_color_cube[MAX_SCREEN_COLORS] = + { ... colors ... }; + + png_set_dither(png_ptr, std_color_cube, + MAX_SCREEN_COLORS, MAX_SCREEN_COLORS, + NULL,0); + } + } + +PNG files describe monochrome as black being zero and white being one. +The following code will reverse this (make black be one and white be +zero): + + if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY) + png_set_invert_mono(png_ptr); + +This function can also be used to invert grayscale and gray-alpha images: + + if (color_type == PNG_COLOR_TYPE_GRAY || + color_type == PNG_COLOR_TYPE_GRAY_ALPHA) + png_set_invert_mono(png_ptr); + +PNG files store 16 bit pixels in network byte order (big-endian, +ie. most significant bits first). This code changes the storage to the +other way (little-endian, i.e. least significant bits first, the +way PCs store them): + + if (bit_depth == 16) + png_set_swap(png_ptr); + +If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you +need to change the order the pixels are packed into bytes, you can use: + + if (bit_depth < 8) + png_set_packswap(png_ptr); + +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 + + png_set_read_user_transform_fn(png_ptr, + read_transform_fn); + +You must supply the function + + void read_transform_fn(png_ptr ptr, row_info_ptr + row_info, png_bytep data) + +See pngtest.c for a working example. Your function will be called +after all of the other transformations have been processed. + +You can also set up a pointer to a user structure for use by your +callback function, and you can inform libpng that your transform +function will change the number of channels or bit depth with the +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: + + voidp read_user_transform_ptr = + png_get_user_transform_ptr(png_ptr); + +The last thing to handle is interlacing; this is covered in detail below, +but you must call the function here if you want libpng to handle expansion +of the interlaced image. + + number_of_passes = png_set_interlace_handling(png_ptr); + +After setting the transformations, libpng can update your png_info +structure to reflect any transformations you've requested with this +call. This is most useful to update the info structure's rowbytes +field so you can use it to allocate your image memory. This function +will also update your palette with the correct screen_gamma and +background if these have been given with the calls above. + + png_read_update_info(png_ptr, info_ptr); + +After you call png_read_update_info(), you can allocate any +memory you need to hold the image. The row data is simply +raw byte data for all forms of images. As the actual allocation +varies among applications, no example will be given. If you +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 +call png_read_image() and libpng will read in all the image data +and put it in the memory area supplied. You will need to pass in +an array of pointers to each row. + +This function automatically handles interlacing, so you don't need +to call png_set_interlace_handling() or call this function multiple +times, or any of that other stuff necessary with png_read_rows(). + + png_read_image(png_ptr, row_pointers); + +where row_pointers is: + + png_bytep row_pointers[height]; + +You can point to void or char or whatever you use for pixels. + +If you don't want to read in the whole image at once, you can +use png_read_rows() instead. If there is no interlacing (check +interlace_type == PNG_INTERLACE_NONE), this is simple: + + png_read_rows(png_ptr, row_pointers, NULL, + number_of_rows); + +where row_pointers is the same as in the png_read_image() call. + +If you are doing this just one row at a time, you can do this with +a single row_pointer instead of an array of row_pointers: + + png_bytep row_pointer = row; + png_read_row(png_ptr, row_pointer, NULL); + +If the file is interlaced (interlace_type != 0 in the IHDR chunk), things +get somewhat harder. The only current (PNG Specification version 1.2) +interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7) +is a somewhat complicated 2D interlace scheme, known as Adam7, that +breaks down an image into seven smaller images of varying size, based +on an 8x8 grid. + +libpng can fill out those images or it can give them to you "as is". +If you want them filled out, there are two ways to do that. The one +mentioned in the PNG specification is to expand each pixel to cover +those pixels that have not been read yet (the "rectangle" method). +This results in a blocky image for the first pass, which gradually +smooths out as more pixels are read. The other method is the "sparkle" +method, where pixels are drawn only in their final locations, with the +rest of the image remaining whatever colors they were initialized to +before the start of the read. The first method usually looks better, +but tends to be slower, as there are more pixels to put in the rows. + +If you don't want libpng to handle the interlacing details, just call +png_read_rows() seven times to read in all seven images. Each of the +images is a valid image by itself, or they can all be combined on an +8x8 grid to form a single image (although if you intend to combine them +you would be far better off using the libpng interlace handling). + +The first pass will return an image 1/8 as wide as the entire image +(every 8th column starting in column 0) and 1/8 as high as the original +(every 8th row starting in row 0), the second will be 1/8 as wide +(starting in column 4) and 1/8 as high (also starting in row 0). The +third pass will be 1/4 as wide (every 4th pixel starting in column 0) and +1/8 as high (every 8th row starting in row 4), and the fourth pass will +be 1/4 as wide and 1/4 as high (every 4th column starting in column 2, +and every 4th row starting in row 0). The fifth pass will return an +image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2), +while the sixth pass will be 1/2 as wide and 1/2 as high as the original +(starting in column 1 and row 0). The seventh and final pass will be as +wide as the original, and 1/2 as high, containing all of the odd +numbered scanlines. Phew! + +If you want libpng to expand the images, call this before calling +png_start_read_image() or png_read_update_info(): + + if (interlace_type == PNG_INTERLACE_ADAM7) + number_of_passes + = png_set_interlace_handling(png_ptr); + +This will return the number of passes needed. Currently, this +is seven, but may change if another interlace type is added. +This function can be called even if the file is not interlaced, +where it will return one pass. + +If you are not going to display the image after each pass, but are +going to wait until the entire image is read in, use the sparkle +effect. This effect is faster and the end result of either method +is exactly the same. If you are planning on displaying the image +after each pass, the "rectangle" effect is generally considered the +better looking one. + +If you only want the "sparkle" effect, just call png_read_rows() as +normal, with the third parameter NULL. Make sure you make pass over +the image number_of_passes times, and you don't change the data in the +rows between calls. You can change the locations of the data, just +not the data. Each pass only writes the pixels appropriate for that +pass, and assumes the data from previous passes is still valid. + + png_read_rows(png_ptr, row_pointers, NULL, + number_of_rows); + +If you only want the first effect (the rectangles), do the same as +before except pass the row buffer in the third parameter, and leave +the second parameter NULL. + + png_read_rows(png_ptr, NULL, row_pointers, + number_of_rows); + +.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); + +When you are done, you can free all memory allocated by libpng like this: + + png_destroy_read_struct(&png_ptr, &info_ptr, + &end_info); + +It is also possible to individually free the info_ptr members that +point to libpng-allocated storage with the following function: + + png_free_data(png_ptr, info_ptr, mask, seq) + mask - identifies data to be freed, a mask + containing the logical OR of one or + more of + PNG_FREE_PLTE, PNG_FREE_TRNS, + PNG_FREE_HIST, PNG_FREE_ICCP, + PNG_FREE_PCAL, PNG_FREE_ROWS, + PNG_FREE_SCAL, PNG_FREE_SPLT, + PNG_FREE_TEXT, PNG_FREE_UNKN, + or simply PNG_FREE_ALL + seq - sequence number of item to be freed + (-1 for all items) + +This function may be safely called when the relevant storage has +already been freed, or has not yet been allocated, or was allocated +by the user and not by libpng, and will in those +cases do nothing. The "seq" parameter is ignored if only one item +of the selected data type, such as PLTE, is allowed. If "seq" is not +-1, and multiple items are allowed for the data type identified in +the mask, such as text or sPLT, only the n'th item in the structure +is freed, where n is "seq". + +The default behavior is only to free data that was allocated internally +by libpng. This can be changed, so that libpng will not free the data, +or so that it will free data that was allocated by the user with png_malloc() +or png_zalloc() and passed in via a png_set_*() function, with + + png_data_freer(png_ptr, info_ptr, freer, mask) + mask - which data elements are affected + same choices as in png_free_data() + freer - one of + PNG_DESTROY_WILL_FREE_DATA + PNG_SET_WILL_FREE_DATA + PNG_USER_WILL_FREE_DATA + +This function only affects data that has already been allocated. +You can call this function after reading the PNG data but before calling +any png_set_*() functions, to control whether the user or the png_set_*() +function is responsible for freeing any existing data that might be present, +and again after the png_set_*() functions to control whether the user +or png_destroy_*() is supposed to free the data. When the user assumes +responsibility for libpng-allocated data, the application must use +png_free() to free it, and when the user transfers responsibility to libpng +for data that the user has allocated, the user must have used png_malloc() +or png_zalloc() to allocate it. + +If you allocated your row_pointers in a single block, as suggested above in +the description of the high level read interface, you must not transfer +responsibility for freeing it to the png_set_rows or png_read_destroy function, +because they would also try to free the individual row_pointers[i]. + +If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword +separately, do not transfer responsibility for freeing text_ptr to libpng, +because when libpng fills a png_text structure it combines these members with +the key member, and png_free_data() will free only text_ptr.key. Similarly, +if you transfer responsibility for free'ing text_ptr from libpng to your +application, your application must not separately free those members. + +The png_free_data() function will turn off the "valid" flag for anything +it frees. If you need to turn the flag off for a chunk that was freed by your +application instead of by libpng, you can use + + png_set_invalid(png_ptr, info_ptr, mask); + mask - identifies the chunks to be made invalid, + containing the logical OR of one or + more of + PNG_INFO_gAMA, PNG_INFO_sBIT, + PNG_INFO_cHRM, PNG_INFO_PLTE, + PNG_INFO_tRNS, PNG_INFO_bKGD, + PNG_INFO_hIST, PNG_INFO_pHYs, + PNG_INFO_oFFs, PNG_INFO_tIME, + PNG_INFO_pCAL, PNG_INFO_sRGB, + PNG_INFO_iCCP, PNG_INFO_sPLT, + PNG_INFO_sCAL, PNG_INFO_IDAT + +For a more compact example of reading a PNG image, see the file example.c. + +.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 +png_read_end(), you make one call to png_process_data(), which calls +callbacks when it has the info, a row, or the end of the image. You +set up these callbacks with png_set_progressive_read_fn(). You don't +have to worry about the input/output functions of libpng, as you are +giving the library the data directly in png_process_data(). I will +assume that you have read the section on reading PNG files above, +so I will only highlight the differences (although I will show +all of the code). + +png_structp png_ptr; +png_infop info_ptr; + + /* An example code fragment of how you would + initialize the progressive reader in your + application. */ + int + initialize_png_reader() + { + png_ptr = png_create_read_struct + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, + user_error_fn, user_warning_fn); + if (!png_ptr) + return (ERROR); + info_ptr = png_create_info_struct(png_ptr); + if (!info_ptr) + { + png_destroy_read_struct(&png_ptr, (png_infopp)NULL, + (png_infopp)NULL); + return (ERROR); + } + + if (setjmp(png_jmpbuf(png_ptr))) + { + png_destroy_read_struct(&png_ptr, &info_ptr, + (png_infopp)NULL); + return (ERROR); + } + + /* This one's new. You can provide functions + to be called when the header info is valid, + when each row is completed, and when the image + is finished. If you aren't using all functions, + you can specify NULL parameters. Even when all + three functions are NULL, you need to call + png_set_progressive_read_fn(). You can use + any struct as the user_ptr (cast to a void pointer + for the function call), and retrieve the pointer + from inside the callbacks using the function + + png_get_progressive_ptr(png_ptr); + + which will return a void pointer, which you have + to cast appropriately. + */ + png_set_progressive_read_fn(png_ptr, (void *)user_ptr, + info_callback, row_callback, end_callback); + + return 0; + } + + /* A code fragment that you call as you receive blocks + of data */ + int + process_data(png_bytep buffer, png_uint_32 length) + { + if (setjmp(png_jmpbuf(png_ptr))) + { + png_destroy_read_struct(&png_ptr, &info_ptr, + (png_infopp)NULL); + return (ERROR); + } + + /* This one's new also. Simply give it a chunk + of data from the file stream (in order, of + course). On machines with segmented memory + models machines, don't give it any more than + 64K. The library seems to run fine with sizes + of 4K. Although you can give it much less if + necessary (I assume you can give it chunks of + 1 byte, I haven't tried less then 256 bytes + yet). When this function returns, you may + want to display any rows that were generated + in the row callback if you don't already do + so there. + */ + png_process_data(png_ptr, info_ptr, buffer, length); + return 0; + } + + /* This function is called (as set by + png_set_progressive_read_fn() above) when enough data + has been supplied so all of the header has been + read. + */ + void + info_callback(png_structp png_ptr, png_infop info) + { + /* Do any setup here, including setting any of + the transformations mentioned in the Reading + PNG files section. For now, you _must_ call + either png_start_read_image() or + png_read_update_info() after all the + transformations are set (even if you don't set + any). You may start getting rows before + png_process_data() returns, so this is your + last chance to prepare for that. + */ + } + + /* This function is called when each row of image + data is complete */ + void + row_callback(png_structp png_ptr, png_bytep new_row, + png_uint_32 row_num, int pass) + { + /* If the image is interlaced, and you turned + on the interlace handler, this function will + be called for every row in every pass. Some + of these rows will not be changed from the + previous pass. When the row is not changed, + the new_row variable will be NULL. The rows + and passes are called in order, so you don't + really need the row_num and pass, but I'm + supplying them because it may make your life + easier. + + For the non-NULL rows of interlaced images, + you must call png_progressive_combine_row() + passing in the row and the old row. You can + call this function for NULL rows (it will just + return) and for non-interlaced images (it just + does the memcpy for you) if it will make the + code easier. Thus, you can just do this for + all cases: + */ + + png_progressive_combine_row(png_ptr, old_row, + new_row); + + /* where old_row is what was displayed for + previously for the row. Note that the first + pass (pass == 0, really) will completely cover + the old row, so the rows do not have to be + initialized. After the first pass (and only + for interlaced images), you will have to pass + the current row, and the function will combine + the old row and the new row. + */ + } + + void + end_callback(png_structp png_ptr, png_infop info) + { + /* This function is called after the whole image + has been read, including any chunks after the + image (up to and including the IEND). You + will usually have the same info chunk as you + had in the header, although some data may have + been added to the comments and time fields. + + Most people won't do much here, perhaps setting + a flag that marks the image as finished. + */ + } + + + +.SH IV. Writing + +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 +custom writing functions. See the discussion under Customizing libpng. + + FILE *fp = fopen(file_name, "wb"); + if (!fp) + { + return (ERROR); + } + +Next, png_struct and png_info need to be allocated and initialized. +As these can be both relatively large, you may not want to store these +on the stack, unless you have stack space to spare. Of course, you +will want to check if they return NULL. If you are also reading, +you won't want to name your read structure and your write structure +both "png_ptr"; you can call them anything you like, such as +"read_ptr" and "write_ptr". Look at pngtest.c, for example. + + png_structp png_ptr = png_create_write_struct + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, + user_error_fn, user_warning_fn); + if (!png_ptr) + return (ERROR); + + png_infop info_ptr = png_create_info_struct(png_ptr); + if (!info_ptr) + { + png_destroy_write_struct(&png_ptr, + (png_infopp)NULL); + return (ERROR); + } + +If you want to use your own memory allocation routines, +define PNG_USER_MEM_SUPPORTED and use +png_create_write_struct_2() instead of png_create_write_struct(): + + png_structp png_ptr = png_create_write_struct_2 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, + user_error_fn, user_warning_fn, (png_voidp) + user_mem_ptr, user_malloc_fn, user_free_fn); + +After you have these structures, you will need to set up the +error handling. When libpng encounters an error, it expects to +longjmp() back to your routine. Therefore, you will need to call +setjmp() and pass the png_jmpbuf(png_ptr). If you +write the file from different routines, you will need to update +the png_jmpbuf(png_ptr) every time you enter a new routine that will +call a png_*() function. See your documentation of setjmp/longjmp +for your compiler for more information on setjmp/longjmp. See +the discussion on libpng error handling in the Customizing Libpng +section below for more information on the libpng error handling. + + if (setjmp(png_jmpbuf(png_ptr))) + { + png_destroy_write_struct(&png_ptr, &info_ptr); + fclose(fp); + return (ERROR); + } + ... + 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 +opened in binary mode. Again, if you wish to handle writing data in +another way, see the discussion on libpng I/O handling in the Customizing +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. +You must supply a function + + void write_row_callback(png_ptr, png_uint_32 row, + int pass); + { + /* put your code here */ + } + +(You can give it another name that you like instead of "write_row_callback") + +To inform libpng about your function, use + + png_set_write_status_fn(png_ptr, write_row_callback); + +You now have the option of modifying how the compression library will +run. The following functions are mainly for testing, but may be useful +in some cases, like if you need to write PNG files extremely fast and +are willing to give up some compression, or if you want to get the +maximum possible compression at the expense of slower writing. If you +have no special needs in this area, let the library do what it wants by +not calling this function at all, as it has been tuned to deliver a good +speed/compression ratio. The second parameter to png_set_filter() is +the filter method, for which the only valid values are 0 (as of the +July 1999 PNG specification, version 1.2) or 64 (if you are writing +a PNG datastream that is to be embedded in a MNG datastream). The third +parameter is a flag that indicates which filter type(s) are to be tested +for each scanline. See the PNG specification for details on the specific filter +types. + + + /* turn on or off filtering, and/or choose + specific filters. You can use either a single + PNG_FILTER_VALUE_NAME or the logical OR of one + or more PNG_FILTER_NAME masks. */ + png_set_filter(png_ptr, 0, + PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE | + PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB | + PNG_FILTER_UP | PNG_FILTER_VALUE_UP | + PNG_FILTER_AVE | PNG_FILTER_VALUE_AVE | + PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH| + PNG_ALL_FILTERS); + +If an application +wants to start and stop using particular filters during compression, +it should start out with all of the filters (to ensure that the previous +row of pixels will be stored in case it's needed later), and then add +and remove them after the start of compression. + +If you are writing a PNG datastream that is to be embedded in a MNG +datastream, the second parameter can be either 0 or 64. + +The png_set_compression_*() functions interface to the zlib compression +library, and should mostly be ignored unless you really know what you are +doing. The only generally useful call is png_set_compression_level() +which changes how much time zlib spends on trying to compress the image +data. See the Compression Library (zlib.h and algorithm.txt, distributed +with zlib) for details on the compression levels. + + /* set the zlib compression level */ + png_set_compression_level(png_ptr, + Z_BEST_COMPRESSION); + + /* set other zlib parameters */ + png_set_compression_mem_level(png_ptr, 8); + png_set_compression_strategy(png_ptr, + Z_DEFAULT_STRATEGY); + png_set_compression_window_bits(png_ptr, 15); + png_set_compression_method(png_ptr, 8); + png_set_compression_buffer_size(png_ptr, 8192) + +extern PNG_EXPORT(void,png_set_zbuf_size) + +.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 +chunk (as of PNG Specification 1.2, anyway). See png_write_end() and +the latest PNG specification for more information on that. If you +wish to write them before the image, fill them in now, and flag that +data as being valid. If you want to wait until after the data, don't +fill them until png_write_end(). For all the fields in png_info and +their data types, see png.h. For explanations of what the fields +contain, see the PNG specification. + +Some of the more important parts of the png_info are: + + png_set_IHDR(png_ptr, info_ptr, width, height, + bit_depth, color_type, interlace_type, + compression_type, filter_method) + width - holds the width of the image + in pixels (up to 2^31). + height - holds the height of the image + in pixels (up to 2^31). + bit_depth - holds the bit depth of one of the + image channels. + (valid values are 1, 2, 4, 8, 16 + and depend also on the + color_type. See also significant + bits (sBIT) below). + color_type - describes which color/alpha + channels are present. + PNG_COLOR_TYPE_GRAY + (bit depths 1, 2, 4, 8, 16) + PNG_COLOR_TYPE_GRAY_ALPHA + (bit depths 8, 16) + PNG_COLOR_TYPE_PALETTE + (bit depths 1, 2, 4, 8) + PNG_COLOR_TYPE_RGB + (bit_depths 8, 16) + PNG_COLOR_TYPE_RGB_ALPHA + (bit_depths 8, 16) + + PNG_COLOR_MASK_PALETTE + PNG_COLOR_MASK_COLOR + PNG_COLOR_MASK_ALPHA + + interlace_type - PNG_INTERLACE_NONE or + PNG_INTERLACE_ADAM7 + compression_type - (must be + PNG_COMPRESSION_TYPE_DEFAULT) + filter_method - (must be PNG_FILTER_TYPE_DEFAULT + or, if you are writing a PNG to + be embedded in a MNG datastream, + can also be + PNG_INTRAPIXEL_DIFFERENCING) + + png_set_PLTE(png_ptr, info_ptr, palette, + num_palette); + palette - the palette for the file + (array of png_color) + num_palette - number of entries in the palette + + png_set_gAMA(png_ptr, info_ptr, gamma); + gamma - the gamma the image was created + at (PNG_INFO_gAMA) + + png_set_sRGB(png_ptr, info_ptr, srgb_intent); + srgb_intent - the rendering intent + (PNG_INFO_sRGB) The presence of + the sRGB chunk means that the pixel + data is in the sRGB color space. + This chunk also implies specific + values of gAMA and cHRM. Rendering + intent is the CSS-1 property that + has been defined by the International + Color Consortium + (http://www.color.org). + It can be one of + PNG_sRGB_INTENT_SATURATION, + PNG_sRGB_INTENT_PERCEPTUAL, + PNG_sRGB_INTENT_ABSOLUTE, or + PNG_sRGB_INTENT_RELATIVE. + + + png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr, + srgb_intent); + srgb_intent - the rendering intent + (PNG_INFO_sRGB) The presence of the + sRGB chunk means that the pixel + data is in the sRGB color space. + This function also causes gAMA and + cHRM chunks with the specific values + that are consistent with sRGB to be + written. + + png_set_iCCP(png_ptr, info_ptr, name, compression_type, + profile, proflen); + name - The profile name. + compression - The compression type; always + PNG_COMPRESSION_TYPE_BASE for PNG 1.0. + You may give NULL to this argument to + ignore it. + profile - International Color Consortium color + profile data. May contain NULs. + proflen - length of profile data in bytes. + + png_set_sBIT(png_ptr, info_ptr, sig_bit); + sig_bit - the number of significant bits for + (PNG_INFO_sBIT) each of the gray, red, + green, and blue channels, whichever are + appropriate for the given color type + (png_color_16) + + png_set_tRNS(png_ptr, info_ptr, trans, num_trans, + trans_values); + trans - array of transparent entries for + palette (PNG_INFO_tRNS) + trans_values - graylevel or color sample values 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); + (PNG_INFO_hIST) + hist - histogram of palette (array of + png_uint_16) + + png_set_tIME(png_ptr, info_ptr, mod_time); + mod_time - time image was last modified + (PNG_VALID_tIME) + + png_set_bKGD(png_ptr, info_ptr, background); + background - background color (PNG_VALID_bKGD) + + png_set_text(png_ptr, info_ptr, text_ptr, num_text); + text_ptr - array of png_text holding image + comments + 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. Must contain + 1-79 characters. + text_ptr[i].text - text comments for current + keyword. Can be NULL or empty. + 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 or + empty for unknown). + text_ptr[i].translated_keyword - keyword in UTF-8 (NULL + or empty for unknown). + num_text - number of comments + + png_set_sPLT(png_ptr, info_ptr, &palette_ptr, + num_spalettes); + palette_ptr - array of png_sPLT_struct structures + to be added to the list of palettes + in the info structure. + num_spalettes - number of palette structures to be + added. + + png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y, + unit_type); + offset_x - positive offset from the left + edge of the screen + offset_y - positive offset from the top + edge of the screen + unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER + + png_set_pHYs(png_ptr, info_ptr, res_x, res_y, + unit_type); + res_x - pixels/unit physical resolution + in x direction + res_y - pixels/unit physical resolution + in y direction + unit_type - PNG_RESOLUTION_UNKNOWN, + PNG_RESOLUTION_METER + + png_set_sCAL(png_ptr, info_ptr, unit, width, height) + unit - physical scale units (an integer) + width - width of a pixel in physical scale units + height - height of a pixel in physical scale units + (width and height are doubles) + + png_set_sCAL_s(png_ptr, info_ptr, unit, width, height) + unit - physical scale units (an integer) + width - width of a pixel in physical scale units + height - height of a pixel in physical scale units + (width and height are strings like "2.54") + + png_set_unknown_chunks(png_ptr, info_ptr, &unknowns, + num_unknowns) + unknowns - array of png_unknown_chunk + structures holding unknown chunks + unknowns[i].name - name of unknown chunk + unknowns[i].data - data of unknown chunk + unknowns[i].size - size of unknown chunk's data + 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. Within each of the "locations", +the chunks are sequenced according to their position in the +structure (that is, the value of "i", which is the order in which +the chunk was either read from the input file or defined with +png_set_unknown_chunks). + +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. +Each png_text structure holds a language code, a keyword, a text value, +and a compression type. + +The compression types have the same valid numbers as the compression +types of the image data. Currently, the only valid number is zero. +However, you can store text either compressed or uncompressed, unlike +images, which always have to be compressed. So if you don't want the +text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE. +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. +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 +png_write_end() with the same struct. + +The keywords that are given in the PNG Specification are: + + Title Short (one line) title or + caption for image + Author Name of image's creator + Description Description of image (possibly long) + Copyright Copyright notice + Creation Time Time of original image creation + (usually RFC 1123 format, see below) + Software Software used to create the image + Disclaimer Legal disclaimer + Warning Warning of nature of content + Source Device used to create the image + Comment Miscellaneous comment; conversion + from other image format + +The keyword-text pairs work like this. Keywords should be short +simple descriptions of what the comment is about. Some typical +keywords are found in the PNG specification, as is some recommendations +on keywords. You can repeat keywords in a file. You can even write +some text before the image and some after. For example, you may want +to put a description of the image before the image, but leave the +disclaimer until after, so viewers working over modem connections +don't have to wait for the disclaimer to go over the modem before +they start seeing the image. Finally, keywords should be full +words, not abbreviations. Keywords and text are in the ISO 8859-1 +(Latin-1) character set (a superset of regular ASCII) and can not +contain NUL characters, and should not contain control or other +unprintable characters. To make the comments widely readable, stick +with basic ASCII, and avoid machine specific character set extensions +like the IBM-PC character set. The keyword must be present, but +you can leave off the text string on non-compressed pairs. +Compressed pairs must have a text string, as only the text string +is compressed anyway, so the compression would be meaningless. + +PNG supports modification time via the png_time structure. Two +conversion routines are provided, png_convert_from_time_t() for +time_t and png_convert_from_struct_tm() for struct tm. The +time_t routine uses gmtime(). You don't have to use either of +these, but if you wish to fill in the png_time structure directly, +you should provide the time in universal time (GMT) if possible +instead of your local time. Note that the year number is the full +year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and +that months start with 1. + +If you want to store the time of the original image creation, you should +use a plain tEXt chunk with the "Creation Time" keyword. This is +necessary because the "creation time" of a PNG image is somewhat vague, +depending on whether you mean the PNG file, the time the image was +created in a non-PNG format, a still photo from which the image was +scanned, or possibly the subject matter itself. In order to facilitate +machine-readable dates, it is recommended that the "Creation Time" +tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"), +although this isn't a requirement. Unlike the tIME chunk, the +"Creation Time" tEXt chunk is not expected to be automatically changed +by the software. To facilitate the use of RFC 1123 dates, a function +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 +png_write_info_before_PLTE, png_write_info, or png_write_end function. +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. + +.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 +in the info structure. All defined output +transformations are permitted, 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 in the info structure (you can use +png_set_rows() to put image data in the info structure), 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 the set of transformations indicated by the transform mask, +then png_write_image(), and finally png_write_end(). + +(The final parameter of this call is not yet used. Someday it might point +to transformation parameters required by some future output transform.) + +You must use png_transforms and not call any png_set_transform() functions +when you use png_write_png(). + +.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: + + png_write_info_before_PLTE(png_ptr, info_ptr); + png_set_unknown_chunks(png_ptr, info_ptr, ...); + png_write_info(png_ptr, info_ptr); + +After you've written the file 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 +should occur. This is important, as some of these change the color +type and/or bit depth of the data, and some others only work on +certain color types and bit depths. Even though each transformation +checks to see if it has data that it can do something with, you should +make sure to only enable a transformation if it will be valid for the +data. For example, don't swap red and blue on grayscale data. + +PNG files store RGB pixels packed into 3 or 6 bytes. This code tells +the library to strip input data that has 4 or 8 bytes per pixel down +to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2 +bytes per pixel). + + png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE); + +where the 0 is unused, and the location is either PNG_FILLER_BEFORE or +PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel +is stored XRGB or RGBX. + +PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as +they can, resulting in, for example, 8 pixels per byte for 1 bit files. +If the data is supplied at 1 pixel per byte, use this code, which will +correctly pack the pixels into a single byte: + + png_set_packing(png_ptr); + +PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your +data is of another bit depth, you can write an sBIT chunk into the +file so that decoders can recover the original data if desired. + + /* Set the true bit depth of the image data */ + if (color_type & PNG_COLOR_MASK_COLOR) + { + sig_bit.red = true_bit_depth; + sig_bit.green = true_bit_depth; + sig_bit.blue = true_bit_depth; + } + else + { + sig_bit.gray = true_bit_depth; + } + if (color_type & PNG_COLOR_MASK_ALPHA) + { + sig_bit.alpha = true_bit_depth; + } + + png_set_sBIT(png_ptr, info_ptr, &sig_bit); + +If the data is stored in the row buffer in a bit depth other than +one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG), +this will scale the values to appear to be the correct bit depth as +is required by PNG. + + png_set_shift(png_ptr, &sig_bit); + +PNG files store 16 bit pixels in network byte order (big-endian, +ie. most significant bits first). This code would be used if they are +supplied the other way (little-endian, i.e. least significant bits +first, the way PCs store them): + + if (bit_depth > 8) + png_set_swap(png_ptr); + +If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you +need to change the order the pixels are packed into bytes, you can use: + + if (bit_depth < 8) + png_set_packswap(png_ptr); + +PNG files store 3 color pixels in red, green, blue order. This code +would be used if they are supplied as blue, green, red: + + png_set_bgr(png_ptr); + +PNG files describe monochrome as black being zero and white being +one. This code would be used if the pixels are supplied with this reversed +(black being one and white being zero): + + png_set_invert_mono(png_ptr); + +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 + + png_set_write_user_transform_fn(png_ptr, + write_transform_fn); + +You must supply the function + + void write_transform_fn(png_ptr ptr, row_info_ptr + row_info, png_bytep data) + +See pngtest.c for a working example. Your function will be called +before any of the other transformations are processed. + +You can also set up a pointer to a user structure for use by your +callback function. + + png_set_user_transform_info(png_ptr, user_ptr, 0, 0); + +The user_channels and user_depth parameters of this function are ignored +when writing; you can set them to zero as shown. + +You can retrieve the pointer via the function png_get_user_transform_ptr(). +For example: + + voidp write_user_transform_ptr = + png_get_user_transform_ptr(png_ptr); + +It is possible to have libpng flush any pending output, either manually, +or automatically after a certain number of lines have been written. To +flush the output stream a single time call: + + png_write_flush(png_ptr); + +and to have libpng flush the output stream periodically after a certain +number of scanlines have been written, call: + + png_set_flush(png_ptr, nrows); + +Note that the distance between rows is from the last time png_write_flush() +was called, or the first row of the image if it has never been called. +So if you write 50 lines, and then png_set_flush 25, it will flush the +output on the next scanline, and every 25 lines thereafter, unless +png_write_flush() is called before 25 more lines have been written. +If nrows is too small (less than about 10 lines for a 640 pixel wide +RGB image) the image compression may decrease noticeably (although this +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 you have the +whole image in memory, you can just call png_write_image() and libpng +will write the image. You will need to pass in an array of pointers to +each row. This function automatically handles interlacing, so you don't +need to call png_set_interlace_handling() or call this function multiple +times, or any of that other stuff necessary with png_write_rows(). + + png_write_image(png_ptr, row_pointers); + +where row_pointers is: + + png_byte *row_pointers[height]; + +You can point to void or char or whatever you use for pixels. + +If you don't want to write the whole image at once, you can +use png_write_rows() instead. If the file is not interlaced, +this is simple: + + png_write_rows(png_ptr, row_pointers, + number_of_rows); + +row_pointers is the same as in the png_write_image() call. + +If you are just writing one row at a time, you can do this with +a single row_pointer instead of an array of row_pointers: + + png_bytep row_pointer = row; + + 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 the 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 +these images for you, or you can do them yourself. If you want to +build them yourself, see the PNG specification for details of which +pixels to write when. + +If you don't want libpng to handle the interlacing details, just +use png_set_interlace_handling() and call png_write_rows() the +correct number of times to write all seven sub-images. + +If you want libpng to build the sub-images, call this before you start +writing any rows: + + number_of_passes = + png_set_interlace_handling(png_ptr); + +This will return the number of passes needed. Currently, this +is seven, but may change if another interlace type is added. + +Then write the complete image number_of_passes times. + + png_write_rows(png_ptr, row_pointers, + number_of_rows); + +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, +you can pass NULL. + + png_write_end(png_ptr, info_ptr); + +When you are done, you can free all memory used by libpng like this: + + png_destroy_write_struct(&png_ptr, &info_ptr); + +It is also possible to individually free the info_ptr members that +point to libpng-allocated storage with the following function: + + png_free_data(png_ptr, info_ptr, mask, seq) + mask - identifies data to be freed, a mask + containing the logical OR of one or + more of + PNG_FREE_PLTE, PNG_FREE_TRNS, + PNG_FREE_HIST, PNG_FREE_ICCP, + PNG_FREE_PCAL, PNG_FREE_ROWS, + PNG_FREE_SCAL, PNG_FREE_SPLT, + PNG_FREE_TEXT, PNG_FREE_UNKN, + or simply PNG_FREE_ALL + seq - sequence number of item to be freed + (-1 for all items) + +This function may be safely called when the relevant storage has +already been freed, or has not yet been allocated, or was allocated +by the user and not by libpng, and will in those +cases do nothing. The "seq" parameter is ignored if only one item +of the selected data type, such as PLTE, is allowed. If "seq" is not +-1, and multiple items are allowed for the data type identified in +the mask, such as text or sPLT, only the n'th item in the structure +is freed, where n is "seq". + +If you allocated data such as a palette that you passed +in to libpng with png_set_*, you must not free it until just before the call to +png_destroy_write_struct(). + +The default behavior is only to free data that was allocated internally +by libpng. This can be changed, so that libpng will not free the data, +or so that it will free data that was allocated by the user with png_malloc() +or png_zalloc() and passed in via a png_set_*() function, with + + png_data_freer(png_ptr, info_ptr, freer, mask) + mask - which data elements are affected + same choices as in png_free_data() + freer - one of + PNG_DESTROY_WILL_FREE_DATA + PNG_SET_WILL_FREE_DATA + PNG_USER_WILL_FREE_DATA + +For example, to transfer responsibility for some data from a read structure +to a write structure, you could use + + png_data_freer(read_ptr, read_info_ptr, + PNG_USER_WILL_FREE_DATA, + PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST) + png_data_freer(write_ptr, write_info_ptr, + PNG_DESTROY_WILL_FREE_DATA, + PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST) + +thereby briefly reassigning responsibility for freeing to the user but +immediately afterwards reassigning it once more to the write_destroy +function. Having done this, it would then be safe to destroy the read +structure and continue to use the PLTE, tRNS, and hIST data in the write +structure. + +This function only affects data that has already been allocated. +You can call this function before calling after the png_set_*() functions +to control whether the user or png_destroy_*() is supposed to free the data. +When the user assumes responsibility for libpng-allocated data, the +application must use +png_free() to free it, and when the user transfers responsibility to libpng +for data that the user has allocated, the user must have used png_malloc() +or png_zalloc() to allocate it. + +If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword +separately, do not transfer responsibility for freeing text_ptr to libpng, +because when libpng fills a png_text structure it combines these members with +the key member, and png_free_data() will free only text_ptr.key. Similarly, +if you transfer responsibility for free'ing text_ptr from libpng to your +application, your application must not separately free those members. +For a more compact example of writing a PNG image, see the file example.c. + +.SH V. Modifying/Customizing libpng: + +There are three issues here. The first is changing how libpng does +standard things like memory allocation, input/output, and error handling. +The second deals with more complicated things like adding new chunks, +adding new transformations, and generally changing how libpng works. +Both of those are compile-time issues; that is, they are generally +determined at the time the code is written, and there is rarely a need +to provide the user with a means of changing them. The third is a +run-time issue: choosing between and/or tuning one or more alternate +versions of computationally intensive routines; specifically, optimized +assembly-language (and therefore compiler- and platform-dependent) +versions. + +Memory allocation, input/output, and error handling + +All of the memory allocation, input/output, and error handling in libpng +goes through callbacks that are user-settable. The default routines are +in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change +these functions, call the appropriate png_set_*_fn() function. + +Memory allocation is done through the functions png_malloc() +and png_free(). These currently just call the standard C functions. If +your pointers can't access more then 64K at a time, you will want to set +MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling +memory allocation on a platform will change between applications, these +functions must be modified in the library at compile time. If you prefer +to use a different method of allocating and freeing data, you can use +png_create_read_struct_2() or png_create_write_struct_2() to register +your own functions as described above. +These functions also provide a void pointer that can be retrieved via + + mem_ptr=png_get_mem_ptr(png_ptr); + +Your replacement memory functions must have prototypes as follows: + + png_voidp malloc_fn(png_structp png_ptr, + png_size_t size); + void free_fn(png_structp png_ptr, png_voidp ptr); + +Your malloc_fn() must return NULL in case of failure. The png_malloc() +function will normally call png_error() if it receives a NULL from the +system memory allocator or from your replacement malloc_fn(). + +Input/Output in libpng is done through png_read() and png_write(), +which currently just call fread() and fwrite(). The FILE * is stored in +png_struct and is initialized via png_init_io(). If you wish to change +the method of I/O, the library supplies callbacks that you can set +through the function png_set_read_fn() and png_set_write_fn() at run +time, instead of calling the png_init_io() function. These functions +also provide a void pointer that can be retrieved via the function +png_get_io_ptr(). For example: + + png_set_read_fn(png_structp read_ptr, + voidp read_io_ptr, png_rw_ptr read_data_fn) + + png_set_write_fn(png_structp write_ptr, + voidp write_io_ptr, png_rw_ptr write_data_fn, + png_flush_ptr output_flush_fn); + + voidp read_io_ptr = png_get_io_ptr(read_ptr); + voidp write_io_ptr = png_get_io_ptr(write_ptr); + +The replacement I/O functions must have prototypes as follows: + + void user_read_data(png_structp png_ptr, + png_bytep data, png_size_t length); + void user_write_data(png_structp png_ptr, + png_bytep data, png_size_t length); + void user_flush_data(png_structp png_ptr); + +Supplying NULL for the read, write, or flush functions sets them back +to using the default C stream functions. It is an error to read from +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() (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_CONSOLE_IO defined +(because you don't want the messages) or PNG_NO_STDIO defined (because +fprintf() isn't available). If you wish to change the behavior of the error +functions, you will need to set up your own message callbacks. These +functions are normally supplied at the time that the png_struct is created. +It is also possible to redirect errors and warnings to your own replacement +functions after png_create_*_struct() has been called by calling: + + png_set_error_fn(png_structp png_ptr, + png_voidp error_ptr, png_error_ptr error_fn, + png_error_ptr warning_fn); + + png_voidp error_ptr = png_get_error_ptr(png_ptr); + +If NULL is supplied for either error_fn or warning_fn, then the libpng +default function will be used, calling fprintf() and/or longjmp() if a +problem is encountered. The replacement error functions should have +parameters as follows: + + void user_error_fn(png_structp png_ptr, + png_const_charp error_msg); + void user_warning_fn(png_structp png_ptr, + png_const_charp warning_msg); + +The motivation behind using setjmp() and longjmp() is the C++ throw and +catch exception handling methods. This makes the code much easier to write, +as there is no need to check every return code of every function call. +However, there are some uncertainties about the status of local variables +after a longjmp, so the user may want to be careful about doing anything after +setjmp returns non-zero besides returning itself. Consult your compiler +documentation for more details. For an alternative approach, you may wish +to use the "cexcept" facility (see http://cexcept.sourceforge.net). + +.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 +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. + +.SS Configuring for 16 bit platforms + +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. + +.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. + +.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 +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 *. + +.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 +warning functions at the time that png_create_*_struct() is called, +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.). + +.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 +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. + +.SS Configuring zlib: + +There are special functions to configure the compression. Perhaps the +most useful one changes the compression level, which currently uses +input compression values in the range 0 - 9. The library normally +uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests +have shown that for a large majority of images, compression values in +the range 3-6 compress nearly as well as higher levels, and do so much +faster. For online applications it may be desirable to have maximum speed +(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also +specify no compression (Z_NO_COMPRESSION = 0), but this would create +files larger than just storing the raw bitmap. You can specify the +compression level by calling: + + png_set_compression_level(png_ptr, level); + +Another useful one is to reduce the memory level used by the library. +The memory level defaults to 8, but it can be lowered if you are +short on memory (running DOS, for example, where you only have 640K). +Note that the memory level does have an effect on compression; among +other things, lower levels will result in sections of incompressible +data being emitted in smaller stored blocks, with a correspondingly +larger relative overhead of up to 15% in the worst case. + + png_set_compression_mem_level(png_ptr, level); + +The other functions are for configuring zlib. They are not recommended +for normal use and may result in writing an invalid PNG file. See +zlib.h for more information on what these mean. + + png_set_compression_strategy(png_ptr, + strategy); + png_set_compression_window_bits(png_ptr, + window_bits); + png_set_compression_method(png_ptr, method); + png_set_compression_buffer_size(png_ptr, size); + +.SS Controlling row filtering + +If you want to control whether libpng uses filtering or not, which +filters are used, and how it goes about picking row filters, you +can call one of these functions. The selection and configuration +of row filters can have a significant impact on the size and +encoding speed and a somewhat lesser impact on the decoding speed +of an image. Filtering is enabled by default for RGB and grayscale +images (with and without alpha), but not for paletted images nor +for any images with bit depths less than 8 bits/pixel. + +The 'method' parameter sets the main filtering method, which is +currently only '0' in the PNG 1.2 specification. The 'filters' +parameter sets which filter(s), if any, should be used for each +scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS +to turn filtering on and off, respectively. + +Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB, +PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise +ORed together with '|' to specify one or more filters to use. +These filters are described in more detail in the PNG specification. +If you intend to change the filter type during the course of writing +the image, you should start with flags set for all of the filters +you intend to use so that libpng can initialize its internal +structures appropriately for all of the filter types. (Note that this +means the first row must always be adaptively filtered, because libpng +currently does not allocate the filter buffers until png_write_row() +is called for the first time.) + + filters = PNG_FILTER_NONE | PNG_FILTER_SUB + PNG_FILTER_UP | PNG_FILTER_AVE | + PNG_FILTER_PAETH | PNG_ALL_FILTERS; + + png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE, + filters); + The second parameter can also be + PNG_INTRAPIXEL_DIFFERENCING if you are + writing a PNG to be embedded in a MNG + datastream. This parameter must be the + same as the value of filter_method used + in png_set_IHDR(). + +It is also possible to influence how libpng chooses from among the +available filters. This is done in one or both of two ways - by +telling it how important it is to keep the same filter for successive +rows, and by telling it the relative computational costs of the filters. + + double weights[3] = {1.5, 1.3, 1.1}, + costs[PNG_FILTER_VALUE_LAST] = + {1.0, 1.3, 1.3, 1.5, 1.7}; + + png_set_filter_heuristics(png_ptr, + PNG_FILTER_HEURISTIC_WEIGHTED, 3, + weights, costs); + +The weights are multiplying factors that indicate to libpng that the +row filter should be the same for successive rows unless another row filter +is that many times better than the previous filter. In the above example, +if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a +"sum of absolute differences" 1.5 x 1.3 times higher than other filters +and still be chosen, while the NONE filter could have a sum 1.1 times +higher than other filters and still be chosen. Unspecified weights are +taken to be 1.0, and the specified weights should probably be declining +like those above in order to emphasize recent filters over older filters. + +The filter costs specify for each filter type a relative decoding cost +to be considered when selecting row filters. This means that filters +with higher costs are less likely to be chosen over filters with lower +costs, unless their "sum of absolute differences" is that much smaller. +The costs do not necessarily reflect the exact computational speeds of +the various filters, since this would unduly influence the final image +size. + +Note that the numbers above were invented purely for this example and +are given only to help explain the function usage. Little testing has +been done to find optimum values for either the costs or the weights. + +.SS Removing unwanted object code + +There are a bunch of #define's in pngconf.h that control what parts of +libpng are compiled. All the defines end in _SUPPORTED. If you are +never going to use a capability, you can change the #define to #undef +before recompiling libpng and save yourself code and data space, or +you can turn off individual capabilities with defines that begin with +PNG_NO_. + +You can also turn all of the transforms and ancillary chunk capabilities +off en masse with compiler directives that define +PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, +or all four, +along with directives to turn on any of the capabilities that you do +want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable +the extra transformations but still leave the library fully capable of reading +and writing PNG files with all known public chunks +Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive +produces a library that is incapable of reading or writing ancillary chunks. +If you are not using the progressive reading capability, you can +turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse +this with the INTERLACING capability, which you'll still have). + +All the reading and writing specific code are in separate files, so the +linker should only grab the files it needs. However, if you want to +make sure, or if you are building a stand alone library, all the +reading files start with pngr and all the writing files start with +pngw. The files that don't match either (like png.c, pngtrans.c, etc.) +are used for both reading and writing, and always need to be included. +The progressive reader is in pngpread.c + +If you are creating or distributing a dynamically linked library (a .so +or DLL file), you should not remove or disable any parts of the library, +as this will cause applications linked with different versions of the +library to fail if they call functions not available in your library. +The size of the library itself should not be an issue, because only +those sections that are actually used will be loaded into memory. + +.SS Requesting debug printout + +The macro definition PNG_DEBUG can be used to request debugging +printout. Set it to an integer value in the range 0 to 3. Higher +numbers result in increasing amounts of debugging information. The +information is printed to the "stderr" file, unless another file +name is specified in the PNG_DEBUG_FILE macro definition. + +When PNG_DEBUG > 0, the following functions (macros) become available: + + png_debug(level, message) + png_debug1(level, message, p1) + png_debug2(level, message, p1, p2) + +in which "level" is compared to PNG_DEBUG to decide whether to print +the message, "message" is the formatted string to be printed, +and p1 and p2 are parameters that are to be embedded in the string +according to printf-style formatting directives. For example, + + png_debug1(2, "foo=%d\n", foo); + +is expanded to + + if(PNG_DEBUG > 2) + fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo); + +When PNG_DEBUG is defined but is zero, the macros aren't defined, but you +can still use PNG_DEBUG to control your own debugging: + + #ifdef PNG_DEBUG + fprintf(stderr, ... + #endif + +When PNG_DEBUG = 1, the macros are defined, but only png_debug statements +having level = 0 will be printed. There aren't any such statements in +this version of libpng, but if you insert some they will be printed. + +.SH VI. 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 VII. MNG support + +The MNG specification (available at http://www.libpng.org/pub/mng) allows +certain extensions to PNG for PNG images that are embedded in MNG datastreams. +Libpng can support some of these extensions. To enable them, use the +png_permit_mng_features() function: + + feature_set = png_permit_mng_features(png_ptr, mask) + mask is a png_uint_32 containing the logical OR of the + features you want to enable. These include + PNG_FLAG_MNG_EMPTY_PLTE + PNG_FLAG_MNG_FILTER_64 + PNG_ALL_MNG_FEATURES + feature_set is a png_uint_32 that is the logical AND of + your mask with the set of MNG features that is + supported by the version of libpng that you are using. + +It is an error to use this function when reading or writing a standalone +PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped +in a MNG datastream. As a minimum, it must have the MNG 8-byte signature +and the MHDR and MEND chunks. Libpng does not provide support for these +or any other MNG chunks; your application must provide its own support for +them. You may wish to consider using libmng (available at +http://www.libmng.com) instead. + +.SH VIII. Changes to Libpng from version 0.88 + +It should be noted that versions of libpng later than 0.96 are not +distributed by the original libpng author, Guy Schalnat, nor by +Andreas Dilger, who had taken over from Guy during 1996 and 1997, and +distributed versions 0.89 through 0.96, but rather by another member +of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are +still alive and well, but they have moved on to other things. + +The old libpng functions png_read_init(), png_write_init(), +png_info_init(), png_read_destroy(), and png_write_destroy() have been +moved to PNG_INTERNAL in version 0.95 to discourage their use. These +functions will be removed from libpng version 2.0.0. + +The preferred method of creating and initializing the libpng structures is +via the png_create_read_struct(), png_create_write_struct(), and +png_create_info_struct() because they isolate the size of the structures +from the application, allow version error checking, and also allow the +use of custom error handling routines during the initialization, which +the old functions do not. The functions png_read_destroy() and +png_write_destroy() do not actually free the memory that libpng +allocated for these structs, but just reset the data structures, so they +can be used instead of png_destroy_read_struct() and +png_destroy_write_struct() if you feel there is too much system overhead +allocating and freeing the png_struct for each image read. + +Setting the error callbacks via png_set_message_fn() before +png_read_init() as was suggested in libpng-0.88 is no longer supported +because this caused applications that do not use custom error functions +to fail if the png_ptr was not initialized to zero. It is still possible +to set the error callbacks AFTER png_read_init(), or to change them with +png_set_error_fn(), which is essentially the same function, but with a new +name to force compilation errors with applications that try to use the old +method. + +Starting with version 1.0.7, you can find out which version of the library +you are using at run-time: + + png_uint_32 libpng_vn = png_access_version_number(); + +The number libpng_vn is constructed from the major version, minor +version with leading zero, and release number with leading zero, +(e.g., libpng_vn for version 1.0.7 is 10007). + +You can also check which version of png.h you used when compiling your +application: + + png_uint_32 application_vn = PNG_LIBPNG_VER; + +.SH IX. Y2K Compliance in libpng + +December 3, 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.8 are Y2K compliant. It is my belief that earlier +versions were also Y2K compliant. + +Libpng only has three year fields. One is a 2-byte unsigned integer that +will hold years up to 65535. The other two hold the date in text +format, and will hold years up to 9999. + +The integer is + "png_uint_16 year" in png_time_struct. + +The strings are + "png_charp time_buffer" in png_struct and + "near_time_buffer", which is a local character string in png.c. + +There are seven time-related functions: + + png_convert_to_rfc_1123() in png.c + (formerly png_convert_to_rfc_1152() in error) + png_convert_from_struct_tm() in pngwrite.c, called + in pngwrite.c + png_convert_from_time_t() in pngwrite.c + png_get_tIME() in pngget.c + png_handle_tIME() in pngrutil.c, called in pngread.c + png_set_tIME() in pngset.c + png_write_tIME() in pngwutil.c, called in pngwrite.c + +All appear to handle dates properly in a Y2K environment. The +png_convert_from_time_t() function calls gmtime() to convert from system +clock time, which returns (year - 1900), which we properly convert to +the full 4-digit year. There is a possibility that applications using +libpng are not passing 4-digit years into the png_convert_to_rfc_1123() +function, or that they are incorrectly passing only a 2-digit year +instead of "year - 1900" into the png_convert_from_struct_tm() function, +but this is not under our control. The libpng documentation has always +stated that it works with 4-digit years, and the APIs have been +documented as such. + +The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned +integer to hold the year, and can hold years as large as 65535. + +zlib, upon which libpng depends, is also Y2K compliant. It contains +no date-related code. + + + Glenn Randers-Pehrson + libpng maintainer + PNG Development Group + +.SH NOTE + +Note about libpng version numbers: + +Due to various miscommunications, unforeseen code incompatibilities +and occasional factors outside the authors' control, version numbering +on the library has not always been consistent and straightforward. +The following table summarizes matters since version 0.89c, which was +the first widely used release: + + source png.h png.h shared-lib + version string int version + ------- ------ ----- ---------- + 0.89c ("beta 3") 0.89 89 1.0.89 + 0.90 ("beta 4") 0.90 90 0.90 + 0.95 ("beta 5") 0.95 95 0.95 + 0.96 ("beta 6") 0.96 96 0.96 + 0.97b ("beta 7") 1.00.97 97 1.0.1 + 0.97c 0.97 97 2.0.97 + 0.98 0.98 98 2.0.98 + 0.99 0.99 98 2.0.99 + 0.99a-m 0.99 99 2.0.99 + 1.00 1.00 100 2.1.0 + 1.0.0 1.0.0 100 2.1.0 + 1.0.0 (from here on, the 100 2.1.0 + 1.0.1 png.h string is 10001 2.1.0 + 1.0.1a-e identical to the 10002 from here on, the + 1.0.2 source version) 10002 shared library is 2.V + 1.0.2a-b 10003 where V is the source + 1.0.1 10001 code version except as + 1.0.1a-e 10002 2.1.0.1a-e noted. + 1.0.2 10002 2.1.0.2 + 1.0.2a-b 10003 2.1.0.2a-b + 1.0.3 10003 2.1.0.3 + 1.0.3a-d 10004 2.1.0.3a-d + 1.0.4 10004 2.1.0.4 + 1.0.4a-f 10005 2.1.0.4a-f + 1.0.5 (+ 2 patches) 10005 2.1.0.5 + 1.0.5a-d 10006 2.1.0.5a-d + 1.0.5e-r 10100 2.1.0.5e-r + 1.0.5s-v 10006 2.1.0.5s-v + 1.0.6 (+ 3 patches) 10006 2.1.0.6 + 1.0.6d-g 10007 2.1.0.6d-g + 1.0.6h 10007 10.6h + 1.0.6i 10007 10.6i + 1.0.6j 10007 2.1.0.6j + 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14 + 1.0.7beta15-18 1 10007 2.1.0.7beta15-18 + 1.0.7rc1-2 1 10007 2.1.0.7rc1-2 + 1.0.7 1 10007 2.1.0.7 + 1.0.8beta1-4 1 10008 2.1.0.8beta1-4 + 1.0.8rc1 1 10008 2.1.0.8rc1 + 1.0.8 1 10008 2.1.0.8 + 1.0.9beta1-6 1 10009 2.1.0.9beta1-6 + 1.0.9rc1 1 10009 2.1.0.9rc1 + 1.0.9beta7-10 1 10009 2.1.0.9beta7-10 + 1.0.9rc2 1 10009 2.1.0.9rc2 + 1.0.9 1 10009 2.1.0.9 + 1.0.10beta1 1 10010 2.1.0.10beta1 + 1.0.10rc1 1 10010 2.1.0.10rc1 + 1.0.10 1 10010 2.1.0.10 + 1.0.11beta1-3 1 10011 2.1.0.11beta1-3 + 1.0.11rc1 1 10011 2.1.0.11rc1 + 1.0.11 1 10011 2.1.0.11 + 1.0.12beta1-2 2 10012 2.1.0.12beta1-2 + 1.0.12rc1 2 10012 2.1.0.12rc1 + 1.0.12 2 10012 2.1.0.12 + 1.1.0a-f - 10100 2.1.1.0a-f abandoned + 1.2.0beta1-2 2 10200 2.1.2.0beta1-2 + 1.2.0beta3-5 3 10200 3.1.2.0beta3-5 + 1.2.0rc1 3 10200 3.1.2.0rc1 + 1.2.0 3 10200 3.1.2.0 + 1.2.1beta-4 3 10201 3.1.2.1beta1-4 + 1.2.1rc1-2 3 10201 3.1.2.1rc1-2 + 1.2.1 3 10201 3.1.2.1 + 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6 + 1.0.13beta1 10 10013 10.so.0.1.0.13beta1 + 1.0.13rc1 10 10013 10.so.0.1.0.13rc1 + 1.2.2rc1 12 10202 12.so.0.1.2.2rc1 + 1.0.13 10 10013 10.so.0.1.0.13 + 1.2.2 12 10202 12.so.0.1.2.2 + 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6 + 1.2.3 12 10203 12.so.0.1.2.3 + 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3 + 1.2.4rc1 13 10204 12.so.0.1.2.4rc1 + 1.0.14 10 10014 10.so.0.1.0.14 + 1.2.4 13 10204 12.so.0.1.2.4 + 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2 + 1.0.15rc1 10 10015 10.so.0.1.0.15rc1 + 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.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5 + 1.0.16 10 10016 10.so.0.1.0.16 + 1.2.6 13 10206 12.so.0.1.2.6 + 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2 + 1.0.17rc1 10 10017 12.so.0.1.0.17rc1 + 1.2.7rc1 13 10207 12.so.0.1.2.7rc1 + 1.0.17 10 10017 12.so.0.1.0.17 + 1.2.7 13 10207 12.so.0.1.2.7 + 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5 + 1.0.18rc1-5 10 10018 12.so.0.1.0.18rc1-5 + 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5 + 1.0.18 10 10018 12.so.0.1.0.18 + 1.2.8 13 10208 12.so.0.1.2.8 + +Henceforth the source version will match the shared-library minor +and patch numbers; the shared-library major version number will be +used for changes in backward compatibility, as it is intended. The +PNG_PNGLIB_VER macro, which is not used within libpng but is available +for applications, is an unsigned integer of the form xyyzz corresponding +to the source version x.y.z (leading zeros in y and z). Beta versions +were given the previous public release number plus a letter, until +version 1.0.6j; from then on they were given the upcoming public +release number plus "betaNN" or "rcN". + +.SH "SEE ALSO" +libpngpf(3), png(5) +.LP +.IR libpng : +.IP +http://libpng.sourceforge.net (follow the [DOWNLOAD] link) +http://www.libpng.org/pub/png + +.LP +.IR zlib : +.IP +(generally) at the same location as +.I libpng +or at +.br +ftp://ftp.info-zip.org/pub/infozip/zlib + +.LP +.IR PNG specification: RFC 2083 +.IP +(generally) at the same location as +.I libpng +or at +.br +ftp://ds.internic.net/rfc/rfc2083.txt +.br +or (as a W3C Recommendation) at +.br +http://www.w3.org/TR/REC-png.html + +.LP +In the case of any inconsistency between the PNG specification +and this library, the specification takes precedence. + +.SH AUTHORS +This man page: Glenn Randers-Pehrson + + +The contributing authors would like to thank all those who helped +with testing, bug fixes, and patience. This wouldn't have been +possible without all of you. + +Thanks to Frank J. T. Wojcik for helping with the documentation. + +Libpng version 1.2.8 - December 3, 2004: +Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. +Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). + +Supported by the PNG development group +.br +png-implement at ccrc.wustl.edu (subscription required; write to +majordomo at ccrc.wustl.edu with "subscribe png-implement" in the message). + +.SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE: + +(This copy of the libpng notices is provided for your convenience. In case of +any discrepancy between this copy and the notices in the file png.h that is +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, December 3, 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 individual added to the list of Contributing Authors + + Cosmin Truta + +libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002, are +Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are +distributed according to the same disclaimer and license as libpng-1.0.6 +with the following individuals added to the list of Contributing Authors + + Simon-Pierre Cadieux + Eric S. Raymond + Gilles Vollant + +and with the following additions to the disclaimer: + + There is no warranty against interference with your + enjoyment of the library or against infringement. + There is no warranty that our efforts or the library + will fulfill any of your particular purposes or needs. + This library is provided with all faults, and the entire + risk of satisfactory quality, performance, accuracy, and + effort is with the user. + +libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are +Copyright (c) 1998, 1999 Glenn Randers-Pehrson +Distributed according to the same disclaimer and license as libpng-0.96, +with the following individuals added to the list of Contributing Authors: + + Tom Lane + Glenn Randers-Pehrson + Willem van Schaik + +libpng versions 0.89, June 1996, through 0.96, May 1997, are +Copyright (c) 1996, 1997 Andreas Dilger +Distributed according to the same disclaimer and license as libpng-0.88, +with the following individuals added to the list of Contributing Authors: + + John Bowler + Kevin Bracey + Sam Bushell + Magnus Holmgren + Greg Roelofs + Tom Tanner + +libpng versions 0.5, May 1995, through 0.88, January 1996, are +Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc. + +For the purposes of this copyright and license, "Contributing Authors" +is defined as the following set of individuals: + + Andreas Dilger + Dave Martindale + Guy Eric Schalnat + Paul Schmidt + Tim Wegner + +The PNG Reference Library is supplied "AS IS". The Contributing Authors +and Group 42, Inc. disclaim all warranties, expressed or implied, +including, without limitation, the warranties of merchantability and of +fitness for any purpose. The Contributing Authors and Group 42, Inc. +assume no liability for direct, indirect, incidental, special, exemplary, +or consequential damages, which may result from the use of the PNG +Reference Library, even if advised of the possibility of such damage. + +Permission is hereby granted to use, copy, modify, and distribute this +source code, or portions hereof, for any purpose, without fee, subject +to the following restrictions: + +1. The origin of this source code must not be misrepresented. + +2. Altered versions must be plainly marked as such and + must not be misrepresented as being the original source. + +3. This Copyright notice may not be removed or altered from + any source or altered source distribution. + +The Contributing Authors and Group 42, Inc. specifically permit, without +fee, and encourage the use of this source code as a component to +supporting the PNG file format in commercial products. If you use this +source code in a product, acknowledgment is not required but would be +appreciated. + + +A "png_get_copyright" function is available, for convenient use in "about" +boxes and the like: + + printf("%s",png_get_copyright(NULL)); + +Also, the PNG logo (in PNG format, of course) is supplied in the +files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31). + +Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a +certification mark of the Open Source Initiative. + +Glenn Randers-Pehrson +glennrp at users.sourceforge.net +December 3, 2004 + +.\" end of man page + diff --git a/sys/src/cmd/gs/libpng/libpngpf.3 b/sys/src/cmd/gs/libpng/libpngpf.3 deleted file mode 100644 index d196d70c4..000000000 --- a/sys/src/cmd/gs/libpng/libpngpf.3 +++ /dev/null @@ -1,1096 +0,0 @@ -.TH LIBPNGPF 3 "December 3, 2004" -.SH NAME -libpng \- Portable Network Graphics (PNG) Reference Library 1.2.8 -(private functions) -.SH SYNOPSIS -\fB\fB#include \fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_build_gamma_table (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_build_grayscale_palette (int \fP\fI\fP\fIbit_depth\fP\fB\fP\fB, png_colorp \fI\fIpalette\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_calculate_crc (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIptr\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_check_chunk_name (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIchunk_name\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBpng_size_t png_check_keyword (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charpp \fI\fInew_key\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_combine_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fI\fImask\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_correct_palette (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, int \fI\fInum_palette\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBint png_crc_error (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBint png_crc_finish (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIskip\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_crc_read (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBpng_voidp png_create_struct (int \fI\fItype\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBpng_voidp png_create_struct_2 (int \fP\fI\fP\fItype\fP\fB\fP\fB, png_malloc_ptr \fP\fI\fP\fImalloc_fn\fP\fB\fP\fB, png_voidp \fI\fImem_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBpng_charp png_decompress_chunk (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fP\fI\fP\fIcomp_type\fP\fB\fP\fB, png_charp \fP\fI\fP\fIchunkdata\fP\fB\fP\fB, png_size_t \fP\fI\fP\fIchunklength\fP\fB\fP\fB, png_size_t \fP\fI\fP\fIprefix_length\fP\fB\fP\fB, png_size_t \fI\fI*data_length\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_destroy_struct (png_voidp \fI\fIstruct_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_destroy_struct_2 (png_voidp \fP\fI\fP\fIstruct_ptr\fP\fB\fP\fB, png_free_ptr \fP\fI\fP\fIfree_fn\fP\fB\fP\fB, png_voidp \fI\fImem_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_background (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fItrans_values\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIbackground\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIbackground_1\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_table\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_from_1\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_to_1\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_from_1\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_to_1\fP\fB\fP\fB, int \fI\fIgamma_shift\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_bgr (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_chop (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_dither (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIpalette_lookup\fP\fB\fP\fB, png_bytep \fI\fIdither_lookup\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_expand (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_16p \fI\fItrans_value\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_expand_palette (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, png_bytep \fP\fI\fP\fItrans\fP\fB\fP\fB, int \fI\fInum_trans\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_gamma (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_table\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_table\fP\fB\fP\fB, int \fI\fIgamma_shift\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_gray_to_rgb (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_invert (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_pack (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fI\fIbit_depth\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_packswap (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_read_filler (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIfiller\fP\fB\fP\fB, png_uint_32 \fI\fIflags\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_read_interlace (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fP\fI\fP\fIpass\fP\fB\fP\fB, png_uint_32 \fI\fItransformations\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_read_invert_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_read_swap_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_read_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBint png_do_rgb_to_gray (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_shift (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_8p \fI\fIbit_depth\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_strip_filler (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fI\fIflags\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_swap (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_unpack (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_unshift (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_8p \fI\fIsig_bits\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_write_interlace (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fI\fIpass\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_write_invert_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_write_swap_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_do_write_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid *png_far_to_near (png_structp png_ptr,png_voidp \fP\fI\fP\fIptr\fP\fB\fP\fB, int \fI\fIcheck\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_flush (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBpng_int_32 png_get_int_32 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBpng_uint_16 png_get_uint_16 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBpng_uint_32 png_get_uint_31 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBpng_uint_32 png_get_uint_32 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_bKGD (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_cHRM (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_gAMA (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_hIST (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_IEND (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_IHDR (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_iCCP (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_iTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_oFFs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_pCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_pHYs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_PLTE (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_sBIT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_sCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_sPLT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_sRGB (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_tIME (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_tRNS (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_unknown (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_handle_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_info_destroy (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_init_mmx_flags (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_init_read_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_process_IDAT_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIbuffer_length\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_process_some_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_check_crc (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_crc_finish (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_crc_skip (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_fill_buffer (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_handle_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_handle_unknown (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_handle_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_have_end (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_have_info (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_have_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_process_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_read_chunk (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_read_end (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_read_IDAT (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_read_sig (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_read_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_read_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_restore_buffer (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIbuffer_length\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_push_save_buffer (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_read_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_read_filter_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIprev_row\fP\fB\fP\fB, int \fI\fIfilter\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_read_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_read_push_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_read_start_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_read_transform_info (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_reset_crc (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_save_int_32 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_int_32 \fI\fIi\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_save_uint_16 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, unsigned int \fI\fIi\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_save_uint_32 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_uint_32 \fI\fIi\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBint png_set_text_2 (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_textp \fP\fI\fP\fItext_ptr\fP\fB\fP\fB, int \fI\fInum_text\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_cHRM (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, double \fP\fI\fP\fIwhite_x\fP\fB\fP\fB, double \fP\fI\fP\fIwhite_y\fP\fB\fP\fB, double \fP\fI\fP\fIred_x\fP\fB\fP\fB, double \fP\fI\fP\fIred_y\fP\fB\fP\fB, double \fP\fI\fP\fIgreen_x\fP\fB\fP\fB, double \fP\fI\fP\fIgreen_y\fP\fB\fP\fB, double \fP\fI\fP\fIblue_x\fP\fB\fP\fB, double \fI\fIblue_y\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_cHRM_fixed (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwhite_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwhite_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIred_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIred_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIgreen_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIgreen_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIblue_x\fP\fB\fP\fB, png_uint_32 \fI\fIblue_y\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_filtered_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIfiltered_row\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_find_filter (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_row_infop \fI\fIrow_info\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_gAMA (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, double \fI\fIfile_gamma\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_gAMA_fixed (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIint_file_gamma\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_hIST (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_16p \fP\fI\fP\fIhist\fP\fB\fP\fB, int \fI\fInum_hist\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_iCCP (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIname\fP\fB\fP\fB, int \fP\fI\fP\fIcompression_type\fP\fB\fP\fB, png_charp \fP\fI\fP\fIprofile\fP\fB\fP\fB, int \fI\fIproflen\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_IDAT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_IEND (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_IHDR (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwidth\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIheight\fP\fB\fP\fB, int \fP\fI\fP\fIbit_depth\fP\fB\fP\fB, int \fP\fI\fP\fIcolor_type\fP\fB\fP\fB, int \fP\fI\fP\fIcompression_type\fP\fB\fP\fB, int \fP\fI\fP\fIfilter_type\fP\fB\fP\fB, int \fI\fIinterlace_type\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_iTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fP\fI\fP\fIcompression\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fIlang\fP\fB\fP\fB, png_charp \fP\fI\fP\fItranslated_key\fP\fB\fP\fB, png_charp \fI\fItext\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_oFFs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIx_offset\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIy_offset\fP\fB\fP\fB, int \fI\fIunit_type\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_pCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIpurpose\fP\fB\fP\fB, png_int_32 \fP\fI\fP\fIX0\fP\fB\fP\fB, png_int_32 \fP\fI\fP\fIX1\fP\fB\fP\fB, int \fP\fI\fP\fItype\fP\fB\fP\fB, int \fP\fI\fP\fInparams\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunits\fP\fB\fP\fB, png_charpp \fI\fIparams\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_pHYs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIx_pixels_per_unit\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIy_pixels_per_unit\fP\fB\fP\fB, int \fI\fIunit_type\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_PLTE (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, png_uint_32 \fI\fInum_pal\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_sBIT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_color_8p \fP\fI\fP\fIsbit\fP\fB\fP\fB, int \fI\fIcolor_type\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_sCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunit\fP\fB\fP\fB, double \fP\fI\fP\fIwidth\fP\fB\fP\fB, double \fI\fIheight\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_sCAL_s (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunit\fP\fB\fP\fB, png_charp \fP\fI\fP\fIwidth\fP\fB\fP\fB, png_charp \fI\fIheight\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_sig (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_sRGB (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fI\fIintent\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_sPLT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_spalette_p \fI\fIpalette\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_start_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fItext\fP\fB\fP\fB, png_size_t \fI\fItext_len\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_tIME (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_timep \fI\fImod_time\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_tRNS (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fItrans\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIvalues\fP\fB\fP\fB, int \fP\fI\fP\fInumber\fP\fB\fP\fB, int \fI\fIcolor_type\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_write_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fItext\fP\fB\fP\fB, png_size_t \fP\fI\fP\fItext_len\fP\fB\fP\fB, int \fI\fIcompression\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoidpf png_zalloc (voidpf \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, uInt \fP\fI\fP\fIitems\fP\fB\fP\fB, uInt \fI\fIsize\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -\fB\fBvoid png_zfree (voidpf \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, voidpf \fI\fIptr\fP\fB\fP\fB);\fP\fP - -\fI\fB - -\fI\fB\fI\fB - -\fI\fB - -.SH DESCRIPTION -The functions listed above are used privately by libpng -and are not recommended for use by applications. They are -not "exported" to applications using shared libraries. They -are listed alphabetically here as an aid to libpng maintainers. -See png.h for more information on these functions. - -.SH SEE ALSO -libpng(3), png(5) -.SH AUTHOR -Glenn Randers-Pehrson diff --git a/sys/src/cmd/gs/libpng/libpngpf.3.man b/sys/src/cmd/gs/libpng/libpngpf.3.man new file mode 100644 index 000000000..d196d70c4 --- /dev/null +++ b/sys/src/cmd/gs/libpng/libpngpf.3.man @@ -0,0 +1,1096 @@ +.TH LIBPNGPF 3 "December 3, 2004" +.SH NAME +libpng \- Portable Network Graphics (PNG) Reference Library 1.2.8 +(private functions) +.SH SYNOPSIS +\fB\fB#include \fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_build_gamma_table (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_build_grayscale_palette (int \fP\fI\fP\fIbit_depth\fP\fB\fP\fB, png_colorp \fI\fIpalette\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_calculate_crc (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIptr\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_check_chunk_name (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIchunk_name\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBpng_size_t png_check_keyword (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charpp \fI\fInew_key\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_combine_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fI\fImask\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_correct_palette (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, int \fI\fInum_palette\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBint png_crc_error (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBint png_crc_finish (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIskip\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_crc_read (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBpng_voidp png_create_struct (int \fI\fItype\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBpng_voidp png_create_struct_2 (int \fP\fI\fP\fItype\fP\fB\fP\fB, png_malloc_ptr \fP\fI\fP\fImalloc_fn\fP\fB\fP\fB, png_voidp \fI\fImem_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBpng_charp png_decompress_chunk (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fP\fI\fP\fIcomp_type\fP\fB\fP\fB, png_charp \fP\fI\fP\fIchunkdata\fP\fB\fP\fB, png_size_t \fP\fI\fP\fIchunklength\fP\fB\fP\fB, png_size_t \fP\fI\fP\fIprefix_length\fP\fB\fP\fB, png_size_t \fI\fI*data_length\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_destroy_struct (png_voidp \fI\fIstruct_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_destroy_struct_2 (png_voidp \fP\fI\fP\fIstruct_ptr\fP\fB\fP\fB, png_free_ptr \fP\fI\fP\fIfree_fn\fP\fB\fP\fB, png_voidp \fI\fImem_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_background (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fItrans_values\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIbackground\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIbackground_1\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_table\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_from_1\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_to_1\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_from_1\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_to_1\fP\fB\fP\fB, int \fI\fIgamma_shift\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_bgr (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_chop (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_dither (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIpalette_lookup\fP\fB\fP\fB, png_bytep \fI\fIdither_lookup\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_expand (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_16p \fI\fItrans_value\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_expand_palette (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, png_bytep \fP\fI\fP\fItrans\fP\fB\fP\fB, int \fI\fInum_trans\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_gamma (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIgamma_table\fP\fB\fP\fB, png_uint_16pp \fP\fI\fP\fIgamma_16_table\fP\fB\fP\fB, int \fI\fIgamma_shift\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_gray_to_rgb (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_invert (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_pack (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fI\fIbit_depth\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_packswap (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_read_filler (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIfiller\fP\fB\fP\fB, png_uint_32 \fI\fIflags\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_read_interlace (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fP\fI\fP\fIpass\fP\fB\fP\fB, png_uint_32 \fI\fItransformations\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_read_invert_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_read_swap_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_read_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBint png_do_rgb_to_gray (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_shift (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_8p \fI\fIbit_depth\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_strip_filler (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_uint_32 \fI\fIflags\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_swap (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_unpack (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_unshift (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_color_8p \fI\fIsig_bits\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_write_interlace (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, int \fI\fIpass\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_write_invert_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_write_swap_alpha (png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_do_write_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid *png_far_to_near (png_structp png_ptr,png_voidp \fP\fI\fP\fIptr\fP\fB\fP\fB, int \fI\fIcheck\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_flush (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBpng_int_32 png_get_int_32 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBpng_uint_16 png_get_uint_16 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBpng_uint_32 png_get_uint_31 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBpng_uint_32 png_get_uint_32 (png_bytep \fI\fIbuf\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_bKGD (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_cHRM (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_gAMA (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_hIST (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_IEND (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_IHDR (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_iCCP (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_iTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_oFFs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_pCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_pHYs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_PLTE (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_sBIT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_sCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_sPLT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_sRGB (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_tIME (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_tRNS (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_unknown (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_handle_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_info_destroy (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_init_mmx_flags (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_init_read_transformations (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_process_IDAT_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIbuffer_length\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_process_some_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_check_crc (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_crc_finish (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_crc_skip (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_fill_buffer (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_handle_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_handle_unknown (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_handle_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_have_end (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_have_info (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_have_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIrow\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_process_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_read_chunk (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_read_end (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_read_IDAT (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_read_sig (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_read_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_read_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_restore_buffer (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIbuffer\fP\fB\fP\fB, png_size_t \fI\fIbuffer_length\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_push_save_buffer (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_read_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_read_filter_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_row_infop \fP\fI\fP\fIrow_info\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIrow\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIprev_row\fP\fB\fP\fB, int \fI\fIfilter\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_read_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_read_push_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_read_start_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_read_transform_info (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fI\fIinfo_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_reset_crc (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_save_int_32 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_int_32 \fI\fIi\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_save_uint_16 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, unsigned int \fI\fIi\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_save_uint_32 (png_bytep \fP\fI\fP\fIbuf\fP\fB\fP\fB, png_uint_32 \fI\fIi\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBint png_set_text_2 (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_infop \fP\fI\fP\fIinfo_ptr\fP\fB\fP\fB, png_textp \fP\fI\fP\fItext_ptr\fP\fB\fP\fB, int \fI\fInum_text\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_cHRM (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, double \fP\fI\fP\fIwhite_x\fP\fB\fP\fB, double \fP\fI\fP\fIwhite_y\fP\fB\fP\fB, double \fP\fI\fP\fIred_x\fP\fB\fP\fB, double \fP\fI\fP\fIred_y\fP\fB\fP\fB, double \fP\fI\fP\fIgreen_x\fP\fB\fP\fB, double \fP\fI\fP\fIgreen_y\fP\fB\fP\fB, double \fP\fI\fP\fIblue_x\fP\fB\fP\fB, double \fI\fIblue_y\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_cHRM_fixed (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwhite_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwhite_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIred_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIred_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIgreen_x\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIgreen_y\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIblue_x\fP\fB\fP\fB, png_uint_32 \fI\fIblue_y\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_data (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_filtered_row (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fI\fIfiltered_row\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_find_filter (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_row_infop \fI\fIrow_info\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_finish_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_gAMA (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, double \fI\fIfile_gamma\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_gAMA_fixed (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fI\fIint_file_gamma\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_hIST (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_16p \fP\fI\fP\fIhist\fP\fB\fP\fB, int \fI\fInum_hist\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_iCCP (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIname\fP\fB\fP\fB, int \fP\fI\fP\fIcompression_type\fP\fB\fP\fB, png_charp \fP\fI\fP\fIprofile\fP\fB\fP\fB, int \fI\fIproflen\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_IDAT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fIdata\fP\fB\fP\fB, png_size_t \fI\fIlength\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_IEND (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_IHDR (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIwidth\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIheight\fP\fB\fP\fB, int \fP\fI\fP\fIbit_depth\fP\fB\fP\fB, int \fP\fI\fP\fIcolor_type\fP\fB\fP\fB, int \fP\fI\fP\fIcompression_type\fP\fB\fP\fB, int \fP\fI\fP\fIfilter_type\fP\fB\fP\fB, int \fI\fIinterlace_type\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_iTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fP\fI\fP\fIcompression\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fIlang\fP\fB\fP\fB, png_charp \fP\fI\fP\fItranslated_key\fP\fB\fP\fB, png_charp \fI\fItext\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_oFFs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIx_offset\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIy_offset\fP\fB\fP\fB, int \fI\fIunit_type\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_pCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIpurpose\fP\fB\fP\fB, png_int_32 \fP\fI\fP\fIX0\fP\fB\fP\fB, png_int_32 \fP\fI\fP\fIX1\fP\fB\fP\fB, int \fP\fI\fP\fItype\fP\fB\fP\fB, int \fP\fI\fP\fInparams\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunits\fP\fB\fP\fB, png_charpp \fI\fIparams\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_pHYs (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIx_pixels_per_unit\fP\fB\fP\fB, png_uint_32 \fP\fI\fP\fIy_pixels_per_unit\fP\fB\fP\fB, int \fI\fIunit_type\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_PLTE (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_colorp \fP\fI\fP\fIpalette\fP\fB\fP\fB, png_uint_32 \fI\fInum_pal\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_sBIT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_color_8p \fP\fI\fP\fIsbit\fP\fB\fP\fB, int \fI\fIcolor_type\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_sCAL (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunit\fP\fB\fP\fB, double \fP\fI\fP\fIwidth\fP\fB\fP\fB, double \fI\fIheight\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_sCAL_s (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIunit\fP\fB\fP\fB, png_charp \fP\fI\fP\fIwidth\fP\fB\fP\fB, png_charp \fI\fIheight\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_sig (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_sRGB (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, int \fI\fIintent\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_sPLT (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_spalette_p \fI\fIpalette\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_start_row (png_structp \fI\fIpng_ptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_tEXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fItext\fP\fB\fP\fB, png_size_t \fI\fItext_len\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_tIME (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_timep \fI\fImod_time\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_tRNS (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_bytep \fP\fI\fP\fItrans\fP\fB\fP\fB, png_color_16p \fP\fI\fP\fIvalues\fP\fB\fP\fB, int \fP\fI\fP\fInumber\fP\fB\fP\fB, int \fI\fIcolor_type\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_write_zTXt (png_structp \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, png_charp \fP\fI\fP\fIkey\fP\fB\fP\fB, png_charp \fP\fI\fP\fItext\fP\fB\fP\fB, png_size_t \fP\fI\fP\fItext_len\fP\fB\fP\fB, int \fI\fIcompression\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoidpf png_zalloc (voidpf \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, uInt \fP\fI\fP\fIitems\fP\fB\fP\fB, uInt \fI\fIsize\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +\fB\fBvoid png_zfree (voidpf \fP\fI\fP\fIpng_ptr\fP\fB\fP\fB, voidpf \fI\fIptr\fP\fB\fP\fB);\fP\fP + +\fI\fB + +\fI\fB\fI\fB + +\fI\fB + +.SH DESCRIPTION +The functions listed above are used privately by libpng +and are not recommended for use by applications. They are +not "exported" to applications using shared libraries. They +are listed alphabetically here as an aid to libpng maintainers. +See png.h for more information on these functions. + +.SH SEE ALSO +libpng(3), png(5) +.SH AUTHOR +Glenn Randers-Pehrson diff --git a/sys/src/cmd/gs/libpng/png.5 b/sys/src/cmd/gs/libpng/png.5 deleted file mode 100644 index db7c83416..000000000 --- a/sys/src/cmd/gs/libpng/png.5 +++ /dev/null @@ -1,74 +0,0 @@ -.TH PNG 5 "December 3, 2004" -.SH NAME -png \- Portable Network Graphics (PNG) format -.SH DESCRIPTION -PNG (Portable Network Graphics) is an extensible file format for the -lossless, portable, well-compressed storage of raster images. PNG provides -a patent-free replacement for GIF and can also replace many -common uses of TIFF. Indexed-color, grayscale, and truecolor images are -supported, plus an optional alpha channel. Sample depths range from -1 to 16 bits. -.br - -PNG is designed to work well in online viewing applications, such as the -World Wide Web, so it is fully streamable with a progressive display -option. PNG is robust, providing both full file integrity checking and -fast, simple detection of common transmission errors. Also, PNG can store -gamma and chromaticity data for improved color matching on heterogeneous -platforms. - -.SH "SEE ALSO" -.IR libpng(3), zlib(3), deflate(5), and zlib(5) -.LP -PNG specification (second edition), November 2003: -.IP -.br - \-rx -.fi -.PP -For example, on a 9-pin Epson-compatible printer, you get the -lowest-density (fastest) mode with -.PP -.nf - gs \-sDEVICE=epson \-r60x72 -.fi -.PP -and the highest-density (best output quality) mode with -.PP -.nf - gs \-sDEVICE=epson \-r240x72. -.fi -.PP -If you select a printer as the output device, Ghostscript also allows you -to choose where Ghostscript sends the output \-\- on Unix systems, usually -to a temporary file. To send the output to a file "foo.xyz", -use the switch -.PP -.nf - \-sOutputFile=foo.xyz -.fi -.PP -You might want to print each page separately. To do this, send the output -to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile=" -switch with "%d" in a filename template: -.PP -.nf - \-sOutputFile=foo%d.xyz -.fi -.PP -Each resulting file receives one page of output, and the files are numbered -in sequence. "%d" is a printf format specification; you can also use a -variant like "%02d". -.PP -On Unix and MS Windows systems you can also send output to a pipe. For example, to -pipe output to the "\fBlpr\fR" command (which, on many Unix systems, -directs it to a printer), use the option -.PP -.nf - \-sOutputFile=%pipe%lpr -.fi -.PP -Note that the '%' characters need to be doubled on MS Windows to avoid -mangling by the command interpreter. -.PP -You can also send output to standard output: -.PP -.nf - \-sOutputFile=\- -.fi -or -.nf - \-sOutputFile=%stdout% -.fi -.PP -In this case you must also use the \fB\-q\fR switch, to prevent Ghostscript -from writing messages to standard output. -.PP -To select a specific paper size, use the command line switch -.PP -.nf - -sPAPERSIZE= -.fi -.PP -for instance -.PP -.nf - -sPAPERSIZE=a4 -.fi -or -.nf - -sPAPERSIZE=legal -.fi -.PP -Most ISO and US paper sizes are recognized. See the usage documenatation for -a full list, or the definitions in the initialization file "gs_statd.ps". -.PP -Ghostscript can do many things other than print or view PostScript and -PDF files. For example, if you want to know the bounding box of a -PostScript (or EPS) file, Ghostscript provides a special "device" that -just prints out this information. -.PP -For example, using one of the example files distributed with Ghostscript, -.PP -.nf - gs \-sDEVICE=bbox golfer.ps -.fi -.PP -prints out -.PP -.nf - %%BoundingBox: 0 25 583 732 - %%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445 -.fi -.SH OPTIONS -.TP -.BI \-\- " filename arg1 ..." -Takes the next argument as a file name as usual, but takes all remaining -arguments (even if they have the syntactic form of switches) and defines -the name "ARGUMENTS" in "userdict" (not "systemdict") as an -array of those strings, \fBbefore\fR running the file. When Ghostscript -finishes executing the file, it exits back to the shell. -.TP -.BI \-D name = token -.TQ -.BI \-d name = token -Define a name in "systemdict" with the given definition. The token must be -exactly one token (as defined by the "token" operator) and may contain no -whitespace. -.TP -.BI \-D name -.TQ -.BI \-d name -Define a name in "systemdict" with value=null. -.TP -.BI \-S name = string -.TQ -.BI \-s name = string -Define a name in "systemdict" with a given string as value. This is -different from \fB\-d\fR. For example, \fB\-dname=35\fR is equivalent to the -program fragment -.br - /name 35 def -.br -whereas \fB\-sname=35\fR is equivalent to -.br - /name (35) def -.TP -.B \-q -Quiet startup: suppress normal startup messages, and also do the -equivalent of \fB\-dQUIET\fR. -.TP -.BI \-g number1 x number2 -Equivalent to \fB\-dDEVICEWIDTH=\fR\fInumber1\fR and -\fB\-dDEVICEHEIGHT=\fR\fInumber2\fR. This is for the benefit of devices -(such as X11 windows) that require (or allow) width and height to be -specified. -.TP -.BI \-r number -.TQ -.BI \-r number1 x number2 -Equivalent to \fB\-dDEVICEXRESOLUTION=\fR\fInumber1\fR and -\fB\-dDEVICEYRESOLUTION=\fR\fInumber2\fR. This is for the benefit of -devices such as printers that support multiple X and Y resolutions. If -only one number is given, it is used for both X and Y resolutions. -.TP -.BI \-I directories -Adds the designated list of directories at the head of the -search path for library files. -.TP -.B \- -This is not really a switch, but indicates to Ghostscript that standard -input is coming from a file or a pipe and not interactively from the -command line. Ghostscript reads from standard input until it reaches -end-of-file, executing it like any other file, and then continues with -processing the command line. When the command line has been entirely -processed, Ghostscript exits rather than going into its interactive mode. -.PP -Note that the normal initialization file "gs_init.ps" makes "systemdict" -read-only, so the values of names defined with \fB\-D\fR, \fB\-d\fR, -\fB\-S\fR, or \fB\-s\fR cannot be changed (although, of course, they can be -superseded by definitions in "userdict" or other dictionaries.) -.SH "SPECIAL NAMES" -.TP -.B \-dDISKFONTS -Causes individual character outlines to be loaded from the disk -the first time they are encountered. (Normally Ghostscript loads all the -character outlines when it loads a font.) This may allow loading more -fonts into RAM, at the expense of slower rendering. -.TP -.B \-dNOCACHE -Disables character caching. Useful only for debugging. -.TP -.B \-dNOBIND -Disables the "bind" operator. Useful only for debugging. -.TP -.B \-dNODISPLAY -Suppresses the normal initialization of the output device. -This may be useful when debugging. -.TP -.B \-dNOPAUSE -Disables the prompt and pause at the end of each page. This may be -desirable for applications where another program is driving Ghostscript. -.TP -.B \-dNOPLATFONTS -Disables the use of fonts supplied by the underlying platform (for instance -X Windows). This may be needed if the platform fonts look undesirably -different from the scalable fonts. -.TP -.B \-dSAFER -Disables the "deletefile" and "renamefile" operators and the ability to -open files in any mode other than read-only. This strongly recommended for -spoolers, conversion scripts or other sensitive environments where a badly -written or malicious PostScript program code must be prevented from changing -important files. -.TP -.B \-dWRITESYSTEMDICT -Leaves "systemdict" writable. This is necessary when running special -utility programs such as \fBfont2c\fR and \fBpcharstr\fR, which must bypass -normal PostScript access protection. -.TP -.BI \-sDEVICE= device -Selects an alternate initial output device, as described above. -.TP -.BI \-sOutputFile= filename -Selects an alternate output file (or pipe) for the initial output -device, as described above. -.SH FILES -.PP -The locations of many Ghostscript run-time files are compiled into the -executable when it is built. On Unix these are typically based in -\fB/usr/local\fR, but this may be different on your system. Under DOS they -are typically based in \fBC:\\GS\fR, but may be elsewhere, especially if -you install Ghostscript with \fBGSview\fR. Run "\fBgs -h\fR" to find the -location of Ghostscript documentation on your system, from which you can -get more details. -.TP -.B /usr/local/share/ghostscript/#.##/* -Startup files, utilities, and basic font definitions -.TP -.B /usr/local/share/ghostscript/fonts/* -More font definitions -.TP -.B /usr/local/share/ghostscript/#.##/examples/* -Ghostscript demonstration files -.TP -.B /usr/local/share/ghostscript/#.##/doc/* -Diverse document files -.SH "INITIALIZATION FILES" -When looking for the initialization files "gs_*.ps", the files related to -fonts, or the file for the "run" operator, Ghostscript first tries to open -the file with the name as given, using the current working directory if no -directory is specified. If this fails, and the file name doesn't specify -an explicit directory or drive (for instance, doesn't contain "/" on Unix -systems or "\\" on MS Windows systems), Ghostscript tries directories in this -order: -.TP 4 -1. -the directories specified by the \fB\-I\fR switches in the command -line (see below), if any; -.TP -2. -the directories specified by the \fBGS_LIB\fR environment variable, -if any; -.TP -3. -the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the -Ghostscript makefile when the executable was built. When \fBgs\fR is built -on Unix, \fBGS_LIB_DEFAULT\fR is usually -"/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts" -where "#.##" represents the Ghostscript version number. -.PP -Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter) -may be either a single directory or a list of directories separated by -":". -.SH ENVIRONMENT -.TP -.B GS_OPTIONS -String of options to be processed before the command line options -.TP -.B GS_DEVICE -Used to specify an output device -.TP -.B GS_FONTPATH -Path names used to search for fonts -.TP -.B GS_LIB -Path names for initialization files and fonts -.TP -.B TEMP -Where temporary files are made -.SH X RESOURCES -Ghostscript, or more properly the X11 display device, looks for the -following resources under the program name "Ghostscript": -.TP -.B borderWidth -The border width in pixels (default = 1). -.TP -.B borderColor -The name of the border color (default = black). -.TP -.B geometry -The window size and placement, WxH+X+Y (default is NULL). -.TP -.B xResolution -The number of x pixels per inch (default is computed from \fBWidthOfScreen\fR -and \fBWidthMMOfScreen\fR). -.TP -.B yResolution -The number of y pixels per inch (default is computed from -\fBHeightOfScreen\fR and \fBHeightMMOfScreen\fR). -.TP -.B useBackingPixmap -Determines whether backing store is to be used for saving display window -(default = true). -.PP -See the usage document for a more complete list of resources. To set these -resources on Unix, put them in a file such as "~/.Xresources" in the -following form: -.PP -.nf - Ghostscript*geometry: 612x792\-0+0 - Ghostscript*xResolution: 72 - Ghostscript*yResolution: 72 -.fi -.PP -Then merge these resources into the X server's resource database: -.PP -.nf - % xrdb \-merge ~/.Xresources -.fi -.SH SEE ALSO -The various Ghostscript document files (above), especially \fBUse.htm\fR. -.SH BUGS -See the Usenet news group comp.lang.postscript. -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -Russell J. Lang, gsview at ghostgum.com.au, is the author of most of the -MS Windows code in Ghostscript. diff --git a/sys/src/cmd/gs/man/gs.1.man b/sys/src/cmd/gs/man/gs.1.man new file mode 100644 index 000000000..f95aa5515 --- /dev/null +++ b/sys/src/cmd/gs/man/gs.1.man @@ -0,0 +1,404 @@ +.\" $Id: gs.1,v 1.38 2005/10/20 19:46:55 ray Exp $ +.TH GS 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +gs \- Ghostscript (PostScript and PDF language interpreter and previewer) +.SH SYNOPSIS +\fBgs\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(Unix, VMS)\fR +.br +\fBgswin32c\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows)\fR +.br +\fBgswin32\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(MS Windows 3.1)\fR +.br +\fBgsos2\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... \fB(OS/2)\fR +.de TQ +.br +.ns +.TP \\$1 +.. +.SH DESCRIPTION +The \fBgs\fR (\fBgswin32c\fR, \fBgswin32\fR, \fBgsos2\fR) +command invokes \fBGhostscript\fR, an interpreter of Adobe Systems' +\fBPostScript\fR(tm) and \fBPortable Document Format\fR (PDF) languages. +\fBgs\fR reads "files" in sequence and executes them as Ghostscript +programs. After doing this, it reads further input from the standard input +stream (normally the keyboard), interpreting each line separately. The +interpreter exits gracefully when it encounters the "quit" command (either +in a file or from the keyboard), at end-of-file, or at an interrupt signal +(such as Control-C at the keyboard). +.PP +The interpreter recognizes many option switches, some of which are described +below. Please see the usage documenation for complete information. Switches +may appear anywhere in the command line and apply to all files thereafter. +Invoking Ghostscript with the \fB\-h\fR or \fB\-?\fR switch produces a +message which shows several useful switches, all the devices known to +that executable, and the search path for fonts; on Unix it also shows the +location of detailed documentation. +.PP +Ghostscript may be built to use many different output devices. To see +which devices your executable includes, run "\fBgs -h\fR". Unless you +specify a particular device, Ghostscript normally opens the first one of +those and directs output to it, so if the first one in the list is the one +you want to use, just issue the command +.PP +.nf + gs myfile.ps +.fi +.PP +You can also check the set of available devices from within Ghostscript: +invoke Ghostscript and type +.PP +.nf + devicenames == +.fi +.PP +but the first device on the resulting list may not be the default device +you determine with "\fBgs -h\fR". To specify "AbcXyz" as the +initial output device, include the switch +.PP +.nf + \-sDEVICE=AbcXyz +.fi +.PP +For example, for output to an Epson printer you might use the command +.PP +.nf + gs \-sDEVICE=epson myfile.ps +.fi +.PP +The "\-sDEVICE=" switch must precede the first mention of a file to print, +and only the switch's first use has any effect. +.PP +Finally, you can specify a default device in the environment variable +\fBGS_DEVICE\fR. The order of precedence for these alternatives from +highest to lowest (Ghostscript uses the device defined highest in the list) +is: +.PP +Some devices can support different resolutions (densities). To specify +the resolution on such a printer, use the "\-r" switch: +.PP +.nf + gs \-sDEVICE= \-rx +.fi +.PP +For example, on a 9-pin Epson-compatible printer, you get the +lowest-density (fastest) mode with +.PP +.nf + gs \-sDEVICE=epson \-r60x72 +.fi +.PP +and the highest-density (best output quality) mode with +.PP +.nf + gs \-sDEVICE=epson \-r240x72. +.fi +.PP +If you select a printer as the output device, Ghostscript also allows you +to choose where Ghostscript sends the output \-\- on Unix systems, usually +to a temporary file. To send the output to a file "foo.xyz", +use the switch +.PP +.nf + \-sOutputFile=foo.xyz +.fi +.PP +You might want to print each page separately. To do this, send the output +to a series of files "foo1.xyz, foo2.xyz, ..." using the "\-sOutputFile=" +switch with "%d" in a filename template: +.PP +.nf + \-sOutputFile=foo%d.xyz +.fi +.PP +Each resulting file receives one page of output, and the files are numbered +in sequence. "%d" is a printf format specification; you can also use a +variant like "%02d". +.PP +On Unix and MS Windows systems you can also send output to a pipe. For example, to +pipe output to the "\fBlpr\fR" command (which, on many Unix systems, +directs it to a printer), use the option +.PP +.nf + \-sOutputFile=%pipe%lpr +.fi +.PP +Note that the '%' characters need to be doubled on MS Windows to avoid +mangling by the command interpreter. +.PP +You can also send output to standard output: +.PP +.nf + \-sOutputFile=\- +.fi +or +.nf + \-sOutputFile=%stdout% +.fi +.PP +In this case you must also use the \fB\-q\fR switch, to prevent Ghostscript +from writing messages to standard output. +.PP +To select a specific paper size, use the command line switch +.PP +.nf + -sPAPERSIZE= +.fi +.PP +for instance +.PP +.nf + -sPAPERSIZE=a4 +.fi +or +.nf + -sPAPERSIZE=legal +.fi +.PP +Most ISO and US paper sizes are recognized. See the usage documenatation for +a full list, or the definitions in the initialization file "gs_statd.ps". +.PP +Ghostscript can do many things other than print or view PostScript and +PDF files. For example, if you want to know the bounding box of a +PostScript (or EPS) file, Ghostscript provides a special "device" that +just prints out this information. +.PP +For example, using one of the example files distributed with Ghostscript, +.PP +.nf + gs \-sDEVICE=bbox golfer.ps +.fi +.PP +prints out +.PP +.nf + %%BoundingBox: 0 25 583 732 + %%HiResBoundingBox: 0.808497 25.009496 582.994503 731.809445 +.fi +.SH OPTIONS +.TP +.BI \-\- " filename arg1 ..." +Takes the next argument as a file name as usual, but takes all remaining +arguments (even if they have the syntactic form of switches) and defines +the name "ARGUMENTS" in "userdict" (not "systemdict") as an +array of those strings, \fBbefore\fR running the file. When Ghostscript +finishes executing the file, it exits back to the shell. +.TP +.BI \-D name = token +.TQ +.BI \-d name = token +Define a name in "systemdict" with the given definition. The token must be +exactly one token (as defined by the "token" operator) and may contain no +whitespace. +.TP +.BI \-D name +.TQ +.BI \-d name +Define a name in "systemdict" with value=null. +.TP +.BI \-S name = string +.TQ +.BI \-s name = string +Define a name in "systemdict" with a given string as value. This is +different from \fB\-d\fR. For example, \fB\-dname=35\fR is equivalent to the +program fragment +.br + /name 35 def +.br +whereas \fB\-sname=35\fR is equivalent to +.br + /name (35) def +.TP +.B \-q +Quiet startup: suppress normal startup messages, and also do the +equivalent of \fB\-dQUIET\fR. +.TP +.BI \-g number1 x number2 +Equivalent to \fB\-dDEVICEWIDTH=\fR\fInumber1\fR and +\fB\-dDEVICEHEIGHT=\fR\fInumber2\fR. This is for the benefit of devices +(such as X11 windows) that require (or allow) width and height to be +specified. +.TP +.BI \-r number +.TQ +.BI \-r number1 x number2 +Equivalent to \fB\-dDEVICEXRESOLUTION=\fR\fInumber1\fR and +\fB\-dDEVICEYRESOLUTION=\fR\fInumber2\fR. This is for the benefit of +devices such as printers that support multiple X and Y resolutions. If +only one number is given, it is used for both X and Y resolutions. +.TP +.BI \-I directories +Adds the designated list of directories at the head of the +search path for library files. +.TP +.B \- +This is not really a switch, but indicates to Ghostscript that standard +input is coming from a file or a pipe and not interactively from the +command line. Ghostscript reads from standard input until it reaches +end-of-file, executing it like any other file, and then continues with +processing the command line. When the command line has been entirely +processed, Ghostscript exits rather than going into its interactive mode. +.PP +Note that the normal initialization file "gs_init.ps" makes "systemdict" +read-only, so the values of names defined with \fB\-D\fR, \fB\-d\fR, +\fB\-S\fR, or \fB\-s\fR cannot be changed (although, of course, they can be +superseded by definitions in "userdict" or other dictionaries.) +.SH "SPECIAL NAMES" +.TP +.B \-dDISKFONTS +Causes individual character outlines to be loaded from the disk +the first time they are encountered. (Normally Ghostscript loads all the +character outlines when it loads a font.) This may allow loading more +fonts into RAM, at the expense of slower rendering. +.TP +.B \-dNOCACHE +Disables character caching. Useful only for debugging. +.TP +.B \-dNOBIND +Disables the "bind" operator. Useful only for debugging. +.TP +.B \-dNODISPLAY +Suppresses the normal initialization of the output device. +This may be useful when debugging. +.TP +.B \-dNOPAUSE +Disables the prompt and pause at the end of each page. This may be +desirable for applications where another program is driving Ghostscript. +.TP +.B \-dNOPLATFONTS +Disables the use of fonts supplied by the underlying platform (for instance +X Windows). This may be needed if the platform fonts look undesirably +different from the scalable fonts. +.TP +.B \-dSAFER +Disables the "deletefile" and "renamefile" operators and the ability to +open files in any mode other than read-only. This strongly recommended for +spoolers, conversion scripts or other sensitive environments where a badly +written or malicious PostScript program code must be prevented from changing +important files. +.TP +.B \-dWRITESYSTEMDICT +Leaves "systemdict" writable. This is necessary when running special +utility programs such as \fBfont2c\fR and \fBpcharstr\fR, which must bypass +normal PostScript access protection. +.TP +.BI \-sDEVICE= device +Selects an alternate initial output device, as described above. +.TP +.BI \-sOutputFile= filename +Selects an alternate output file (or pipe) for the initial output +device, as described above. +.SH FILES +.PP +The locations of many Ghostscript run-time files are compiled into the +executable when it is built. On Unix these are typically based in +\fB/usr/local\fR, but this may be different on your system. Under DOS they +are typically based in \fBC:\\GS\fR, but may be elsewhere, especially if +you install Ghostscript with \fBGSview\fR. Run "\fBgs -h\fR" to find the +location of Ghostscript documentation on your system, from which you can +get more details. +.TP +.B /usr/local/share/ghostscript/#.##/* +Startup files, utilities, and basic font definitions +.TP +.B /usr/local/share/ghostscript/fonts/* +More font definitions +.TP +.B /usr/local/share/ghostscript/#.##/examples/* +Ghostscript demonstration files +.TP +.B /usr/local/share/ghostscript/#.##/doc/* +Diverse document files +.SH "INITIALIZATION FILES" +When looking for the initialization files "gs_*.ps", the files related to +fonts, or the file for the "run" operator, Ghostscript first tries to open +the file with the name as given, using the current working directory if no +directory is specified. If this fails, and the file name doesn't specify +an explicit directory or drive (for instance, doesn't contain "/" on Unix +systems or "\\" on MS Windows systems), Ghostscript tries directories in this +order: +.TP 4 +1. +the directories specified by the \fB\-I\fR switches in the command +line (see below), if any; +.TP +2. +the directories specified by the \fBGS_LIB\fR environment variable, +if any; +.TP +3. +the directories specified by the \fBGS_LIB_DEFAULT\fR macro in the +Ghostscript makefile when the executable was built. When \fBgs\fR is built +on Unix, \fBGS_LIB_DEFAULT\fR is usually +"/usr/local/share/ghostscript/#.##:/usr/local/share/ghostscript/fonts" +where "#.##" represents the Ghostscript version number. +.PP +Each of these (\fBGS_LIB_DEFAULT\fR, \fBGS_LIB\fR, and \fB\-I\fR parameter) +may be either a single directory or a list of directories separated by +":". +.SH ENVIRONMENT +.TP +.B GS_OPTIONS +String of options to be processed before the command line options +.TP +.B GS_DEVICE +Used to specify an output device +.TP +.B GS_FONTPATH +Path names used to search for fonts +.TP +.B GS_LIB +Path names for initialization files and fonts +.TP +.B TEMP +Where temporary files are made +.SH X RESOURCES +Ghostscript, or more properly the X11 display device, looks for the +following resources under the program name "Ghostscript": +.TP +.B borderWidth +The border width in pixels (default = 1). +.TP +.B borderColor +The name of the border color (default = black). +.TP +.B geometry +The window size and placement, WxH+X+Y (default is NULL). +.TP +.B xResolution +The number of x pixels per inch (default is computed from \fBWidthOfScreen\fR +and \fBWidthMMOfScreen\fR). +.TP +.B yResolution +The number of y pixels per inch (default is computed from +\fBHeightOfScreen\fR and \fBHeightMMOfScreen\fR). +.TP +.B useBackingPixmap +Determines whether backing store is to be used for saving display window +(default = true). +.PP +See the usage document for a more complete list of resources. To set these +resources on Unix, put them in a file such as "~/.Xresources" in the +following form: +.PP +.nf + Ghostscript*geometry: 612x792\-0+0 + Ghostscript*xResolution: 72 + Ghostscript*yResolution: 72 +.fi +.PP +Then merge these resources into the X server's resource database: +.PP +.nf + % xrdb \-merge ~/.Xresources +.fi +.SH SEE ALSO +The various Ghostscript document files (above), especially \fBUse.htm\fR. +.SH BUGS +See the Usenet news group comp.lang.postscript. +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +Russell J. Lang, gsview at ghostgum.com.au, is the author of most of the +MS Windows code in Ghostscript. diff --git a/sys/src/cmd/gs/man/gslp.1 b/sys/src/cmd/gs/man/gslp.1 deleted file mode 100644 index faf4fce3f..000000000 --- a/sys/src/cmd/gs/man/gslp.1 +++ /dev/null @@ -1,100 +0,0 @@ -.\" $Id: gslp.1,v 1.37 2005/10/20 19:46:55 ray Exp $ -.TH GSLP 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- -.SH NAME -gslp \- Format and print text using ghostscript -.br -gsbj \- Format and print text for BubbleJet printer using ghostscript -.br -gsdj \- Format and print text for DeskJet printer using ghostscript -.br -gsdj500 \- Format and print text for DeskJet 500 BubbleJet using ghostscript -.br -gslj \- Format and print text for LaserJet printer using ghostscript -.SH SYNOPSIS -.na -\fBgslp\fB -\-12BclqRr \-b
\-f \-F \-L \-p -\-T -\-\-add\-to\-space\ -\-\-add\-to\-width\ -\-\-columns\ -\-\-detect -\-\-first\-page\ -\-\-kern\ -\-\-last\-page\ -\-\-(heading|footing)\-(left|center|right)\ -\-\-margin\-(top|bottom|left|right)\ -\-\-no\-eject\-(file|formfeed) -\-\-spacing\ -[gs\ options] [files] -.ad -.br -\fBgsbj\fR [options] [files] -.br -\fBgsdj\fR [options] [files] -.br -\fBgsdj500\fR [options] [files] -.br -\fBgslj\fR [options] [files] -.SH DESCRIPTION -This utility provides functionality approximately equivalent to the Unix -.BR enscript (1) -program. It prints plain text files using a single font. -It currently handles tabs and formfeeds, but not backspaces. -It will line-wrap when using fixed-pitch fonts. -It will also do kerning and width adjustment. -.PP -The default device (\-sDEVICE=) and resolution (\-r) are as follows: -.nf -.na - gslp epson 180 - gsbj bj10e 180 - gsdj deskjet 300 - gsdj500 djet500 300 - gslj laserjet 300 -.ad -.fi -By default the current date is formatted as the center header. -.SH OPTIONS -.IP "Standard switches implemented:" --12BclqRr -b
-f -F -L -p -.IP "Sun switches implemented:" --T set tab width -.IP "Switches ignored:" --GghKkmow -# -C -d -J -n -P -S -s -t -v -.IP "Switches added:" -.RS -.IP "--add-to-space " -add the given number of 1/72" units to the width of each -space (may be negative) -.IP "--add-to-width " -add the given number of 1/72" units to the width of each -character (may be negative) -.IP "--columns " -print in columns -.IP "--detect" -treat the file as PostScript if it starts with %! -.IP "--first-page " -start printing at page -.IP "--kern " -kern using information from the given .AFM file -.IP "--last-page " -stop printing after page -.IP "--(heading|footing)-(left|center|right) " -set the heading/footing fields; use -B first to clear -.IP "--margin-(top|bottom|left|right) " -set a margin -.IP "--no-eject-(file|formfeed)" -end-of-file/FF only starts a new column, not a new sheet -.IP "--spacing " -use double (n=2), triple (n=3), etc. spacing -.RE -Also, the string %# in a heading or footing is replaced with the page #. -.SH SEE ALSO -gs(1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/gslp.1.man b/sys/src/cmd/gs/man/gslp.1.man new file mode 100644 index 000000000..faf4fce3f --- /dev/null +++ b/sys/src/cmd/gs/man/gslp.1.man @@ -0,0 +1,100 @@ +.\" $Id: gslp.1,v 1.37 2005/10/20 19:46:55 ray Exp $ +.TH GSLP 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +gslp \- Format and print text using ghostscript +.br +gsbj \- Format and print text for BubbleJet printer using ghostscript +.br +gsdj \- Format and print text for DeskJet printer using ghostscript +.br +gsdj500 \- Format and print text for DeskJet 500 BubbleJet using ghostscript +.br +gslj \- Format and print text for LaserJet printer using ghostscript +.SH SYNOPSIS +.na +\fBgslp\fB +\-12BclqRr \-b
\-f \-F \-L \-p +\-T +\-\-add\-to\-space\ +\-\-add\-to\-width\ +\-\-columns\ +\-\-detect +\-\-first\-page\ +\-\-kern\ +\-\-last\-page\ +\-\-(heading|footing)\-(left|center|right)\ +\-\-margin\-(top|bottom|left|right)\ +\-\-no\-eject\-(file|formfeed) +\-\-spacing\ +[gs\ options] [files] +.ad +.br +\fBgsbj\fR [options] [files] +.br +\fBgsdj\fR [options] [files] +.br +\fBgsdj500\fR [options] [files] +.br +\fBgslj\fR [options] [files] +.SH DESCRIPTION +This utility provides functionality approximately equivalent to the Unix +.BR enscript (1) +program. It prints plain text files using a single font. +It currently handles tabs and formfeeds, but not backspaces. +It will line-wrap when using fixed-pitch fonts. +It will also do kerning and width adjustment. +.PP +The default device (\-sDEVICE=) and resolution (\-r) are as follows: +.nf +.na + gslp epson 180 + gsbj bj10e 180 + gsdj deskjet 300 + gsdj500 djet500 300 + gslj laserjet 300 +.ad +.fi +By default the current date is formatted as the center header. +.SH OPTIONS +.IP "Standard switches implemented:" +-12BclqRr -b
-f -F -L -p +.IP "Sun switches implemented:" +-T set tab width +.IP "Switches ignored:" +-GghKkmow -# -C -d -J -n -P -S -s -t -v +.IP "Switches added:" +.RS +.IP "--add-to-space " +add the given number of 1/72" units to the width of each +space (may be negative) +.IP "--add-to-width " +add the given number of 1/72" units to the width of each +character (may be negative) +.IP "--columns " +print in columns +.IP "--detect" +treat the file as PostScript if it starts with %! +.IP "--first-page " +start printing at page +.IP "--kern " +kern using information from the given .AFM file +.IP "--last-page " +stop printing after page +.IP "--(heading|footing)-(left|center|right) " +set the heading/footing fields; use -B first to clear +.IP "--margin-(top|bottom|left|right) " +set a margin +.IP "--no-eject-(file|formfeed)" +end-of-file/FF only starts a new column, not a new sheet +.IP "--spacing " +use double (n=2), triple (n=3), etc. spacing +.RE +Also, the string %# in a heading or footing is replaced with the page #. +.SH SEE ALSO +gs(1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/gsnd.1 b/sys/src/cmd/gs/man/gsnd.1 deleted file mode 100644 index c37105cf3..000000000 --- a/sys/src/cmd/gs/man/gsnd.1 +++ /dev/null @@ -1,20 +0,0 @@ -.\" $Id: gsnd.1,v 1.37 2005/10/20 19:46:55 ray Exp $ -.TH GSND 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- -.SH NAME -gsnd \- Run ghostscript (PostScript and PDF engine) without display -.SH SYNOPSIS -\fBgsnd\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... -.SH DESCRIPTION -This script simply invokes -.BR gs (1) -with the -.B -NODISPLAY -flag, followed by any other arguments from the command-line. -.SH SEE ALSO -gs(1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/gsnd.1.man b/sys/src/cmd/gs/man/gsnd.1.man new file mode 100644 index 000000000..c37105cf3 --- /dev/null +++ b/sys/src/cmd/gs/man/gsnd.1.man @@ -0,0 +1,20 @@ +.\" $Id: gsnd.1,v 1.37 2005/10/20 19:46:55 ray Exp $ +.TH GSND 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +gsnd \- Run ghostscript (PostScript and PDF engine) without display +.SH SYNOPSIS +\fBgsnd\fR [ \fIoptions\fR ] [ \fIfiles\fR ] ... +.SH DESCRIPTION +This script simply invokes +.BR gs (1) +with the +.B -NODISPLAY +flag, followed by any other arguments from the command-line. +.SH SEE ALSO +gs(1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/pdf2dsc.1 b/sys/src/cmd/gs/man/pdf2dsc.1 deleted file mode 100644 index e02659206..000000000 --- a/sys/src/cmd/gs/man/pdf2dsc.1 +++ /dev/null @@ -1,34 +0,0 @@ -.\" $Id: pdf2dsc.1,v 1.36 2005/10/20 19:46:55 ray Exp $ -.TH PDF2DSC 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- -.SH NAME -pdf2dsc \- generate a PostScript page list of a PDF document -.SH SYNOPSIS -\fBpdf2dsc\fR \fIinput.pdf\fR [ \fIoutput.dsc\fR ] -.SH DESCRIPTION -\fBpdf2dsc\fR uses \fBgs\fR(1) to read an Adobe \fBPortable Document -Format\fR (PDF) document "input.pdf" and create a \fBPostScript\fR(tm) -document "output.dsc" that conforms to Adobe's \fBDocument Structuring -Conventions\fR (DSC) requirements. -.PP -This new document simply tells Ghostscript to read the PDF file and to -display pages one at a time. The generated document can then be viewed -with any PostScript viewer based on Ghostscript, like \fBghostview\fR(1) on -Unix or \fBGSview\fR on Windows, with which the user can browse through the -pages of the PDF document in any order. -.PP -If no output file is named on the command line, the name of the output file -is that of the input file with any extension removed, followed by the -extension "\.dsc". -.SH CAVEATS -The DSC document uses Ghostscript-specific procedures. In addition, the -original PDF document must be accessible when the DSC document is -processed. -.PP -You need the file "pdf2dsc.ps" (originally by Russell Lang) supplied with -Ghostscript since release 3.53. -.SH SEE ALSO -gs(1), ghostview(1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -Yves Arrouye and Russell Lang gsview at ghostgum.com.au diff --git a/sys/src/cmd/gs/man/pdf2dsc.1.man b/sys/src/cmd/gs/man/pdf2dsc.1.man new file mode 100644 index 000000000..e02659206 --- /dev/null +++ b/sys/src/cmd/gs/man/pdf2dsc.1.man @@ -0,0 +1,34 @@ +.\" $Id: pdf2dsc.1,v 1.36 2005/10/20 19:46:55 ray Exp $ +.TH PDF2DSC 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- +.SH NAME +pdf2dsc \- generate a PostScript page list of a PDF document +.SH SYNOPSIS +\fBpdf2dsc\fR \fIinput.pdf\fR [ \fIoutput.dsc\fR ] +.SH DESCRIPTION +\fBpdf2dsc\fR uses \fBgs\fR(1) to read an Adobe \fBPortable Document +Format\fR (PDF) document "input.pdf" and create a \fBPostScript\fR(tm) +document "output.dsc" that conforms to Adobe's \fBDocument Structuring +Conventions\fR (DSC) requirements. +.PP +This new document simply tells Ghostscript to read the PDF file and to +display pages one at a time. The generated document can then be viewed +with any PostScript viewer based on Ghostscript, like \fBghostview\fR(1) on +Unix or \fBGSview\fR on Windows, with which the user can browse through the +pages of the PDF document in any order. +.PP +If no output file is named on the command line, the name of the output file +is that of the input file with any extension removed, followed by the +extension "\.dsc". +.SH CAVEATS +The DSC document uses Ghostscript-specific procedures. In addition, the +original PDF document must be accessible when the DSC document is +processed. +.PP +You need the file "pdf2dsc.ps" (originally by Russell Lang) supplied with +Ghostscript since release 3.53. +.SH SEE ALSO +gs(1), ghostview(1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +Yves Arrouye and Russell Lang gsview at ghostgum.com.au diff --git a/sys/src/cmd/gs/man/pdf2ps.1 b/sys/src/cmd/gs/man/pdf2ps.1 deleted file mode 100644 index 345968e8f..000000000 --- a/sys/src/cmd/gs/man/pdf2ps.1 +++ /dev/null @@ -1,21 +0,0 @@ -.\" $Id: pdf2ps.1,v 1.38 2005/10/20 19:46:55 ray Exp $ -.TH PDF2PS 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- -.SH NAME -pdf2ps \- Ghostscript PDF to PostScript translator -.SH SYNOPSIS -\fBpdf2ps\fR [ \fIoptions\fR ] \fIinput.pdf [output.ps]\fR -.SH DESCRIPTION -\fBpdf2ps\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document -Format\fR (PDF) file "input.pdf" to \fBPostScript\fR(tm) in "output.ps". -Normally the output is allowed to use PostScript Level 2 (but not PostScript -LanguageLevel 3) constructs; the \fB-dLanguageLevel=1\fR option restricts -the output to Level 1, while \fB-dLanguageLevel=3\fR allows using -LanguageLevel 3 in the output. -.SH FILES -Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your -system, from which you can get more details. -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. diff --git a/sys/src/cmd/gs/man/pdf2ps.1.man b/sys/src/cmd/gs/man/pdf2ps.1.man new file mode 100644 index 000000000..345968e8f --- /dev/null +++ b/sys/src/cmd/gs/man/pdf2ps.1.man @@ -0,0 +1,21 @@ +.\" $Id: pdf2ps.1,v 1.38 2005/10/20 19:46:55 ray Exp $ +.TH PDF2PS 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- +.SH NAME +pdf2ps \- Ghostscript PDF to PostScript translator +.SH SYNOPSIS +\fBpdf2ps\fR [ \fIoptions\fR ] \fIinput.pdf [output.ps]\fR +.SH DESCRIPTION +\fBpdf2ps\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document +Format\fR (PDF) file "input.pdf" to \fBPostScript\fR(tm) in "output.ps". +Normally the output is allowed to use PostScript Level 2 (but not PostScript +LanguageLevel 3) constructs; the \fB-dLanguageLevel=1\fR option restricts +the output to Level 1, while \fB-dLanguageLevel=3\fR allows using +LanguageLevel 3 in the output. +.SH FILES +Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your +system, from which you can get more details. +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. diff --git a/sys/src/cmd/gs/man/pdfopt.1 b/sys/src/cmd/gs/man/pdfopt.1 deleted file mode 100644 index f969b81d5..000000000 --- a/sys/src/cmd/gs/man/pdfopt.1 +++ /dev/null @@ -1,27 +0,0 @@ -.\" $Id: pdfopt.1,v 1.36 2005/10/20 19:46:55 ray Exp $ -.TH PDFOPT 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- -.SH NAME -pdfopt \- Ghostscript PDF Optimizer -.SH SYNOPSIS -\fBpdfopt\fR [ \fIoptions\fR ] \fIinput.pdf output.pdf\fR -.SH DESCRIPTION -\fBpdfopt\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document -Format\fR (PDF) file "input.pdf" to a so-called optimized form in -"output.pdf". Optimization puts the elements of the file into a more linear -order and adds "hint" pointers, allowing Adobe's Acrobat(TM) products to -display individual pages of the file more quickly when accessing the file -through a network. -.PP -Note: input.pdf and output.pdf must not be the same. If they are, the file -will probably be destroyed. \fBpdfopt\fR currently does not check for this. -.SH FILES -Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your -system, from which you can get more details. -.SH SEE ALSO -"Linearized PDF" in Adobe's PDF reference manual, -http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. diff --git a/sys/src/cmd/gs/man/pdfopt.1.man b/sys/src/cmd/gs/man/pdfopt.1.man new file mode 100644 index 000000000..f969b81d5 --- /dev/null +++ b/sys/src/cmd/gs/man/pdfopt.1.man @@ -0,0 +1,27 @@ +.\" $Id: pdfopt.1,v 1.36 2005/10/20 19:46:55 ray Exp $ +.TH PDFOPT 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- +.SH NAME +pdfopt \- Ghostscript PDF Optimizer +.SH SYNOPSIS +\fBpdfopt\fR [ \fIoptions\fR ] \fIinput.pdf output.pdf\fR +.SH DESCRIPTION +\fBpdfopt\fR uses \fBgs\fR(1) to convert the Adobe \fBPortable Document +Format\fR (PDF) file "input.pdf" to a so-called optimized form in +"output.pdf". Optimization puts the elements of the file into a more linear +order and adds "hint" pointers, allowing Adobe's Acrobat(TM) products to +display individual pages of the file more quickly when accessing the file +through a network. +.PP +Note: input.pdf and output.pdf must not be the same. If they are, the file +will probably be destroyed. \fBpdfopt\fR currently does not check for this. +.SH FILES +Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your +system, from which you can get more details. +.SH SEE ALSO +"Linearized PDF" in Adobe's PDF reference manual, +http://partners.adobe.com/asn/developer/acrosdk/DOCS/pdfspec.pdf +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. diff --git a/sys/src/cmd/gs/man/pf2afm.1 b/sys/src/cmd/gs/man/pf2afm.1 deleted file mode 100644 index be2001b27..000000000 --- a/sys/src/cmd/gs/man/pf2afm.1 +++ /dev/null @@ -1,23 +0,0 @@ -.\" $Id: pf2afm.1,v 1.37 2005/10/20 19:46:55 ray Exp $ -.TH PF2AFM 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- -.SH NAME -pf2afm \- Make an AFM file from Postscript (PFB/PFA/PFM) font files using ghostscript -.SH SYNOPSIS -\fBpf2afm\fR \fIfontfilename\fR -.SH DESCRIPTION -This script invokes -.BR gs (1) -to make an AFM file from PFB / PFA and (optionally) PFM files. -Output goes to -.IR fontfilename.afm , -which must not already exist. -.SH SEE ALSO -gs(1) -.br -pf2afm.ps in the Ghostscript lib directory. -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/pf2afm.1.man b/sys/src/cmd/gs/man/pf2afm.1.man new file mode 100644 index 000000000..be2001b27 --- /dev/null +++ b/sys/src/cmd/gs/man/pf2afm.1.man @@ -0,0 +1,23 @@ +.\" $Id: pf2afm.1,v 1.37 2005/10/20 19:46:55 ray Exp $ +.TH PF2AFM 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +pf2afm \- Make an AFM file from Postscript (PFB/PFA/PFM) font files using ghostscript +.SH SYNOPSIS +\fBpf2afm\fR \fIfontfilename\fR +.SH DESCRIPTION +This script invokes +.BR gs (1) +to make an AFM file from PFB / PFA and (optionally) PFM files. +Output goes to +.IR fontfilename.afm , +which must not already exist. +.SH SEE ALSO +gs(1) +.br +pf2afm.ps in the Ghostscript lib directory. +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/pfbtopfa.1 b/sys/src/cmd/gs/man/pfbtopfa.1 deleted file mode 100644 index 0d8a37bb1..000000000 --- a/sys/src/cmd/gs/man/pfbtopfa.1 +++ /dev/null @@ -1,18 +0,0 @@ -.\" $Id: pfbtopfa.1,v 1.38 2005/10/20 19:46:55 ray Exp $ -.TH PFBTOPFA 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- -.SH NAME -pfbtopfa \- Convert Postscript .pfb fonts to .pfa format using ghostscript -.SH SYNOPSIS -\fBpfbtopfa\fR \fIinput.pfb\fR \fI[output.pfa]\fR -.SH DESCRIPTION -This script invokes -.BR gs (1) -to convert a .pfb file into a .pfa file. -.SH SEE ALSO -gs(1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/pfbtopfa.1.man b/sys/src/cmd/gs/man/pfbtopfa.1.man new file mode 100644 index 000000000..0d8a37bb1 --- /dev/null +++ b/sys/src/cmd/gs/man/pfbtopfa.1.man @@ -0,0 +1,18 @@ +.\" $Id: pfbtopfa.1,v 1.38 2005/10/20 19:46:55 ray Exp $ +.TH PFBTOPFA 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +pfbtopfa \- Convert Postscript .pfb fonts to .pfa format using ghostscript +.SH SYNOPSIS +\fBpfbtopfa\fR \fIinput.pfb\fR \fI[output.pfa]\fR +.SH DESCRIPTION +This script invokes +.BR gs (1) +to convert a .pfb file into a .pfa file. +.SH SEE ALSO +gs(1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/printafm.1 b/sys/src/cmd/gs/man/printafm.1 deleted file mode 100644 index 1668713ed..000000000 --- a/sys/src/cmd/gs/man/printafm.1 +++ /dev/null @@ -1,19 +0,0 @@ -.\" $Id: printafm.1,v 1.37 2005/10/20 19:46:55 ray Exp $ -.TH PRINTAFM 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- -.SH NAME -printafm \- Print the metrics from a Postscript font in AFM format using ghostscript -.SH SYNOPSIS -\fBprintafm\fR \fIfontname\fR -.SH DESCRIPTION -This script invokes -.BR gs (1) -to print the metrics from a font in AFM format. -Output goes to stdout. -.SH SEE ALSO -gs(1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/printafm.1.man b/sys/src/cmd/gs/man/printafm.1.man new file mode 100644 index 000000000..1668713ed --- /dev/null +++ b/sys/src/cmd/gs/man/printafm.1.man @@ -0,0 +1,19 @@ +.\" $Id: printafm.1,v 1.37 2005/10/20 19:46:55 ray Exp $ +.TH PRINTAFM 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +printafm \- Print the metrics from a Postscript font in AFM format using ghostscript +.SH SYNOPSIS +\fBprintafm\fR \fIfontname\fR +.SH DESCRIPTION +This script invokes +.BR gs (1) +to print the metrics from a font in AFM format. +Output goes to stdout. +.SH SEE ALSO +gs(1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/ps2ascii.1 b/sys/src/cmd/gs/man/ps2ascii.1 deleted file mode 100644 index 984385bb8..000000000 --- a/sys/src/cmd/gs/man/ps2ascii.1 +++ /dev/null @@ -1,31 +0,0 @@ -.\" $Id: ps2ascii.1,v 1.37 2005/10/20 19:46:55 ray Exp $ -.TH PS2ASCII 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- -.SH NAME -ps2ascii \- Ghostscript translator from PostScript or PDF to ASCII -.SH SYNOPSIS -\fBps2ascii\fR [ \fIinput.ps\fR [ \fIoutput.txt\fR ] ] -.br -\fBps2ascii\fR \fIinput.pdf\fR [ \fIoutput.txt\fR ] -.SH DESCRIPTION -\fBps2ascii\fR uses \fBgs\fR(1) to extract ASCII text from -\fBPostScript\fR(tm) or Adobe \fBPortable Document Format\fR (PDF) -files. If no files are specified on the command line, \fBgs\fR reads from -standard input; but PDF input must come from an explicitly-named file, not -standard input. If no output file is specified, the ASCII text is written -to standard output. -.PP -\fBps2ascii\fR doesn't look at font encoding, and isn't very good at -dealing with kerning, so for PostScript (but not currently PDF), you might -consider \fBpstotext\fR (see below). -.SH FILES -Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your -system, from which you can get more details. -.SH SEE ALSO -pstotext(1), http://www.research.digital.com/SRC/virtualpaper/pstotext.html -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -David M. Jones made substantial improvements -to \fBps2ascii\fR. diff --git a/sys/src/cmd/gs/man/ps2ascii.1.man b/sys/src/cmd/gs/man/ps2ascii.1.man new file mode 100644 index 000000000..984385bb8 --- /dev/null +++ b/sys/src/cmd/gs/man/ps2ascii.1.man @@ -0,0 +1,31 @@ +.\" $Id: ps2ascii.1,v 1.37 2005/10/20 19:46:55 ray Exp $ +.TH PS2ASCII 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- +.SH NAME +ps2ascii \- Ghostscript translator from PostScript or PDF to ASCII +.SH SYNOPSIS +\fBps2ascii\fR [ \fIinput.ps\fR [ \fIoutput.txt\fR ] ] +.br +\fBps2ascii\fR \fIinput.pdf\fR [ \fIoutput.txt\fR ] +.SH DESCRIPTION +\fBps2ascii\fR uses \fBgs\fR(1) to extract ASCII text from +\fBPostScript\fR(tm) or Adobe \fBPortable Document Format\fR (PDF) +files. If no files are specified on the command line, \fBgs\fR reads from +standard input; but PDF input must come from an explicitly-named file, not +standard input. If no output file is specified, the ASCII text is written +to standard output. +.PP +\fBps2ascii\fR doesn't look at font encoding, and isn't very good at +dealing with kerning, so for PostScript (but not currently PDF), you might +consider \fBpstotext\fR (see below). +.SH FILES +Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your +system, from which you can get more details. +.SH SEE ALSO +pstotext(1), http://www.research.digital.com/SRC/virtualpaper/pstotext.html +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +David M. Jones made substantial improvements +to \fBps2ascii\fR. diff --git a/sys/src/cmd/gs/man/ps2epsi.1 b/sys/src/cmd/gs/man/ps2epsi.1 deleted file mode 100644 index 04f060192..000000000 --- a/sys/src/cmd/gs/man/ps2epsi.1 +++ /dev/null @@ -1,66 +0,0 @@ -.\" $Id: ps2epsi.1,v 1.35 2005/10/20 19:46:55 ray Exp $ -.TH PS2EPSI 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- -.SH NAME -ps2epsi \- generate conforming Encapsulated PostScript -.SH SYNOPSIS -\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ] \fB(Unix)\fR -.br -\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epi\fR ] \fB(DOS)\fR -.SH DESCRIPTION -\fBps2epsi\fR uses \fBgs\fR(1) to process a \fBPostScript\fR(tm) file and -generate as output a new file which conforms to Adobe's \fBEncapsulated -PostScript Interchange\fR (EPSI) format. EPSI is a special form of -encapsulated PostScript (EPS) which adds to the beginning of the file in -the form of PostScript comments a bitmapped version of the final displayed -page. Programs which understand EPSI (usually word processors or DTP -programs) can use this bitmap to give a preview version on screen of the -PostScript. The displayed quality is often not very good (e.g., low -resolution, no colours), but the final printed version uses the real -PostScript, and thus has the normal PostScript quality. -.SH USAGE -On Unix systems invoke \fBps2epsi\fR like this: -.PP -.br - \fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ] -.PP -where "infile.ps" is the input file and "outfile.epsi" is the resulting -EPSI file. If the output filename is omitted, it is generated from the -input filename. When a standard extension (".ps", ".cps", ".eps" or -".epsf") is used, it is replaced with the output extension ".epsi". On -DOS systems the command is: -.PP -.br - \fBps2epsi\fR \fIinfile.ps outfile.epi\fR -.PP -where "infile.ps" is the original PostScript file, and "outfile.epi" -is the name of the output file. -.SH LIMITATIONS -Not every PostScript file can be encapsulated successfully, because there -are restrictions on what PostScript constructs a correct encapsulated file -may contain. \fBps2epsi\fR does a little extra work to try to help -encapsulation, and it automatically calculates the bounding box required -for all encapsulated PostScript files, so most of the time it does a pretty -good job. There are certain to be cases, however, where the encapsulation -does not work because of the content of the original PostScript file. -.SH COMPATIBILITY -The \fBFramemaker\fR DTP system is one application which understands EPSI -files, and \fBps2epsi\fR has been tested on a number of PostScript diagrams -from a variety of sources, using Framemaker 3.0 on a Sun workstation. -Framemaker on other platforms should be able to use these files, although I -have not been able to test this. -.SH FILES -.TS -tab(>); -l l. -ps2epsi>Unix shell script -ps2epsi.bat>DOS batch file -ps2epsi.ps>the Ghostscript program which does the work -.TE -.fi -.SH SEE ALSO -gs (1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -However, the content may be obsolete, or inconsistent with ps2epsi.txt. -.SH AUTHOR -George Cameron diff --git a/sys/src/cmd/gs/man/ps2epsi.1.man b/sys/src/cmd/gs/man/ps2epsi.1.man new file mode 100644 index 000000000..04f060192 --- /dev/null +++ b/sys/src/cmd/gs/man/ps2epsi.1.man @@ -0,0 +1,66 @@ +.\" $Id: ps2epsi.1,v 1.35 2005/10/20 19:46:55 ray Exp $ +.TH PS2EPSI 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- +.SH NAME +ps2epsi \- generate conforming Encapsulated PostScript +.SH SYNOPSIS +\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ] \fB(Unix)\fR +.br +\fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epi\fR ] \fB(DOS)\fR +.SH DESCRIPTION +\fBps2epsi\fR uses \fBgs\fR(1) to process a \fBPostScript\fR(tm) file and +generate as output a new file which conforms to Adobe's \fBEncapsulated +PostScript Interchange\fR (EPSI) format. EPSI is a special form of +encapsulated PostScript (EPS) which adds to the beginning of the file in +the form of PostScript comments a bitmapped version of the final displayed +page. Programs which understand EPSI (usually word processors or DTP +programs) can use this bitmap to give a preview version on screen of the +PostScript. The displayed quality is often not very good (e.g., low +resolution, no colours), but the final printed version uses the real +PostScript, and thus has the normal PostScript quality. +.SH USAGE +On Unix systems invoke \fBps2epsi\fR like this: +.PP +.br + \fBps2epsi\fR \fIinfile.ps\fR [ \fIoutfile.epsi\fR ] +.PP +where "infile.ps" is the input file and "outfile.epsi" is the resulting +EPSI file. If the output filename is omitted, it is generated from the +input filename. When a standard extension (".ps", ".cps", ".eps" or +".epsf") is used, it is replaced with the output extension ".epsi". On +DOS systems the command is: +.PP +.br + \fBps2epsi\fR \fIinfile.ps outfile.epi\fR +.PP +where "infile.ps" is the original PostScript file, and "outfile.epi" +is the name of the output file. +.SH LIMITATIONS +Not every PostScript file can be encapsulated successfully, because there +are restrictions on what PostScript constructs a correct encapsulated file +may contain. \fBps2epsi\fR does a little extra work to try to help +encapsulation, and it automatically calculates the bounding box required +for all encapsulated PostScript files, so most of the time it does a pretty +good job. There are certain to be cases, however, where the encapsulation +does not work because of the content of the original PostScript file. +.SH COMPATIBILITY +The \fBFramemaker\fR DTP system is one application which understands EPSI +files, and \fBps2epsi\fR has been tested on a number of PostScript diagrams +from a variety of sources, using Framemaker 3.0 on a Sun workstation. +Framemaker on other platforms should be able to use these files, although I +have not been able to test this. +.SH FILES +.TS +tab(>); +l l. +ps2epsi>Unix shell script +ps2epsi.bat>DOS batch file +ps2epsi.ps>the Ghostscript program which does the work +.TE +.fi +.SH SEE ALSO +gs (1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +However, the content may be obsolete, or inconsistent with ps2epsi.txt. +.SH AUTHOR +George Cameron diff --git a/sys/src/cmd/gs/man/ps2pdf.1 b/sys/src/cmd/gs/man/ps2pdf.1 deleted file mode 100644 index 70a243e8d..000000000 --- a/sys/src/cmd/gs/man/ps2pdf.1 +++ /dev/null @@ -1,53 +0,0 @@ -.\" $Id: ps2pdf.1,v 1.42 2005/10/20 19:46:55 ray Exp $ -.TH PS2PDF 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- -.SH NAME -ps2pdf \- Convert PostScript to PDF using ghostscript -.br -ps2pdf12 \- Convert PostScript to PDF\ 1.2 (Acrobat\ 3-and-later compatible) using ghostscript -.br -ps2pdf13 \- Convert PostScript to PDF\ 1.3 (Acrobat\ 4-and-later compatible) using ghostscript -.SH SYNOPSIS -\fBps2pdf\fR [options...] {input.[e]ps|-} [output.pdf|-] -.br -\fBps2pdf12\fR [options...] {input.[e]ps|-} [output.pdf|-] -.br -\fBps2pdf13\fR [options...] {input.[e]ps|-} [output.pdf|-] -.SH DESCRIPTION -The -.B ps2pdf -scripts are work-alikes for nearly all the functionality (but not the -user interface) of Adobe's Acrobat(TM) Distiller(TM) product: they -convert PostScript files to Portable Document Format (PDF) files. -.PP -The three scripts differ as follows: -.IP - -.B ps2pdf12 -will always produce PDF 1.2 output (Acrobat 3-and-later compatible). -.IP - -.B ps2pdf13 -will always produce PDF 1.3 output (Acrobat 4-and-later compatible). -.IP - -.B ps2pdf -per se currently produces PDF 1.2 output (Acrobat 3-and-later -compatible). However, this may change in the future. If you care about -the compatibility level of the output, use -.B ps2pdf12 -or -.BR ps2pdf13 , -or use the -.B \-dCompatibility=1.x -switch in the command line. -.PP -There are some limitations in -.BR ps2pdf 's -conversion. See the HTML documentation for more information. -.SH SEE ALSO -gs(1), ps2pdfwr(1), -.br -Ps2pdf.htm in the Ghostscript documentation -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/ps2pdf.1.man b/sys/src/cmd/gs/man/ps2pdf.1.man new file mode 100644 index 000000000..70a243e8d --- /dev/null +++ b/sys/src/cmd/gs/man/ps2pdf.1.man @@ -0,0 +1,53 @@ +.\" $Id: ps2pdf.1,v 1.42 2005/10/20 19:46:55 ray Exp $ +.TH PS2PDF 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +ps2pdf \- Convert PostScript to PDF using ghostscript +.br +ps2pdf12 \- Convert PostScript to PDF\ 1.2 (Acrobat\ 3-and-later compatible) using ghostscript +.br +ps2pdf13 \- Convert PostScript to PDF\ 1.3 (Acrobat\ 4-and-later compatible) using ghostscript +.SH SYNOPSIS +\fBps2pdf\fR [options...] {input.[e]ps|-} [output.pdf|-] +.br +\fBps2pdf12\fR [options...] {input.[e]ps|-} [output.pdf|-] +.br +\fBps2pdf13\fR [options...] {input.[e]ps|-} [output.pdf|-] +.SH DESCRIPTION +The +.B ps2pdf +scripts are work-alikes for nearly all the functionality (but not the +user interface) of Adobe's Acrobat(TM) Distiller(TM) product: they +convert PostScript files to Portable Document Format (PDF) files. +.PP +The three scripts differ as follows: +.IP - +.B ps2pdf12 +will always produce PDF 1.2 output (Acrobat 3-and-later compatible). +.IP - +.B ps2pdf13 +will always produce PDF 1.3 output (Acrobat 4-and-later compatible). +.IP - +.B ps2pdf +per se currently produces PDF 1.2 output (Acrobat 3-and-later +compatible). However, this may change in the future. If you care about +the compatibility level of the output, use +.B ps2pdf12 +or +.BR ps2pdf13 , +or use the +.B \-dCompatibility=1.x +switch in the command line. +.PP +There are some limitations in +.BR ps2pdf 's +conversion. See the HTML documentation for more information. +.SH SEE ALSO +gs(1), ps2pdfwr(1), +.br +Ps2pdf.htm in the Ghostscript documentation +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/ps2pdfwr.1 b/sys/src/cmd/gs/man/ps2pdfwr.1 deleted file mode 100644 index 767ec02fd..000000000 --- a/sys/src/cmd/gs/man/ps2pdfwr.1 +++ /dev/null @@ -1,31 +0,0 @@ -.\" $Id: ps2pdfwr.1,v 1.41 2005/10/20 19:46:55 ray Exp $ -.TH PS2PDFWR 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- -.SH NAME -ps2pdfwr \- Convert PostScript to PDF without specifying CompatibilityLevel, using ghostscript -.SH SYNOPSIS -\fBps2pdfwr\fR [options...] {input.[e]ps|-} [output.pdf|-] -.SH DESCRIPTION -This wrapper script invokes -.BR gs (1) -with following arguments - -.ce -.B -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite - -as well as the appropriate -.B -dOutputFile -argument, all preceded and followed by any command-line arguments. Finally, the security option -.B -dSAFER -is prepended before all the other options. - -The version-specific -.B ps2pdf -scripts all invoke this one with the addition of the respective compatibility level option. -.SH SEE ALSO -gs(1), ps2pdf(1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/ps2pdfwr.1.man b/sys/src/cmd/gs/man/ps2pdfwr.1.man new file mode 100644 index 000000000..767ec02fd --- /dev/null +++ b/sys/src/cmd/gs/man/ps2pdfwr.1.man @@ -0,0 +1,31 @@ +.\" $Id: ps2pdfwr.1,v 1.41 2005/10/20 19:46:55 ray Exp $ +.TH PS2PDFWR 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +ps2pdfwr \- Convert PostScript to PDF without specifying CompatibilityLevel, using ghostscript +.SH SYNOPSIS +\fBps2pdfwr\fR [options...] {input.[e]ps|-} [output.pdf|-] +.SH DESCRIPTION +This wrapper script invokes +.BR gs (1) +with following arguments + +.ce +.B -q -dNOPAUSE -dBATCH -sDEVICE=pdfwrite + +as well as the appropriate +.B -dOutputFile +argument, all preceded and followed by any command-line arguments. Finally, the security option +.B -dSAFER +is prepended before all the other options. + +The version-specific +.B ps2pdf +scripts all invoke this one with the addition of the respective compatibility level option. +.SH SEE ALSO +gs(1), ps2pdf(1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/ps2ps.1 b/sys/src/cmd/gs/man/ps2ps.1 deleted file mode 100644 index aeeba7cd6..000000000 --- a/sys/src/cmd/gs/man/ps2ps.1 +++ /dev/null @@ -1,33 +0,0 @@ -.\" $Id: ps2ps.1,v 1.44 2005/10/20 19:46:55 ray Exp $ -.TH PS2PS 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- -.SH NAME -ps2ps, eps2eps \- Ghostscript PostScript "distiller" -.SH SYNOPSIS -\fBps2ps\fR [ \fIoptions\fR ] \fIinput.ps output.ps\fR -.br -\fBeps2eps\fR [ \fIoptions\fR ] \fIinput.eps output.eps\fR -.SH DESCRIPTION -\fBps2ps\fR uses \fIgs\fR(1) to convert \fBPostScript\fR(tm) file -"input.ps" to simpler, normalized and (usually) faster PostScript in -"output.ps". Normally the output is allowed to use PostScript Level 2 -or Level 3 constructs, but the \fB\-dLanguageLevel=1\fR option restricts -the output to Level 1. -.PP -\fBeps2eps\fR performs the equivalent optimization for Encapsulated -PostScript (EPS) files. -.PP -Both accept any general Ghostscript command line options, and -respectively options specific to the pswrite and epswrite devices. -.SH FILES -Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your -system, from which you can get more details. -.SH BUGS -The pswrite device used by both \fBps2ps\fR and \fBeps2eps\fR produces much -lower level output than is desirable. Use with caution. -.SH SEE ALSO -ps2pdf(1), ps2ascii(1), ps2epsi(1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software are the primary maintainers of Ghostscript. -Please send bug reports to . diff --git a/sys/src/cmd/gs/man/ps2ps.1.man b/sys/src/cmd/gs/man/ps2ps.1.man new file mode 100644 index 000000000..aeeba7cd6 --- /dev/null +++ b/sys/src/cmd/gs/man/ps2ps.1.man @@ -0,0 +1,33 @@ +.\" $Id: ps2ps.1,v 1.44 2005/10/20 19:46:55 ray Exp $ +.TH PS2PS 1 "20 October 2005" 8.53 "Ghostscript Tools" \" -*- nroff -*- +.SH NAME +ps2ps, eps2eps \- Ghostscript PostScript "distiller" +.SH SYNOPSIS +\fBps2ps\fR [ \fIoptions\fR ] \fIinput.ps output.ps\fR +.br +\fBeps2eps\fR [ \fIoptions\fR ] \fIinput.eps output.eps\fR +.SH DESCRIPTION +\fBps2ps\fR uses \fIgs\fR(1) to convert \fBPostScript\fR(tm) file +"input.ps" to simpler, normalized and (usually) faster PostScript in +"output.ps". Normally the output is allowed to use PostScript Level 2 +or Level 3 constructs, but the \fB\-dLanguageLevel=1\fR option restricts +the output to Level 1. +.PP +\fBeps2eps\fR performs the equivalent optimization for Encapsulated +PostScript (EPS) files. +.PP +Both accept any general Ghostscript command line options, and +respectively options specific to the pswrite and epswrite devices. +.SH FILES +Run "\fBgs -h\fR" to find the location of Ghostscript documentation on your +system, from which you can get more details. +.SH BUGS +The pswrite device used by both \fBps2ps\fR and \fBeps2eps\fR produces much +lower level output than is desirable. Use with caution. +.SH SEE ALSO +ps2pdf(1), ps2ascii(1), ps2epsi(1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software are the primary maintainers of Ghostscript. +Please send bug reports to . diff --git a/sys/src/cmd/gs/man/wftopfa.1 b/sys/src/cmd/gs/man/wftopfa.1 deleted file mode 100644 index a0855de1a..000000000 --- a/sys/src/cmd/gs/man/wftopfa.1 +++ /dev/null @@ -1,20 +0,0 @@ -.\" $Id: wftopfa.1,v 1.37 2005/10/20 19:46:55 ray Exp $ -.TH WFTOPFA 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- -.SH NAME -wftopfa \- Convert a Wadalab base font to Postscript .PFA (or .PFB) -format using ghostscript -.SH SYNOPSIS -\fBwftopfa\fR \fIfontname\fR -.SH DESCRIPTION -This script invokes -.BR gs (1) -to convert a Wadalab base font to Postscript .PFA (or .PFB) -format. -.SH SEE ALSO -gs(1) -.SH VERSION -This document was last revised for Ghostscript version 8.53. -.SH AUTHOR -artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the -primary maintainers of Ghostscript. -This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/man/wftopfa.1.man b/sys/src/cmd/gs/man/wftopfa.1.man new file mode 100644 index 000000000..a0855de1a --- /dev/null +++ b/sys/src/cmd/gs/man/wftopfa.1.man @@ -0,0 +1,20 @@ +.\" $Id: wftopfa.1,v 1.37 2005/10/20 19:46:55 ray Exp $ +.TH WFTOPFA 1 "20 October 2005" 8.53 Ghostscript \" -*- nroff -*- +.SH NAME +wftopfa \- Convert a Wadalab base font to Postscript .PFA (or .PFB) +format using ghostscript +.SH SYNOPSIS +\fBwftopfa\fR \fIfontname\fR +.SH DESCRIPTION +This script invokes +.BR gs (1) +to convert a Wadalab base font to Postscript .PFA (or .PFB) +format. +.SH SEE ALSO +gs(1) +.SH VERSION +This document was last revised for Ghostscript version 8.53. +.SH AUTHOR +artofcode LLC and Artifex Software, bug-gs at ghostscript.com, are the +primary maintainers of Ghostscript. +This manpage by George Ferguson. diff --git a/sys/src/cmd/gs/zlib/zlib.3 b/sys/src/cmd/gs/zlib/zlib.3 deleted file mode 100644 index 3139e2467..000000000 --- a/sys/src/cmd/gs/zlib/zlib.3 +++ /dev/null @@ -1,159 +0,0 @@ -.TH ZLIB 3 "3 October 2004" -.SH NAME -zlib \- compression/decompression library -.SH SYNOPSIS -[see -.I zlib.h -for full description] -.SH DESCRIPTION -The -.I zlib -library is a general purpose data compression library. -The code is thread safe. -It provides in-memory compression and decompression functions, -including integrity checks of the uncompressed data. -This version of the library supports only one compression method (deflation) -but other algorithms will be added later -and will have the same stream interface. -.LP -Compression can be done in a single step if the buffers are large enough -(for example if an input file is mmap'ed), -or can be done by repeated calls of the compression function. -In the latter case, -the application must provide more input and/or consume the output -(providing more output space) before each call. -.LP -The library also supports reading and writing files in -.IR gzip (1) -(.gz) format -with an interface similar to that of stdio. -.LP -The library does not install any signal handler. -The decoder checks the consistency of the compressed data, -so the library should never crash even in case of corrupted input. -.LP -All functions of the compression library are documented in the file -.IR zlib.h . -The distribution source includes examples of use of the library -in the files -.I example.c -and -.IR minigzip.c . -.LP -Changes to this version are documented in the file -.I ChangeLog -that accompanies the source, -and are concerned primarily with bug fixes and portability enhancements. -.LP -A Java implementation of -.I zlib -is available in the Java Development Kit 1.1: -.IP -http://www.javasoft.com/products/JDK/1.1/docs/api/Package-java.util.zip.html -.LP -A Perl interface to -.IR zlib , -written by Paul Marquess (pmqs@cpan.org), -is available at CPAN (Comprehensive Perl Archive Network) sites, -including: -.IP -http://www.cpan.org/modules/by-module/Compress/ -.LP -A Python interface to -.IR zlib , -written by A.M. Kuchling (amk@magnet.com), -is available in Python 1.5 and later versions: -.IP -http://www.python.org/doc/lib/module-zlib.html -.LP -A -.I zlib -binding for -.IR tcl (1), -written by Andreas Kupries (a.kupries@westend.com), -is availlable at: -.IP -http://www.westend.com/~kupries/doc/trf/man/man.html -.LP -An experimental package to read and write files in .zip format, -written on top of -.I zlib -by Gilles Vollant (info@winimage.com), -is available at: -.IP -http://www.winimage.com/zLibDll/unzip.html -and also in the -.I contrib/minizip -directory of the main -.I zlib -web site. -.SH "SEE ALSO" -The -.I zlib -web site can be found at either of these locations: -.IP -http://www.zlib.org -.br -http://www.gzip.org/zlib/ -.LP -The data format used by the zlib library is described by RFC -(Request for Comments) 1950 to 1952 in the files: -.IP -http://www.ietf.org/rfc/rfc1950.txt (concerning zlib format) -.br -http://www.ietf.org/rfc/rfc1951.txt (concerning deflate format) -.br -http://www.ietf.org/rfc/rfc1952.txt (concerning gzip format) -.LP -These documents are also available in other formats from: -.IP -ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html -.LP -Mark Nelson (markn@ieee.org) wrote an article about -.I zlib -for the Jan. 1997 issue of Dr. Dobb's Journal; -a copy of the article is available at: -.IP -http://dogma.net/markn/articles/zlibtool/zlibtool.htm -.SH "REPORTING PROBLEMS" -Before reporting a problem, -please check the -.I zlib -web site to verify that you have the latest version of -.IR zlib ; -otherwise, -obtain the latest version and see if the problem still exists. -Please read the -.I zlib -FAQ at: -.IP -http://www.gzip.org/zlib/zlib_faq.html -.LP -before asking for help. -Send questions and/or comments to zlib@gzip.org, -or (for the Windows DLL version) to Gilles Vollant (info@winimage.com). -.SH AUTHORS -Version 1.2.2 -Copyright (C) 1995-2004 Jean-loup Gailly (jloup@gzip.org) -and Mark Adler (madler@alumni.caltech.edu). -.LP -This software is provided "as-is," -without any express or implied warranty. -In no event will the authors be held liable for any damages -arising from the use of this software. -See the distribution directory with respect to requirements -governing redistribution. -The deflate format used by -.I zlib -was defined by Phil Katz. -The deflate and -.I zlib -specifications were written by L. Peter Deutsch. -Thanks to all the people who reported problems and suggested various -improvements in -.IR zlib ; -who are too numerous to cite here. -.LP -UNIX manual page by R. P. C. Rodgers, -U.S. National Library of Medicine (rodgers@nlm.nih.gov). -.\" end of man page diff --git a/sys/src/cmd/gs/zlib/zlib.3.man b/sys/src/cmd/gs/zlib/zlib.3.man new file mode 100644 index 000000000..3139e2467 --- /dev/null +++ b/sys/src/cmd/gs/zlib/zlib.3.man @@ -0,0 +1,159 @@ +.TH ZLIB 3 "3 October 2004" +.SH NAME +zlib \- compression/decompression library +.SH SYNOPSIS +[see +.I zlib.h +for full description] +.SH DESCRIPTION +The +.I zlib +library is a general purpose data compression library. +The code is thread safe. +It provides in-memory compression and decompression functions, +including integrity checks of the uncompressed data. +This version of the library supports only one compression method (deflation) +but other algorithms will be added later +and will have the same stream interface. +.LP +Compression can be done in a single step if the buffers are large enough +(for example if an input file is mmap'ed), +or can be done by repeated calls of the compression function. +In the latter case, +the application must provide more input and/or consume the output +(providing more output space) before each call. +.LP +The library also supports reading and writing files in +.IR gzip (1) +(.gz) format +with an interface similar to that of stdio. +.LP +The library does not install any signal handler. +The decoder checks the consistency of the compressed data, +so the library should never crash even in case of corrupted input. +.LP +All functions of the compression library are documented in the file +.IR zlib.h . +The distribution source includes examples of use of the library +in the files +.I example.c +and +.IR minigzip.c . +.LP +Changes to this version are documented in the file +.I ChangeLog +that accompanies the source, +and are concerned primarily with bug fixes and portability enhancements. +.LP +A Java implementation of +.I zlib +is available in the Java Development Kit 1.1: +.IP +http://www.javasoft.com/products/JDK/1.1/docs/api/Package-java.util.zip.html +.LP +A Perl interface to +.IR zlib , +written by Paul Marquess (pmqs@cpan.org), +is available at CPAN (Comprehensive Perl Archive Network) sites, +including: +.IP +http://www.cpan.org/modules/by-module/Compress/ +.LP +A Python interface to +.IR zlib , +written by A.M. Kuchling (amk@magnet.com), +is available in Python 1.5 and later versions: +.IP +http://www.python.org/doc/lib/module-zlib.html +.LP +A +.I zlib +binding for +.IR tcl (1), +written by Andreas Kupries (a.kupries@westend.com), +is availlable at: +.IP +http://www.westend.com/~kupries/doc/trf/man/man.html +.LP +An experimental package to read and write files in .zip format, +written on top of +.I zlib +by Gilles Vollant (info@winimage.com), +is available at: +.IP +http://www.winimage.com/zLibDll/unzip.html +and also in the +.I contrib/minizip +directory of the main +.I zlib +web site. +.SH "SEE ALSO" +The +.I zlib +web site can be found at either of these locations: +.IP +http://www.zlib.org +.br +http://www.gzip.org/zlib/ +.LP +The data format used by the zlib library is described by RFC +(Request for Comments) 1950 to 1952 in the files: +.IP +http://www.ietf.org/rfc/rfc1950.txt (concerning zlib format) +.br +http://www.ietf.org/rfc/rfc1951.txt (concerning deflate format) +.br +http://www.ietf.org/rfc/rfc1952.txt (concerning gzip format) +.LP +These documents are also available in other formats from: +.IP +ftp://ftp.uu.net/graphics/png/documents/zlib/zdoc-index.html +.LP +Mark Nelson (markn@ieee.org) wrote an article about +.I zlib +for the Jan. 1997 issue of Dr. Dobb's Journal; +a copy of the article is available at: +.IP +http://dogma.net/markn/articles/zlibtool/zlibtool.htm +.SH "REPORTING PROBLEMS" +Before reporting a problem, +please check the +.I zlib +web site to verify that you have the latest version of +.IR zlib ; +otherwise, +obtain the latest version and see if the problem still exists. +Please read the +.I zlib +FAQ at: +.IP +http://www.gzip.org/zlib/zlib_faq.html +.LP +before asking for help. +Send questions and/or comments to zlib@gzip.org, +or (for the Windows DLL version) to Gilles Vollant (info@winimage.com). +.SH AUTHORS +Version 1.2.2 +Copyright (C) 1995-2004 Jean-loup Gailly (jloup@gzip.org) +and Mark Adler (madler@alumni.caltech.edu). +.LP +This software is provided "as-is," +without any express or implied warranty. +In no event will the authors be held liable for any damages +arising from the use of this software. +See the distribution directory with respect to requirements +governing redistribution. +The deflate format used by +.I zlib +was defined by Phil Katz. +The deflate and +.I zlib +specifications were written by L. Peter Deutsch. +Thanks to all the people who reported problems and suggested various +improvements in +.IR zlib ; +who are too numerous to cite here. +.LP +UNIX manual page by R. P. C. Rodgers, +U.S. National Library of Medicine (rodgers@nlm.nih.gov). +.\" end of man page -- cgit v1.2.3