LCD Crystals PDD by hcj


									University of Southern Mississippi
Center of Higher Learning
High Performance Visualization Center
February 2002                                 Report CHL-HPVC-02-03

Project Documentation Design (PDD)
LCD Crystals Visualization

                                                        G. Q. Morris
                                                        C. H. Johnson
                                                      Dr. P. H. Ranelli
                                                               N. Kaul
                                                             M. C. Gill
                                                         D. R. Runnels
                                                      A. K. Rajendran
                                               Center of Higher Learning

                                                              Dr. J. Lee
                                        University of Southern Mississippi
                      Project Documentation Design (PDD)
                           LCD Crystals Visualization

1. Introduction

   This project visualizes molecular rods in three-dimensional space based on a data set
   generated by Dr. Joon Lee, a physics professor at the University of Southern Mississippi.
   This simulation deals with the reactions of LCD crystals to a constant cooling temperature.
   Dr. Lee can acquire a better grasp of how these structures are behaving through a virtual
   CAVE application rather than still pictures or numerical analysis. Along with user tools,
   such as isolating individual LCD rods, Dr. Lee or any user achieves a higher degree of
   interactivity with this animation.

1.1 Purpose of this document

   This document will fully explain the procedures and functions that interact to form the LCD
   Visualization system. Key components will be broken into subcomponents so the reader
   has a full understanding of the performance of the package. Data elements and formats
   useful for reuse are provided. In closing, this manuscript should provide a developer with all
   the information one needs to utilize, expand, or implement the LCD application.

1.2 Scope of the development project

   The project goals include the real-time animation in a CAVE-like environment of molecular
   rods in a constantly cooled environment. User navigation along with several menu features
   allows the user the flexibility and power to successfully analyze the alignment of the
   crystals. The action of the simulation may be paused as individual particles are tagged for
   sole analysis. Also, a frame-by-frame study may be conducted via the Rewind and Forward
   controls. The data set may be restarted and its progress is visualized with a status bar. All
   options or mode changes are handled with the user‟s wand and/or its buttons.

   This task implements a data format that is discussed in the following literature. As long as
   the layout is compatible, data sets may be interchanged in the package with assistance
   from a preprocessing program called the LCD PREPROCESSOR.

   The following sections will provide all of the documentation needed to provide insight into
   the LCD Visualization system.

1.3 Definitions, acronyms, and abbreviations

   ASCII – American Standard Code for Information Interchange
   CAVE - A recursive acronym that stands for CAVE Automatic Virtual Environment,
         otherwise known as CAVE Audio Visual Environment.
   CHL - Center of Higher Learning
   HPVC – High Performance Visualization Center, a division of CHL
   LCD – liquid crystal display
   SGI – Silicon Graphics
   TCP – Transmission Control Protocol

1.4 References

       “CAVElib users manual.” URL:
       “Cavernsoft generation 2.” URL:

     M. Woo, J. Neider, T. Davis, “OpenGL programming guide, second edition.” Addison-
   Wesley Developers Press, Reading Massachusetts, 1997.

1.5 Overview of document

   The remainder of this document contains a description of the system architecture, which will
   provide an overview of the various elements and components of the project. The system
   architecture description will also explain the interrelationships and dependencies among the
   components of the project, as well as the user interface.

   Section 3 provides a detailed description of components in a template format. The
   template is described in Section 3.1. The advantages of code reuse and relationships are
   exploited and explained in Section 4. This section details the role reuse plays in the project
   design as well as the motivation for any changes made in the design. Relationships to other
   products are also discussed. Section 5 explains the design decisions and tradeoffs made
   due, for example, to system limitations. Finally, Section 6 will explain how to use this
   project, how to pre-process the data as well as how to compile and execute the code.

2. System Architecture Description

   This project has three main components: INITIALIZATION, FRAME_PROCESSOR, and
   DISPLAY DRIVER; all will be outlined here. The LCD Visualization package handles all
   static geometry, state variables, and object creations in the INITIALIZATION component.
   The bulk of the package is being driven by the other two looping components. In a CAVE
   environment, a display callback is needed and a frame callback may also be implemented.
   In LCD, the FRAME PROCESSOR module is executed once before each frame;
   subsequently, the DISPLAY DRIVER is parsed either once for mono visual mode or twice
   for stereo. All components will be outlined in Section 2.1 as well as in the module

2.1 Overview of modules / components

      DATA SET – Dr. Lee provided CHL with a data set that he generated from a software
       simulation. This data set is an ASCII file that contains six doubles per line for a constant
       amount of molecular rods per frame. The format of each line is that of x1, y1, z1, x2, y2,
       and z2. These fields are separated strictly by white space. The first three entries
       represent the end point of a rod and the second three data items denote the other
       endpoint. A preprocessing program, known as the LCD PREPROCESSOR component,
       peruses the file and computes the number of frames and crystals in the animation. This
       calculation is constant throughout the rendering cycle. After the predetermined amount
       of LCD crystal information is absorbed for one frame, there exists a dummy line in the
       file that separates each frame. This separating line‟s only valid data is a frame number;
       the remaining piece of the line is garbage.

      INITIALIZATION – This module will prepare the application for all of the tools that it
       requires. Fonts, textures, display lists, sound configurations, and OpenGL state
       variables are created and stored if possible. Sounds are handled via Cavernsoft G2, a
       hybrid networking database library. INITIALIZATION creates an audio client that will
       connect to the computer housing the SOUND SERVER. The ROD component
       responsible for displaying and manipulating a single molecule is initialized for every LCD
       crystal in the scene.
       o   Font specifications
               Helvetica, 24pt.
               #include “font2.h”

       o   Textures used
               “menu.bmp” – represents the virtual menu (Figure 1)
               “logo.bmp” – HPVC logo (Figure 2)
               “splat2.bmp” – background texture mapped onto the mouse pointer
                  (Figure 3)

       o   SOUND SERVER – This thread is a daemon running on the local host that will
           receive messages from the sound client created by the INITIALIZATION
           component. The information passed is the name of the sound file to play. Using
           SGI software, audio is then heard.
               “erased.aiff” – the exiting quote
               “error.aiff” – error sound notifying the user of a mistake
               “laser.aiff” – sound that confirms a tagging selection
               “selected.aiff” – sound confirming a valid menu selection

   ROD – This component is the sole class of the graphical system. All rods have one
    instantiation of this construct. This object will store a rod‟s location, construct a cylinder
    with a set number of quads, provide normal/lighting calculations, control the color of the
    crystal, and perform a tagging function for isolation.

   FRAME PROCESSOR – This component handles all file operations such as opening,
    reading, and seeking the data set. This module, as mentioned earlier, is executed once
    before the next frame is rendered. It is noted that all file operations for any CAVE
    application should be handled in a separate callback than the display due to the side
    effects in stereo mode. In stereo mode, the display callback routine gets parsed twice,
    once for each eye, causing your file reading to be incorrect. The FRAME PROCESSOR
    relies on a subcomponent to monitor button 2 on the user‟s wand for special features.

           o   BUTTON 2 MONITOR – Manipulating and controlling the data set is this
               module‟s primary function. Rewinding or forwarding the data set frame by
               frame are performed in this function along with the accompanying sounds,
               which are passed to the SOUND SERVER.

   DISPLAY DRIVER – This module will render the scene and lean on two subcomponents
    to assist. The menu, the status bar, the mouse pointer, the tagging sword, and any text
    needed are drawn in the virtual world via this component. The USER DISPLAY UNIT
    and the MENU PERFORMER are also utilized.

           o   USER DISPLAY UNIT – This unit will handle drawing all molecular rods via
               the ROD component. The CHL logo is also a resultant of this function.
               Lastly, if the user has recently selected a mode, this module will display the
               text detailing the mode. The two possible modes are Frame Freeze and
               Movie Mode. Movie Mode deals with a looping animation of the crystals
               while Frame Freeze allows the user to suspend time and observe the
               alignment of the crystals. Both modes allow the user to freely navigate.

           o   MENU PERFORMER – This function polls the user‟s actions and sets
               corresponding shared variables that represent actions. There are six
               possible menu selections, Tag, Rewind, Forward, Reset, Restart, and Exit,
                  and three of them are handled in this component. These options are Restart,
                  which starts the data set from the beginning, Reset, which transports the user
                  back to the origin of the virtual world, and Exit.

      LCD PREPROCESSOR – This module is a standalone program that parses the file and
       produces a header file known as frame.h. In this header file, two constants
       representing the number of LCD frames and crystals in the simulation and an array that
       contains the seek locations of the various frames of the data set file is resident. This
       array is key to the Rewind option. It is noted that if a new data set were to be used, the
       LCD PREPROCESSOR must be executed upon that data set.

              o   Usage
                      prepro <data_set_filename>

