SansGUI supports OpenGL graphics programming via this reference class. It provides the developers with a framework that bridges Windows message processing and OpenGL Application Programming Interface (API). The functional abstraction of the framework is described in the Class Functions section below.
All attributes in class Graphics are hidden. They are not visible to the users in the SansGUI Run-Time Environment, but can be revealed by entering a Service Session via Tools>Service Session... menu selection. The password for this example is not set, or set to an empty string. Simply click on the OK button when SansGUI asks you to enter the password.
+ 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; the user may click on and release the mouse button without moving
the mouse. If the mouse is not moved, the two point coincide. When 0)None
is selected and the user clicks on any point within the graphic 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 graphic 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 represents the width and height, in pixels, of the
graphic window. When the graphic window is resized by the user, SansGUI
updates these values and then calls the Pre-Evaluation class function.
+ 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 uses the user interface control to rotate the 3D object.
The range of the x and y values are limited to [-180..+180] for a full circle.
The value of z is set to 0.0 and is currently not used by SansGUI. Although
the default behavior assoicated 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 manipulate the user interface control to move the 3D
objects. The x and y values are normalized to the range [-1..+1], 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.
The graphic windows are created and maintained by the SansGUI framework; therefore,
the developer does 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:
1) Initialize: to set up the rendering context, clear color, shading model,
etc.
2) Reshape: to handle the view port and projection changes when the graphic
window is resized.
3) Display: to render the 3D graphic scene. This is the primary function that
draws all 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:
4) 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 functions will be executed not only during simulation runs but also in response to windows messages, such as resizing and painting, as appropriate. During a simulation run, the Pre-Evaluation (Reshape, or resize window) and Post-Evaluation (Display, or reder scene) will be called only during screen refresh cycles. When the functions are not called during a regular simulation run, such as responding to windows messages, the SG_STAT_EDIT status bit is set to inform the simulator. These four functions are called only when the graphic window is opened. Other DLL functions in the Graphics class are handled normally as in other reference classes.
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.
+ Begin Run function (SG_xBgnRun_Graphics_Solid): to set up the OpenGL
rendering context.
+ Pre-Evaluation function (SG_xPreEval_Graphics_Solid): to respond to
windows size change message after the user resizes the window.
+ Evaluation function (SG_xEval_Graphics_Solid): to process the user's
selection. If the 3D scene is to be changed, the developer can call the
Post-Evaluation function to reder it.
+ Post-Evaluation function (SG_xPostEval_Graphics_Solid): to render 3D
graphic objects in the scene.