New Class Graphics Documentation

Class Graphics is introduced in SansGUI version 1.2. This section contains a copy of the documentation extracted from the SansGUI Getting Started guide and the Reference Manual that are related to this new class.

Point of Attraction 5: Solid: A new stop in the SanGUI getting started tour.
Class Graphics Reference Page: A detailed documentation of the new Graphics class.

Point of Attraction 5: Solid

Introduction

In this example, we explore the new interactive 3D graphics features in the SansGUI Modeling and Simulation Environment and demonstrate how SansGUI supports OpenGLŽ graphics programming directly in Microsoft Visual C++ and Compaq Visual Fortran. With the new Graphics class introduced in SansGUI version 1.2, simulators can incorporate 3-dimensional graphics for scientific or engineering visualization and data exploration.

The Solid simulator contains a class named Solid, which is derived from the new Graphics class. The code in Solid simply calls the OpenGL Auxiliary Library routines aux{Solid|Wire}* to draw 3-dimensional objects. The shapes of the objects can be Tetrahedron, Cube, Octahedron, Dodecahedron, Icosahedron, Box, Cylinder, Cone, Sphere, Torus, or Teapot. They can be displayed in either solid rendering form, or simply in wire frame. Three primitive colors, cyan, magenta, and yellow, can be applied to the objects by the user.

The Solid simulator uses the cycle simulation mechanism in SansGUI to control simulation runs. It rotates the displaying object along the vertical (Y) axis by a hard-coded 5 degree increment each time. The simulation control object has its Ending Cycle Number set to 0, meaning that the simulation will run forever. You will need to use the control buttons in the Run toolbar to stop or pause a simulation.

Hands-On Session

To quickly try out the new 3D graphics features, open the Shapes Project Model located in the samples\Solid subdirectory of the SansGUI installation directory to load it into the SansGUI environment. The Execution dialogs, including three Graphics dialogs and the Plot Results dialog, will be automatically opened. You can click on the Run In-Process button in the Run toolbar to start the simulation. Should the Execution dialogs not displayed automatically, you can open them manually with the following procedures:

Select the Object tab (the first tab) from the Left Pane.
Scroll the Tree View to the bottom to reveal MySolid, Teapot, and Torus 3D graphics objects.
Right click on MySolid and then select View Object from the context menu.
Do the same on the Teapot and Torus objects to open their Graphics dialogs.
Click on the Plot Results button in the Run toolbar to obtain the Plot Results dialog.

The simulator in this example rotates the graphic objects about the vertical (Y) axis with a specific increment. The Plot Results dialog shows the trace of the Y-rotation angles through time. The horizontal scroll bar has its scroll box running from left to right, corresponding with the rotation angles that are ranged from -180 to +180 degrees. While it is moving, you can grab the scroll box and drag it to any position in the scroll bar to see how the strip chart in the Plot Results dialog responds to your change. With this feature, the simulator can be implemented to allow users to fine tune control variables even when the simulation is running.

Now, let's explore a few more SansGUI run-time features and change some of the 3D object properties:

While the simulation is running, click on the Pause/Resume button next to the Run In-Process button in the Run toolbar. The simulation will be paused.
Click on the Step button next to the Pause/Resume button to perform single stepping. Do it a few times to see how the 3D displays and the result plot change.
At this moment, move the Plot Results dialog away to reveal the Right Pane of the Shapes :Project Model. You can maximize the window by clicking on the Maximize (middle) button on the right side of the Windows title bar of the Project Model so that its Right Pane can be enlarged.
On the Left Pane, scroll down the Tree View so that MySolid, Teapot, and Torus objects are visible. Click on any one of them. You will see the properties of the objects being listed in the Right Pane.
Click on the Solid attribute of the Teapot object under the iType column and select Wireframe. Notice now the Teapot is displayed with a wireframe mesh.
Change any of the properties to your preferences and continue to play with simulation runs, pausing, and single stepping.
Play with object rotation by moving the horizontal and vertical scroll boxes in the Graphics window. You can perform these operations whether the simulation is running or not.

