Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XGRABSC(1X)							   XGRABSC(1X)

NAME
       xgrabsc - grab rectangular screen images	and store in files

SYNOPSIS
       xgrabsc	[-d display]  [-id windowId]  [-colorwin windowId] [-o output-
	       File] [-s seconds] [-post seconds] [-b percent]	[-and andBits]
	       [-or orBits]   [-page widthxheight-hmarg-vmarg]	 [-bell	 -grab
	       -verbose	-borders -frame	-key  -stretch	-root  -click  -coords
	       widthxheight+x+y	-offset	widthxheight+x+y
	       -reverse	-bw -mdither -dither -halftone
	       -ps -cps	-simple	-xwd -ppm -xwdxy -bm -bm2 -bm3 -puzzle
	       -bin -comp -eps -l -limit -preview -prev	-previewonly -colproc]

DESCRIPTION
       xgrabsc lets you	grab arbitrary rectangular images from an X server and
       writes them to standard output in a variety of formats.

       Command line options also allow reduction of colormaps, halftoning  and
       dithering  of color images, and direct mapping of color images to mono-
       chrome.

       Options must be seperated with spaces or	tabs.  They  may  be  preceded
       with a dash, but	this optional and provided for Un*x addicts.  Many may
       also be prefixed	with 'no', or an additional dash, to turn them off.

       The default output format is  gray-scale	 non-encapsulated  Postscript,
       with  image compression (if image compression significantly reduces the
       amount of output).

       If you desire an	output format not produced by xgrabsc, try  using  the
       PBM  package  by	 Jef Poskanzer to convert xgrabsc to that format.  PBM
       can read	xgrabsc's PPM and XWD output formats and convert them to a lot
       of different formats.

GENERAL	OPTIONS
       -d displayName or -display displayName
	       Use  an	alternate  display.  If	no display is specified	on the
	       command line, xgrabsc looks for the environment	variable  DIS-
	       PLAY for	the name of the	display	and screen to grab from.  Note
	       that you	must have permission to	access the display on  another
	       computer.

       -bell   The  display's  bell is normally	rung while the screen is being
	       accessed.  This turns the bell on or off	(-nobell will turn  it
	       off).

       -grab   Enable  server  grabs.  Normally	xgrabsc	will "grab" the	server
	       so that the screen is frozen while a rectangle is selected  and
	       the  image  is extracted.  If the screen	is not frozen, rubber-
	       banding may cause video droppings on  portions  of  the	screen
	       that are	changing.  Use -nograb to turn off server grabs.
	       Server  grabs  are  automatically disabled if verbose output is
	       requested to avoid freezing up the system.

       -o output-file or -output output-file
	       Write output to output-file instead of  standard	 output.   The
	       output-file name, minus directory and extension,	is used	as the
	       internal	name for the image in formats supporting image	names.
	       Postscript,  xwd,  pixmap  and bitmap formats all support image
	       names.

       -s seconds or -sleep seconds
	       Sleep for seconds seconds before	 commencing  operation.	  This
	       should  be  used	 if you	need some time to get the target image
	       ready.

       -post seconds
	       Sleep for seconds  seconds  after  window/rectangle  selection.
	       This  is	 commonly used to pop up menus after a window has been
	       selected	but before xgrabsc takes its snapshot.

       -verbose
	       Display	processing  information	 on  standard	error	output
	       (stderr).

SELECTION OPTIONS
       -id window ID
	      Dump  the	 window	with the given ID.  ID numbers can be in deci-
	      mal, or hexidecimal (prefixed with "0x").	 The name of a	window
	      can  be given instead of an ID number, and xgrabsc will look for
	      the first	window with that name.

       -key   Select the window	under  the  mouse  when	 the  Control  key  is
	      pressed.	 This  option  is  normally  used in getting images of
	      menus.  Pop up the menu, optionally move the pointer to the win-
	      dow containing the menu, and strike the Control key to begin the
	      dump.

       -root  Dump the entire screen (root window).

       -stretch
	      Use rubber-band rectangle	to select region to grab.  This	is the
	      default.

       -click Wait for a click on a window and dump the	selected window.

       -coords widthxheight+x+y
	      Selects  the given area of the screen, without mouse or keyboard
	      interaction.  Use	this if	you need to grab the same area of  the
	      screen  over and over again.  Standard X coordinate notation can
	      be used, but a width and height must be given.

       -coords widthxheight+x+y
	      Offsets the area to be grabbed by	x@y  and  changes  the	area's
	      width  and  height  to  widthxheight.  Using this	you can	grab a
	      sub-area of the source area, or even grab	an  area  adjacent  to
	      the source area.

