PGL 1.1.2 Release Notes February 1997

Table of Contents

• What's New?
• Supported Platforms
• Organization
• Requirements
• Installation
• Compiling and Linking PGL Applications
• Example Programs
• Performance Notes
• Known Problems and Limitations

The most notable changes since Release 1.0e include:

• Vastly expanded documentation. It may not tell you everything you want to know about PGL, but it covers most of it. Suggestions for additions or improvements are welcome.

• Changes in the way initialization options are specified for PGInit. This will require minor modifications to existing PGL applications.

• Users now have a choice of rasterization routines, providing a trade-off between speed and quality. See PGSetTrRasterMethod for details.

• Additional tuning of the rasterization routines to provide better performance on scenes which are composed of large numbers of very small primitives.

• Int64 and Unsigned64 data types are now truly 64 bits on those platforms which support 64-bit integers (previously they were only 32 bits). These are used primarily by the performance metric routines, where counters can easily exceed the limits of 32-bit arithmetic.

• A new utility is included for converting raw RGB images to YMF format. Converters from other formats can easily be built using the routines provided in the source file toymf/toYMF.c.

• DUI has been modified to allow applications to specify the desired user interface program at runtime. Code has also been added to perform authorization checks on incoming connection requests.

• An additional example program (DUIgrid) has been included to illustrate the use of DUI.

• All known bugs in PGL itself have been fixed. However, there are some outstanding problems which result from bugs or misfeatures of the underlying OS platforms on which PGL runs. See the section on Known Problems and Limitations, below.

The uniprocessor versions of PGL may be useful for initial development and debugging of codes which will ultimately be ported to parallel platforms. The uniprocessor versions also include the executables required for workstation-based image display (ymfd and ymovie) and interaction (duid and dui).

The PGL software distribution uses the following platform identifiers:

paragon - Intel Paragon.

sp2 - IBM SP2 w/ MPI.

sun4 - Sun SPARC w/ SunOS 4.1.x.

sun4_5 - Sun SPARC w/ SunOS 5.x.

iris4d - SGI MIPS w/ IRIX 5.x.

     PGL/app-defaults
     PGL/docs
     PGL/examples
     PGL/paragon/bin
     PGL/paragon/include
     PGL/paragon/lib

setenv PGLDIR /usr/local/unsupported/PGL

setenv XAPPLRESDIR $PGLDIR/app-defaults

The lib directories contain the libraries themselves, libPG.a, libPV.a, libPO.a, and libDUI.a. Programs should normally link against these libraries for production runs. Debug versions of the libraries are also available, and should be used during initial development and testing of PGL programs, or whenever an application encounters problems which appear to be PGL-related. The debug versions are denoted by the letter "d" appended to the library name: libPGd.a, libPVd.a, libPOd.a, libDUId.a. The debug versions are compiled with the appropriate options (e.g., -g) for use with system debuggers, and also contain extensive internal consistency checks. The debug libraries run much more slowly than the standard libraries, which are compiled with full optimization.

An instrumented version of the PGL library is also available which collects extensive statistics about the rendering process. This library has an "m" designation (libPGm.a). The performance instrumentation has been designed to be as inobtrusive as possible, and generally adds only a modest overhead to the execution time. Routines are provided to control what information is collected and to retrieve and process the accumulated results.

The bin directory contains executables for the YMF image conversion and display utilities, the DUI daemon (duid), and the default user interface program (dui). ymfd, duid, and dui are built and installed only for the workstation (Sun and SGI) versions of the system, since they are not intended for use on the parallel platforms.

To access the executables, you should add the bin directory to your search path:

set path=($path $PGLDIR/$ARCH/bin)

zcat PGL-1.1.tar.Z | tar xvpf -

The next step is to edit the configuration files to suit your local environment. These are found in the top-level source directory. There are two files of interest, platform.conf and site.conf, where platform is the platform identifier for the system on which you are building PGL.

The platform.conf file contains platform-specific definitions for things like the compiler name and options, library pathnames, etc. The site.conf file is used to define where include files, libraries, executables, documentation, etc. should be installed. In most cases all you should need to do is define DESTDIR to point to a top-level installation directory. Depending on your local configuration, you may also want to redefine SRCDIR, DOCDIR, HTMLDIR, and EXAMPLEDIR.

