Class Graphics

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.

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 render 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.

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

• Components and References in the SansGUI User's Guide

• Accessing Class Properties, Adding Classes and Defining Reference Classes in the SansGUI Developer's Guide

• 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.

SansGUI Modeling and Simulation Environment Version 1.2

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

http://protodesign-inc.com