Zoom in and out of the scene by pressing the + or - keys on the numeric keypad.

Please consult the User Interface Controls section of Class Graphics in the SansGUI Reference Manual for a summary of the default user interface operations implemented in the Solid simulator. In the next demonstration, we will explore the user selection feature in the Graphics windows. In this Solid example project, it simply echoes the selection points in the Message View. Other applications may handle the user selections differently.

From the Bottom Pane, click on the Message tab to reveal the Message View.
In a Graphics window, such as the one displaying the Teapot object, move the mouse pointer to any point within the window, press down the left mouse button, drag the mouse pointer while the mouse button is still down, and then release the mouse button for a rectangular selection area.
Watch the message posted in the Message View. The coordinates of the two corner points are displayed.

Repeat the selection on a different Graphics window and examine the message in the Message view. These messages are associated with different objects. The Properties dialogs of the objects can be opened by double clicking on the object names or selecting Properties from the right-click context menu.

In order to capture the 3D graphics images for publication purposes, SansGUI supports hard-copy printing, copying to Windows clipboard, and exporting images to Bitmap (.BMP) or JPEG (.JPG) files. All of these functions can be performed by selecting the corresponding menu items from the right-click context menus in the Graphics windows. For more details, please consult the Solid simulator on-line manual, which can be accessed from the About SansGUI dialog box:

Select Help from the pull-down menu.
From the pull-down menu, select About SansGUI...
In the Installed Simulators list box in the About SansGUI dialog, locate the icon with the name Solid.
Right click on the Solid icon, a What's this? menu is displayed.
Click on What's this?, your Internet browser will be invoked to display the Solid simulator on-line manual.

On-line manual pages specific to Solid classes and objects can also be accessed by clicking on the large icon buttons at the upper-left corner of the associated Properties dialogs.

Developer's Corner

Once you have the SansGUI Professional Edition license key installed, you can open the Schema Definition file of Solid (Solid.sgs) from the samples\Solid subdirectory of the SansGUI installation directory. In addition to the regular In-Process and External Process simulation control classes, there is only one class, <Reference>Graphics.Solid, created for this particular simulator. You can find its definitions with the following procedures:

Open the Solid.sgs Schema Definition file from the samples\Solid directory.
Select the Reference tab (the third tab) in the Left Pane.
Click on the Solid class to see all the attributes being displayed in the Right Pane.
The attributes with a light yellow color, or the background color set for pop-up tips in your Windows environment, are inherited from its parent, the Graphics class. These intrinsic attributes are updated by SansGUI in the SansGUI Data Objects, used by SansGUI to communicate with the simulator.
The last four attributes, iShape, iColor, iType, and fAngle, are created specifically for the Solid simulator. The first three are enumerated items while the last one contains a copy of the Y-Axis rotation angle for plotting purposes.

Double click on the Solid class in the Left Pane to open its Class Properties dialog.
From the Identity tab, you can see the Documentation Location field is filled with an HTML file path. We use this to indicate which on-line page shall be opened when the user clicks on the large icon button in the Graphics Object Properties dialogs.
Click on the DLL tab. You can see four DLL function entry points being checked: Begin Run, Pre-Evaluation, Evaluation, and Post-Evaluation. Please consult the Class Graphics reference pages in the SansGUI Reference Manual for their function call semantics.
Click on the Cancel button to close the Class Properties dialog.

The project workspaces for building the Solid simulator DLL in Microsoft Visual C++ 6.0 and Compaq Visual Fortran 6.x are included in the samples\Solid\Solid_1_0 and samples\Solid_Solid_1_0F subdirectories, respectively. You can load any one of the two project workspaces to access the source code, modify them, and the rebuild the DLLs. There is only one source file associated with the <Reference>Graphics.Solid class in each project workspace. It is the only one needed in the Solid simulator. Please read the comments in the source code and consult the Class Graphics reference pages to find out how to set up the rendering context, respond to window resizing messages, render scene, and respond to user selections. If you would like to rebuild the DLL, please read the OpenGL Auxiliary Library bug fixes information in the Acknowledgements section right after the Developer's Corner.

