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