2.2 Structure and relationships

   The following diagrams depict an overall view of the system as well as the interconnectivity
   between the key modules and subcomponents. Header files and libraries will be revealed in
   module template section. Figure 4 represents the overall view and most abstract look of the
   LCD system. Figure 5, 6, and 7 illustrate the FRAME PROCESSOR, INITIALIZATION, and
   DISPLAY DRIVER modules respectively.

                                    data set
                                                               FRAME                     exiting
             LCD                     shared
        Visualization                memory                                         cleanup

                                                          DISPLAY DRIVER

          PREPROCESSOR                                      navigation

                        Figure 4: Overall View of the LCD Visualization

          FRAME PROCESSOR                         open files
                                                   if at the                      BUTTON 2
                                                   beginning                       MONITOR

                             read frame                           update
                            data /ignore                       frame count
                             dummy line

                        Figure 5: FRAME PROCESSOR component
                                              DISPLAY DRIVER

                                                check SOUND
            initialize                           CLIENT and
          OpenGL state                          update text

        set up lighting                           DISPLAY
         and materials                              UNIT

          set up fonts
          and textures                          draw status
                                                  bar and

        build display
           lists for
         mouse, logo,                               MENU
            and menu                             PERFORMER

                                                handle Tag
          attach sound                          by calling
            client to                             the ROD
          sound daemon                             method

            all rods

Figure 6: INITIALIZATION Component   Figure 7: DISPLAY DRIVER Component
2.3 User interface

   The LCD Visualization has been implemented on the CAVE (Figure 8), the RAVE (Figure
   9), and the Immersadesk (Figure 10). Text locations and key object placement was
   conducted to achieve this compatibility. The user interacts with LCD via a wand and stereo
   glasses (Figure 11, 12). By pressing a wand button, a virtual menu will remain about five
   feet away from the user. By moving one‟s hand the virtual mouse pointer will move
   accordingly. By pressing another button, the user may select a menu option. Sound effects
   governing the user‟s process provide another level of interaction with the package. The
   user has navigation capabilities allowing him/her to explore the various molecular
   alignments from different vantage points.

           Figure 8: CAVE                                   Figure 9: RAVE                        Figure 10: Immersadesk


             Figure 11: Crystal Eyes shutter                                       Figure 4.
               glasses and infrared emitter                                    Navigation Wand
3. Detailed Description of Components

3.1 Component template description
 Identification The name of the component.
     Type       A module, subprogram, data file, etc.
   Purpose      Requirements implemented by the design component.
                 What the component does, the transformation process, the specific inputs
  Function       that are processed, the outputs that are produced, where the data items are
                 stored, and which data items are modified.
                 The internal structure of the component, the constituents of the component,
Subordinates     and the functional requirements satisfied by each part, functions within a
                 How the component‟s function and performance relate to other components.
Dependencies     The other components that use this component. Interaction details such as
                 timing, interaction conditions (such as order of execution and data sharing).
                 Detailed descriptions of all external and internal interfaces as well as of any
  Interfaces     mechanisms for communicating through messages, parameters, or common
                 data areas. All error messages and error codes should be identified.
                 A complete description of all resources (hardware or software) external to
                 the component but required to carry out its functions.
                 The full description of the functions presented in the Subordinates
 Processing      subsection. Pseudocode may be used to document algorithms, equations,
                 and logic.
                 For the data internal to the component, describes the representation
                 method, initial values, use semantics, and format.
3.2 LCD

Identification   leecave.c
    Type         OpenGL CAVE C++ application
                 This program will delegate responsibilities through various CAVE
  Purpose        callbacks. It initiates, maintains, and ultimately disposes of shared
                 First, this module initializes the CAVE environment and subsequently will
                 exit the CAVE cleanly. This component initializes shared memory, which
                 is the data that both the frame (FRAME PROCESSOR) and display
                 callback (DISPLAY DRIVER) can access. Command line syntax is parsed
                 so the sound client and correct data set may be loaded. The initialization
                 (INITIALIZATION), frame, and display callbacks and their respective
                 arguments are set. The INITIALIZATION component will be called first;
                 the FRAME PROCESSOR will execute once per frame followed by two
                 executions of the DISPLAY DRIVER, assuming stereo mode.

                 The user exits the application through the menu or, depending on the
  Function       evolution of the wand, by button 4. This module will monitor the exiting
                 capabilities. Once an exit begins, the function will cleanup or delete any
                 shared memory.

                 The other feature this module provides is the navigation feature. The
                 analog of the wand is constantly polled and through these manipulations,
                 the user‟s status in the virtual world is constantly updated through world
                 coordinates. Automatic head tracking, provided by the CAVE library allows
                 the user to physically move around and also alter the world coordinates.
                 However, due to limited space and tracking proximity, the navigate ()
                 function allows the user to travel via the wand.
                 share_data (void);
                 check_syntax (int, char **);
Subordinates     navigate (void);
                 cleanup (void);
                 This function is the managing function that initiates the multiprocessing.
                 The order of execution is state here as being:

                 1.)   initializing shared memory
                 2.)   check syntax
                 3.)   initialize the CAVE library
                 4.)   execute an initialization callback
                 5.)   execute the FRAME PROCESSOR
                 6.)   execute the DISPLAY DRIVER for the right eye