IMAGE PROCESSING OPTIONS
       -nobdrs or -noborders
	      Remove  window  borders from window images.  This	option applies
	      only to selection	by ID (-id) or xwd-style selection (-click).
	      Note that	Motif-style window frames are not window borders.   To
	      remove these you should use the -noframe option.	The xgrab win-
	      dow interface's Include Borders option removes both  frames  and
	      borders.

       -bdrs or	-borders
	      Include  window-manager  borders	in window images.  This	option
	      applies only to selection	by ID  (-id)  or  xwd-style  selection
	      (-click).	 Use -nobdrs or	-noborders to turn it off.

       -b percent or -brighten percent
	      brighten	or darken the image by percent.	 Percentages are given
	      as integers. 100 is the base and a larger	number	will  brighten
	      the image	while a	smaller	number will darken the image.

       -and andBits
	      Clear all	colormap bits up to the	given plane.  This has the ef-
	      fect of darkening	the image somewhat and shrinking the  apparent
	      depth of the image (and, consequently, the size of the color ta-
	      ble).  AndBits should be in the range [1-8] inclusive.

       -or orBits
	      Set all colormap bits up to the given plane.  This brightens the
	      image somewhat and also shrinks the apparent depth of the	image.
	      When both	-A and -O are specified, ANDing	will occur before  OR-
	      ing.

       -reverse
	      Reverse the colors in the	image.	The bits of each color used in
	      the image	are inverted.

       -bw    Convert the source color image to	a monochrome bitmap.  All col-
	      ors  falling  below  the	average	 color intensity are mapped to
	      black.  Others are mapped	to white.

       -halftone
	      Convert the source color image to	a halftoned monchrome  bitmap.
	      Resolution  is maintained	by increasing the size of the image by
	      a	factor of four on both axes.

       -mdither
	      Convert the source color image to	a dithered monochrome  bitmap.
	      This  is	like  halftoning, but resolution is sacrificed to keep
	      the resulting image the same size	as the original.   The	matrix
	      dithering	 algorithm  used with this option is most suitable for
	      line-drawings and	text.  For more	complex	graphics  the  -dither
	      option is	recommended.

       -dither
	      Convert  the  source color image to a dithered monochrome	bitmap
	      with the Floyd-Steinberg algorithm.

       -nodither
	      Turns off	any dithering.	Use this if your  XGRABSC  environment
	      variable specifies dithering and you want	to override it to pro-
	      duce an undithered image.

       -colorWin windowId
	      Specifies	a window id (in	hex) whose colormap should be used for
	      the grabbed image.  Generally xgrabsc will find the correct col-
	      ormap for	your image.  If	you have  lots	of  private  colormaps
	      around  you  may	need to	use this option	to ensure that xgrabsc
	      selects the proper one.
	      ID numbers can be	in  decimal,  or  hexidecimal  (prefixed  with
	      "0x").   The name	of a window can	be given instead of an ID num-
	      ber, and xgrabsc will look for the first window with that	name.

OUTPUT FORMAT OPTIONS
       -cps   Write output in Postscript format	using the colorimage  operator
	      for  color  printers.   Color to grayscale conversion is bundled
	      into the output so you can actually use either color or  cheaper
	      grayscale	 printers.   For  monochrome  displays,	the -ps	option
	      will give	more compact output.

       -ps    Write output in Postscript format	for greyscale  printers.   The
	      number  of bits per Postscript sample is determined by the depth
	      of the image.

       -ppm   Write output in Portable Bitmap format.  Unix image viewers such
	      as  xv  and ImageMagick can accept this format, and the Portable
	      Bitmap package can convert this to many other image formats.

       -xwd   Write output in xwd format.  Use this if you want	to convert  to
	      another output format with Pbm+.

       Write output in xwd -xy format.	This is	like xwd, but allows black and
	      white images to be written with eight pixels per byte instead of
	      the default one pixel per	byte.  While xwud and xpr will	handle
	      this format, some	programs will not.

       -bm    Write  the  output  in X Bitmap format if	the image is black and
	      white, or	X Pixmap format	if the image is	gray or	color.

       -bm2   Write the	output in X Bitmap format if the image	is  black  and
	      white, or	X Pixmap format	2 if the image is gray or color.  -bm3
	      Write the	output in X Bitmap format if the image	is  black  and
	      white, or	X Pixmap format	3 if the image is gray or color.

       -puzzle
	      Write  output  in	 a format suitable for loading into the	puzzle
	      program (see example below).

