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

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:

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:

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.

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:

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:

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.

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:

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

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.

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.

See Also

 



C:\FH_Suite\htmlgifs\home.gif SansGUI Documentation Errata Quick Reference Cards

SansGUI Modeling and Simulation Environment Version 1.2

Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.

http://protodesign-inc.com