Dependencies     7.)   execute the DISPLAY DRIVER for the left eye
                 8.)   navigation function

                 5, 6, and 7, as a set, are running concurrently repeatedly with 8.

                 Once exiting begins,

                 9.) clean up shared memory
                 10.) exit the CAVE environment
             As previously stated, the shared memory that allows interaction between
             the FRAME PROCESSOR and the DISPLAY DRIVER is created here.
             The command line arguments are passed into this component. The
             executable script will pass two arguments; however, the user states one
             argument. A sample execution run of the LCD Visualization system would

                lcd data_set_filename

             where data_set_filename is a data set expected to be in the
             data_sets/ subdirectory. The script, lcd, has an embedded argument,
Interfaces   which is the local host machine that will be used to connect the sound
             client to the SOUND SERVER component.

             If there are not three parameters when LCD fires, the error message

                ERROR:     usage lcd [data_set_filename]

             will be shown.

             Shared memory is allocated here.
             C++ Compiler. OpenGL and CAVE libraries. Header files include
Resources    <cave_ogl.h>, <malloc.h>, and <math.h>.
             share_data – This function allocates memory for a handful of pointers to
             be used in the program. The sole reason shared memory is needed is for
             the interaction between the FRAME PROCESSOR component and the
             DISPLAY DRIVER. The C function malloc () is used for the memory
             allocation. These variables are initialized to their default values.

             check_syntax – This function makes sure only three arguments are
             sent to the LCD component. The arguments are the executable file, the
             local host machine name, and the data set filename. The local host name
             is copied into the string variable client for later use when building the
             sound client. The data set filename is stored in data_filename and this
             filename will be expected in the subdirectory data_sets/.

Processing   navigate - This function is a looping construct that executes until an
             Exit selection has been detected. This procedure is scaled towards time.
             First, the time is calculated between the current execution of the function to
             the previous function. The analog joystick on the wand is monitored in two
             directions: the y direction, which is vertical, and the x direction, which is
             horizontal. If the intensity of the y direction is sufficient, the direction
             vector of how the wand is pointed is retrieved. This coupled with the
             intensity of the y direction, constant speed scale, and time differential
             brings the user to a new location in the world. The x direction is for
             rotating one‟s view. The higher the magnitude of this x analog, the faster
             the rotation. The CAVE library handles all timing, vector, translation, and
             rotation techniques.

             cleanup – This function simply utilizes the C function free and clears
             the previously allocated shared memory.
  Data       No data is utilized by this component.

Identification   init ()
    Type         CAVE callback function
                 This function sets up static geometry, OpenGL state variables, lighting,
                 fonts, textures, rods, and the sound configuration.
                 This component sets the background color to black and the shading model
                 to smooth for higher graphical quality. Two lights are supplied in the scene;
                 one on the left and the other on the right eight units away from the origin.
                 These lights exude a blue ambient and diffuse light with white specular light.
                 Therefore, depending on a materials shininess property, a white highlight
                 will appear on the object that light affects. A slight shininess property is
                 placed on the objects, namely the rods, in the scene.

                 A Helvetica 24 pt. font is created and is stored as a collection of display lists
                 that will be automatically called when text is rendered in the virtual world.
                 Three textures are allocated, configured, and stored in texture id variables
  Function       for later use when drawing the CHL HPVC logo, the menu, and the mouse
                 pointer. Display lists for any non-moving objects are defined in three
                 separate subordinates. The logo and menu display lists are simple
                 rectangles with their corresponding texture plastered. The mouse pointer is
                 a polygon that forms an arrow; in this case, the texture (“splat2.bmp”)
                 was cut up to fit the polygon.

                 Lastly, some other initializations are conducted. The sound client is created
                 and linked to the SOUND SERVER that is automatically running as a
                 daemon when the LCD script is executed. All LCD crystal objects are
                 configured and initialized to default values.
                 fontstuff (void);
                 load_bmp_texture (char *, int, GLuint *);
                 build_2D_pointer_list (void);
Subordinates     build_logo_list (void);
                 build_menu_list (void);
                 do_sound_init (void);
                 rod::init (void);
                 fontstuff () relies on “font2.h”, which will define a default Helvetica
                 24 pt. font. load_bmp_texture () stems from “texture.h”, which
                 performs image data extraction and texture binding. The rod class is called
                 with the rod initialization method. These methods are located in “rodr.h”.
                 This component is a one-time participant in the LCD Visualization package.
                 It prepares the world with basic but needed information and is never
                 executed again.
                 There are no arguments to this function and shared memory is not
                 C++ compiler. OpenGL, Cavernsoft G2 libraries. Header files include
 Resources       <cave_ogl.h>, “font2.h”, “texture.h”, “CAVERN.hxx”, and
             fontstuff – This function will create a font display list. To render any
             text at the current raster position, printString (char *) should be
             called with the argument being the text of interest.

             load_bmp_texture – This function will look at the texture file supplied
             and the parameter indicating the type of texture binding and parse the
             image file. The dimensions, planes, and bits per pixel of the image will be
             extracted and the r,g, and b data will be loaded into a buffer. This function
             only handles the Microsoft .bmp format with a power of two for both
             dimensions. A texture id variable is returned and may be used further in the

             build_2D_pointer_list – This function creates a two-dimensional
             pointer that may be used to select menu options. A texture map will be
             applied to the polygon. This pointer will be at the same z point in space as
             the front wall.

             build_logo_list – This function creates a display list with the CHL
             HPVC logo texture. Since, this logo will be rendered every frame, utilizing a
             display list will be faster and more efficient.

Processing   build_menu_list – This function will build a menu and texture it with
             “menu.bmp”. The menu will be at a constant depth and will give the user
             six options: Tag, Forward, Rewind, Restart, Reset, and Exit.

             do_sound_init – This routine will initialize Caversoft G2 with the call
             CAVERNinit (). Next, a CAVERNdb_client_c object known as
             sclient will connect to a host computer. The method init () will allow
             sclient this functionality. The exact statement is

                   sclient.init (“”);.

             “” will be the local computer name, which is an embedded
             argument in the LCD script, that is currently executing the LCD
             Visualization. This computer already has a sound server daemon
             (sserver.cxx) that has been polling for connections since run time.

             rod::init – This class method is executed for every molecular rod in the
             scene. This number depends solely on the data set. The LCD
             PREPROCESSOR component looks at the data set and calculates the
             number of rods in the file. This method initializes all rods to being untagged,
             calculates the degree offsets for each face of the manufactured cylinder,
             and sets a default radius.
             The only data inherent to this component is the Microsoft .bmp texture files.
             This format consists of a 18-byte header. Next, two integers occur, which
             are the width and the height of the file, followed by a short, which represents
             the bits per pixel.
             The next 24 bytes is information disregarded. The color information of the
             image, the red, green, and blue intensities at each pixel, rounds out the
             used portion of the format.
3.4 ROD

