.TH gr_monitor 1 "Gr_Monitor" "MH" \" -*- nroff -*-
.SH NAME
gr_monitor \- Graphical Process Monitor V0.53
.SH SYNOPSIS
.B gr_monitor
[-host h]  
[-sleep n] 
[-noskip]
[-stdin]   
[-perrow n]
[-gap x]   
[-witdh n] 
[-height n]
[-geometry]
[-angle n] 
[-dolly n] 
[-zoom x]
[-zhorz x]
[-zvert x]
[-color]   
[-nolight] 
[-fog]     
[-onebuf]  
[-rotate]  
[-verbose]
[-v]

.B gr_gather
[-sleep n]
.br
.SH DESCRIPTION
.B Gr_Monitor 
displays information about processes resident on a UNIX system.
For each process it displays a 3D bar graph of CPU consumed, memory
consumed, resident set size,
and elapsed time. The processes are group by username. Each username
grouping sits on its own little plinth. 

This program is also quite useful for hogging CPU.

There are controls for translating, rotating, scaling, lighting and
fog effects.

Gr_monitor consists of two components:
.B gr_monitor
and
.B gr_gather.
Gr_gather gathers data from the
Linux process file system.  Gr_monitor receives this info via a pipe
and displays in in a X11 Mesa or X11 OpenGL window.

Gr_monitor may optionally use rsh to run gr_gather on a remote host.

The gr_monitor input data format is easily understood and could be used
to display other kinds of data without any modification.

Gr_monitor is something I hacked together to learn more about OpenGL,
SGI's open standard for 2D/3D graphics. The whole thing was developed
under Linux using the Mesa OpenGL look-a-like library.

.SS OPTIONS
.TP
.I "-host hostname"
Gr_monitor will use rsh to fire up gr_gather on another host.
Data will be piped back to the local host for display.
.TP
.I "-sleep seconds"
Time to sleep between updates.  The default is 5 seconds
(if you manually invoke gr_gather, it's default
is one second).
A sleep of 0 (zero) will cause gr_monitor to start up halted
(the space bar will single step the display).
.TP
.I "-noskip"
Normally data will be skipped if the renderer can't keep up
with it.  When playing back pre-recorded data via the -stdin option, 
you may need to switch off skipping.
.TP
.I "-stdin"
Take data in gr_gather format from standard input.
.TP
.I "-perrow n"
If a row exceeds this many processes, a new row will be started.
.TP
.I "-gap x"
Space between plinths (a real number).
.TP
.I "-width n"
Display width in pixels.
.TP
.I "-height"
Display height in pixels.
.TP
.I "-geometry "
Normal X11 geometry spec.
.TP
.I "-angle n"
Tilt on X axis in degrees.
.TP
.I "-dolly n"
Distant to translate in the z axis (dolly the camera).
.TP
.I "-zoom x"
Projection zoom factor.
.TP
.I "-zhorz x"
Horizontal zoom factor.
.TP
.I "-zvert n"
Vertical zoom factor.
.TP
.I "-color"
Use own color map.  Colors will look better.  Worth a look.
.TP
.I "-nolight"
Turn off lighting effects.
.TP
.I "-fog"
Turn on fog effects.
.TP
.I "-onebuf"
Use single buffering of the display image.
.TP
.I "-rotate"
Start up rotating.
.TP
.I "-verbose"
or
.I "-v"
Provides some feedback to stderr.  Maximum output is generated
by -verbose.  Alternatively the -v option will only
report skipped data sets due to the monitor 
not being able to keep up with the gatherer, which is
useful when trying to select a good -sleep value.

.SH GR_MONITOR WINDOW

The following controls are available in the gr_monitor
window.  The middle mouse button will bring a keyboard quick reference.
The right mouse button will bring up another small menu duplicating
some of the keyboard functions.  When pressing keys beware of
excessive type-a-head (count your key presses).

Here is a summary of the keys and what they do:

.TP
.I "ESC"
Exits gr_monitor.

.TP
.I "?"
Dump a key summary on stdout.

.TP
.I "p/P"
Increase or decrease the items per row guideline by one (default 12).
Handy if you don't like the layout.

.TP
.I "a/A"
Zoom in or out.

.TP
.I "x/X y/Y z/Z"
Rotation about the specified axis.  
Lowercase +ve rotation.  Uppercase -ve rotation.

.TP
.I "i/I j/J k/K"
Translation along the specified axis (i,j,k implies x,y,z).

.TP
.I "r"
Toggles rotation. 

.TP
.I "0 1 2 3 4 5 6 7 8 9"
Selects a bar type.  Can only select from the first 10 bar types.

