xieperf - XIE server extension test and demo program


SYNTAX

       xieperf [-option ...]


DESCRIPTION

       The  xieperf  program  is  based  upon R5 x11perf(1) , and
       while not entirely comprehensive in its  coverage  of  the
       XIE  protocol (see BUGS, below), it is intended to be use-
       ful in the evaluation of XIE implementations in the  areas
       of  protocol  adherance and performance.  The xieperf pro-
       gram includes tests which execute  each  of  the  protocol
       requests  and  photoflo elements specified by revision 5.0
       of the XIE protocol. In addition, xieperf provides  a  set
       of  tests  which can be used to validate the detection and
       transmission of XIE protocol request errors, such as  Flo-
       Match, FloValue, and so forth. Finally, xieperf provides a
       customizable demonstration program for XIE.

       A test is made up of three components executed in sequence
       -  an initialization function, a test function, and an end
       function. The initialization function is  responsible  for
       allocating  and  populating  test  resources, such as pho-
       tomaps and LUTs, and for creating a stored photoflo  which
       will  be executed by the test function. The test function,
       in most cases, simply executes the stored photoflo  for  a
       specified  number of repetitions.  The end function, which
       is called following the test function, is  used  primarily
       to  destroy  any non-cachable server resources used by the
       test, and to free any memory which was  dynamically  allo-
       cated by the client. Some tests, such as -modify1, -await,
       -abort, and -redefine, perform additional steps within the
       test function inner loop, as required by the element being
       tested, or in an attempt to make the  test  more  visually
       appealing.

       Evaluating  the  performance of individual XIE elements is
       not as simple as measuring Core X drawing times.  The  XIE
       protocol requires elements to be embedded within photoflos
       in order  to  be  exercised,   and  the  minimum  possible
       photoflo  size is two.  This implies that it is impossible
       to measure performance of a single element in isolation  -
       the  time  it  takes  to run the flo depends on what other
       elements exist in the flo.  Extrapolating performance of a
       single  elment  (or technique) in a flo must be done care-
       fully, on a case-by-case basis,  since in general measured
       element  performance  depends  on  input  image size, data
       type, and other factors,  all of which can  be  influenced
       by  upstream  flo  elements.  Note further that the number
       and type of elements in a flo can  be  influenced  by  the
       visuals available on the display,  so even flo-flo compar-
       isons on machines with different visuals must be done with
       vide the resulting labels file to x11perfcomp(1) to obtain
       correct output. See the x11perfcomp(1) man pages for  more
       details on this.


