NAME
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 proto-
col (see BUGS, below), it is intended to be useful in the
evaluation of XIE implementations in the areas of protocol
adherance and performance. The xieperf program includes
tests which execute each of the protocol requests and photo-
flo 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 pro-
tocol request errors, such as FloMatch, FloValue, and so
forth. Finally, xieperf provides a customizable demonstra-
tion 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 photomaps
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 allocated 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 proto-
col 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 carefully, 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 comparisons on machines with different visu-
als must be done with caution.

Many test labels contain an abbreviated pipeline descrip-
tion. For instance. IP/IL/P/ED indicates ImportPhotomap,
ImportLUT, Point, and ExportDrawable. Pipelines ending in ED
(ExportDrawable) often include hidden elements such as Ban-
dExtract, ConvertToIndex, Dither, or Point to match the flo
output to the screen visual. Pipelines ending in EP
(ExportPhotomap) will result in a blank window.

xieperf is compatible with x11perfcomp(1), which is used to
compare the outputs of different xieperf and x11perf runs in
a nice, tabular format. In xieperf you will need to use the
-labels option (see OPTIONS, below), and provide the result-
ing 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 warning
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 exe-
cuted 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 speci-
fied in a script file, or from stdin if <file>
is "-". Tests are specified by newline-
terminated input lines of the form "command
[-reps n ] [ -repeat m ]". Characters follow-
ing 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 line
option.

-time <s> Specifies how long in seconds each test should
be run (default 5 seconds).

-depth <depth>
Use a visual with <depth> planes per pixel
(default is the default visual).

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

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

-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 override_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 speci-
fied by xieperf

-showtechs Display a comprehensive list of techniques, by
category, indicating which of the techniques
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 display infor-
mation on any signals received during execu-
tion 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 execution
timing is not important. Execution times will
not be reported by xieperf when this option is
enabled. The inner loop repeat count, addi-
tionally, is set to a value of 5 (but can be
overridden by the -reps option).

-all Runs all tests. This may take a while, depend-
ing on the speed of your machine, and its
floating point capabilities. This option is
ignored if a script file is used.

-tests Generate a list of the available tests for the
xieperf program. In x11perf , this list is
normally displayed in the usage statement. 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 connected
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 specified
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.

-ImportObscuredEvent through -ExportAvailable
Test generation of events. Requires -events
flag.

-BadValue through -FloValueError
Test generation of errors. Requires -errors
flag. -ColorList Create and destroy ColorList
resource test.

-LUT Create and destroy LUT resource test.

-Photomap Create and destroy Photomap resource test.

-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 -QueryTechniquesWhiteAdjust
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 PutClient-
Data(). 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
ImportClientLUT -> 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
Flos of the form ImportClientPhoto -> Export-
Photomap using various decode techniques, e.g.
G32D, TIFF2, UncompressedTriple, and so forth.

-importclientroi1
ImportClientROI with 10 rectangles.

-importclientroi2
ImportClientROI with 100 rectangles.

-encodephoto1 through -encodephoto14
Flos of the form ImportPhotomap -> ExportPho-
tomap using various encode techniques, 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 vari-
ous encode techniques, e.g. G32D, TIFF2,
UncompressedTriple, and so forth. The image
before encoding is displayed in the left win-
dow, 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 rectangles. 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 window
which overlaps the image.

-exportclienthistogramroi1 through -exportclienthistogramroi4
Same as the ExportClientHistogram test, but
using a ROI to identify the area of interest.

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

-importlut1 Test ImportLUT element, LUT size is 256.

-importphoto1 ImportPhotomap -> ExportPhotomap, with source
and destination equal.

-importphoto2 ImportPhotomap -> ExportDrawable, window des-
tination.

-importroi1 ImportROI -> ExportROI, 10 rectangles, source
and destination ROIs equal.

-importroi2 ImportROI -> ExportROI, 100 rectangles, source
and destination ROIs equal.

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

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

-importdrawable3
ImportDrawable -> ExportDrawable, Destination
window obscured by source window.

-importdrawable4
ImportDrawable -> ExportDrawable, Source win-
dow 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.

-convolve3 LaPlacian 3x3 convolution test. Edge or
highpass filter.

-convolve4 LaPlacian 5x5 convolution test. Edge or
highpass filter.

-convolveroi1 LaPlacian 3x3 convolution test, with ROI.