The intrinsic attributes in class Graphics are defined as hidden; they are hidden from the user in the SansGUI Run-Time Environment with a password protection. The password for the Solid simulator is actually not set (or set as a blank string). You can enter a Service Session by selecting Tools>Service Session... from the pull-down menu in the Shapes Project Model and click on the OK button without entering anything in the Enter Password field. Once a service session is entered, all the hidden attributes associated the the Graphics objects can be revealed in the Right Pane and in the Object Properties dialogs.

The doc\Solid subdirectory of the SansGUI installation directory contains a set of hand-crafted documentation files written in the Hyper-Text Markup Language (HTML). These files demonstrate one means to incorporate on-line help document into the SansGUI environment. The HTML file names serve as the document entry points of the simulator classes and are entered in the Class Properties dialogs in the Schema Definition of Solid.

Acknowledgements

The Solid example uses aux{Wire|Solid}* 3D object drawing routines in the OpenGL Auxiliary Library from Silicon Graphics, Inc. The original GLAUX.LIB distributed with Microsoft Windows contains quite a few bugs in these drawing routines and was compiled and linked with using single-threaded libraries option. It caused abnormal drawing behavior and conflicted with C run-time library routines in the Solid example. We would like to thank Richard S. Wright, Jr., the author of OpenGL SuperBible, for sending us the GLAUX source code with his bug fixes and his permission to redistribute the fixed code.

We have created a project workspace in Microsoft Visual Studio and rebuilt the library with the Multi-threaded DLL option set so that the C run-time library will not be conflicted. The newly built GLAUX.LIB can be found in the sys subdirectory of the SansGUI installation directory. You should backup the old GLAUX.LIB and use the new one if you would like to rebuild Solid or create any project that uses GLAUX. The source files of GLAUX are included in a zip file named GLAUXM.ZIP, which can also be found in the sys subdirectory.

References

Fosner, R. 1997. OpenGL Programming for Windows 95 and Windows NT, Addison-Wesley, Reading, Massachusetts.

Lawrence, N. 2002. Compaq Visual Fortran: A Guide to Creating Windows Applications, Digital Press, Boston, Massachusetts.

Woo, M., Neider, J., Davis, T., and Shreiner, D., OpenGL Architecture Review Board. 1999. OpenGL Programming Guide: The Official Guide to Learning OpenGL, Version 1.2, 3/e, Addison-Wesley, Reading, Massachusetts.

Wright, R. S., Jr., and Sweet, M. R. 1999. OpenGL SuperBible, 2/e, Waite Group Press, Corte Madera, California.

Class Graphics Reference Page

Class Graphics is an intrinsic class in SansGUI that supports 3-dimensional (3D) graphics object display for scientific or engineering visualization and data exploration. It provides simulation developers with a framework that simplifies multi-threaded, multi-windows, 3D graphics programming, using the industry-standard OpenGLŽ API from Silicon Graphics, Inc. Interactive 3D graphics operations, such as translation, rotation, zooming in and out, and user selection, are supported with user interface controls in this class, handled automatically by SansGUI. However, the actual responses to these controls may be modified by the simulation developer according to the requirements of the subclasses in the simulators.

Attributes

Class Graphics contains intrinsic attributes useful for windows and 3D graphics operations. These predefined attributes are hidden attributes, which can be accessed programmatically or examined in a Service Session in the SansGUI Run-Time Environment. Similar to the Collection intrinsic class, class Graphics can be extended to include additional attributes the simulation developers need. This class is a reference class, meaning that its subclasses and their deriving objects can be referred to and updated by other objects or parts for dynamic 3D scene rendering at simulation run time.

