/* $XConsortium: README,v 5.4 94/04/17 20:46:06 hersh Exp $ */

/*****************************************************************

Copyright (c) 1989, 1990, 1991  X Consortium

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of the X Consortium shall not be
used in advertising or otherwise to promote the sale, use or other dealings
in this Software without prior written authorization from the X Consortium.

Copyright (c) 1989, 1990, 1991 by Sun Microsystems, Inc.

                        All Rights Reserved

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 Sun Microsystems
not be used in advertising or publicity pertaining to distribution
of the software without specific, written prior permission.  

SUN MICROSYSTEMS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT 
SHALL SUN MICROSYSTEMS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL 
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.

******************************************************************/


		InsPEX, the PEX test suite
		--------------------------

InsPEX is an automated test suite for testing PEX, through
the PHIGS/PHIGS+ C language binding.  It performs operations
through PHIGS functions, and tests for the expected results
using the PHIGS binding itself, and Xlib.  Many tests use an
interpreter for faster execution time and more efficient
test development.  Tests requiring verification of pixels
use Xlib to retrieve pixel and color map information; the
resulting images are either verified automatically, or
compared against saved images.  An X-based tool, Inspector,
is supplied for comparing images against saved reference
images, and saving the new images as acceptable images if
desired. 

YOU MUST HAVE A VALID X3D-PEX SERVER RUNNING BEFORE YOU 
START THE InsPEX TEST SUITE. IT WILL NOT START A SERVER FOR YOU!!!

This file contains:

       * Some comments on porting.

       * A brief list of other sources for information about InsPEX.  
	The PEX-SI User Guide, in particular, should be referred to 
	for a more complete description of the test suite. 

	* Some comments on this release of InsPEX.




		PORTING ISSUES
		--------------

Portability Goals and Non-Goals
-------------------------------

InsPEX is intended to work with 8-bit pseudocolor framebuffers.  We
assume Unix, and have the goal of working under both System V and BSD
systems.  We also intend InsPEX to work on any 32-bit machine
architecture.  We do not have the goal of working on non-Unix systems
or different frame buffer depths.  

While support for other frame buffer depths is not built
into InsPEX, some provisions were made for porting to other
depths.  In the definition of the file format for saved images,
found in the comment for i_save_image() in tools/pexint/pixutils.c,
the first byte is intended to identify the type of file.
The only supported type is PSEUDOCOLOR, but other types could
be defined and added.  Their structure after the description string,
width, and height fields would be different, and this first byte
would be used to differentiate how the files were created and should
be handled.

Porting Tests and the Interpreter
---------------------------------

Some portable data types are declared in portable.h in 
INSPEXHOME/tools/pexint, for use in the interpreter and other
tests.  

