PEXtk - An Immediate Mode Interface to PEX PEXtk is a GL-like immediate mode interface to PEX. It contains many utilities to assist in porting to PEX. The interface was intended for users who are familiar with other low level 3D graphics libraries, such as SGI's GL and HP's Starbase. PEXtk Version 1.2 Based on MIT PEXlib 5.1 Major changes from PEXtk Version 1.1 to 1.2: Picking support was added. Support for KPC Sphere primitive was added. Major changes from PEXtk Version 1.0 to 1.1: Underlying PEXlib API was changed to use the MIT PEXlib instead of the DEC PEXlib. IMPORTANT: You must use the MIT PEXlib to link with the PEXtk programs. To build the PEXtk library and test programs, do the following: * Get the PEXtk.tar.Z, PEXtk.PS.tar.Z, and PEXtk.README files from /contrib on ftp.x.org (was export.lcs.mit.edu). Uncompress the PEXtk.tar.Z and PEXtk.PS.tar.Z files. * Extract the data from the PEXtk library tar file using tar xvf PEXtk.tar and also from the PEXtk Reference Manual Postscript file tar xvf PEXtk.PS.tar The following information makes references to the 'BASE_DIR' directory. This is the same directory where the PEXtk files were extracted . It is the directory where the README file is located. * If your system is a full X11R5 system with the MIT PEXlib installed, then you should be able to use xmkmf in the src, example, and test directories to create the Makefiles This can be done going to the BASE_DIR directory and typing 'make Makefiles'. Otherwise, there are some existing example Makefiles named Makefile.{sun,hp,es}. The src/Makefile.es is for a SUN with a E&S Freedom graphics system installed. The other Makefile.sun files should work with the Freedom graphics. If you do not have a SUN,HP,or ES, then you can try the stock Makefile (with some minor modifications, probably) to see if it works for you. Otherwise, use xmkmf. You must have the latest libXmu.a to run on any 24 bit graphics system (there was a bug in the 24bit XmuLookupStandardColormap routine). If you do not have the latest libXmu.a and you will be running on a 24 bit system, then you can bypass this Xmu routine by defining -DES in the src/Makefile. This will not work properly on the HP systems (but as far as I know HP is shipping the corrected libXmu.a). If you have an old libXmu.a and run on a 24 bit system, you will get an X error such as: X Error of failed request: BadColor (invalid Colormap parameter) You can change the BASE_DIR variable in the distibuted src/Makefile, test/Makefile and mbuf/Makefile to be the directory in which the tar files were extracted, or leave it as '../'. Also, make any necessary changes to the CFLAGS, LDFLAGS, and RANLIB variables in the Imakefile pr Makefile which is appro- priate for your compiler. PEXtk is compatable with the K&R C compiler (portable C, either pcc or /bin/cc). You will need to change the variable PEXLIB in the test/Makefile to be the PEXlib on your system. Some example locations are listed in the Makefile. If you have a complete X11R5 system, then you should use -lPEX5. For the Kubota Denali platform, the 'hardware sphere' primitives can be used by defining -DKPC in the Makefile, and then adding the library -lKPEX to the linked libraries. * The PEXtk library and all the basic test programs and examples can be built by going to the BASE_DIR and typing 'make all'. * The PEXtk Reference Manual is in the PEXtk.PS.tar.Z file. This is is a compressed tar file of the following Postscript files: doc/pextk.ps doc/pextkTOC.ps doc/pextk_appendix.ps doc/pextk_intro.ps doc/pextk_title.ps * Note that there is a BASE_DIR/include/X11 directory and a BASE_DIR/include/x11 directory. The x11 directory contains various PEX include files, X11 include files, and the multibuf.h include files. If your system does not have these include files, then you can copy or move the include files in the x11 directory to the X11 directory. If you need to do this for any of the include files, then use caution when linking with libraries built using other include files, as problems may occur (such as functions being undefined). Multi-Buffer Extension If the Multi-Buffer extension is available on the server, which can be verified by running "xdpyinfo | grep Multi-Buffering", PEXtk will will use it to do double buffering. If it is not available, then PEXtk will attempt to use the E&S/HP double buffering extension, otherwise double buffering will be performed using Pixmaps. The Multi-Buffer library can either be the /usr/lib/libXext.a (which is recommended, if available), or it can be built by going to the BASE_DIR/mbuf directory and typing 'xmkmf; make '. If you must link in the Multi-Buffer library supplied, then modify the variable $(EXTLIB) in the pextk/test/Makefile to use '../libXext.a'. Since most systems will have libXext.a, you should not have to bother with the mbuf directory at all, and the mbuf directory can be deleted. The Multi-Buffer library was supplied with PEXtk due to some systems being pre-X11R4, which did not have the proper Multi-Buffer interface. Testing Note that PEXtk has been tested on a DEC 5000/200 8/24 bit systems, the SHOgraphics PEXstation, the NCD X/PEX terminal, the Kubota Denali, some SUN GX testing, some HP 700 series testing, and a limited amount of testing using the PEX-SI on a SUN Sparc 2. Note that the PEX-SI does not support HLHSR at this time. You will find that many of the examples have strange artifacts due to this. Makefile The Makefile is set up such that the PEX 5.1 include files are in the /usr/include/X11/PEX5 directory. You should make sure that they are installed on your system. If they are not, they can be put there by copying those in the $(BASE_DIR)/include/X11/PEX5 directory, but you should contact your computer manufacturer to obtain these include files. High Performance To achieve the highest performance possible, use the server side structures (Pcreate_struct,Pclose_struct) for geometry. This puts the data in server side structure storage, and hence does not have to be "sent down the wire" again when that geometry is to be dis- played. Also, avoid using the Pbegin_... Pend_..., and the Ppoly_point_... routines in immediate mode, since these routines must use a data cache (buffer). You will see no performance problem if you use them in retained (structure) mode. However, use caution when editing them, otherwise there could be unpredicable results. Edit them in exactly the same order and mode as they were created. Use the Ppoly_fill, Ppoly_shade, Ppoly_line routines to achieve the best possible performance in immediate mode. Note that these pass all the data on a per element (polygon/line) basis, and do not need multiple calls per element (such as Pbegin_poly with Pvertex). The Ppoly_fill_area and Ppoly_index routines use the attributes which are set with Pshade_mode (such as interior style). Test Programs The test programs are located in BASE_DIR/test, and they can be built one at a time. If you will be using the supplied Multi-Buffering library (in the BASE_DIR/mbuf directory) then it will need to be built first. Usually, the library libXext.a will suffice as the Multi-Buffering libary. All of the test programs can be built by typing 'make all' in the BASE_DIR/test directory. Once all of the tests are built, you can run the csh script conf_test.csh to test the conformance of the tests. Since their are no example images of what it 'should' look like, this test script simply tests whether the programs run properly. You should try 'make stest' first. This is the most basic test. The stest program is a very simple test program to display a line being rotated. It would normally be the first test program to use to verify that the PEXtk library is functioning properly and that linking was successful. ind_test - demos use of index colors. lgt_test - demos use of moving a light. dep_test - demos use of depth cueing. dbl_test - demos use of altenative way to do double buffering. This program will not work on HP or SUN 24 bit platforms running PEX 5.1, since they only support the E&S double buffering escape method at this time. It should function properly for PEX 5.2. pck_test - demos use of picking. prm_test - demos use of various PEXtk primitives. utl_test - demos use of utilities, arc, circle and sphere. tri_test - demos use of triangle mesh. vue_test - demos use of the view routines (Ppersp_view, etc.). win_test - demos use of multiple windows. Example Programs The are 11 examples programs located in the BASE_DIR/examples directory. Since there is no User's Guide written for PEXtk, these example programs are intended to help you understand how many of the routines work together. first - a very simple PEXtk program. index_clr - shows how to use index colors and the color tables. pick - a simple example of picking various PEXtk primitives. poly_area - an example of using the Ppoly_fill_area primitive. sphere - shows the use of the PEXtk Sphere Utility. text - shows font searching, font loading, and using text. vpt - creates multiple viewports and animates one of them. win2 - shows how to use PEXtk with multiple windows. light/ light1 - a simple example of lighting. light2 - moves a light around a rotating flat shaded object. light3 - moves a light around a rotating smooth shaded object. Editing Use caution with Pbegin_... Pend_... routines when editing. PEXtk maintains state data to send to the server, and these routines must be called exactly as before. Picking Picking support has just been included in this version of PEXtk. See the Pbegin_pick and Pend_pick man pages in the PEXtk Reference Manual for more information. Routines not implemented yet: Display List - Pcreate_display_list, Pclose_display_list, Pcall_display_list Platform dependant - All texture primitives Pdither, Ptransparency Not fully verified: Pset_display_buffer, Pset_update_buffer Ppolar_view, Plookat_view Other notes The float type is specified as 'float'. If it becomes necessary for portability reasons (and from a concensus of the users), this can be changed to 'double'. Some NURBS routines have been implemented, Pnurb_surface, Pnurb_curve, Psurface_parm_range, Pcurve_parm_range, Psurface_approx_method, Pcurve_approx_method. The routine Pplane_mask and Plogical_function have been added to support the Digital MPEX options. However, in PEXtk 1.1, there is no way to link in the MPEX PEXlib routines, since they are not available in the MIT PEXlib. Hopefully, these routines will be PEX 6.0. Bugs There are problems with Ppoly_index (PEXSetOfFillAreaSets) on the DEC with backface culling on. On the SUN, add the complile option -DSUN. Currently, there seems to be problems will filled polygons on the PEX-SI with the latest patches applied. On the original PEX-SI release it works correctly. Note that the DEC Multi-Buffer Extension has a bug when NOT using the zbuffer. The ZBuffer should always be enabled on DEC platforms that have Multi-Buffer extension. Any bugs that are found (or changes that you may have made to make PEXtk compile on your system), should be sent to rws@kpc.com Also, to be kept informed of future releases and bug fixes, send a request to be added to the e-mail list for PEXtk to rws@kpc.com General information/requests can be posted on comp.windows.x.pex ______________________________________________________________________________ - Bob Schulte rws@kpc.com