Identification   rodr.h
    Type         Rod class
                 The purpose of this class was to establish a foundation for each molecular
  Purpose        rod. By letting each rod contain information about itself, it was easy to
                 manipulate the rod and perform selection queries.
                 This component has several methods that are utilized by the LCD
                 Visualization system. Four public methods exist, which are init,
                 set_coord, draw, and tag_matched. This is the only interaction an
                 applications-programmer can have with this class. The class does have
                 private methods that actually construct the rod. The rod is built like a
                 cylinder. The reason that the cylinder quadratic provided by OpenGL was
                 not implemented was due to the perceived bugs accompanying several
                 rotations and translations. Therefore, this class creates the cylinder.
                 init (void);
                 set_coord (float, float, float, float, float, float);
                 draw (void);
Subordinates     get_normal_vector (int, int);
                 tag_matched (float *);
                 set_up_area (void):
                 This class is used by the INITIALIZATION, USER DISPLAY UNIT,
Dependencies     BUTTON 2 MONITOR, and FRAME PROCESSOR component with the
                 init, draw, tag_matched, and set_coord methods respectively.
 Interfaces      There is no interface for this class. Simply instantiate a rod class.
 Resources       C++ compiler. Header files include “rodr.h”.
                 init – This function initializes the rod to being unselected and a radius of
                 0.1. This value will be used to construct the rod. Also, the degree offset
                 between each face comprising the cylinder is calculated.

                 set_coord – Six floats, which are the two endpoints of the rod, are
                 passed into this function. These values are stored in the data members of
                 the class. The private method set_up_area calculates the x,y,z
                 locations of both endpoints for each face.

                 draw – Lighting is controlled in this routine. If a rod is selected, to create
 Processing      the illusion of that crystal being red, a red light must be activated because
                 without sufficient material properties, objects will be the color of the light.
                 A blue light is active when a rod is unselected; therefore, each object
                 instantiation will toggle the light based on that particular rod‟s selection
                 status. Normals are calculated based on the slope of the rod. The rod is
                 then drawn from the endpoints calculated by set_up_area.

                 get_normal_vector – This function stores up at least three points on a
                 plane so a normal can be calculated. The first argument represents the
                 ordering of the points because a counter-clockwise scheme is always
                 assumed. The second parameter indicates the face of the cylinder.
             tag_matched – The wand sword‟s location in world coordinates is
             passed into this function. This vector is checked against the bounding box
             of the object. If successful, it is checked against the area of the cylinder
             with a small percentage error. If this check is successful, the selection
             data member is toggled.
             set_up_area – The slope of the rod is found based on the two endpoint
             vectors to find the planes of interest. Next, using the C functions cos ()
             and sin () along with the radius, the faces needed to form a rod are
             set_coord () receives six values that are taken from the data set that
  Data       the LCD Visualization is built around. These values are the same x,y,z
             values representing the endpoints found in the file.

Identification   frame ()
    Type         CAVE callback function
                 This component will handle all pre-frame conditions in addition to file I/O.
                 Since the drawing callback should consist primarily of OpenGL, most
  Purpose        calculations, device code, and shared memory manipulation is handled in
                 this function.
                 This function handles all file operations including opening, closing,
                 rewinding, seeking, and reading of the data set. Frame numbers are
                 stored and updated for the forwarding, rewinding, status bar, and text
                 procedures. The modes of the LCD Visualization, “Movie Mode” and
                 “Frame Freeze”, are monitored as well as all implications of the wand

                 Initially, the data set file is open and will only be reopened after the end of
                 the data set file is parsed. Next, the shared memory variable
                 restart_flag is evaluated and if this action is selected from the menu,
  Function       frame numbers are reset and the first frame is processed from the data
                 set. Also, if the system is in rewind mode, a special variable called
                 cutoff is set allowing the file mechanism to loop back to the end of the
                 data set. Button 3 on the wand controls the mode of the application. If a
                 mode is switched, all menu option variables are reset to default values.
                 The BUTTON 2 MONITOR component handles all complications involving
                 button 2. Finally, a new frame‟s worth of data is processed and the frame
                 number is updated accordingly. It is of note that a rate variable is
                 induced into the FRAME PROCESSOR that controls how often input is
                 processed. Incrementing this variable causes the frame rates to lower
                 while decrementing results in a faster simulation.
                 open_files (void);
                 discard_text_line (void);
Subordinates     look_at_button_2 (void);
                 read_rod_data (void);
                 This component requires a data set that represents a molecular rod in the
                 following format:

                        x1 y1 z1 x2 y2 z2.

                 A dummy line separates each successive frame in the data set file. This
                 file is in ASCII format. To actually read this data, this component relies on
                 the ROD component.

                 This component is executed once per frame before the drawing callback,
                 or DISPLAY DRIVER component, is processed twice for each eye.

                 Shared memory flags are toggled here and are perused in the DISPLAY
                 DRIVER to produce the correct renderings.
             No arguments are passed to this component. Shared memory does
             provide a link between the FRAME PROCESSOR and the DISPLAY

             In the event of the subordinate function open_files () not being able
             to open an input file correctly, the error message

             Problems opening [filename]

             would be displayed.
             C++ compiler. CAVE library. Necessary include files are:
Resources    <cave_ogl.h>, <fstream.h>, “rodr.h”, and <string.h>.
             open_files - This function opens the data set file for reading. An error
             message is printed if this function cannot be done. In order for a new data
             set to be read by the LCD Visualization system, this function‟s open
             method must be replaced with the correct filename of the data set with its
             path relative to the current directory.

             discard_text_line – This function will process the garbage line that
             separates frames in the data set file. The first long integer on the line
             contains the frame number in the simulation. After that a series of
             characters are read until the newline character is found marking the end of
Processing   the line.

             look_at_button_2 – This component will be explained further in a
             module template in discussion of the BUTTON 2 MONITOR component.
             In general, this function polls button 2 on the wand and depending on what
             option and mode that has been previously selected, a particular action is

             read_rod_data – Each rod in the visualization has it‟s current
             coordinates stored in a massive array of rod instantiations. This procedure
             is executed once per frame so an animation can be created.
             The ASCII data set is processed in this component. It has for each
             molecular rod the representation

                   x1 y1 z1 x2 y2 z2.
             The two 3-tuples represent two endpoints of the molecular rod. For each
             rod in the simulation, this format remains consistent. There are a static
             number of rods and frames in the data set but these numbers may vary
             between data sets. In between successive frames, there is a garbage or
             dummy line that serves to separate a frame‟s worth of data.