Next, you must build the top-level Makefile. In the top-level source directory

make -f Makefile.master ARCH=platform

Finally, you build everything. In the top-level source directory,

make World |& tee make.World.out

PGLDIR = /usr/local/unsupported/PGL/platform
PGLINCDIR = $(PGLDIR)/include
PGLLIBDIR = $(PGLDIR)/lib

...

myprog:  myprog.c
        $(CC) $(CFLAGS) -I$(PGLINCDIR) -o $@ myprog.c \
              -L$(PGLLIBDIR) -lDUI -lPO -lPV -lPG -lm

On some platforms, additional libraries may be needed for things such as socket routines. If you get unresolved references when try to link your PGL applications, check the appropriate platform.conf file to see what else is required. Additional examples can be found in $PGLDIR/examples/Makefile.

• rand4 -random triangles in a rotating cubic volume
• grid -rotating parametric surface
• DUIgrid -parametric surface with interactive user interface

rand4 will run on an 8-bit display, while grid and DUIgrid are configured to use 24-bit color. The X11 utility xdpyinfo may be used to determine the visual types which are available on your display. (ymfd will complain if it can't find an X visual with the appropriate characteristics. We suggest directing stdout and stderr of ymfd and duid someplace where it will be visible, such as a console or terminal window.)

Suggested invocations of the example programs are given below. Rendering performance will be better with larger numbers of processors, although network bottlenecks may limit the display rate. We recommend a minimum of 4 processors for rand4, and 16 or more processors for grid and DUIgrid.

rand4 -N 10000 -T 0.02 -F 100 ymfd@workstation.domain
grid -X 100 -Y 100 ymfd@workstation.domain
DUIgrid -X 100 -Y 100 workstation.domain

Paragon

• We recommend that you use the -plk runtime switch to lock your application's data pages into memory. In some cases we have observed significant performance degradation when running on large numbers of processors without -plk.

SP2

• Figure 1: Rendering rate as a function of buffer depth.

  Performance on the SP2, while generally quite good, has been found to be especially sensitive to the choice of message length (Fig. 1). This parameter can be controlled using the PGSetBufMethod routine. It is suggested that SP2 users insert the following call immediately after the call to PGInit:

  PGSetBufMethod(PG_BUF_DOUBLE, 170, 85)

  If memory is at a premium, the last two arguments may be decreased, with some potential loss of performance, depending on the number of processors in use and the complexity of the scene being rendered. The third argument should be about half the value of the second argument. Very small values of either argument may result in poor performance.

Paragon

• The Paragon's default message-passing configuration is not sufficiently robust to accommodate PGL's demanding asynchronous communication requirements. The result is system crashes and hangs when running with large numbers of processors. Even though PGL's rendering algorithms require essentially all-to-all communication, the workaround is to set a small value for the number of correspondents (-noc runtime option), e.g.,

  rand4 -sz 384 -noc 4 -plk -N 1000000 -T 0.02 -F 100 /pfs/myname/rand4
  

  Unfortunately, use of this option degrades performance somewhat. Although the critical number of processors varies from release to release of the software, for reliable operation we recommend using -noc whenever a job requires more than 128 processors. If your system administrators are willing to tolerate a few crashes, some experimentation is in order to determine the most efficient value for -noc as a function of system size. For more information on -noc and other communication parameters, consult the Paragon System User's Guide.

SGI

• X11 colormap handling for 8-bit visuals does not work properly on certain combinations of older SGI hardware and newer SGI operating systems. In particular, we have had trouble on Crimson systems with VGXT graphics under IRIX 5.3. This may cause ymovie and ymfd to display incorrect colors for 8-bit YMF image streams.

Sun Solaris

• The interaction of UNIX domain sockets with various socket-related system calls varies widely among UNIX implementations, which makes DUI's access validation mechanisms less secure than they should be. The problem is particularly severe under SunOS 5.x, which in some cases fails to enforce access permissions on UNIX domain sockets. This could conceivably result in unauthorized execution of user interface programs. Therefore, these programs should be designed so that they won't have adverse consequences (such as overwriting critical files) if they are executed either accidentally or maliciously. For more details, consult the documentation for duid and dui.