Add xmag_multivis from x-S12

[unleashed-userland.git] / components / x11 / xmag_multivis / src / xmag_multivis.man

.\" Copyright (c) 1994, 2008, Oracle and/or its affiliates. All rights reserved.
.\"
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the "Software"),
.\" to deal in the Software without restriction, including without limitation
.\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
.\" and/or sell copies of the Software, and to permit persons to whom the
.\" Software is furnished to do so, subject to the following conditions:
.\"
.\" The above copyright notice and this permission notice (including the next
.\" paragraph) shall be included in all copies or substantial portions of the
.\" Software.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
.\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
.\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
.\" DEALINGS IN THE SOFTWARE.
.\"
.TH xmag_multivis 6 "23 March 1992"
.IX "xmag_multivis" "" "\f3xmag_multivis\f1(6) \(em screen maginifcation demo" ""
.IX "demo" "screen" "demonstration programs" "screen magnification demo \(em \f3xmag_multivis\f1(6)"
.SH NAME
xmag_multivis \- magnify parts of the screen
.SH SYNOPSIS
.B "xmag_multivis"
[
.BI \-display " display"
] [
.BI \-geometry " geom"
] [
.BI \-source " geom"
] [
.BI \-mag " magfactor"
] [
.BI \-bw " pixels"
] [
.BI \-bd " color"
] [
.BI \-bg " colorpixelvalue"
] [
.BI \-fn " fontname"
] [
.BI \-z
]
.SH DESCRIPTION
.PP
The
.B xmag_multivis
program allows you to magnify portions of the screen.  If no
explicit region is specified, a square centered around the pointer is displayed
indicating the area to be enlarged.  Once a region has been selected, a window
is popped up showing a blown up version of the region in which each pixel in 
the source image is represented by a small square of the same color.  Pressing
Button1 on the pointer in the enlargement window pops up a small window 
displaying, in hexadecimal notation,
the position, pixel value, and RGB value of the pixel
under the pointer until the
button is released.  Pressing the space bar or any other pointer button removes
the enlarged image so that another region may be selected.
Pressing ``q'', ``Q'', or ``^C'' in the 
enlargement window exits the program.
.PP
On displays that export multiple Visuals, the selected region is
first examined for overlaps by windows of differing depth, visual or
colormap. If the selected region does contain such windows, the
image displayed in the enlargement window is constructed by
compositing the images from the various windows under the selected
region. In this case, the composite image will only be displayed
in a TrueColor 24 bit deep window, provided such a window can be 
created on that screen.
The image displayed in the enlargement window will exhibit
true colors for every pixel in the composite image, regardless of
the Colormap state (Installed/UnInstalled) of any of the windows within
the selected region.
.sp
.SH OPTIONS
.TP 8
.BI \-display " display"
This option specifies the X server to use for both reading the screen and
displaying the enlarged version of the image.
.TP 8
.BI \-geometry " geom"
This option specifies the size and/or location of the enlargement window.  By
default, the size is computed from the size of the source region and the 
desired magnification.  Therefore, only one of
.BI \-source " size"
and 
.BI \-mag " magfactor"
options may be specified if a window size is given with this option.
.TP 8
.BI \-source " geom"
This option specifies the size and/or location of the source region on the
screen.  By default, a 64x64 square centered about the pointer is provided
for the user to select an area of the screen.  The size of the source is used
with the desired magnification to compute the default enlargement window
size.  Therefore, only one of
.BI \-geometry " size"
and 
.BI \-mag " magfactor"
options may be specified if a source size is given with this option.
.TP 8 
.BI \-mag " magfactor"
This option specifies an integral factor by which the source region should be
enlarged.  The default magnification is 5.
This is used with the size of the source to compute the default
enlargement window size.  Therefore, only one of
.BI \-geometry " size"
and
.BI \-source " geom"
options may be specified if a magnification factor is 
given with this option.
.TP 8
.BI \-bw " pixels"
This option specifies the width in pixels of the border surrounding the
enlargement window.
.TP 8
.BI \-bd " color"
This option specifies the color to use for the border surrounding the 
enlargement window.
.TP 8
.BI \-bg " colororpixelvalue"
This option specifies the name of the color to be used as the background of 
the enlargement window.  If the name begins with a percent size (%), it is
interpreted to be an absolute pixel value.  This is useful when displaying
large areas since pixels that are the same color as the background do not
need to be painted in the enlargement.  The default is to use the BlackPixel
of the screen.
.TP 8
.BI \-fn " fontname"
This option specifies the name of a font to use when displaying pixel values
(used when Button1 is pressed in the enlargement window).
.TP 8
.B \-z
This option indicates that the server should be grabbed during the dynamics
and the call to XGetImage.  This is useful for ensuring that clients don't
change their state as a result of entering or leaving them with the pointer.
.SH X DEFAULTS
The
.B xmag_multivis
program uses the following X resources:
.TP 8
.BR geometry " (class " Geometry ")"
Specifies the size and/or location of the enlargement window.
.TP 8
.BR source " (class " Source ")"
Specifies the size and/or location of the source region on the screen.
.TP 8
.BR magnification " (class " Magnification ")"
Specifies the enlargement factor.
.TP 8
.BR borderWidth " (class " BorderWidth ")"
Specifies the border width in pixels.
.TP 8
.BR borderColor " (class " BorderColor ")"
Specifies the color of the border.
.TP 8
.BR background " (class " Background ")"
Specifies the color or pixel value to be used for the background of the 
enlargement window.
.TP 8
.BR font " (class " Font ")"
Specifies the name of the font to use when displaying pixel values when the
user presses Button1 in the enlargement window.
.SH SEE ALSO
.BR xwd (1),
.BR xmag (1)
.SH BUGS
.PP
On displays that export multiple visuals, if the selected
region needs to be composited from each window,
.B xmag_multivis
insists
on a TrueColor 24 bit window to display the selected region,
and exits with a failure if such a window cannot be created.
It would be nice, instead if
.B xmag_multivis
would determine the
best possible visual to display the image, or instead tried
to display the image in a visual selected by the user in
a command line option.
.PP
Because the window size equals the source size times the magnification, you
only need to specify two of the three parameters.  This can be confusing.
.PP
Being able to drag the pointer around and see a dynamic display
would be very nice.
.PP
Another possible interface would be for the user to drag out the desired
area to be enlarged.
.SH COPYRIGHT
.PP
Copyright 1988, Massachusetts Institute of Technology.
.PP
MultiVisual code: Copyright 1990, 1997, Oracle and/or its affiliates. All rights reserved.
.SH AUTHOR
.PP
Jim Fulton, MIT X Consortium
.PP
MultiVisual code: Milind Pansare, Sun Microsystems, Inc.