Copyright 1991, Addison-Wesley Publishing Company, Inc. Addison-Wesley Publishing Company, Inc. makes no representations or warranties, express or implied, with respect to this software and its documentation, including without limitations, any implied warranties of merchantibility or fitness for a particular purpose, all of which are expressly disclaimed. The exclusion of implied warranties is not permitted by some states. The above exclusion may not apply to you. This warranty provides you with specific legal rights. There may be other rights that you have which may vary from state to state. Adopters of Foley, van Dam, Feiner, and Hughes' Computer Graphics: Principles and Practice, 2nd edition may copy this software for students in their classes. The software may not otherwise be reproduced without the prior written permission of the publishers. ============================================================================ OVERVIEW OF THE PACKAGES SRGP (Simple Raster Graphics Package) and SPHIGS (Simple Programmer's Hierarchical Interactive Graphics System) reflect the two major schools of interactive graphics programming. SRGP combines features of the Quickdraw and Xlib 2D integer raster-graphics packages. SPHIGS provides the fundamental features of a 3D floating-point package with hierarchical display lists. The packages are designed for instructional use but can be used to implement significant graphics applications. ============================================================================== VERSION INFORMATION Version numbers: SRGP: 1.0 SPHIGS: 0.9 For full information on known bugs and omissions in these versions, and differences with the textbook's description, please read section 0 of the srgp.doc and sphigs.doc reference manuals. SPHIGS v0.9 corrects the many compilation problems present in the original shipment (v0.8). Mr. Sklar wishes to thank the many users who contributed information and source code leading to this new version, especially the Ross family (Hugh and Ann). A list of the changes in SPHIGS source from v0.8 to v0.9 is found in the "changes.doc" file described below. You should be able to use either of these language platforms to run SRGP and SPHIGS applications: *) Turbo C v2.0 *) Turbo C++ v1.0 **************************************************************** HOWEVER, if you wish to tinker with the source to SPHIGS, note that THE SPHIGS LIBRARY CAN ONLY BE MADE WITH THIS LANGUAGE PLATFORM: *) Turbo C v2.0 **************************************************************** Moreover, use of the integrated-environment compiler (TC) is NOT desirable; use the command-line compiler (TCC). ========================================================================== ABOUT THE FILES \README This file! \SRGP\SRGP.LIB The Turbo C library with which you must link in order to use SRGP \SRGP\SRGP.H The header file that you must include at the top of your SRGP application \SRGP\SRGPPUBL.H Header files included by SRGP.H \SRGP\SRGP_SPH.H \SRGP\SRGP_COM.H \SRGP\GEOM.H The header file for the small set of geometric utilities included in the SRGP library. \SRGP\*.FNT The MetaGraphics font files for use with an SRGP application \SRGPDOC\SRGP.DOC A text file which is a terse but complete description of SRGP \SRGPDOC\COLORS.DOC A list of the "common colors" available to the routine SRGP_loadCommonColor() \METASHEL.EXE MetaGraphics TSR program needed to run SRGP/PC applications \SRGPDEMO\README About the demo programs provided in the SRGPDEMO directory. \SPHIGS\*.H Header files needed for the creation of SPHIGS applications \SPHIGS\SPHIGS.LIB The Turbo C library with which you must link in order to use SPHIGS \SPHSRC\*.[CH] Header and source files needed to create the SPHIGS library (in case you wish to make modifications to SPHIGS) \SPHSRC\MAKEFILE Help in creating the object files \SPHSRC\BUILDLIB.BAT A batch file you can use to create SPHIGS.LIB \SPHSRC\OBJLIST.RSP A file used by "tlib"... to create SPHIGS.LIB \SPHDOC\SPHIGS.DOC A text file which is a terse but complete description of SPHIGS \SPHDEMO\README About the demo program provided in the SPHDEMO directory \SPHDEMO\*.[CH] Source code for the SPHDEMO program \SPHDEMO\MAKEFILE Help in creating the SPHDEMO program ============================================================================= FEEDBACK Please send bug reports and suggestions for improvement (of both the software and the documentation) to: Graphics Textbook Support c/o Dr. van Dam Brown University box 1910 Providence, RI 02912 If you have email available, you can send mail to "graphtext@cs.brown.edu". Please put the phrase "Report-Software-Bug" in the Subject line. =========================================================================== GENERAL INFORMATION ABOUT SRGP/PC Currently SRGP/PC does not support the following (see the reference manual for details): * plane masking * XOR write mode for transparent bitmap patterns and text * application control of table sizes *** Warning *** NOTE: all SRGP applications MUST call SRGP_end before terminating! Otherwise, your system will hang and require rebooting. *** Mice *** SRGP attempts to detect whether you have a mouse installed on your system. If it detects that you do not, it stops with an appropriate error message. However, to SRGP modems or any serial port may look like a serial mouse; therefore SRGP may think you have a mouse when you do not. As a result, it is VERY important to have your mouse driver running before you attempt to invoke an SRGP application. If you do not, your system will hang! *** Fonts *** Two fonts (in various sizes) are provided in the directory \SRGP: one called "system" and another called "extsys". You may load any of these fonts by calling SRGP_loadFont(); for instance, SRGP_loadFont("system00") loads the font stored in SYSTEM00.FNT. SRGP attempt to find the font file by looking in (1) the current directory, (2) a directory called \METAWNDO (if it exists), and (3) the directory \SRGP (if it exists). If it can't find it in any of these places, an error message is sent to your logfile, if you are tracing; the program continues to use the current font. NOTE: SRGP uses SYSTEM08.FNT by default. Do not erase this font from your disk or move it somewhere SRGP can't find it! If you do, SRGP will terminate with an appropriate error message. NOTE: The two-digit number on each font file's name has no meaning; it does not tell you anything about the font's size. *** Colors *** Because it is compatible with color workstations running X11 and color Macintoshes, PC-SRGP was designed with VGA cards in mind, since only VGA cards have the same concept of a LUT table in which colors are stored. Monochrome cards are similarly well supported. However CGA cards are admittedly not well supported because their concept of color is very different. CGA cards use several hard-wired palettes from which to select hard- wired colors rather than having a color table to store arbitrary colors like EGA/VGA cards do. As a result, PC-SRGP uses the CGA card's palette 0 and calls to SRGP_loadColorTable() and SRGP_loadCommonColor() have no effect. ============================================================================== GENERAL INFORMATION ABOUT SPHIGS/PC SPHIGS applications are also SRGP applications; the SPHIGS package calls SRGP to perform all its graphics operations. Therefore, the same graphics limitations listed in the above section also apply to SPHIGS. SPHIGS is heavily dependent upon floating-point operations; thus, it will be quite sluggish on machines that do not have floating-point accelerator chips. If you are planning to use SPHIGS as an aid for learning about PHIGS and about modeling in general, you'll be satisfied without an accelerator; but if your intention is more serious, involving research or professional work, you should consider enhancing your hardware with an accelerator. ============================================================================== GENERAL INFORMATION ON WRITING SRGP APPLICATIONS IN TURBO C NOTE: This information is no substitute for: 1) Reading the "SRGP for Turbo C" reference manual 2) Being literate in ANSI C 3) Having access to Chapter 2 of the Foley, et.al. textbook 4) Having access to the Turbo C manuals Section "0" of the "SRGP for TURBO C" documentation is very important. It tells you about current shortcomings and omissions in the current version of SRGP/PC, and differences between SRGP/PC and the SRGP spec in the textbook. In order to compile inside Turbo C's integrated environment, you must create a "project file" for your application. This file consists of your applications files followed by the SRGP library. Example: if my application, FOO.C, uses routines in UTIL.C as well as SRGP routines, my project file would contain the following three lines: FOO.C UTIL.C \SRGP\SRGP.LIB Note that an abosolute path must be given for each file. Please see your Turbo C reference manual for more details on project files, as well as the project file for the examples on your disk. Before compiling make sure that the Options/Directories menu is set up properly to point to all the necessary include and library files. Not doing so will result in compilation errors starting with one stating "file xxxx not found." IMPORTANT: The object files in the SRGP library were compiled using the LARGE memory model. Not compiling your application with the LARGE model will cause link errors. Also note that by default Turbo C's own graphics library is linked in. With SRGP, this is unnecessary and may make your executable file unnecessarily larger. To turn this off, look under the Options/Linker menu and turn the "Graphics library" choice off. ============================================================================== GENERAL INFORMATION ON WRITING SPHIGS/PC APPLICATIONS IN TURBO C Section "0" of the "SPHIGS for ANSI-C" document is very important. It tells you about current omissions in the current version of SPHIGS/PC, and differences between SPHIGS/PC and the SPHIGS spec in the textbook. Before writing an SPHIGS/PC application, you must create the SPHIGS.LIB file. Create a TURBO C project that contains all the .c source files found in \SPHSRC. Compile that project into a .LIB file. Of course, you only need perform this operation once. Some users may wish to create two different projects (one called "MAT" and one called "SPHIGS") to create two different libraries ("MAT.LIB" and "SPHIGS.LIB"). The former would contain the .c files whose names begin with "MAT". This is useful if, on your system, it is advisable to keep down the sizes of libraries. Once you have created the MAT and SPHIGS libraries, you can begin writing SPHIGS applications. The project file should contain your application's source files as well as: \SRGP\SRGP.LIB MAT.LIB SPHIGS.LIB Again, you must use the LARGE memory model, and you should turn the "Graphics library" choice off. ============================================================================== RUNNING YOUR SRGP/SPHIGS APPLICATION Once your program is successfully compiled, you must run your application by passing it to the program METASHEL.EXE. Example: I just compiled the FOO project to create FOO.EXE. To run FOO.EXE, I type this: A:> METASHEL FOO This is different from running most applications: you usually run an application by simply typing in its name at the DOS prompt. If you run an SRGP/SPHIGS program using the "old" way, your system will hang! Beware! Obviously, this method makes it impossible to run your program from within the Turbo C integrated environment. If you find the system hangs or is in a strange state after an SRGP/SPHIGS application finishes, it probably is the case that the application fails to call SRGP_end() before terminating. Fix the source code if that's the case. For advanced users: The metashel program can be installed as a TSR. Use "metashel /i" to install, and "metashel /k" to remove. We do not recommend running Turbo C while the TSR is installed. ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- -------------------------------------------------------------------------------