Selection Tracker (iTracker): A hidden attribute of enumerated item type: 0) None, 1) Point, 2) Line, and 3) Rectangle. All user selections are generalized into two points: the beginning point where the user clicks on the left mouse button and holds it down, and the ending point where the user releases the mouse button. The mouse movement between the two points is optional, that is, the user may click on and release the mouse button without moving the mouse. If the mouse is not moved during the process, the two point coincide. When 0) None is selected and the user clicks on any point within the Graphics Window, SansGUI still calls the evaluation function, if it is supplied by the simulation developer. The only difference is that there is no visual cue (tracker) displayed by SansGUI. The value can be set in the Begin Run class function programmatically, or in a service session interactively.
Selection Area [x1 y1 x2 y2] (iSelect): A hidden attribute of a vector of four integers. The first two are the screen coordinates of the beginning point, and the last two are the screen coordinates of the ending point. Both of them are in pixels with the point (0,0) being at the upper left corner of the Graphics Window. After the user makes a selection, SansGUI updates these coordinates and calls the Evaluation class function. To normalize these screen coordinates, divide them by the window's width and height from the next attribute, Window Size. Swap the two point and y-axis direction if necessary.
Window Size [x y] (iWinSize): A hidden attribute of a vector of two integers. These represent the width and height, in pixels, of the Graphics Window, excluding the window's frame. When the Graphics Window is resized by the user, SansGUI updates these values and then calls the Pre-Evaluation class function (see below).
Scaling Factors [x y z] (fScale): A hidden attribute of a vector of three single-precision floating point numbers. SansGUI uses the Z element as the zoom factor set by the user. The range of the zoom factor is normalized to [+0.05..+2], inclusive, with the default value set to 1. The developer can scale the factors up or down to satisfy the requirement of the 3D modeling space. The values of x and y, set to default 1.0, are currently not used by SansGUI. Although the default behavior associated with this vector is to scale the 3D objects, or effectively zooming into and out of the scene, the developer may interpret the values differently to implement special graphic controls.
Rotation Angles [x y z] (fRotate): A hidden attribute of a vector of three single-precision floating point numbers. SansGUI updates the x and y values when the user manipulates the user interface control to rotate the 3D object. The range of the x and y values are limited to [-180..+180], inclusive, for a full circle. The value of z is set to 0.0 and is currently not used by SansGUI. Although the default behavior associated with this vector is to rotate the 3D objects, the developer may interpret the values differently to implement special graphic controls.
Translation Vector [x y z] (fTranslate): A hidden attribute of a vector of three single-precision floating point numbers. SansGUI updates the x and y values when the user manipulates the user interface control to move the 3D objects. The x and y values are normalized to the range [-1..+1], inclusive, with (-1,-1) being at the lower-left corner, (+1,+1) at the upper-right corner, and (0,0) at the center of the window. The value of z is set to 0.0 and is currently not used by SansGUI. The developer can scale the translation vector to fit into the requirement of the 3D modeling space. Although the default behavior associated with this vector is to translate the objects, the developer may interpret the values differently to implement special graphic controls.
Control Flags (Reserved) (iFlags): Reserved for future use.
External File (Reserved) (sExtFile): Reserved for future use.

Class Functions

The Graphic Windows are created and maintained by the SansGUI framework; therefore, the developers do not need to deal with all the windows management issues between Win32 and OpenGL APIs. As suggested by Woo et al. in their OpenGL Programming Guide, three abstract functions are needed to integrate OpenGL graphics into any window-based systems:

Initialize: to set up the rendering context, clear color, shading model, etc.
Reshape: to handle the view port and projection changes when the graphic window is resized.
Display: to render the 3D graphic scene. This is the primary function that draws the 3D objects into the scene. No buffer swapping call is needed in this routine because SansGUI handles double buffering automatically.

In addition to the three functions above, we include a fourth function, Select, to handle interactive user selections in the abstraction:

Select: to respond to user's selection. The mouse pointer positions are returned as described in the Selection Area attribute above.