Identification   look_at_button_2 ()
    Type         C++ function
                 The purpose of this component is to handle all the possibilities of pressing
                 or depressing button 2 on the wand for a variety of different option states.
                 This component first evaluates if the second button has been pressed and
                 released. Next, menu options are evaluated in this order: Tag, Forward,
                 and Rewind.

                 To determine if the virtual sword has tagged any particular rod, a looping
                 construct is performed in which all ROD components utilize their
                 tag_matched method. The coordinates of the end of the sword are sent
                 as arguments and a TRUE or FALSE is returned. If a molecule is tagged,
                 a sound message representing this action is sent to the SOUND SERVER
                 component to be processed and ultimately played by the audio system.
                 The tag_matched method will handle the color changes of the tagged
                 rods to isolate them for the user.

                 Next, the Forward option is analyzed. A message will be built that will
                 convey to the user what frame she is currently viewing. Countdowns that
  Function       will control how long the user will see this message are initialized. The
                 next frame‟s data is processed as the frame number variable, frame_num,

                 The Rewind option is somewhat analogous to the Forward option. The
                 frame number is obviously decremented. A special variable, cutoff,
                 controlled by the FRAME PROCESSOR, determines whether we are
                 rewinding from the start to the end. The proper decrementing along with
                 this special condition ensures that the proper frame is read. Another
                 message is built for user interaction along with the initialization of the print
                 countdown variables. Before the data of the new frame that is rewinded by
                 the user is read, the proper file location is found by a seekg () routine.
                 The LCD PREPROCESSOR component is responsible for creating an
                 array of file location addresses so a more efficient Rewind option can be
                 coded. Because each frame is of variable length, this array is a must.
                 rod::tag_matched (float *);
                 build_string (long);
Subordinates     read_rod_data (void);
                 discard_text_line (void);
                 The data set is processed in this component due to the Forward and
                 Rewind options that allow the user to move through the data set one frame
                 at a time. Shared memory variables are monitored and toggled and will
Dependencies     affect rendering techniques in the DISPLAY DRIVER component.

                 This component is a subcomponent of the FRAME PROCESSOR and is
                 therefore executed once per frame before the DISPLAY DRIVER.
                 No arguments are passed to this component. Shared memory is
                 manipulated. Cavernsoft messages are sent under the right conditions to
                 the SOUND SERVER component (See Interfaces section of MENU
                 PERFORMER component).
             C++ compiler. CAVE library. Header files include <cave_ogl.h>,
             “rodr.h”, “CAVERN.hxx”, <string.h>, and <fstream.h>.
             rod::tag_matched – The wand sword‟s location in world coordinates is
             passed into this function. This vector is checked against the bounding box
             of the object. If successful, it is checked against the area of the cylinder
             with a small percentage error. If this check is successful, the selection
             data member is toggled.

             build_string – This function will build a string for the Forward and
             Rewind option. The output string resulting from this function will resemble
             “Frame # out of #”. For example, Frame 3 out of 200 could be
             a possible output string and would be rendered virtually for user
Processing   notification.

             read_rod_data – Each rod in the visualization has it‟s current
             coordinates stored in a massive array of rod instantiations. This procedure
             is executed once per frame so an animation can be created.

             discard_text_line – This function will process the garbage line that
             separates frames in the data set file. The first long integer on the line
             contains the frame number in the simulation. After that a series of
             characters are read until the newline character is found marking the end of
             the line.
             The aforementioned ASCII data set is utilized with the following format
             representing an LCD crystal:

                   x1 y1 z1 x2 y2 z2.
             This represents a pair of rod endpoints in xyz space. All rods for every
             frame will have this representation. A garbage line that is ignored save for
             the frame number will divide frames.

Identification   display ()
    Type         CAVE callback function
                 This component is the driving rendering function responsible for the display
                 of all static and dynamic geometry in the scene.
                 The sound client, established by the INITIALIZATION component,
                 rechecks the communication link with the SOUND SERVER for a possible
                 broken connection. If the link is terminated or broken, the sound client will
                 reconnect. The toggling of a mode is rendered by text and is handled by
                 the USER DISPLAY UNIT. A countdown variable is passed to this
                 component notifying the function as to the length of time to display the text.
                 Furthermore, the status bar, indicating the data set frame position is

                 Next, button 1 on the user wand is monitored. This button handles menu
                 selections and depending on which option is preferred, the flow of the
                 DISPLAY DRIVER component will be altered slightly. As long as any
  Function       option remains unselected, the virtual menu and dynamic mouse pointer
                 will continue to be rendered. When an option is finally selected, the shared
                 memory variables tag_flag, forward_flag, and rewind_flag are
                 evaluated. If an option was toggled off, the corresponding toggle variable
                 is reset and print_flag is toggled on. This flag indicates that a
                 message will be displayed communicating the disabling of an option.
                 decision_time () is a subordinate that handles the toggling on of a
                 function and will be highlighted in the MENU PERFORMER component.
                 tag_flag is also evaluated, and, if found to be TRUE, perform_tag
                 () will draw a five foot sword controlled by the wand that will allow a user
                 to tag individual molecular rods. Finally, any disabling option text is printed
                 for a short period of time.
                 draw_screen (int *, int &);
                 draw_status_bar (void);
                 draw_pointer (void);
Subordinates     decision_time (float *);
                 perform_tag (void);
                 print_text_option (char *);
                 As previously stated, this component is executed once in mono mode and
                 twice in stereo mode. The order of execution is as follows:

                 DISPLAY DRIVER, etc. for mono and
                 (left eye), FRAME PROCESSOR, DISPLAY DRIVER (right eye), DISPLAY
                 DRIVER (left eye), etc. for stereo mode.

                 Shared memory is manipulated to control the flow of execution in the
                 No arguments are passed to this component; however, the common data
                 area is updated and evaluated.
             C++ compiler, OpenGL, CAVE library. Header files include
Resources    <cave_ogl.h>, “CAVERN.hxx”, and <string.h>.
             draw_screen – This function is also known as the USER DISPLAY UNIT
             component. It draws all of the rods at their proper locations. It also
             renders the proper mode, “Movie Mode” or “Frame Freeze”, in the form of
             text. Lastly, the HPVC CHL logo is rendered in the upper left corner of the
             front wall.

             draw_status_bar – This function will draw a status bar notifying the
             user how far he/she has traveled through the data set. This tool is very
             similar to a file download update in that the bar continually progresses and
             the percentage is constantly updated.

             draw_pointer – This function draws a virtual pointer on the front wall
             approximately five feet away from the user in physical coordinates. The
             user can control with his arm movements the mouse pointer on the xy
             plane. “splat2.bmp” provides the texture of the pointer. CAVE calls
             are used to retrieve the direction and position of the wand to correctly
             position the mouse pointer in the virtual world. The physical coordinates of
Processing   the tip of the mouse pointer are returned from this function.

             decision_time – This function constitutes the MENU PERFORMER
             component. Basically, this function handles the toggling on of a menu
             option and the respective processing. Selection, error, and exit sound
             messages are also sent in this function.

             perform_tag – This function is very similar to that of draw_pointer.
             The wand‟s direction and position vectors are utilized to calculate an
             endpoint for a virtual sword that is rendered. The sword is composed of a
             semi-thick line with a point on the end. This point must be placed within an
             area of a rod to be tagged. The world, not physical, coordinates are
             returned from this function in order to be matched to a rod‟s set of

             print_text_option – This function is in charge of simply printing a
             desired message, which is the lone argument, at the bottom of the front
             wall. The text will appear white.
             “splat2.bmp” is a texture file that is used to texture the mouse pointer.
             This is a Microsoft .bmp image file that consists of an 18-byte header.
             Next, two integers occur, which are the width and the height of the file,
             followed by a short, which represents the bits per pixel.
             The next 24 bytes is information disregarded. The color information of the
             image, the red, green, and blue intensities at each pixel, rounds out the
             used portion of the format.

