PEXlib Announcement

	Sony Microsystems Company is pleased to announce the
	availability of a low level interface to the PEX protocol
	(PEXlib) together with a number of clients and example
	programs.

			PEXlib Version 2.1

			Sony Microsystems

			     7/11/91


1. What is PEX ?

	PEX is the only standard way to do 3D graphics under X
	windowing system.  PEX contains two components: the extension
	to the server which renders 3D graphics and the API library
	which allows the developer to realize PEX functions.

	The original PEX shipped from MIT has only one API library,
	which is based upon the ISO standard PHIGS/PHIGS+.  Since
	PHIGS/PHIGS+ style API does not fully exploit PEX
	functionalities and imposes considerable policy and overhead,
	it is natural to expect an alternative API.

2. What is PEXlib?

	PEXlib is a thin veneer of interface which issues PEX protocol
	requests to the server.  It has one to one mapping of every PEX
	protocol request plus some convenient functions to ease
	programming.

	PEXlib is at the same level of Xlib, the library which issues
	X11 protocol requests to the server.  It is designed to be
	similar to Xlib in programming style and practices.

	Since it is low level like Xlib, we expect people to write
	higher level interface on top of PEXlib.  A PHIGS/PHIGS+ API
	may be written on top of PEXlib, the proposed PEXtk and PEXIm
	tool-kits can also be written on top of PEXlib.  Applications
	can use PEXlib directly just as they may use Xlib directly.  It
	is also an excellent vehicle to test the PEX server
	implementation.

	PEXlib attempts to match PEX protocols as close as possible.
	It does not do more than the protocol specifies.  This means no
	input functions and policy of any kind.

3. What does this PEXlib package contain ?

	The PEXlib package submitted to MIT has the source code for

	a. the PEXlib source code

	b. documentation, mainly man pages

	c. a few applications that exhibit PEXlib functionalities

	d. example programs: "auto_box", "beach_ball", and "helloWorld"

4. How do I get PEXlib?

	PEXlib is part of the MIT X11R5 contrib software.  It is
	distributed by MIT with X11R5.

	Sites with ftp access can get it from

	export.lcs.mit.edu:contrib/Xpex.tar.Z

5. Once I get the tar package, what do I do next ?

	Uncompress it the file and then following the building and
	installation instructions below.

6. Support

	This is our first public release of our PEXlib interface and
	though we have fairly extensively tested this library it is
	certain that bugs remain and that this low level interface
	exposes problems in the PEX sample implementation.  Sony
	Microsystems welcomes suggestions for enhancements and bug
	reports, send these to pexlib@smsc.sony.com.

BUILDING PEXlib

	PEXlib must be built under the PEX-SI source directory
	(mit/extensions/lib/PEX). 

Perform the following steps to build PEXlib:

	[STEP 1] % cd <the root directory of your X11R5 source tree>

	[STEP 2] % cd extensions/lib/PEX 

	[STEP 3] % tar xf Xpex.tar

	[STEP 4] % make Makefile

	[STEP 5] % make Makefiles

	[STEP 6] % make depend

	[STEP 7] % make clean

	[STEP 8] % make 

INSTALLING PEXlib

Perform the following steps to install PEXlib

	[STEP 1] % cd <the root directory of your X11R5 source tree>

	[STEP 2] % cd extensions/lib/PEX/Xpex

	[STEP 3] % make install install.man DESTDIR=</usr/X11>

SPECIAL NOTE: When installing PEXlib, the pexscope binary executable
(if it already exists under /usr/bin/X11) will be overwritten. You
should make a backup copy of the original pexscope before installing
the PEXlib software.


Experience with PEXlib at Sony Microsystems

One way we have been extensively using PEXlib is to validate
functionality provided fro each PEX Resource of Sony's PEX Server.

Here is a summary of our findings :

	Extension Information

		The client pexdpyinfo is intended to be the PEX
		equivalent of the X client xdpyinfo.  This client,
		making use of PEX requests GetExtensionInfo,
		GetEnumTypeInfo, and GetImpDepConstants, displays all
		Core PEX Extension Information. The information
		returned from the SI Server was compared to the
		implementation dependent functionality specified in
		appendix B of the PEX-SI User Guide. It seems quite
		solid.

	Lookup Tables

		The client pexlutinfo displays the default information
		of each lookup table type as well as the predefined
		entries for each type.  The information displayed
		matches those predefined values specified Appendix B in
		the PEX-SI user guide.

	Pipeline Contexts

		The client pexpcinfo displays the default values of the
		Pipeline Context (PC) resource.  The most values
		returned match those specified in Appendix B of the
		PEX-SI user guide. I have fixed a trivial bug in the
		PEXlib PC code that verifies most PC values returned
		from the server.  This fix will be sent out in a code
		patch (to be decided).

		Please Note: This client is incomplete. The full
			working client will be sent out in the same
			code patch (to be decided).

	Renderers

		The client pexrdrinfo attempts to display the default
		renderer attributes and dynamics values.  For some
		reason, I was unable to obtain more than two attribute
		values at a time.  Most of the return values match
		those specified in Appendix B of the PEX-SI user
		guide.

	Search Contexts

		The client pexscinfo attempts to display the default
		values of the Search Context (SC) resource. All return
		values match those specified in the PEX Protocol
		Specification Document (v5.0P).

	PHIGS Workstations

		The client pexwksinfo attempts to display the default
		workstation attributes and workstation dynamics. It
		also displays the default pick device descriptors
		(DC_HitBox and NPC_HitVolume).  The most values
		returned match those specified in the PEX Protocol
		Specification Document (v5.0P).

	PEX Fonts 

		I could not do too much in this area. For some reason,
		sending the PEXOpenFont request causes the server to
		core dump.  This is one bug that I am trying to nail
		down.  It turns out that PEX-SI PHIGS does not exercise
		the use of this resource class.  The client pexlsfonts
		will be available once this bug is fixed.

	Output Commands 

		In addition to validating the PEX resources, we
		developed an output command handling scheme which suits
		both Immediate Mode Rendering (IMR) and PHIGS
		Workstation Graphics applications development.
		Examples of this output command handling scheme may be
		found in the clients auto_box, beach_ball, and
		helloWorld in the directory Xpex/examples.

		Unfortunately, the IMR versions of these clients are
		not available yet. We hope to have them in our next
		release.

	Utility Functions 

		In the course of writing the first PEXlib applications,
		the need for utility functions to aid the setting of
		transformation matrices used by functions such as
		SetLocalTransformation, SetViewRep, etc., was
		anticipated and has been implemented. I simply cloned
		the utility functions that PEX-SI PHIGS offers.

		The only utility function that has not been completely
		implemented is XpexComputeGeometricNormal.


THE LAST WORD 

THE bottom line is that we have found PEXlib to be a useful tool to
validate the functionality of the PEX-SI server.  The PEX-SI server is
robust to the extent that it holds up well during the policy-free use
of the PEX protocol. So far, none of the clients have the value mask(s)
set causing all the attributes to be inquired simultaneously.  This is
due to the inability to get the server to return values correctly when
the valuemask is set to "ALL".  It not clear yet whether this is a
server or a PEXlib problem.

Finally, Sony Microsystems welcomes feedback that on any and all
problems/issues relating to PEXlib and or the implementation.

Please address all questions/comments/bug report to pexlib@smsc.sony.com.

Erwin Hom
Sony Microsystems