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 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 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 FloMatch, 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 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 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 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 visuals must be done with caution.

Many test
labels contain an abbreviated pipeline description. For instance. IP/IL/P/ED
indicates ImportPhotomap, ImportLUT, Point, and ExportDrawable. Pipelines
ending in ED (ExportDrawable) often include hidden elements such as BandExtract,
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 resulting labels file to x11perfcomp(1)
to obtain correct
output. See the x11perfcomp(1)
man pages for more details on this.

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 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 specified 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 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 specified 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
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 generation.

-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, additionally,
is set to a value of 5 (but can be overridden by the -reps option).

-all

Runs all tests. This may take a while, depending 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.

This tests creates a photoflo which is started and blocks for
data provided by PutClientData(). 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 -> ExportPhotomap 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 -> ExportPhotomap 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 various 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 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.

-exportclienthistogramcplane1 through
-exportclienthistogramcplane4

Same as the ExportClientHistogram test, but
using a Control Plane to identify the area of interest.

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 element 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 ExportDrawable.
CCIR 601-1 coefficients.

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 configuration. 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.

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

-pointphoto1

Simple
Point element test. Photomap destination.

-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 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 offsets and size.

-modify2

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

-modify3

Test XieModifyPhotoflo() by changing ExportDrawable
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 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 righthand
window. The goal of these test is to show that ConvertFromRGB -> ConvertToRGB
is lossless.

-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, Constrain,
Dither, Geometry, MatchHistogram, BandCombine, and BandSelect elements.
See the Postscript file ''complex.ps'' for a rendition of the photoflo which
is executed.

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.