.TP
.I "s/S"
Scale selected bar type up or down.  Lowercase = up. Uppercase = down.

.TP
.I "n or N"
Scale selected bar type by 1.0 (i.e. reset scale).

.TP
.I "o or O"
Turn off selected bar type.

.TP
.I "l or L"
Toggle lighting. 

.TP
.I "f or F"
Toggle fog effects.

.TP
.I "h or H"
Halt the display.

.TP
.I "SPACE"
Step one frame through a halted display.

.SH ENVIRONMENT


.B GR_GATHER_COMMAND 
can contain an alternative command to run instead
of gr_gather.

.SH DATA FORMAT

The pipe will contain data sets one after the other, each
data set will contain:
   a title line
   nitems nvalues valuename1 valuename2 valuename3 ...
   item ID
   group ID
   value1 value2 value3 ...

For example:
   Selected processes on sputnik3
   4 3 CPU RSS MEM
   100
   michael
   0.000000 0.043189 0.000000 
   196
   root
   0.166667 0.559287 0.178711 
   250
   michael
   2.083333 1.768806 0.609375 
   275
   michael
   0.000000 0.054172 0.021484 

.SH SEE ALSO

.BR top (1) 
.BR ps (1)

.SH BUGS AND LIMITATIONS

Please send any bug reports to michael@actrix.gen.nz.

This program is an absolute hog.  Gr_Monitor is very slow on a typical
486 with a non-accelerated graphics card (I don't know if an
accelerated card would help).  But it is fun to watch, especially on a
machine where processes or users are coming and going. It is very
useful for spotting hogs and uninhibited growth.

For some reason, in the standard color map mode under Mesa-Linux, the
background clears to white instead of black.

If I knew more about OpenGL it would probably be a better utility.

.SH AUTHOR
Michael Hamilton (michael@actrix.gen.nz)

.SH ACKNOWLEDGEMENTS

Brian Paul (brianp@ssec.wisc.edu) is the author of the The Mesa 3-D
graphics library.

Linux gr_gather is based on 
.B procps top 
by Branko Lankester, Roger Binns, by
Michael K. Johnson.

Gr_monitor is based on a cut up of the GLUT example/scube.c which
rotates a cube above a checker board with shadows, lighting etc.
Thanks to GLUT author Mark J. Kilgard (mjk@sgi.com), scube author
David G Yu.

Thanks are also due to all those people who have made Linux so great.

.SH LICENCE

(c) Copyright 1995, Michael Hamilton.

I don't really know whether I have any rights on this work, but your
rights are restricted by the copyrights on the work on which it is
based (so what ever they say goes for me too):

Gr_gather is covered by the same licence as 
.B procps:
the GNU GENERAL PUBLIC LICENCE.

For gr_monitor you have the same rights as stated in the original SGI
copyright:

(c) Copyright 1993, 1994, Silicon Graphics, Inc.

ALL RIGHTS RESERVED 

Permission to use, copy, modify, and distribute this software for 
any purpose and without fee is hereby granted, provided that the above
copyright notice appear in all copies and that both the copyright notice
and this permission notice appear in supporting documentation, and that 
the name of Silicon Graphics, Inc. not be used in advertising
or publicity pertaining to distribution of the software without specific,
written prior permission. 

THE MATERIAL EMBODIED ON THIS SOFTWARE IS PROVIDED TO YOU "AS-IS"
AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE,
INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.  IN NO EVENT SHALL SILICON
GRAPHICS, INC.  BE LIABLE TO YOU OR ANYONE ELSE FOR ANY DIRECT,
SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY
KIND, OR ANY DAMAGES WHATSOEVER, INCLUDING WITHOUT LIMITATION,
LOSS OF PROFIT, LOSS OF USE, SAVINGS OR REVENUE, OR THE CLAIMS OF
THIRD PARTIES, WHETHER OR NOT SILICON GRAPHICS, INC.  HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSS, HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE
POSSESSION, USE OR PERFORMANCE OF THIS SOFTWARE.
 
US Government Users Restricted Rights 
Use, duplication, or disclosure by the Government is subject to
restrictions set forth in FAR 52.227.19(c)(2) or subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013 and/or in similar or successor
clauses in the FAR or the DOD or NASA FAR Supplement.
Unpublished-- rights reserved under the copyright laws of the
United States.  Contractor/manufacturer is Silicon Graphics,
Inc., 2011 N.  Shoreline Blvd., Mountain View, CA 94039-7311.

OpenGL(TM) is a trademark of Silicon Graphics, Inc.