-convolveroi2 LaPlacian 5x5 convolution test, with ROI.

-convolvecplane1
LaPlacian 3x3 convolution test, with Control
Plane.

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

-math1 through -mathcplane7
Various tests which exercise the Math element,
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 -arithmeticmonadiccplane9
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 -
........rithmeticroifloatmonadic9
Arithmetic element tests, photomap and con-
stant operands, ROIs, unconstrained.

-band1 BandSelect element test. Image input is triple
band. If visual of xieperf window is a color
visual, then three BandSelect elements are
used to extract the indivudual bands, they are
combined once again using BandCombine, and
displayed using ConvertToIndex. If the visual
is not color, e.g. GrayScale or StaticGray,
then the flo simply uses one BandSelect ele-
ment to extract a single band for display.

-band2 BandCombine test. Input bands are made of of
three separate single band photomaps. These
are combined using a BandCombine element,
which is followed by a BandExtract and Export-
Drawable. CCIR 601-1 coefficients.

-band3 BandExtract test. Input is a triple band pho-
tomap. CCIR 601-1 coefficients. Destination
window colormap is gray ramp.

-band4 BandExtract test. Input is a triple band pho-
tomap. CCIR 601-1 coefficients. Destination
window colormap is RGB_BEST_MAP standard
colormap.

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

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

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

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

-compareroimonadic1 through -compareroimonadic6
Test various compare operators with photomap,
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 photomap,
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.

-unconstrain1 ImportPhotomap, Unconstrain,
Constrain(ClipScale), ExportDrawable test.

-pasteup1 through -pasteup2
PasteUp element tests.

-geometry1 through -geometry14
Geometry element tests, including rotations,
scales, and mirroring. NearestNeighbor tech-
nique.

-geometry15 through -geometry28
Geometry element tests, including rotations,
scales, and mirroring. AntiAlias technique.

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

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

-dither1 Dither test, ErrorDiffusion dither technique,
ExportDrawable.

-dither2 Dither test, ErrorDiffusion dither technique,
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, Export-
Drawable.

-dither8 Dither test, Default dither technique, Export-
DrawablePlane.

-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
Logical element, photomap and constant of 0
operands, various operators, Control Planes.

-logicaldyadiccplane1 through -logicaldyadiccplane16
Logical element, dyadic photomaps as operands,
various operators, Control Planes.

-blend1 Blend element test. Monadic source, 0.1 source
constant. Alpha constant of 0.5.

-blend2 Blend element test. Dyadic sources. Alpha con-
stant of 0.5.

-blendroi1 Blend test. Monadic source, 0.1 source con-
stant. Alpha constant of 0.5. ROIs.

-blendroi2 Blend element test. Dyadic sources. Alpha con-
stant 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 con-
stant 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 colormaps
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 configuration. The number of flo pairs
created is also dependent upon test configura-
tion. The tests can be configured so that the
test init function will constrain the input
photomap 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
Simple Point element tests. Drawable destina-
tion. -pointroi1 Simple Point element test
which uses ROIs. Drawable destination.

-pointcplane1 Simple Point element test which uses a Control
Plane. Drawable destination.

-pointphoto1 Simple Point element test. Photomap destina-
tion.

-pointroiphoto1
Simple Point element test which uses a ROIs.
Photomap destination.

-pointcplanephoto1
Simple Point element test which uses a Control
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 elements.
The test init function creates a photoflo
based upon one of the two flographs. The
inner loop of the test function uses XieRede-
finePhotoflo() 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 offsets
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 arith-
metic 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 ran-
domly during each iteration of the test func-
tion inner loop.

-modify5 This test creates a rather long flo of arith-
metic 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 appropriate place
in the larger image.

-rgb1 through -rgb16
These tests all basically take an
UncompressedTriple 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 right-
hand window. The goal of these test is to show
that ConvertFromRGB -> ConvertToRGB is loss-
less.

-converttoindexpixel
ConvertToIndex test, TripleBand BandByPixel.

-converttoindexplane
ConvertToIndex test, TripleBand BandByPlane.

-convertfromindex
The test init function uses a flo containing
ConvertToIndex to display an image in the left
window. The test function uses this drawable
as input to a flo which does ConvertFromIndex
-> ConvertToIndex and sends 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 elements are
either inadequately tested, or ignored altogether. 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.