OPTIONS

       xieperf accepts the options listed below:

       -display host:dpy
                     Specifies which display to use.

       -images <path>
                     Normally,  xieperf  references  image  files
                     located in the directory  ``images'',  which
                     xieperf  assumes  is located in your current
                     directory. If the  ``images''  directory  is
                     not  in  your current directory, or the file
                     has been renamed, use this option to specify
                     its location.

       -timeout <s>  Some tests require the reception of an event
                     such as FloNotify to continue, and may cause
                     xieperf  to  hang should these events not be
                     received. This option  allows  the  user  to
                     specify  a timeout value which, if exceeded,
                     will cause xieperf to give up waiting for an
                     event, and continue on with the next test in
                     sequence.  Should an event timeout, a  warn-
                     ing  message  will be printed to stderr. The
                     default timeout value is 60 seconds.

       -sync         Runs the tests in synchronous mode.

       -script <file>
                     Using this option gives the user the ability
                     to  run  a subset of the available tests and
                     control the number of times  the  tests  are
                     executed  on  an  individual  basis. This is
                     thought to be especially  useful  for  those
                     running  xieperf for demonstration purposes.
                     Using this option  causes  xieperf  to  read
                     commands specified in a script file, or from
                     stdin if <file> is ``-''. Tests  are  speci-
                     fied  by  newline-terminated  input lines of
                     the form "command [-reps n ] [ -repeat m ]".
                     Characters  following  and including "#" are
                     treated  as  comments.  See  the   -mkscript
                     option.

       -repeat <n>   Repeats  each  test n times (by default each
                     test is run 2 times).  This  option  may  be
                     used in script files also, in which case the
                     script file -repeat  overrides  the  command

       -StaticGray   Use  a  StaticGray  visual  (default  is the
                     default visual).

       -StaticColor  Use a StaticColor  visual  (default  is  the
                     default visual).

       -TrueColor    Use  a  TrueColor  visual  (default  is  the
                     default visual).

       -DirectColor  Use a DirectColor  visual  (default  is  the
                     default visual).

       -WMSafe       If  xieperf  must be run in a window manager
                     environment, use this flag to  make  xieperf
                     aware  of  this.  If specified, xieperf will
                     create a window, identical to  the  size  of
                     the  root  window,  and  all further windows
                     created by xieperf will be  transient  popup
                     children  of  this  window.  If this flag is
                     omitted,  xieperf   will   set   the   over-
                     ride_redirect  attribute  of  all windows to
                     ``True'' and will also do evil  things  such
                     as  calling  XInstallColormap.   Using  this
                     option will  cause  the  window  manager  to
                     (hopefully) obey window geometry hints spec-
                     ified by xieperf

       -showtechs    Display a comprehensive list of  techniques,
                     by  category,  indicating which of the tech-
                     niques are supported by the XIE server.

       -showlabels   Print test label to screen prior to  calling
                     any  of  the test code. This allows the user
                     to know which test is executing in case  the
                     test hangs for some reason.

       -showevents   Be  verbose  when  running  event  and error
                     tests. Also, can be used to catch  and  dis-
                     play  information  on  any  signals received
                     during execution of xieperf that  the  error
                     events  received  by  xieperf  are valid the
                     first time the tests are executed on  a  new
                     platform.

       -events       Run tests which test for event generation.

       -errors       Run tests which test for error event genera-
                     tion.

       -loCal        Skip test calibration. This may be used when
                     running  xieperf  in situations where execu-
                     is normally displayed in  the  usage  state-
                     ment.  It  was  yanked  from  the  usage  of
                     xieperf because it was too lengthy.

       -mkscript     Generate a script file suitable for use with
                     the  script  option. If -repeat or -reps are
                     also specified, they will  be  automatically
                     placed  at  the  end  of each command in the
                     script. The script is generated  to  stderr.
                     See the -script command, above.

       -cache <n>    Most  test  flos utilize a photomap resource
                     for a source.  A photomap cache of up  to  n
                     entries  is  controlled  by xieperf to avoid
                     having to  constantly  reload  these  images
                     during  test  initialization.   The  default
                     cache size is 4. If a value  less  than  the
                     default is specified, the cache size will be
                     set to the default.

       -labels       Generates just the  descriptive  labels  for
                     each  test  specified. Use -all or -range to
                     specify  which  tests  are   included.   See
                     x11perfcomp(1) for more details.

       -DIS          Pretend  we  are  running xieperf while con-
                     nected to a DIS-only capable  implementation
                     of  XIE.  This will cause xieperf to execute
                     those tests which only use protocol requests
                     found  in  the DIS subset of XIE, and bypass
                     those  which  are  not  DIS  compatible.  If
                     xieperf  detects  a  DIS  server, it will do
                     this  automatically,  and  this  option   is
                     ignored.   Use -all or -range to specify the
                     initial range of tests.

       -range <test1>[,<test2>]
                     Runs all the tests starting from the  speci-
                     fied   name  test1  until  the  name  test2,
                     including both  the  specified  tests.  Some
                     tests,  like the event and error tests, also
                     require the -errors or  -events  options  to
                     specified.  This  option  is  ignored  if  a
                     script it used.

       -reps <n>     Fix the inner loop repetitions  to  n.  This
                     indicates how many time the photoflo will be
                     executed each time the  test  is  run.  This
                     option  is overridden on a per-test basis if
                     specified in a  script.  Typically,  xieperf
                     determines  the  ideal number of reps during
                     each test's calibration period.

       -ROI          Create and destroy ROI resource test.

       -Photospace   Create and destroy Photospace test.

       -Photoflo     Create and destroy Photoflo test.

       -QueryPhotomap
                     Query Photomap resource test.

       -QueryColorList
                     Query ColorList resource test.

       -QueryTechniquesDefault through -QueryTechniquesWhiteAd-
                     just
                     Query techniques as specified by test  name.

       -QueryPhotoflo
                     Query photoflo test.

       -PurgeColorList
                     PurgeColorList test.

       -Abort        This  tests  creates  a  photoflo  which  is
                     started and blocks for data provided by Put-
                     ClientData().  Instead  of sending the data,
                     the  test  uses  XieAbort()  to   stop   the
                     photoflo,  and  then  waits for PhotofloDone
                     event to be send by the server. If the  test
                     times  out  waiting  for  the event, a error
                     message is sent to stderr.

       -Await        This test creates a flo of the form  Import-
                     ClientLUT  ->  ExportLUT, and starts the flo
                     executing.   xieperf  then  forks,  and  the
                     child  process  streams  the LUT data to the
                     flo using PutClientData,  while  the  parent
                     blocks  in XieAwait. If the flo successfully
                     finishes, XieAwait will return and  the  flo
                     state,  after  query,  will indicate that it
                     has completed. If XieAwait does not complete
                     naturally, or after return from XieAwait the
                     flo is still active, an error is reported to
                     stderr.  Note,  on a really slow machine, it
                     is possible that XieAwait will return before
                     the  flo  has  a  chance  to finish. In this
                     case, use the -timeout  option  to  increase
                     the timeout for this test.

       -importclientlut1
                     ImportClientLUT -> ExportLUT test.

       -importclientphoto1 through -importclientphoto9
                     e.g. G32D, TIFF2, UncompressedTriple, and so
                     forth.   Original  encoding is shown in left
                     window, image after  encoding  is  shown  in
                     right window.

       -encodeclientphoto1 through -encodeclientphoto11
                     Two  flos, one of the form ImportPhotomap ->
                     ExportClientPhoto, and the other of the form
                     ImportClientPhoto  ->  ExportPhotomap, where
                     ExportClientPhoto in the first flo uses var-
                     ious  encode  techniques,  e.g. G32D, TIFF2,
                     UncompressedTriple, and so forth. The  image
                     before  encoding  is  displayed  in the left
                     window, while the  right  window  shows  the
                     image which was encoded in the first flo and
                     read back in the second flo.

       -exportclientlut1
                     ExportClientLUT test. LUT is displayed in  a
                     histogram window.

       -exportclientroi1
                     ExportClientROI  test,  10  ROIs.  The  ROIs
                     which are sent to the server are represented
                     by the filled rectangles. The ROIs which are
                     received back from the server by the  client
                     are drawn as white bordered non-filled rect-
                     angles.  The  resulting  output  illustrates
                     how  the server combined the rectangles sent
                     to it.

       -exportclientroi2
                     Same as exportclientroi1, except  using  100
                     rectangles.

       -exportclienthistogram1 through -exportclienthistogram4
                     ExportClientHistogram  tests  using  various
                     images. The histogram is displayed in a win-
                     dow which overlaps the image.

       -exportclienthistogramroi1 through -exportclienthistogram-
                     roi4
                     Same as the ExportClientHistogram test,  but
                     using  a  ROI to identify the area of inter-
                     est.

       -exportclienthistogramcplane1  through   -exportclienthis-
                     togramc- plane4
                     Same as the ExportClientHistogram test,  but
                     using  a  Control Plane to identify the area
                     of interest.

       -importdrawable1
                     ImportDrawable -> ExportDrawable, Source  is
                     pixmap, destination is window.

       -importdrawable2
                     ImportDrawable -> ExportDrawable, Source and
                     destination is window.

       -importdrawable3
                     ImportDrawable ->  ExportDrawable,  Destina-
                     tion window obscured by source window.

       -importdrawable4
                     ImportDrawable   ->  ExportDrawable,  Source
                     window obscured by destination window.

       -importdrawable5
                     ImportDrawablePlane ->  ExportDrawablePlane,
                     pixmap, source = destination.

       -importdrawable6
                     ImportDrawablePlane  -> ExportDrawablePlane,
                     window, source = destination.

       -importdrawable7
                     ImportDrawablePlane ->  ExportDrawablePlane,
                     window, source obscures destination.

       -importdrawable8
                     ImportDrawablePlane  -> ExportDrawablePlane,
                     window, destination obscures source.

       -constrain1   Constrain HardClip technique test,  drawable
                     destination.

       -constrain2   Constrain ClipScale technique test, drawable
                     destination.

       -constrainphoto1
                     Constrain HardClip technique test,  photomap
                     destination.

       -constrainphoto2
                     Constrain ClipScale technique test, photomap
                     destination.

       -convolve1    Boxcar 3x3 convolution  test.  Smoothing  or
                     lowpass filter.

       -convolve2    Boxcar  5x5  convolution  test. Smoothing or
                     lowpass filter.

       -convolvecplane2
                     LaPlacian 5x5 convolution test, with Control
                     Plane.

       -math1 through -mathcplane7
                     Various tests which exercise the  Math  ele-
                     ment,  some  tests  using  ROIs  and control
                     planes.

       -arithmeticdyadic1 through -arithmeticdyadic5
                     Arithmetic element tests, using photomaps as
                     the operands.

       -arithmeticmonadic1 through -arithmeticmonadic9
                     Arithmetic  element tests, photomap and con-
                     stant operands.

       -arithmeticdyadicroi1 through -arithmeticdyadicroi5
                     Arithmetic element tests, using photomaps as
                     the operands, with ROIs.

       -arithmeticmonadicroi1 through -arithmeticmonadicroi9
                     Arithmetic  element tests, photomap and con-
                     stant operands, with ROIs.

       -arithmeticdyadiccplane1 through -arithmeticdyadiccplane5
                     Arithmetic element tests, using photomaps as
                     the operands, with Control Planes.

       -arithmeticmonadiccplane1 through -arithmeticmonadicc-
                     plane9
                     Arithmetic element tests, photomap and  con-
                     stant operands, with Control Planes.

       -arithmeticfloatdyadic1 though -arithmeticfloatdyadic5
                     Arithmetic element tests, using photomaps as
                     the operands, unconstrained.

       -arithmeticfloatmonadic1 though -arithmeticfloatmonadic9
                     Arithmetic element tests, photomap and  con-
                     stant operands, unconstrained.

       -arithmeticroifloatdyadic1 to -arithmeticroifloatdyadic5
                     Arithmetic  element  tests, photomaps as the
                     operands, ROIs, unconstrained.

       -arithmeticroifloatmonadic1 to -...rithmeticroifloat-
                     monadic9
                     Arithmetic  element tests, photomap and con-
                     stant operands, ROIs, unconstrained.

       -band1        BandSelect  element  test.  Image  input  is
                     ExportDrawable. CCIR 601-1 coefficients.

       -band3        BandExtract  test.  Input  is  a triple band
                     photomap. CCIR 601-1 coefficients.  Destina-
                     tion window colormap is gray ramp.

       -band4        BandExtract  test.  Input  is  a triple band
                     photomap. CCIR 601-1 coefficients.  Destina-
                     tion  window  colormap is RGB_BEST_MAP stan-
                     dard colormap.

       -band5        BandExtract test. Input  is  a  triple  band
                     photomap. CCIR 601-1 coefficients.  Destina-
                     tion  window  colormap  is   RGB_DEFAULT_MAP
                     standard colormap.

       -comparedyadic1 through -comparedyadic6
                     Test  various  Compare operators with dyadic
                     photomap operands.

       -comparemonadic1 through -comparemonadic6
                     Test various  compare  operators  with  pho-
                     tomap, constant operands.

       -compareroidyadic1 through -compareroidyadic6
                     Test  various  Compare operators with dyadic
                     photomap operands, using ROIs.

       -compareroimonadic1 through -compareroimonadic6
                     Test various  compare  operators  with  pho-
                     tomap, constant operands, using ROIs.

       -comparecplanedyadic1 through -comparecplanedyadic6
                     Test  various  Compare operators with dyadic
                     photomap operands, Control Planes.

       -comparecplanemonadic1 through -comparecplanemonadic6
                     Test various  compare  operators  with  pho-
                     tomap, constant operands, Control Planes.

       -matchhistogram1 through -matchhistogram18
                     MatchHistogram  element tests, using various
                     images and histogram matching techniques.

       -matchhistogramroi1 through -matchhistogramroi6
                     A selection of MatchHistogram element tests,
                     with ROIs.

       -matchhistogramcplane1 through -matchhistogramcplane6
                     A selection of MatchHistogram element tests,
                     with Control Planes.

                     scales, and mirroring.  AntiAlias technique.

       -geometry29 through -geometry42
                     Geometry element tests, including rotations,
                     scales, and  mirroring.   BilinearInterpola-
                     tion technique.

       -geomg31dscale1 through -geometryfaxradio1
                     Tests  to  exercise the various FAX decoders
                     and the Geometry element.

       -dither1      Dither  test,  ErrorDiffusion  dither  tech-
                     nique, ExportDrawable.

       -dither2      Dither  test,  ErrorDiffusion  dither  tech-
                     nique, ExportDrawablePlane.

       -dither3      Dither test,  Ordered(4)  dither  technique,
                     ExportDrawable.

       -dither4      Dither  test,  Ordered(4)  dither technique,
                     ExportDrawablePlane.

       -dither5      Dither test,  Ordered(8)  dither  technique,
                     ExportDrawable.

       -dither6      Dither  test,  Ordered(8)  dither technique,
                     ExportDrawablePlane.

       -dither7      Dither  test,  Default   dither   technique,
                     ExportDrawable.

       -dither8      Dither   test,   Default  dither  technique,
                     ExportDrawablePlane.

       -logicalmonadic1 through -logicalmonadic16
                     Logical element, photomap and a constant  of
                     0 as operands, various operators.

       -logicaldyadic1 through -logicaldyadic16
                     Logical  element  tests, dyadic photomaps as
                     operands, various operators.

       -logicalmonadicroi1 through -logicalmonadicroi16
                     Logical element, photomap and constant of  0
                     operands, various operators, ROIs.

       -logicaldyadicroi1 through -logicaldyadicroi16
                     Logical   element,   dyadic   photomaps   as
                     operands, various operators, ROIs.

       -logicalmonadiccplane1 through -logicalmonadiccplane16
                     stant. Alpha constant of 0.5. ROIs.

       -blendroi2    Blend  element  test.  Dyadic sources. Alpha
                     constant of 0.5. Uses ROIs.

       -blendcplane1 Blend test. Monadic source, 0.1 source  con-
                     stant. Alpha constant of 0.5. Control Plane.

       -blendcplane2 Blend element test.  Dyadic  sources.  Alpha
                     constant of 0.5. Control Plane.

       -blendalpha1  Blend  test. Monadic source, 220 source con-
                     stant. Alpha plane is a photomap.

       -blendalpha2  Blend test. Dyadic sources. Alpha plane is a
                     constant 220.

       -blendalpharoi1
                     Blend  test. Monadic source, 220 source con-
                     stant. Alpha plane photomap. ROIs.

       -blendalpharoi2
                     Blend test. Dyadic sources. Alpha plane is a
                     constant 220. ROIs.

       -triplepoint1 through -triplepoint2
                     Illustrate  use  of  point and Standard col-
                     ormaps for rendering triple band images.

       -funnyencode1 through -funnyencode8
                     These tests are design  to  perform  limited
                     exercising  of  XIE's  capability of dealing
                     with various encodings of flo  source  data.
                     The  test  init  function obtains a photomap
                     using ICP -> EP.  A  series  of  independent
                     permanent  flo  pairs, one of the form IP ->
                     EP, and the other of the basic  form  IP  ->
                     ED, are constructed. The encoding parameters
                     for the ExportPhotomap (EP) element  in  the
                     first  flo  are derived from test configura-
                     tion. The number of  flo  pairs  created  is
                     also  dependent upon test configuration. The
                     tests can be configured  so  that  the  test
                     init  function will constrain the input pho-
                     tomap to a specified number of levels, on  a
                     per-band basis, so that word-sized and quad-
                     sized pixels are passed  through  the  flos.
                     Some tests below take advantage of this. See
                     tests.c for test configuration, and hints on
                     how to add similar tests.

       -point1 through -point3
       -pointcplanephoto1
                     Simple  Point element test which uses a Con-
                     trol Plane. Photomap destination.

       -redefine     Two flographs are created which are the same
                     in structure, expect for the x and y offsets
                     specified for the  ExportDrawable  flo  ele-
                     ments.  The  test  init  function  creates a
                     photoflo based upon  one  of  the  two  flo-
                     graphs.  The inner loop of the test function
                     uses  XieRedefinePhotoflo()   to   alternate
                     between  each  of  the  flographs. Make sure
                     that your ineer loop reps are 2  or  greater
                     in  order  to  exercise this test fully (see
                     -reps).

       -modify1      Test XieModifyPhotoflo() by adjust ROI  off-
                     sets and size.

       -modify2      Test XieModifyPhotoflo() by changing the LUT
                     input to a Point element.

       -modify3      Test XieModifyPhotoflo() by changing Export-
                     Drawable x and y offsets.

       -modify4      This  test  creates  a  rather  long  flo of
                     arithmetic elements, each which does nothing
                     more  than  add 1 to a small image. The test
                     init function scales the input photomap. The
                     ExportDrawable  x  and  y offset is modified
                     randomly during each iteration of  the  test
                     function inner loop.

       -modify5      This  test  creates  a  rather  long  flo of
                     arithmetic elements, each which does nothing
                     more than add 1 to a large image.  Each rep,
                     the Geometry and ExportDrawable elements  at
                     the  end  of  the  flo are modifed to crop a
                     small piece of the input into its  appropri-
                     ate place in the larger image.

       -rgb1 through -rgb16
                     These  tests  all  basically  take an Uncom-
                     pressedTriple image as  input,  send  it  to
                     ConvertFromRGB  which  converts the image to
                     some configured colorspace,  and  then  send
                     the converted image on to ConvertToRGB prior
                     to display. The original image is  displayed
                     in  the lefthand window, and the image which
                     has passed through the flo is shown  in  the
                     righthand  window. The goal of these test is
                     to show that ConvertFromRGB ->  ConvertToRGB
                     the resulting image to the right window. The
                     result should be lossless.

       -complex      A  somewhat  large  flo  which  uses control
                     planes, LUTs, Point, PasteUp, Logical,  Con-
                     strain,  Dither,  Geometry,  MatchHistogram,
                     BandCombine, and  BandSelect  elements.  See
                     the  Postscript  file  ''complex.ps''  for a
                     rendition of the photoflo which is executed.


X DEFAULTS

       There are no X defaults used by this program.


SEE ALSO

       X(1), x11perf(1), x11perfcomp(1)


BUGS

       There  should  be a IMAGES environment variable to augment
       the -images option.

       Many tests only  scratch  the  surface  of  possible  test
       cases.  Some of the options available for certain flo ele-
       ments are either inadequately  tested,  or  ignored  alto-
       gether.   There  are  insufficent tests for bitonal, large
       pixel, or triple band tests.

       Some of the test  names  are  inconsistently  cased,  e.g.
       -Abort and -dither1.

       Some  tests  are hopelessly slow when run against machines
       with slow FPUs.

       Bitonal images are for the most part displayed  using  the
       ExportDrawable  flo  element, however, ExportDrawablePlane
       would be a better choice.


AUTHOR

       Syd Logan, AGE Logic, Inc.

X Version 11                Release 6                          13