We have tried to use system calls that are common to both
System V and BSD Unix.  Some SysV incompatibities reported
by an alert sponsor have been fixed, though they require
a "SYSV" to be defined during compilation (see the description
of I_CFLAGS in the Release Notes or inspex.sh, for a method
to set this if it isn't set by the compiler).

Porting the Inspector
---------------------

The chief portability issue for the Inspector is the choice
of Graphical User Interface toolkit.  The current implementation
uses the XView toolkit, which is available from the X Consortium
and from Sun Microsystems.  

To facilitate porting, however, all toolkit-specific code is
isolated into two files, toolkit.c and toolkit.h.  Through
typedefs and function definitions, these files create a separate
interface layer on top of the toolkit being used.  While this
interface looks like a toolkit itself, it has no pretense of being
a general-purpose toolkit -- it was designed strictly to
make this particular application easily portable.  The
interface types and functions should be implementable using
any toolkit.  An incomplete and non-working port to Athena
Widgets is included; if someone can finish this and get it going,
please share it with the PEX community.

Notification, or call-back, procedures are attached to the buttons
of the control panel; since we can't be sure of of what arguments
a given toolkit wants to supply to these functions, they
are expected to be defined without any arguments.  The negative
side to this solution is that it forces greater use of global
variables.

The scrolling list could be implemented as a menu or other
control item.  Selecting the file name in the list could
be used to control loading of files, rather than the current
method of selecting and then hitting "load".


		OTHER DOCUMENTS
		---------------

PEX-SI User Guide - the section on InsPEX is the most detailed
document for the test suite available.

PEX-SI Release Notes - this is not likely to contain any 
information that's not also to be found in this README.

A man page for the NewT interpreter builder is in
$INSPEXHOME/tools/newt/newt.man.  This describes the process of
building an interpreter, the files required, and also the language
understood by the resulting interpreters.

The header comment of the main script, inspex.sh, has
a description of the various option switches and
environment variables used by the test suite.

The file test_descrip in this directory contains an
automatically-extracted description of all the supplied tests.  Every
C-based and interpreter-based test contains a brief description of
what the test does, in a comment marked with "##".  These comments can
be automatically extracted by searching for this sequence, with a
script such as this one:

#!/bin/csh
# extract_doc.csh - given a set of file names, extract the documentation
# lines in them and print them in a nicely separated fashion.
# Documentation lines are marked by a "##".
foreach file ($*)
	echo $file -----
	# extract comment lines, remove '##' and indent slightly.
	grep "##" $file | sed -e "s/##//" | sed -e "s/^/  /"
	echo ""
end
# end of extract_doc.csh.

Here's the command used to create test_descrip in this directory:
	csh% cd $INSPEXHOME
	csh% extract_doc.csh testcases/*/*.{c,pi} > test_descrip




Notes for the final release of the PEX-SI:
-----------------------------------------

This information can also be found in the Release Notes.


This release of InsPEX has greatly increased test coverage,
and some new features.  The areas covered include all the
PHIGS-PLUS graphics primitives, such as fill area sets with data,
quadrilateral meshes, triangle strips, and NURBS.  PHIGS-PLUS
attributes such as direct color specification, depth cuing,
and lighting are also exercised.

The testing of input is somewhat limited by the problem
of simulating mouse and keyboard input in a reliable and 
portable fashion.  For the pick, locator, and stroke devices,
simulating the mouse events is straightforward, but since
the string, valuator, and choice devices are built upon
a toolkit (Athena Widgets in the PEX-SI's case), getting
window ID's for the appropriate windows and sending mouse
clicks to the right place on those windows is more difficult,
and probably impossible to do in a way that could be quickly
ported to another toolkit along with these input devices.
The technology for automatic testing of software using
a graphical user interface under X has not progressed to the
point where we could test this functionality in a way
that would be useful to all the potential users of InsPEX.

For nearly all of the tests that use image comparison
to verify graphical output, we have supplied reference
images generated here using the PEX-SI code.  Due to outstanding
bugs in the code, however, some tests are shipped without
reference images.  Also, since back-facing attributes
are not implemented, the images saved for these tests are
actually incorrect.  We decided to ship them, however,
because they still can be helpful to someone porting
the PEX-SI.  It should be expected that when backfacing
attributes are implemented, these tests will fail and
image comparison will be required.

Along with the README in the main InsPEX directory, there
is a sample log file, sample.log, and an automatically-generated
summary of all the current tests, test_descrip.  See
the README for a description of how that file was
generated.


Running the InsPEX Test Suite
-----------------------------------------

1) MAKE SURE YOU HAVE AN X3D-PEX SERVER RUNNING

2) Go to INSPEXHOME. Set the DISPLAY environment variable and the PEXAPIDIR
environment variable to the proper values. It is also helpful to set MAXFAIL 
to some reasonable value, otherwise InsPEX will stop after test failures.
Also use the VERBOSITY variable to get more clues. See the Using InsPEX 
section of the PEX-SI User Guide.


3) Type run_InsPEX. If you have not changed the relative locations of the
X and PEX directories wrt to the root tree as it appeared on your tape
then InsPEX will go off on its merry way (hopefully) performing a make or two, 
executing interpreted test scripts, compiling and executing some c language 
test programs and reporting the results. If you have moved things around you 
can use these shell scripts:

run_InsPEX
inspex.sh
startpex

as a guide to making versions that will work on your system. Remeber to
try to finesse all environment variables to absolute pathnames as relative
pathnames will make your life hell. Don't curse me I didn't write these scripts
Good Luck.

	  -----------------------------------------

Unix is a trademark of AT&T.