Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 379 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man1/pamcomp.1 b/upstream/debian-bookworm/man1/pamcomp.1
new file mode 100644
index 00000000..d3cd9307
--- /dev/null
+++ b/upstream/debian-bookworm/man1/pamcomp.1
@@ -0,0 +1,379 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pamcomp User Manual" 1 "13 August 2011" "netpbm documentation"
+.PP
+.SH NAME
+pamcomp - composite (overlay) two Netpbm images together
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpamcomp\fP
+
+[\fB-align=\fP{\fBleft\fP | \fBcenter\fP | \fBright\fP |
+\fBbeyondleft\fP | \fBbeyondright\fP}]
+[\fB-valign=\fP{\fBtop\fP | \fBmiddle\fP | \fBbottom\fP|
+\fBabove\fP | \fBbelow\fP}]
+[\fB-xoff=\fP\fIX\fP]
+[\fB-yoff=\fP\fIY\fP]
+[\fB-alpha=\fP\fIalpha-pgmfile\fP]
+[\fB-invert\fP]
+[\fB-opacity=\fP\fIopacity\fP]
+[\fB-mixtransparency\fP]
+[\fB-linear\fP]
+\fIoverlay_file\fP
+[\fIunderlying_file\fP [\fIoutput_file\fP]]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use double
+hyphens instead of single hyphen to denote options.  You may use white
+space in place of the equals sign to separate an option name from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+
+\fBpamcomp\fP reads two images and produces a composite image with
+one of the images overlayed on top of the other, possible
+translucently.  The images need not be the same size.  The input and
+outputs are Netpbm format image files.
+.PP
+In its simplest use, \fBpamcomp\fP simply places the image in the
+file \fIoverlay_file\fP on top of the image in the file
+\fIunderlying_file\fP, blocking out the part of \fIunderlying_file\fP
+beneath it.
+.PP
+If you add the \fB-alpha\fP option, then \fBpamcomp\fP uses the
+image in file \fIalpha-pgmfile\fP as a transparency mask, which means it
+determines the level of transparency of each point in the overlay
+image.  The transparency mask must have the same dimensions as the overlay
+image.  In places where the transparency mask defines the overlay image to be
+opaque, the composite output contains only the contents of the overlay
+image; the underlying image is totally blocked out.  In places where
+the transparency mask defines the overlay image to be transparent, the
+composite output contains none of the overlay image; the underlying
+image shows through completely.  In places where the transparency mask shows
+a value in between opaque and transparent (translucence), the
+composite image contains a mixture of the overlay image and the
+underlying image and the level of translucence determines how much of
+each.
+.PP
+The transparency mask is a PGM file in which a white pixel represents
+opaqueness and a black pixel transparency.  Anything in between is
+translucent.  (Like any Netpbm program, \fBpamcomp\fP will see a PBM
+file as if it is PGM).
+.PP
+If the overlay image is a PAM image of tuple type RGB_ALPHA or
+GRAYSCALE_ALPHA, then the overlay image contains transparency
+information itself and \fBpamcomp\fP uses it the same way as the
+transparency mask described above.  If you supply both an overlay image that
+has transparency information and a transparency mask, \fBpamcomp\fP
+multiplies the two opacities to get the opacity of the overlay pixel.
+.PP
+Before Netpbm 10.25 (October 2004), \fBpamcomp\fP did not recognize the
+transparency information in a PAM image -- it just ignored it.  So people had
+to make appropriate transparency masks in order to have a non-opaque overlay.  Some
+Netpbm programs that convert from image formats that contain transparency
+information are not able to create RGB_ALPHA or GRAYSCALE_ALPHA PAM output, so
+you have to use the old method -- extract the transparency information from
+the original into a separate transparency mask and use that as input to
+\fBpamcomp\fP.
+.PP
+The output image is always of the same dimensions as the underlying
+image.  \fBpamcomp\fP uses only parts of the overlay image that fit
+within the underlying image.
+.PP
+The output image is a PAM image.  Its tuples are color, grayscale, or black
+and white, whichever is the "highest" format between the two input
+images.  The maxval of the output is the least common multiple of the maxvals
+of the input, up to the maximum possible PAM maxval, 65535.
+.PP
+The output has an opacity channel if and only if the underlying image does,
+and then the opacities are as described under the \fB-mixtransparency\fP
+option.  Before Netpbm 10.56 (September 2011), the output never has an opacity
+channel.
+.PP
+To specify where on the underlying image to place the overlay
+image, use the \fB-align\fP, \fB-valign\fP, \fB-xoff\fP, and
+\fB-yoff\fP options.  Without these options, the default horizontal
+position is flush left and the default vertical position is flush top.
+.PP
+The overlay image, in the position you specify, need not fit entirely
+within the underlying image.  \fBpamcomp\fP uses only the parts of the
+overlay image that appear above the underlying image.  It is possible to
+specify positioning such that \fInone\fP of the overlay image is 
+over the underlying image -- i.e. the overlay is out of frame.  If you
+do that, \fBpamcomp\fP issues a warning.
+.PP
+ The overlay and underlying images may be of different formats
+(e.g. overlaying a PBM text image over a full color PPM image) and
+have different maxvals.  The output image has the more general of the
+two input formats and a maxval that is the least common multiple the
+two maxvals (or the maximum maxval allowable by the format, if the LCM
+is more than that).
+
+
+.UN arguments
+.SH ARGUMENTS
+.PP
+The \fIoverlay_file\fP argument is the name of the file containing the
+  overly image, while \fIunderlying_file\fP is the name of the file
+  containing the underlying image.  For either, you may specify '-'
+  to indicate Standard Input, and \fIunderlying\fP file defaults to Standard
+  Input.  Make sure you aren't specifying (or defaulting) Standard Input as
+  both.
+.PP
+Note that there may be a third input file, identified by an
+\fB-alphafile\fP option.
+.PP
+The \fIoutput_file\fP argument is the name of the file to which
+  \fBpamcomp\fP writes the output, creating or truncating it first.  You may
+  specify '-' to indicate Standard Output, in which
+  case \fBpamcomp\fP does not truncate it.  Note that \fBpamcomp\fP is
+  unusual among Netpbm programs, as a historical accident, in having an output
+  file argument; Netpbm programs normally write to Standard Output only.
+  
+  
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpamcomp\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-align=\fP\fIalignment\fP
+This option selects the basic horizontal position of the overlay image
+with respect to the underlying image, in syntax reminiscent of HTML.
+\fBleft\fP means flush left, \fBcenter\fP means centered, and \fBright\fP
+means flush right.
+.sp
+The \fB-xoff\fP option modifies this position.
+
+\fBbeyondleft\fP means just out of frame to the left -- the right edge of
+the overlay is flush with the left edge of the underlying image.  
+\fBbeyondright\fP means just out of frame to the right.  These alignments
+are useful only if you add a \fB-xoff\fP option.    These two values were
+added in Netpbm 10.10 (October 2002).
+.sp
+The default is \fBleft\fP.
+
+.TP
+\fB-valign=\fP\fIalignment\fP
+This option selects the basic vertical position of the overlay image
+with respect to the underlying image, in syntax reminiscent of HTML.
+\fBtop\fP means flush top, \fBmiddle\fP means centered, and \fBbottom\fP
+means flush bottom.
+.sp
+The \fB-yoff\fP option modifies this position.
+
+\fBabove\fP means just out of frame to the top -- the bottom edge of
+the overlay is flush with the top edge of the underlying image.  
+\fBbelow\fP means just out of frame to the bottom.  These alignments
+are useful only if you add a \fB-yoff\fP option.  These two values were
+added in Netpbm 10.10 (October 2002).
+.sp
+The default is \fBtop\fP.
+
+.TP
+\fB-xoff=\fP\fIx\fP
+This option modifies the horizontal positioning of the overlay
+image with respect to the underlying image as selected by the
+\fB-align\fP option.  \fBpamcomp\fP shifts the overlay image from
+that basic position \fIx\fP pixels to the right.  \fIx\fP can be
+negative to indicate shifting to the left.
+.sp
+The overlay need not fit entirely (or at all) on the underlying image.
+\fBpamcomp\fP uses only the parts that lie over the underlying image.
+.sp
+Before Netpbm 10.10 (October 2002), \fB-xoff\fP was mutually 
+exclusive with \fB-align\fP and always measured from the left edge.
+
+.TP
+\fB-yoff=\fP\fIy\fP
+This option modifies the vertical positioning of the overlay
+image with respect to the underlying image as selected by the
+\fB-valign\fP option.  \fBpamcomp\fP shifts the overlay image from
+that basic position \fIy\fP pixels downward.  \fIy\fP can be
+negative to indicate shifting upward.
+.sp
+The overlay need not fit entirely (or at all) on the underlying image.
+\fBpamcomp\fP uses only the parts that lie over the underlying image.
+.sp
+Before Netpbm 10.10 (October 2002), \fB-xoff\fP was mutually 
+exclusive with \fB-valign\fP and always measured from the top edge.
+
+.TP
+\fB-alpha=\fP\fIalpha-pgmfile\fP
+This option names a file that contains the transparency mask.  If you don't
+specify this option, there is no transparency mask, which is equivalent to 
+having a transparency mask specify total opaqueness everywhere.
+.sp
+You can specify \fB-\fP as the value of this option and the transparency
+mask will come from Standard Input.  If you do this, don't specify
+Standard Input as the source of any other input image.
+
+.TP
+\fB-invert\fP
+This option inverts the sense of the values in the transparency mask, which 
+effectively switches the roles of the overlay image and the underlying
+image in places where the two intersect.
+
+.TP
+\fB-opacity=\fP\fIopacity\fP
+This option tells how opaque the overlay image is to be, i.e. how much
+of the composite image should be from the overlay image, as opposed to
+the underlying image.  \fIopacity\fP is a floating point number, with
+1.0 meaning the overlay image is totally opaque and 0.0 meaning it is
+totally transparent.  The default is 1.0.
+.sp
+If you specify a transparency mask (the \fB-alpha\fP option),
+\fBpamcomp\fP uses the product of the opacity indicated by the transparency
+mask (as modified by the \fB-invert\fP option, as a fraction, and
+this opacity value.  The \fB-invert\fP option does not apply to this
+opacity value.
+.sp
+As a simple opacity value, the value makes sense only if it is
+between 0 and 1, inclusive.  However, \fBpamcomp\fP accepts all
+values and performs the same arithmetic computation using whatever
+value you provide.  An opacity value less than zero means the underlay
+image is intensified and then the overlay image is "subtracted" from
+it.  An opacity value greater than unity means the overlay image is
+intensified and the underlay image subtracted from it.  In either
+case, \fBpamcomp\fP clips the resulting color component intensities
+so they are nonnegative and don't exceed the output image's maxval.
+.sp
+This may seem like a strange thing to do, but it has uses.  You can use it
+to brighten or darken or saturate or desaturate areas of the underlay image.
+See
+.BR " this description" (1)\c
+\& of the technique.
+.sp
+This option was added in Netpbm 10.6 (July 2002).  Before Netpbm 10.15
+(April 2003), values less than zero or greater than unity were not allowed.
+
+.TP
+\fB-mixtransparency\fP
+This option controls what \fBpamcomp\fP does where both the underlying and
+overlay image are non-opaque.
+.sp
+By default, the output image has the same transparency as the underlying
+image and the transparency of the underlying image has no effect on the
+composition of color.
+.sp
+But with this option, \fBpamcomp\fP composes the image according to a
+plastic transparency metaphor: the underlying and overlay images are plastic
+slides.  The output image is the slide you get when you stack up those two
+slides.  So the transparency of the output is a combination of the
+transparency of the inputs and the transparency of the underlying image
+affects the underlying image's contribution to the output image's color.
+.sp
+Unlike the metaphorical slide, a PAM pixel has a color even where it is
+completely transparent, so \fBpamcomp\fP departs from the metaphor in that
+case and makes the output color identical to the underlying image.
+.sp
+This option was new in Netpbm 10.56 (September 2011).  Before that, the
+output is always opaque and the \fBpamcomp\fP ignores the transparency of the
+underlying image.
+
+.TP
+\fB-linear\fP
+This option indicates that the inputs are not true Netpbm images but
+rather a light-intesity-proportional variation.  This is relevant only when
+you mix pixels, using the \fB-opacity\fP option or a transparency mask
+(the \fB-alpha\fP option).
+.sp
+The transparency mask and \fB-opacity\fP values indicate a fraction of
+the light intensity of a pixel.  But the PNM and PNM-equivalent PAM
+image formats represent intensities with gamma-adjusted numbers that
+are not linearly proportional to intensity.  So \fBpamcomp\fP, by
+default, performs a calculation on each sample read from its input and
+each sample written to its output to convert between these
+gamma-adjusted numbers and internal intensity-proportional numbers.
+.sp
+Sometimes you are not working with true PNM or PAM images, but
+rather a variation in which the sample values are in fact directly
+proportional to intensity.  If so, use the \fB-linear\fP option to
+tell \fBpamcomp\fP this.  \fBpamcomp\fP then will skip the
+conversions.
+.sp
+The conversion takes time.  And the difference between
+intensity-proportional values and gamma-adjusted values may be small
+enough that you would barely see a difference in the result if you
+just pretended that the gamma-adjusted values were in fact
+intensity-proportional.  So just to save time, at the expense of some
+image quality, you can specify \fB-linear\fP even when you have true
+PPM input and expect true PPM output.
+.sp
+For the first 13 years of Netpbm's life, until Netpbm 10.20
+(January 2004), \fBpamcomp\fP's predecessor \fBpnmcomp\fP always
+treated the PPM samples as intensity-proportional even though they
+were not, and drew few complaints.  So using \fB-linear\fP as a lie
+is a reasonable thing to do if speed is important to you.
+.sp
+Another technique to consider is to convert your PNM image to the
+linear variation with \fBpnmgamma\fP, run \fBpamcomp\fP on it and
+other transformations that like linear PNM, and then convert it back
+to true PNM with \fBpnmgamma -ungamma\fP.  \fBpnmgamma\fP is often
+faster than \fBpamcomp\fP in doing the conversion.
+
+
+
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "pammixmulti.html" (1)\c
+\& mixes together
+two or more images of the same size, in various ways.
+.PP
+.BR "ppmmix" (1)\c
+\& and
+.BR "pnmpaste" (1)\c
+\& are simpler, less general
+versions of the same tool.
+.PP
+.BR "ppmcolormask" (1)\c
+\& and
+.BR "pbmmask" (1)\c
+\&, and
+.BR "\fBpambackground\fP" (1)\c
+\& can help with
+generating a transparency mask.
+.PP
+.BR "pnmcomp" (1)\c
+\& is an older program that
+runs faster, but has less function.
+.PP
+.BR "pnm" (1)\c
+\&
+
+
+.UN history
+.SH HISTORY
+.PP
+\fBpamcomp\fP was new in Netpbm 10.21 (March 2004).  Its predecessor,
+\fBpnmcomp\fP, was one of the first programs added to Netpbm when the
+project went global in 1993.
+
+
+.UN author
+.SH AUTHOR
+
+Copyright (C) 1992 by David Koblas (\fIkoblas@mips.com\fP).
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/pamcomp.html
+.PP
\ No newline at end of file