POSTSCRIPT OPTIONS
       -compress
	      Enable or	suppress Postscript image run-length encoding.	 Post-
	      script  output  is  normally  compressed to minimize the size of
	      output.  If your printer can't  handle  compressed  output,  you
	      should use -nocompress to	turn off compression.

       -eps   Create Encapsulated Postscript output, rather than normal	stand-
	      alone Postscript.	 This adds EPSF	header	comments  and  removes
	      all scaling and translation of the image.

       -l or -landscape
	      Use  landscape layout (with page width and height	exchanged) for
	      Postscript output.  This option is ignored if Encapsulated Post-
	      script  output  is requested.  Width and height may be specified
	      with the -page option.

       -bin   Write Postscript output in binary	rather than using  hexidecimal
	      encoding.	  This	causes	the image portion of the output	to use
	      half as much space, decreasing transmission time to the printer.
	      Note  that  not all print	spoolers can handle 8 bit binary data,
	      so this may not work on your system!

       -limit For Postscript output, check printer memory availability	before
	      attempting  to print an image (the code to perform the checks is
	      integrated into the output of xgrabsc).  This is turned  off  if
	      Encapsulated Postscript output is	requested, and may be disabled
	      completely when building the xgrabsc program.   On  the  command
	      line it may be turned off	with -nolimit.

       -preview	or -prev
	      Selects  Encapsulated Postscript output with an EPSI preview im-
	      age in its header.  The preview image, if	necessary, is dithered
	      to  black	and white either with a	default	dithering algorithm or
	      one you specify on the command line (e.g., -mdither).   Programs
	      such as Frame use	preview	images to display the postscript image
	      during editing sessions.	If you don't  have  a  preview	image,
	      Frame  will  display a blank rectangle.  The image will print OK
	      but you won't see	it while editing.

       -previewonly
	      Like -preview but	writes only the	preview	portion, not the post-
	      script  image.  This may be used to add the preview to an	exist-
	      ing EPS file after having	displayed it using a PostScript	inter-
	      preter.

       -page widthxheight-marginWidth-marginHeight
	      Sets the size of the paper and the borders you desire around the
	      edge of the paper.  Xgrabsc will reduce the image	 if  necessary
	      to  keep	it  within  the	borders	you specify.  The default page
	      size and margins are set when xgrabsc  is	 built.	  Measurements
	      are in inches (e.g., 8.5x11.0-0.5-0.5)

PROCESSING ORDER
       It  is helpful to know the order	of processing when multiple processing
       options are given on the	command	line.

       Processing is done in five phases:  1) set  up,	2)  obtain  image,  3)
       process	colors,	4) poly->monochrome conversions, and 5)	output conver-
       sion.

       The set-up phase	includes processing  command-line  options,  sleeping,
       connecting to X-Windows,	freezing the screen, and grabbing the mouse if
       necessary.

       If the mouse is grabbed for rubber-banding, an upper-left-corner	cursor
       is displayed until the left mouse button	is pressed.  A lower-left-cor-
       ner cursor is then displayed while drawing rubber-rectangles until  the
       mouse button is released.

       If  the	mouse  is grabbed for xwd-style	window selection, an xwd-style
       cursor is displayed until the left mouse	button is pressed.

       The mouse is then released.

       The bell	is then	run and	the image is pulled from the screen.

       Following the image-grab, the bell is run twice and the screen  is  re-
       leased.

       If  the	image  is not monochrome, the color manipulation functions are
       then applied in this order: brighten, AND, and OR, reverse.

       Only one	polychrome to monochrome conversion is allowed.	  If  none  of
       these is	chosen,	the color table	of a polychrome	image is compressed in
       preparation for output conversion.

       The output stream is then opened	and the	image is written  in  the  se-
       lected output format.

ENVIRONMENT
       XGRABSC - specifies command line	arguments to be	processed before those
       actually	entered	on the command line.

       DISPLAY - specifies the name of the display that	 xgrabsc  should  grab
       from.

EXAMPLES
       The simplest form of use, giving	Postscript output, is

	    xgrabsc >outfile.ps

       To write	output in Postscript format and	send to	the printer, use

	    xgrabsc | lpr

       It is sometimes helpful to brighten an image somewhat before it is for-
       matted for Postscript output.  E.g., to brighten	by 30%

	    xgrabsc -b 130 | lpr

       If your printer supports	color, and your	display	is color, you can have
       xgrabsc generate	color output instead of	gray scale:

	    xgrabsc -cps | lpr

       The  default  Postscript	 output	attempts to scale the image so that it
       will all	fit on one page, and is	centered on  the  page.	  If  you  are
       grabbing	 images	 to include in documents, such as with FrameMaker, you
       should ask for Encapsulated Postscript output  with  the	 -eps  switch.
       For example:

	      xgrabsc -eps -o image1.eps

       To select an entire window, write output	in puzzle format and read into
       the puzzle program, use the commands

	    xgrabsc -click -puzzle >outfile.pzl
	    puzzle -picture outfile.pzl

       To have xgrabsc sleep for three seconds before rubber-banding,  display
       processing information, and have	the result displayed with xwud,

	    xgrabsc -xwd -verbose -s 3 | xwud

       To  grab	 an  image from	another	server and then	reduce the colormap to
       three bits by ANDing, use

	    xgrabsc -d other:0.0 -and 5	-bm >outfile.xpm

       You will, of course, have to go to the other machine to select the  im-
       age with	that machine's mouse.

       If  you	know  the name or ID number of the window you want to snapshot
       you can direct xgrabsc to that window on	the command  line.   Utilities
       like  xlswins  or xwininfo can be used to find the names	and ID numbers
       of windows.

       To grab an mpegplay image and display it	in xwud, use
	    xgrabsc -xwd -id "MPEG Play" | xwud

       You can also specify a sub-region to grab, as in
	    xgrabsc -xwd -id "MPEG Play" -offset 100x100+10+10 | xwud

       Grabbing	an area	with the /fI-coords/fP option will use the  root  win-
       dow's  colormap unless you specify an alternate window to use for color
       processing.  If your display allows more	than one colormap  to  be  in-
       stalled	at  once and you are displaying	an mpeg	video that uses	a pri-
       vate colormap, your output using	the  /fI-coords/fP  command  would  be
       technicolor  without  a /fI-colorwin/fP option specifying the mpeg win-
       dow.  E.g.,
	    xgrabsc -xwd -coords 300x300+10+10 -colorwin "MPEG Play" | xwud

