[0m


GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



[1mNAME
     [0mgbench - graphics benchmark

[1mSYNOPSIS
     gbench [0m[-_c_o_m_m_a_n_d_n_a_m_e [_p_a_r_a_m_e_t_e_r_s]]*

[1mDESCRIPTION
     [0m_g_b_e_n_c_h is a graphics benchmark tool.  It currently supports
     2D immediate-mode graphics and runs on top of the X Window
     System, both Version 10 and Version 11.  It is written in C
     and it directly calls the low-level window system client
     library; no toolkit is used.

     When _g_b_e_n_c_h starts, it creates a window and begins process-
     ing commands.  You may supply any number of commands as
     arguments to the program.	Once these commands have been
     processed, commands are read from standard input, one per
     line.  Each command directs _g_b_e_n_c_h to repeatedly perform a
     particular drawing operation.  _g_b_e_n_c_h copies the command to
     the outfile (default:  standard output), executes the com-
     mand, and prints on the outfile the host load average, the
     time for each iteration, and the number of iterations per
     second.

     All times are measured in real (wall-clock) time.	You
     should establish that the host(s) and network (if used) are
     unloaded so that valid numbers may be obtained.

     When _g_b_e_n_c_h performs a sequence of drawing operations, each
     operation is shifted by one pixel in x and y from the previ-
     ous one.  This shifting goes back and forth over a user-
     definable range (default: 32 pixels), the intent being to
     average out the effects of pixel alignment in the frame
     buffer.  Pixel alignment can affect the performance of many
     graphics systems, both low-end memory-mapped frame buffers
     and high-end systems with interleaved pixel processors.

     You can use _g_b_e_n_c_h either interactively, by typing commands
     and viewing the results immediately, or in batch mode, with
     standard input redirected to a script file and output
     redirected to a log file.	To avoid cluttering up the log
     when output is redirected to a file, certain outputs that
     are only useful in interactive use are directed to standard
     error rather than the outfile.

     [1mCommands

     [0mEach command consists of a command name followed by zero or
     more optional parameters separated by white space.  You may
     abbreviate command names to their smallest unique prefix.
     Ambiguous command names are resolved to the first matching
     name.  Any command name may be prefixed with the @



Printed 29/3/95           1 March 1988				1






GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



     character, which forces all output from the command to stan-
     dard error rather than the outfile.  This is useful for
     preventing selected commands from going into a log file.

     The optional parameters consist of zero or more positional
     parameters of the form _v_a_l_u_e, followed by zero or more key-
     word parameters of the form _n_a_m_e=_v_a_l_u_e.  Each positional
     parameter has a name and may be specified in keyword form as
     well.  The positional form is more convenient for interac-
     tive input, while the keyword form is more suited for creat-
     ing self-documenting script files.

     To provide values for parameters that are not specified in a
     command, _g_b_e_n_c_h maintains a set of global defaults that may
     be displayed and changed using the 'default' command.  Each
     default value has a name and may be overridden in a command
     using a _n_a_m_e=_v_a_l_u_e parameter.  The names of all global
     default values are given below.  The

     The first positional parameter for each command is _o_p_t_s.  It
     is a comma-separated list of option flags, the meanings of
     which are described below.  Option flags may be supplied in
     any order.  If the _o_p_t_s parameter is given in positional
     form, the global default option list is prepended to the
     given list; if it is given in keyword form, the given list
     is used as is, overriding the global default option list.

     The commands are:

     arc [_o_p_t_s] [_s_i_z_e] [_a_s_p_e_c_t] [_a_n_g_l_e] [_l_w_i_d_t_h] [_n_a_m_e=_v_a_l_u_e]*
	  Draws an arc of an ellipse.  The ellipse is drawn in a
	  bounding box with an area of _s_i_z_e squared pixels and a
	  height/width ratio of _a_s_p_e_c_t.  The default value of
	  _a_s_p_e_c_t is 1.0, yielding a circular arc.  The arc begins
	  at the 3 o'clock position and continues counterclock-
	  wise for _a_n_g_l_e degrees.  This command works only in the
	  X11 version.

     blit [_o_p_t_s] [_s_i_z_e] [_o_f_f_s_e_t] [_n_a_m_e=_v_a_l_u_e]*
	  Copies a square area of the window, _s_i_z_e pixels on a
	  side, to an area offset by _o_f_f_s_e_t*_s_i_z_e pixels.  The
	  default value for _o_f_f_s_e_t is 0.5.

     map [_o_p_t_s] [_s_i_z_e] [_n_w_i_n] [_n_a_m_e=_v_a_l_u_e]*
	  Maps and then unmaps _n_w_i_n square subwindows, each _s_i_z_e
	  pixels on a side.

     nop [_o_p_t_s] [_n_a_m_e=_v_a_l_u_e]*
	  Performs a window server no-op.  This command works
	  only in the X11 version.

     point [_o_p_t_s]



Printed 29/3/95           1 March 1988				2






GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



	  Draws a point.  This command works only in the X11 ver-
	  sion.

     poly [_o_p_t_s] [_s_i_z_e] [_n_v_e_r_t] [_l_w_i_d_t_h] [_n_a_m_e=_v_a_l_u_e]*
	  Draws a polygon with the specified number of vertices
	  and linewidth, inscribed in a circle of radius _s_i_z_e
	  pixels.

     rect [_o_p_t_s] [_s_i_z_e] [_l_w_i_d_t_h] [_n_a_m_e=_v_a_l_u_e]*
	  Draws an axis-aligned square, _s_i_z_e pixels on a side,
	  with the specified linewidth.

     text [_o_p_t_s] [_n_c_h_a_r] [_p_t_s_i_z_e] [_n_a_m_e=_v_a_l_u_e]*
	  Draws a text string with the specified number of char-
	  acters, at the specified point size.	The closest
	  available point size is chosen.

     vec [_o_p_t_s] [_s_i_z_e] [_a_n_g_l_e] [_l_w_i_d_t_h] [_n_a_m_e=_v_a_l_u_e]*
	  Draws a vector _s_i_z_e pixels long, with the specified
	  linewidth and angle (given in degrees counterclockwise
	  from the 3 o'clock position).

     config
	  Prints the host name, display name, window system ver-
	  sion, current time, and tag (see below) on the outfile.

     defaults [_n_a_m_e=_v_a_l_u_e]*
	  Prints the defaults on standard error and optionally
	  changes them.  The names of the default values are
	  given below.

     help Prints a help message on the outfile listing the avail-
	  able commands and option flags.

     init Restores all defaults to their initial value, and
	  prints the updated set of values on standard error.

     script [_f_i_l_e_n_a_m_e]
	  Run the given script file, which may itself use the
	  'script' command.  If no file is given, the built-in
	  script is run.

     quit Exits _g_b_e_n_c_h.

     !	  Repeat:  Re-issue the previous drawing command, with
	  parameters defaulting to the values used when that com-
	  mand was executed, rather than to the global default
	  values.  Positional and keyword parameters for the com-
	  mand may be given in the normal manner to override the
	  defaults.  As usual, if the _o_p_t_s parameter is given in
	  positional form, the default option list is prepended
	  to the given list, whereas if it is given in keyword



Printed 29/3/95           1 March 1988				3






GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



	  form, the given list overrides the default option list.

     #	  Comment:  causes _g_b_e_n_c_h to write the rest of the com-
	  mand to the outfile. This is useful for putting com-
	  ments in script files.  After echoing and executing
	  each command, _g_b_e_n_c_h writes a result line to the out-
	  file.  Since each result line begins with the comment
	  character, _g_b_e_n_c_h output logs are also valid _g_b_e_n_c_h
	  input scripts.  You can run a log through _g_b_e_n_c_h
	  several times using different hardware configurations.
	  In the resulting log, each command will be followed by
	  a series of result lines, one for each configuration.

     [1mOptions

     [0mThe option flags are as follows:

     ac      Alternate the drawing color between black and white
	     on each drawing operation.  This measures the effect
	     of changing one element of the graphics state for
	     each drawing operation.

     af      Use a separate text item, with its own font identif-
	     ier, for each character in the 'text' command.  The
	     same font is used for all characters.  This option
	     works only in the X11 version.

     ag      Alternate the graphics context on each drawing
	     operation.  The two graphics contexts used are
	     identical except that one draws with white and the
	     other draws with black.  The ac and ag flags can be
	     used to compare the cost of changing one element of
	     the graphics state with the cost of swapping the
	     entire graphics state.

     aw      Alternate windows on each drawing operation.  This
	     flag makes it possible to measure the performance
	     impact of context-switching between windows.  It is
	     important to keep this overhead low in order to sup-
	     port applications that do real-time drawing in mul-
	     tiple windows simultaneously.

     d	     Dragging.	You are prompted to move the mouse around
	     in the window while holding down a mouse button.
	     Every time a mouse motion event is received, _g_b_e_n_c_h
	     draws a background-color rectangle to erase the
	     results of the previous drawing operations, then
	     performs one drawing iteration.  This option allows
	     you to measure the frame rate that the system can
	     achieve during interactive animation.

     f	     Fill the arc, polygon, or rectangle with a solid



Printed 29/3/95           1 March 1988				4






GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



	     color.

     i	     Draw by inverting pixel values rather than painting.
	     This measures the additional cost of reading pixels
	     from the frame buffer before writing.

     m	     Monitor for profiling.  Profiling information is
	     accumulated while this command is executing.  If
	     _g_b_e_n_c_h has been compiled and linked for _g_p_r_o_f pro-
	     filing, this information is written to the file
	     "gmon.out" in the current directory when _g_b_e_n_c_h
	     exits.

     n	     No options.  If you choose no options and you supply
	     _o_p_t as a positional parameter, you must use the n
	     flag as a placeholder.

     o	     Overlap the object being drawn with a very small
	     window.  The overlapping window is made small to
	     avoid a significant change in the number of pixels
	     drawn.  This measures the cost of clipping.

     os      Use an offscreen pixel map identical in size and
	     depth to the graphics window as the source for
	     blits.  This option works only in the X11 version.

     od      Use an offscreen pixel map identical in size and
	     depth to the graphics window as the destination for
	     drawing operations.  After the command has been com-
	     pleted and timed, the contents of the offscreen
	     pixel map are blitted into the graphics window so
	     correct drawing can be verified.  This option works
	     only in the X11 version.  Together, the os and od
	     options allow you to measure the performance impact
	     of offscreen rendering and the cost of moving pixels
	     to and from offscreen memory.

     p	     Polling.  Used in conjunction with the d flag, this
	     flag specifies that _g_b_e_n_c_h should loop continuously,
	     reading the mouse position and performing a drawing
	     iteration, rather than responding to mouse motion
	     events.  This measures the performance difference
	     between polling and event-driven input.

     ps      Polygon self-intersecting.  Draw a polygon with the
	     same vertices and number of edges as usual, but
	     self-intersecting.  _n_v_e_r_t will be rounded up to an
	     odd number if necessary.

     pw      Fill polygons using the non-zero winding number rule
	     rather than the default even-odd rule.  This option
	     works only in the X11 version.



Printed 29/3/95           1 March 1988				5






GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



     r	     Reset defaults.  Copy the set of parameters used in
	     this command to the set of global defaults.

     s	     Use a stipple pattern when drawing.  The stipple
	     pattern is a bitmap that is tessellated over the
	     drawing area.  When a drawing operation is per-
	     formed, the only pixels that are actually drawn are
	     those inside the shape being drawn that correspond
	     to a '1' in the stipple pattern.  These pixels are
	     drawn in the foreground color.  Stippling is fully
	     supported only in the X11 version.

     t	     Use a tile when drawing.  The tile is a pixel map
	     that is tessellated over the drawing area.  When a
	     drawing operation is performed, the pixel value for
	     each pixel inside the shape being drawn is obtained
	     from the tile.  When the s and t flags are used
	     simultaneously, the stipple pattern is used as a
	     tile, with '0' pixels in the stipple pattern select-
	     ing the background color and '1' pixels selecting
	     the foreground color.  This combination works only
	     in the X11 version.

     u	     Unbatched.  Normally the window system client
	     library will batch many requests into a single mes-
	     sage to the window server in order to minimize com-
	     munication overhead.  This option causes the
	     client's request buffer to be flushed after each
	     operation, thereby preventing batching.  This makes
	     it possible to directly measure the performance
	     benefit of batching.

     [1mGlobal defaults

     [0mThe following global defaults may be displayed and set using
     the 'defaults' command:

     timegoal
	     When a command is executed, _g_b_e_n_c_h should repeat the
	     drawing operation under test enough times to get an
	     accurate measurement of its cost, but not so many
	     times that the command takes an inordinate amount of
	     time to execute.  _g_b_e_n_c_h allows you to specify a
	     time goal, which is the number of seconds that each
	     command should take to execute (default: 1).  _g_b_e_n_c_h
	     performs as many iterations as are necessary to
	     reach this goal.  Setting timegoal to 0 forces
	     _g_b_e_n_c_h to execute a single iteration.

     count   Specifies the number of times to perform the primi-
	     tive drawing operation on _e_a_c_h iteration.	This
	     defines the unit of work being measured.  For



Printed 29/3/95           1 March 1988				6






GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



	     example, to measure the time it takes to draw a
	     1000-polygon object, give the command 'p count=1000'
	     and _g_b_e_n_c_h will repeatedly draw 1000 polygons.  To
	     get the feel of dragging around a 1000-polygon
	     object, give the command 'p d count=1000' and _g_b_e_n_c_h
	     will draw 1000 polygons every time the mouse moves.
	     If you want exact control over the number of drawing
	     operations executed for each command, set _t_i_m_e_g_o_a_l
	     to 0 and set _c_o_u_n_t as desired.

     angle   The angle in degrees used for the 'arc' and 'vec'
	     commands.

     aspect  A floating point value representing the height to
	     width ratio of the bounding box for the 'arc' com-
	     mand.  The default value is 1.0, which yields circu-
	     lar arcs.

     font    A comma-separated list of font names for _g_b_e_n_c_h to
	     load.  In the X11 version, each name may contain the
	     wild-card characters * and ?.  A maximum of 16 fonts
	     may be loaded.

     ptsize  The font size, given in points, used in the 'text'
	     command.

     lwidth  The line width used in the drawing operations.

     maxshift
	     Each drawing operation is shifted by one pixel in x
	     and y from the previous operation.  The shifting
	     goes back and forth over a range of _m_a_x_s_h_i_f_t pixels.

     offset  The 'blit' command multiplies the size of the square
	     being blitted by this floating point value to deter-
	     mine how far to move it.  The default value is 0.5,
	     which causes the destination square to overlap the
	     source square.

     nchar   The length in characters of the string drawn by the
	     'text' command.

     nwin    The number of windows mapped by the 'map' command.

     nvert   The number of vertices drawn by the 'poly' command.

     opts    The option list that is prepended to the option list
	     that is given as the first positional parameter of a
	     command.  It can be used to run scripts (including
	     the built-in script) with different lists of
	     options.




Printed 29/3/95           1 March 1988				7






GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



     outfile The name of the file that output is appended to
	     (default:	standard output).

     size    The size in pixels of the objects drawn by the vari-
	     ous drawing commands.

     tag     An uninterpreted string that is included in the out-
	     put of the 'config' command and at the beginning of
	     each result line.	It is useful for associating each
	     result line with a named configuration when a log
	     file is run through _g_b_e_n_c_h several times to accumu-
	     late result lines for different configurations.  For
	     example:

	     gbench -@d tag=configname <oldlog >newlog

	     Note the use of the '@' on the 'defaults' command to
	     prevent the tag-setting command from going into the
	     log.  A suggested tag format is a quadruple of the
	     form

	     <_r_c_p_u>.<_l_c_p_u>.<_w_s_y_s>.<_g_x_s_y_s>

	     where _r_c_p_u is the type of the remote CPU running
	     _g_b_e_n_c_h (if any), _l_c_p_u is the type of the local CPU
	     running the window server, _w_s_y_s is the name of the
	     window system, and _g_x_s_y_s is the type of graphics
	     hardware being used.  Each of these components can
	     be encoded in two or three characters.

     winsize The edge length (in pixels) of the square drawing
	     window.

[1mVERSION
     [0mThis documentation applies to Version 1.0 of _g_b_e_n_c_h.

[1mBUGS
     [0mThere is apparently a bug in the beta release of the awm
     window manager for X11R2 that causes the "map" command to
     hang _g_b_e_n_c_h.  For this reason, we have removed "map" from
     the default script.  We have not found this problem under
     any of the other X11R2 window managers, including the stan-
     dard uwm.

[1mEXTENSIONS
     [0mDifferent drawable depths should be supported.  3D graphics
     and image processing operations should be supported when
     they become available.  Filters should be written to combine
     and format raw log files.

[1mAUTHOR
     [0m_g_b_e_n_c_h is being developed by Craig Dunwoody and Mark Linton



Printed 29/3/95           1 March 1988				8






GBENCH(1)	   InterViews Reference Manual		GBENCH(1)



     at Stanford University's Computer Systems Lab under the
     Quantum project, through a gift from Digital Equipment Cor-
     poration.

[1mADDRESS
     [0mPlease send any comments, bugfixes, scripts, or results to:

     Internet: gbench@lurch.stanford.edu

     USEnet:   {ucbvax,decvax}!decwrl!lurch.stanford.edu!gbench


[1mCOPYRIGHT
      [0mCopyright (c) 1988 by The Board of Trustees
      of the Leland Stanford Junior University.

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

      Stanford makes no representations about the suitability of
      this software for any purpose.  The Software is provided
     "as is"
      without express or implied warranty.


























Printed 29/3/95           1 March 1988				9



[0m