Identification   draw_screen ()
    Type         C++ function
                 The purpose of this component is to draw all the rods at their locations for
  Purpose        the current frame. The logo and mode messages, if any, are also
                 Initially, as with any OpenGL program, the screen is cleared to some
                 predetermined background color. Next, a looping construct renders each
  Function       rod in world coordinates for the current frame with the rod::draw
                 ()method. Provided, a mode has been toggled, a message is rendered
                 for a period of time on the front wall. Lastly, the logo is drawn.
                 rod::draw ();
Subordinates     put_up_message (int);
                 draw_logo (void);
                 This component, evoked by the DISPLAY DRIVER component, relies
                 tremendously on the ROD component. It will handle the rendering of the
                 crystals based on the information that it has obtained from other
                 components regarding the location and selection status of the crystals.
Dependencies     Thus, this component is dependent on “rodr.h”.

                 countdown controls the rendering of the mode text. This variable is
                 decremented and, until it reaches zero, the message will be displayed.
                 Two arguments are passed into this function. The first argument, flag2,
                 represents what mode the application is currently in. Therefore, if the
                 mode needs to be printed, the proper text is displayed. countdown is the
                 timing mechanism for the text rendering. As long as this variable is
                 greater than zero, a text rendering will occur.

                 flag2 and the array of ROD components are part of shared memory that
                 are evaluated and utilized in this component.
                 C++ compiler, OpenGL, CAVE libraries. Header files include
 Resources       <cave_ogl.h>, “rodr.h”, and “texture.h”.
                 rod::draw - Lighting is controlled in this routine. If a rod is selected, to
                 create the illusion of that crystal being red, a red light must be activated
                 because without sufficient material properties, objects will be the color of
                 the light. A blue light is active when a rod is unselected; therefore, each
                 object instantiation will toggle the light based on that particular rod‟s
                 selection status. Normals are calculated based on the slope of the rod.
                 The rod is then drawn from the endpoints calculated by set_up_area.
 Processing      put_up_message – This function displays a user helpful message in
                 physical coordinates notifying the user of what mode currently exists. The
                 text will appear white. The lone argument dictates which message gets
                 rendered. The possible messages are “Movie Mode” or “Frame

                 draw_logo – This function draws the HPVC CHL logo in the upper left
                 corner of the front wall. This rectangle is textured with “logo.bmp”.
       “logo.bmp” is a Microsoft .bmp texture file. This is a Microsoft .bmp
       image file that consists of an 18-byte header. Next, two integers occur,
       which are the width and the height of the file, followed by a short, which
       represents the bits per pixel.
       The next 24 bytes is information disregarded. The color information of the
       image, the red, green, and blue intensities at each pixel, rounds out the
       used portion of the format.

Identification   decision_time ()
    Type         C++ function
                 The purpose of this component is to set the proper shared memory
                 variables responsible for any menu option. Certain selections cannot be
  Purpose        made based on the application mode. All of these constraints are checked
                 and sound effects are also handled here.
                 This component is a subordinate of the DISPLAY DRIVER and, when
                 called, receives the physical coordinates of the virtual mouse pointer.
                 These coordinates are compared to determine which selection, if any, was

                 If the Restart option is selected, perform_restart will be evoked.
                 Also, the select sound message will be sent to the SOUND SERVER and
                 processed representing a valid selection.

                 If the Reset option is selected, perform_reset will be evoked. Again,
                 the select sound message will be sent to the SOUND SERVER and
                 processed representing a valid selection.

                 If the Tag option is selected, the proper mode will allow the option to
                 continue. A tag is prohibited in “Movie Mode” and will result in an error
                 sound effect. A text message steering the user to change modes is
  Function       subsequently displayed. However, if the current mode is “Frame Freeze”,
                 a valid selection sound effect is overheard and an enabling message is
                 rendered. The shared memory variables tag_flag and print_flag
                 are properly set.

                 Both the Rewind and Forward options are similar to that of the Tag option.
                 These options can only be used in “Frame Freeze” mode; thus, an attempt
                 to select these options in “Movie Mode” results in an error message and
                 sound effect. If the options are valid, congratulatory messages appear on
                 the front wall proclaiming the enabling of the option and the SOUND
                 SERVER processes a valid selection sound file. The appropriate shared
                 memory variable, rewind_flag or forward_flag is toggled along with

                 Lastly, the Exit option will result in the exit sound and a call to
                 perform_restart (void);
Subordinates     perform_reset (void);
                 perform_exit (void);
                 The DISPLAY DRIVER calls this program to monitor the virtual menu for
                 every frame. If any selections are made, shared memory is updated so the
                 DISPLAY DRIVER can render the appropriate geometry.
                 The coordinate data passed by the DISPLAY DRIVER controls the flow of
                 execution. If the coordinates are invalid, the function quickly exits. Valid
                 coordinates are traversed by an if-then-else construct.
             Physical coordinates are the arguments passed in from the DISPLAY
             DRIVER. It is a 2-tuple representing the x and y location in physical
             space. Because the virtual menu is always rendered in the same location
             every frame, a coordinated check can determine a possible selection.

             The common data area is significantly updated via this component. This
             function basically sets the path of the DISPLAY DRIVER by manipulating
             the shared memory variables.

             perform_exit () prints to standard output the following line when

             You pressed Button #4.

             The exiting signal is to set button 4 of the wand to TRUE. Most wands do
             not carry this button so the virtual menu is the only way to exit the
             application. However, if you have a fourth button, a quicker exit would be
             to simply press button 4 on the wand.