LIMITATIONS
       Colormaps larger	than 256 entries are  not  currently  supported.  This
       means that it won't work	with your fancy	24-bit display.

       The default screen visual is used as the	visual for the image.  Visuals
       are associated with particular windows, and xgrabsc pretends  ignorance
       about any windows but the root.

       This  software  has been	tested with StaticGray and 8-plane PseudoColor
       on DECStations (using both UWS 2.2 and X11 Release  4).	 It  has  also
       been  tested  with 8-plane PseudoColor on Sun SparcStations and various
       other platforms using X11 Release 4 and Release 5.

       X11 Pixmap format is rather verbose.  You may want to run large	images
       through the compress utility before storing them	in a file.  E.g.,

	    xgrabsc -bm	| compress >outfile.xpm.Z

AUTHOR
	    Bruce Schuchardt
	   GemStone Systems, Inc.
	     bruce@slc.com

ACKNOWLEGEMENTS
       Some of the source code for xgrabsc came	from the xloadimage project by
       Jim Frost (jimf@saber.com) and others.  Jim's copyright	has  been  in-
       cluded both here	and in the source code.

       The  idea for using run-length encoding for Postscript output came from
       the xwd2ps project by Robert Tatar and Craig A. McGowan.

       The ad2c.sed script that	makes it possible to let you run xgrab without
       installing XGrab.ad everywhere is part of the ad2c package developed by
       George Ferguson.

CONTRIBUTORS
       Yves Arrouye wrote the EPS Preview and page-configuration enhancements.

COPYRIGHT
       Copyright (c) 1990-93 Bruce Schuchardt

       Xgrabsc is copywritten material with a very  loose  copyright  allowing
       unlimited  modification	and  distribution if the copyright notices are
       left intact.  Various portions are copywritten by various  people,  but
       all  use	 a modification	of the MIT copyright notice.  Please check the
       cpyright.h for complete copyright information.  The intent is  to  keep
       the  source free, not to	stifle its distribution, so please write to me
       if you have any questions.

       THE AUTHOR DISCLAIMS ALL	WARRANTIES WITH	REGARD TO THIS	SOFTWARE,  IN-
       CLUDING	ALL  IMPLIED  WARRANTIES OF MERCHANTABILITY AND	FITNESS, IN NO
       EVENT SHALL THE AUTHOR BE LIABLE	FOR ANY	SPECIAL,  INDIRECT  OR	CONSE-
       QUENTIAL	 DAMAGES OR ANY	DAMAGES	WHATSOEVER RESULTING FROM LOSS OF USE,
       DATA OR PROFITS,	WHETHER	IN AN ACTION OF	CONTRACT, NEGLIGENCE OR	 OTHER
       TORTIOUS	 ACTION,  ARISING OUT OF OR IN CONNECTION WITH THE USE OR PER-
       FORMANCE	OF THIS	SOFTWARE.

SEE ALSO
       X(1X),  xhost(1),  xwd(1X),   xwud(1X),	 xwd2ps(1X),   xloadimage(1X),
       xpm(1X),	xpr(1X), puzzle(1X), compress(1), uncompress(1), xv(1X)

								   XGRABSC(1X)

NAME | SYNOPSIS | DESCRIPTION | GENERAL OPTIONS | SELECTION OPTIONS | IMAGE PROCESSING OPTIONS | OUTPUT FORMAT OPTIONS | POSTSCRIPT OPTIONS | PROCESSING ORDER | ENVIRONMENT | EXAMPLES | LIMITATIONS | AUTHOR | ACKNOWLEGEMENTS | CONTRIBUTORS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xgrabsc&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help