The Initialize, reshape, select, and display functions are mapped to the Begin Run, Pre-Evaluation, Evaluation, and Post-Evaluation DLL function entry points, respectively, in the SansGUI run-time environment. These four DLL functions associated with Graphics objects are active only when the Graphics windows of the objects are displayed. When the simulation is not running, these DLL functions are called in response to messages from Windows or user's operation (see Per Message column in the table below). Prior to the function calls, SansGUI sets the SG_STAT_EDIT status bit in the Graphics data object to inform the simulator. During a simulation run, the Evaluation (Select) function is called per evaluation cycle, and the Pre-Evaluation (Reshape, or resize window) and Post-Evaluation (Display, or render scene) functions are called only during screen refresh cycles. The SG_STAT_EDIT bit is cleared to indicate that the functions are called in a normal simulation run. Because SansGUI allows the user to operate on windows (reshape, select, rotate, translate, etc.) while the simulation is running, these function calls may possibly be triggered by Windows messages, intermingled with the calls from the simulation execution cycles. Therefore, the developer should check the SG_STAT_EDIT bit to perform appropriate operations in the DLL functions. In addition to the SG_STAT_EDIT bit, a SG_STAT_PRINT bit may be checked to know if the function call is triggered by a printing process. One example of using this bit is to change the background colors of the screen display and hardcopy output.

Function	DLL Entry	Per Message	Per Run Cycle	Per Refresh Cycle
Initialize	SG_xBgnRun	Initial Update	-	-
Reshape	SG_xPreEval	Window Size	-	Called
Select	SG_xEval	Mouse Events	Called	-
Display	SG_xPostEval	Window Paint	-	Called

An important point to remember is that these four functions are called only when the Graphics Window is opened. Other DLL functions in the Graphics class are handled normally as in other reference classes. See the DLL Function Entry Points section for general definitions and semantics.

Begin Run Function (SG_xBgnRun_Graphics): When the SG_STAT_EDIT bit is set, the function performs graphics initialization such as setting up the rendering context; otherwise, performs normal beginning simulation run tasks.
Pre-Evaluation Function (SG_xPreEval_Graphics): When the SG_STAT_EDIT bit is set, the function is called to respond to windows size change message after the user resizes the window; otherwise, it is called once per screen refresh cycle during a simulation run.
Evaluation Function (SG_xEval_Graphics): When the SG_STAT_EDIT bit is set, the function is called to process the user's selection. If the 3D scene is to be changed, the developer can call the Post-Evaluation function explicitly to reder it. When SG_STAT_EDIT is not set, this function is called once per evaluation cycle during a simulation run.
Post-Evaluation Function (SG_xPostEval_Graphics): When the SG_STAT_EDIT bit is set, the function is called to render 3D graphic objects in the scene; otherwise, it is called once per screen refresh cycle during a simulation run. The developer can use this routine to update the Graphics windows so that 3D animation according to the simulation results can be accomplished.

A note for developers using Compaq Visual Fortran: Because we need to turn on the as-is option for external function names, all the OpenGL function calls (FGL*) in the source files shall have all upper-case letters in their names. We use FGL* routines in the examples, as suggested by Compaq Visual Fortran.

Ports and Connectivity

Not applicable.

User Interface Controls

A Graphics dialog is displayed after the user selects the View Object menu item from a Graphics object's context menu or clicks on the View Object button in its Object Properties dialog. The user interface controls listed below are the default settings in class Graphics. The actual behavior of these controls may be different in other simulators. Please check your specific simulator documentation for details.

Key Combination	Operation
Horizontal Scroll Bar	Rotate displayed scene about the Y-axis
Vertical Scroll Bar	Rotate the displayed scene about the X-axis
Arrow Keys	Similar to the horizontal and vertical scroll bars
Ctrl+Arrow Keys	Move the scroll boxes with a larger increment
Shift+Arrow Keys	Move the scroll boxes to the ends
PageUp / PageDown Keys	Move the vertical scroll box with a larger increment
+ Key on Numeric Keypad	Zoom into the displayed scene
- Key on Numeric Keypad	Zoom out off the displayed scene
Ctrl+Left Mouse Button	Drag to move (or translate) the displayed scene
Home Key	Move the scene to the center and reset the rotation angles
End Key	Move the scene to the center and reset the zoom factor

Subclassing Notes

To implement 3D graphics using class Graphics, the simulation developer creates a subclass from this class, adds additional attributes after the intrinsic attributes if needed, and implements the four special DLL functions described in the Class Functions section above.