Interfaces   Cavernsoft put () methods send data to the SOUND SERVER in the
             form of character data. The SOUND SERVER who then uses the SGI
             routine sfplay to process the appropriate sound file parses the character
             data.The put () method for the CAVERNdb_client_c class and has
             the following look:

                client.put (“path”, “key”, (char *) data,

             The first argument of the put () method indicates a relative path from
             any node, client or server, where messages can be logged. The second
             argument is the key argument, which describes the data being sent over.
             This argument is important because quite often structures or arrays are
             sent and it is the programmer‟s responsibility to cast and pack data. The
             key gives him/her a hint of the type of data. The third argument, data, is a
             character pointer, which is the starting address of the block of data being
             sent. Lastly, the fourth argument is the size, in bytes, of the data being

             C++ compiler. CAVE library. Header files include <cave_ogl.h>,
             “CAVERN.hxx”, <string.h>, and <fstream.h>.
             perform_restart – This function will trigger the flag that ultimately
             rewinds the data set file to the beginning. The text “Data set has
             been reinitialized” is stored in a text buffer. The two shared
             memory variables print_flag and restart_flag are toggled on.

             perform_reset – This function will trigger the flag that ultimately sets
             the user‟s viewpoint back to the origin. The text “Viewpoint has been
             returned to the origin” is stored in a text buffer. print_flag is
             toggled on to enable the future rendering of the text. The CAVE function
             CAVENavLoadIdentity () loads up the identity matrix in world
             coordinates and automatically transports the user.

             perform_exit – This function will trigger the CAVE constant
             CAVEBUTTON4 that ultimately exits the application.
             No data is inherent to the component. Shared memory, however, is
  Data       manipulated.

Identification   prepro.c
    Type         Preprocessing C++ program
                 The purpose of this component is to avoid some real time calculations with
  Purpose        the LCD Visualization program. Therefore, this program does some file
                 position calculations that will be useful mainly for the Rewind menu option.
                 The program will first check the syntax of the command line to ensure the
                 program is being used correctly. Next, it will open the input file (data set
                 file) and the output file (“frame.h”). Next, an examination of data line by
                 line is made to determine how many rods exist per frame. It will then
                 document the output file with the name, author, and purpose of the output
                 file. Two constants denoting the number of frames and rods comprising
                 the simulation is detected from the data set file. This value is written as a
                 constant into the generated header file. Lastly, both files are closed.
                 check_syntax (int);
                 open_files (char *);
                 find_num_rods (void)
Subordinates     write_header_comment (void);
                 build_2_constants (int);
                 close_files (void);
                 This component is a preprocessing component. When a new data set is to
                 be fed into the application this component must ingest the said data set
                 and output it‟s associated header file. This component builds a header file
                 with three main variables used by the LCD Visualization package.
Dependencies     NUM_FRAMES symbolizes the number of frames in the simulation.
                 NUM_RODS represents the number of crystals in the simulation. frames[]
                 contains the byte address of each frame so the FRAME PROCESSOR can
                 easily seek backwards to the correct location.
                 The argc and argv parameters are loaded at run time. These variables
                 are valuable since syntax must be checked to ensure proper use of the
                 program. If the syntax is incorrect, the following error message is

                 Usage: prepor <filename>
                 <filename> refers to the data set.

                 argc obviously refers to the number of arguments, which should be two.
 Interfaces      argv is an array of character pointers that contains the actual command
                 strings. argv[1] represents the data set filename.

                 If the data set file could not be correctly opened, the resulting message is

                 [data set filename] could not be found or opened

                 and for an improper opening of the output file, the message is

                 There was a problem opening the output file -> frame.h.
 Resources       C++ compiler. Header files include <fstream.h> and <stdlib.h>.
             check_syntax – This function checks to make sure there is only one
             parameter on the command line. It will exit if this is not the case with a
             hopefully useful error message. argc is passed into the function and is
             evaluated. If it is not „2‟, the exit will happen.

             open_files – This function is responsible for opening the input file (data
             set) and the output file (“frame.h”). If there is a problem with either,
             then an error message will be printed as the program exits.

             find_num_rods – This function will loop through the first five fields of the
             data file. The file reader then looks at the next character. If the next read
             yields a newline character, then the dummy line has been encountered
             marking the end of the frame. All along, a counter has been counting the
             number of lines that represent the rods.

             write_header_comment – This function just writes some comments
             that may prove to be useful in “frame.h”. The information written
             consists of the name of the header file, author, and purpose.
             build_2_constants – This function puts the three necessary variables
             to be used by the LCD Visualization application in “frame.h”. First, it
             constructs the frame array, which will hold the file position of each frame.
             Next, it will build two constants representing the number of frames and
             rods in the data set. In order to build the frames[] array, the tellg ()
             function was used to retrieve the file location. Looping through the data
             set file, each line was ingested and ignored. Once the dummy line
             separating frames was processed, tellg () returned the file position of
             the next frame. This value was then stored into the array. NUM_FRAMES
             was calculated based on how many frame file positions were stored.
             NUM_RODS was passed in as the lone argument and was calculated by the
             function find_num_rods (). The number of rods could be found since
             the garbage line has more than six fields. Therefore, a counter variable
             could track the number of six-field lines before the garbage line.

             close_files – This function will simply close the data set file and the
             output file “frame.h”.
             The data set file is needed in order for the LCD PREPROCESSOR
             component to correctly execute. This data set file must be in the correct
             format which is a 6-tuple separated by whitespace. The first three and
  Data       second three fields represent two endpoints of a molecular crystal. When
             all rods for a frame are represented once per line in ASCII format, a
             dummy line containing no relevant information save for the frame number
             separates individual frames.

Identification   sserver.cxx
    Type         Caversoft C++ program
                 This component will create a CAVERN_db server/client pair to handle
                 incoming sound messages. The client created will define a callback that
  Purpose        will automatically be fired upon reception of a message. The information is
                 parsed and the appropriate sound file is processed with the SGI audio
                 utility sfplay.
                 Cavernsoft G2‟s environment is initialized and a CAVERN_db_server_c
                 and CAVERN_db_client_c instantiation is made. These objects are
                 named server and client respectively.

                 First, a server is created on the local machine via the init () method
  Function       and all clients will subsequently connect to this machine. Next, the local
                 client will repeatedly try to link to the server until a connection is
                 determined. The client then defines a callback function, incoming_data
                 (), which will sift through messages and ultimately process the file.
                 Lastly, both the server and client must continually process in a looping
                 construct to continually poll new connections and/or new incoming data.
                 incoming_data (char *, char * key, void *);
Subordinates     make_sound (char *);
                 This component must be executed before the LCD Visualization system
                 because the client created in the INITIALIZATION component must
                 connect to the server created in the SOUND SERVER. Unlike the local
                 client that will repeatedly attempt a connection, the INITIALIZATION client
                 tries only once.

                 This component is constantly running and will terminate based on the exit
                 message sent from the LCD component. Two clients will connect to the
                 server generated. The purpose of the local client is needed simply to
                 define a user callback on incoming data. The flow of control starts by a
                 user performing an action that requires a sound effect. The LCD client
                 sends a message to the server. The server, being reflective in nature,
                 sends it to all other clients connected to it. This would be the local SOUND
                 SERVER client. When receiving the message, the callback executes, the
Dependencies     message is parsed, and the sound file is processed. Therefore, there is no
                 need for the LCD client to establish a programmer-defined callback due to
                 the one-way messaging.

                 This module depends on the machine; wherever this file is stored, the file
                 must be edited to attach the local client to this machine‟s server. The

                    while (client.init (“[]”) …

                 should be updated with the name of the local host being the parameter to
                 the init () method. Also, the locations of the sound files will differ from
                 machine to machine. In the make_sound () subordinate, make sure the
                 sound files have the proper absolute paths.
             argc and argv are passed in from the command with the lone
             parameter being the local host machine name that the local client can use
             to connect to the server. Messages are received in the callback function
             with the get () method. The format of receiving a message in Caversoft
             G2 with the CAVERN_db_client_c instantiation is

                char * data = client->get (path, key, &size);.

             The resulting bytes are stored in a character array in this case, data. This
             data may be cast by the programmer or left alone since it depends on the
             message. path represents a file directory path to store this data in a
             simple database log entry form. key identifies the type of message and
             sometimes may act as the message itself. size is a return parameter
Interfaces   that indicates how many bytes in length the message is. All messages are
             stored as strings and are parsed with strcmp () to figure the correct
             sound file.

             If the server could not be established, the readout

                Could not initialize the server

             would be displayed. Also, if the client could not successfully connect to the

                The server is not running currently

             would be shown.
             C++ compiler. Cavernsoft G2 library. Header file includes
Resources    “CAVERN.hxx”, <fstream.h>, <unistd.h>, and <stdlib.h>.
             incoming_data – This function is a callback function which will receive
             the data and play the corresponding sound of the message. Using the get
             () method described earlier in the Interfaces section, the data is received.
             Next, it is sent to the function make_sound () for processing.
             Afterwards, the data extracted from the get () method is deleted.

             make_sound – This subordinate is actually called from the callback and
             not the SOUND SERVER component but it is a key component regardless.
Processing   The lone parameter is a character string, which is, in essence, the id of the
             sound to be played. This string is parsed and will be deemed as one of
             four types of messages: “Select”, “Tag”, “Error”, or “Exit”.

             Each one of these message ids has it‟s own sound file. In the event of the
             “Exit” message, erased.aiff is played by the sfplay system utility
             and subsequently, the SOUND SERVER component exits.

             All sound files are in .aiff format.
             The data internal to this component is received through Cavernsoft G2
  Data       messaging in the form of strings.
4. Reuse and Relationships to Other Products

   This project was easily implemented by reusing some standard functions that are necessary
   for any well written graphical package. Fonts and textures were initialized and loaded
   through functions in texture.h and font2.h. These files are used in any program
   where text or an imaged polygon is needed.

   The utility function ltoa () is found in the header file ltoa.h. This function takes any
   long integer and results in the same integer converted to a string. This is useful when
   displaying dynamic numerical text. This function is always a lifesaver because the standard
   C++ library does not support this utility.

   Lastly, a rod class was built that creates it‟s own cylinders. Any user may use this class and
   have access to all of its public methods. One distinct advantage to using the class over the
   OpenGL cylinder structure is that the rod class, found in rodr.h, allows the user to set
   endpoint coordinates. No translations or estimates of length are needed.

   The package itself can be reused with different data sets. A couple of editing procedures
   and preprocessing steps are needed to achieve this task. First, running the new data set as
   an argument to the executable prepro must generate a new frame.h header file. The user
   must also change the sole parameter to the data set of interest for the executable script.

   If a programmer or user wishes to change the varying sound effects that represent different
   degrees of interaction, simply replace the calls to the sfplay utility in the make_sound
   function, located in the SOUND SERVER component, with different file names. Make sure
   that they are file types that can be processed by sfplay. Also, make sure you specify the
   correct path to the file.

5. Design Decisions and Tradeoffs

   A rod class was implemented because of the advanced calculations needed to perform the
   same functionality with the OpenGL supported cylinder. In OpenGL, the cylinder construct
   is drawn down the z-axis. To manipulate this cylinder in 3D space, translations and
   rotations must be made. The data set provides us with two endpoints representing the tail
   and head of the molecular rod. The proper rotation angle as well as translation vector would
   be needed. This effort was attempted; however, the correct rotations and translations did
   not translate into the correct rendering because of possible OpenGL cylinder bugs.
   Therefore, the LCD Visualization system constructs its own cylinders by finding the nearest
   endpoints and the slope. Next a series of quad faces are drawn around the slope vector
   creating a cylinder. No rotations or translations are needed thus reducing potential errors.

   The SOUND SERVER component was added in the final rendition of the package to utilize
   another process and not clutter up the main processor. By allowing messages to be sent, a
   separate processing was handling the sounds. It is a good idea to separate sound from
   graphics for all applications. Initially, the Vanilla Sound Server was utilized. With this
   server, calls were made from the LCD component holding up the flow of execution. The
   sounds would be slightly distorted and a slight lag time would become prevalent after a
   sound effect. Because Cavernsoft allows non-blocking sends, the flow of control is not
   halted. The only down side is this eliminates an all-in-one package since the SOUND
   SERVER component must be executed in addition to the LCD component. However,
   through scripts, this becomes transparent and meaningless to the user.
6.0 Use

  6.1 Preliminaries

     The following header files are needed in the directory where the executable is: rodr.h,
     font2.h, texture.h, frame.h, normal.h, and ltoa.h. These files will now be
     outlined as to why they are being used.

     rodr.h - This header file contains the rod class that handles the positioning, color, and
     inner states of an individual LCD crystals.

     font2.h – This file provides the user with the mechanism for creating a series of
     display lists representing a font and with the means of rendering text.

     frame.h – This frame is a generated header file from the LCD PREPROCESSOR
     component known as prepro. It contains file position addresses that allow the Rewind
     function to be implemented faster and more efficiently.

     normal.h – This header contains functions that will calculate a normal from the
     surface face in question. A vector cross product is used to achieve this. In essence, this
     file controls how light is reflected off of geometry, in this case, a molecular rod, giving a
     more realistic look.

     ltoa.h – This file provides a convenient utility of converting a long integer into its
     corresponding string.

     The data set should be in the proper format that has been discussed throughout the
     document. The data set file should be preprocessed by the LCD PREPROCESSOR
     component prepro to generate the necessary frame.h header file. To do this the
     user types

          prepro [data set filename]

     where [data set filename] is the name of the data set of interest. Make sure the
     resulting frame.h is located in the same directory as the LCD exectuable.

     Lastly, make sure the SOUND SERVER component, sserver.cxx, correctly knows
     the paths of the various sound files. Also, the local client of the SOUND SERVER needs
     to point to the correct machine that the SOUND SERVER is residing as well.

     A compilation script is provided with libraries entailing OpenGl, CAVE, Cavernsoft, X
     Windows, and MPI. The following library options are found in the Makefile script

          -lglut –lGLU –lGL –lm –ll –lX11 –lXi –limage –lmpi –lXmu
          -lXext –lcave_ogl.

     The Caversoft library must also be linked during compilation. The
     CAVERN_APPLICATION_INCLUDES file, located wherever the Cavernsoft distribution is
     placed on the machine, contains several script variables that are included in the
     compilation script.
6.2 Execution

   Once the preliminary steps have been satisfied, the execution script, lcd, can be
   executed. lcd should have the following lines


          sserver $HOSTNAME &
          leecave $HOSTNAME $1

   where sserver and leecave represent the SOUND SERVER and LCD components
   respectively. Also, absolute paths of these executables should be provided although
   they have been omitted in order for clarity. $HOSTNAME is an environment variable that
   will contain the name of the local host machine. $1 will contain the argument that is
   passed in and will represent the data set filename expected in the data_sets
   subdirectory. So, to run the LCD Visualization package with a new properly formatted
   data set called lee7.dat, the command would resemble the following

      lcd lee7.dat

To top