-
An OpenGL framework for win32
- Background
Required resources
- Running opengl.win_prototyping_main.exe
- Required Hardware
Required Software
Software development
- Required Hardware
Required Software
- The main program opengl.win_prototyping_main.exe
- Interactions with mouse and keyboard
- Command line parameters
- -test
- -timer
- -timerfontsize
- -timing
- -timerdelta
- -clock
- -clock24h
- -earthscale
- -earth
- -earthfile
- -timeoffseth
- -timefactor
- -earthloc
- -lat -lon
- -anti
- -mouse
- -fullwindow
- -windowx -windowy -windoww -windowh
- -background
- -fontinfo
- -nologfile
- -showerrors
- -priority
- Setting the command line parameters
- Implementation details
- The Package structure
- Adding new classes
- Compiling and Linking with GNAT
- References
Background
The program described in this document is a side product of a larger OpenGL application developed at AMST-Systemtechnik/Austria in 1998/1999. This application is used in different flight simulators to display the instrument panels of the simulated aircrafts. The author used the framework this software is based upon to develop some nice applications in his spare time.
First, the required hard- and software is given. Then the configuration of the main-program using the command line is presented. The software-structure is shortly described in a last paragraph in order to be able to implement extensions using the given or new classes.
Required Resources
The Software was developed on PCs using windows for the target being also windows.
Running opengl.win_prototyping_main.exe
Required hardware
Basic-hardware:
PC with fast Pentium- or AMD-processor
Graphics card: Fire GL or ELSA Gloria XL
For fast frame updates of more then 30 Hz a fast processor (> 300 MHz) and a graphics card with OpenGL acceleration is recommended. For software development frame updates of about 5 Hz (without antialiasing) are achievable without special OpenGL hardware.
Required software
Operating system:
Windows NT / 95 / 98 / 2000 / ME
Executable: opengl.win_prototyping_main.exe
DLL's: (Dynamic Link Libraries) opengl32.dll und glu32.dll.
Software development
Required hardware
PC with fast Pentium- or AMD-processor
Required software
Operating system:
Windows NT / 95 / 98 / 2000 / ME
Ada compiler: ObjectAda for Windows native Version 3.1.1, 3.1.2 (or later),
(GNAT Version 3.13p for WinNT)
Libraries: Win32Ada binding (includes OpenGL binding)
DLL's: (Dynamic Link Libraries) opengl32.dll and glu32.dll.
The main program opengl.win_prototyping_main.exe
For test purposes simple interactions can be made with Opengl.win_prototyping_main.exe using mouse and keyboard. The command line is used to set options and to select an application.
Interactions with mouse and keyboard
Left mouse button,
key-up, key-down and characters
With the 3 mouse buttons and some keys the
application may be manipulated. The corresponding callbacks are in the package bodies of opengl.win, opengl.clock, opengl.earth.
- Left mouse button
Stops rendering, shows an unchanged image till the button is pressed
again (package body Opengl.Win).
- Middle mouse button
Opens file messages.txt for editing. This file contains messages
that are activated at the given due date and displayed at the bottom of the
clock (simple reminder functionality). For the syntax of the file (date and
time etc.) see the given example file. After the editor is closed the file is
read in if it has changed (package body Opengl.Clock).
- Right mouse button
Pressing the right mouse button finishes the program (package body Opengl.Win).
- Keys (see callback in package body Opengl.Win):
- '+' doubles the render intervall (see Task Windows_Timer).
- '-' halfes the render intervall (see Task Windows_Timer).
- 't' switches off/on the timer output (see below).
- Keys (see callback in package body Opengl.Clock):
- esc switches between these 3 states: shows both clock and
earth, only clock, only earth.
- 'a' change of the alpha value of all clock parts is
enabled/disabled.
- '+' Increment alpha by 0.1 in range 0.0 .. 1.0.
- '-' Decrement alpha by 0.1 in range 0.0 .. 1.0.
- 'c' Enabled/disabled coordinate systems of some clock
parts.
- del Use Display lists for the clock parts or not.
- Keys (see callback in package body Opengl.Earth):
- 'h' switch between
- an earth that is always shown from the sun (xearth-mode), the
time is used to rotate the earth, or
- an earth that is shown for constant lat / lon values, the time
is used to move the sun around the earth (shadow-mode). This
movement generates a moving shadow on the night side of the earth.
- 'f'
Enable altering of filter values. This filter manipulates the
earth-bitmap before using it for 2D texturing. The oceans are changed
from dark blue to lighter blue (to match the authors taste).
- 'm'
Enable altering of the global lighting model. For the explanation of
the next parameters see an OpenGL tutorial.
- 'l'
Enable altering of the light source (which is the sun for the shadow
mode).
- 'o'
Enable altering of the material properties of the lit earth.
- 'k'
Enable altering of the shininess.
- '^'
Enable altering of the spot exponent.
- '<'
Enable altering of the spot cutoff.
- '1'
Enable altering of the constant attenuation.
- '2'
Enable altering of the linear attenuation.
- '3'
Enable altering of the quadratic attenuation.
- '#'
Enable altering of the sun distance.
- 'a'
Enable altering of the ambient color of the previously selected item (lighting
model, light source sun, material properties earth).
- 'd'
Enable altering of the diffuse color of the previously selected item.
- 's'
Enable altering of the specular color of the previously selected item.
- 'i'
Enable altering of the emission color of the lit earth.
- 'r'
Enable altering of the red color component of the previously selected color.
- 'g'
Enable altering of the green color component of the previously selected color.
- 'b'
Enable altering of the blue color component of the previously selected color.
- '4'
Enable altering of the alpha color component of the previously selected color.
- F11
Enable altering of the deviation of the font for the lat / lon numbers (see
'n' - net below).
- F12
Enable altering of the extrusion of the font for the lat / lon numbers (see
'n' - net below).
- '5' .. '8'
Set the texture_env parameter to one of the following values:
4 - decal, 5 - replace, 6 - modulate, 7 - blend
- 'ö'
Enable altering of the filter parameter color-first.
- 'ä'
Enable altering of the filter parameter color-last.
- keypad '+'
Enable altering of the filter parameter color-bias.
- keypad '*'
Enable altering of the filter parameter color-factor.
- '0'
Sets filter color-bias to 0.
- 'p'
Switches the sun-position w-component between 0.0 and 1.0.
- '+'
Increments the previously selected value by an appropriate delta.
- '-'
Decrements the previously selected value by an appropriate delta.
- up
Rotate earth by +10 deg in latitude when in shadow-mode.
- down
Rotate earth by -10 deg in latitude when in shadow-mode.
- left
Rotate earth by -10 deg in longitude when in shadow-mode
- right
Rotate earth by +10 deg in longitude when in shadow-mode.
- F1
Increment time by 1 hour.
- F2
Decrement time by 1 hour.
- F3
Increment time by 1 day.
- F4
Decrement time by 1 day.
- 'w'
Increments time offset by 1 hour.
- 'e'
Decrements time offset by 1 hour.
- keypad up
Translates 10 % earth up.
- keypad down
Translates 10 % earth down.
- keypad left
Translates 10 % earth left.
- keypad right
Translates 10 % earth right.
- page up
Zooms into earth by 10%.
- page down
Zooms out off earth by 10%.
- F5
Multiplies time-factor by 2 (enlarges earth angular velocity).
- F6
Divides time-factor by 2 (reduces earth angular velocity).
- F7
Sets time back to actual one and time-factor back to 1.
- del
Enable/disable usage of display-lists. This has significant impact on the
rendering performance when using the SGI dll's on some graphics cards.
- 'n'
Enable/disable rendering of a net of lat / lon lines including numbers.
- 'c'
Enable/disable rendering of a coordinate system in the center of the
earth.
- ' ' blank
Enable/disable rendering of the earth bitmap. If disabled the bitmap is not
used for 2D-texturing, a pure sphere is rendered.
Command line parameters
There are 3 types of command line parameters:
- Boolean
: If they are given on the command line they are true otherwise they are false,
example: -timer.
- Numbers
: If given the value after the parameter name is used else a default value. The default values are given in the list below.
example: -timerfontsize 3. Numbers may be given as integers or floating-point values.
- Strings
: If given the value after the parameter name is used else a default value.
example: -bmpfile \ada95\pictures\adalogo-new-small.bmp .
The following command line parameters are defined for opengl.win_prototyping_main.exe (see package opengl.command_line):
- -test
Only test objects are rendered which are defined in the package body of Opengl.Test_Screen_Prototyping (this parameter is used in the full main program opengl.win_main to discriminate the normal mode of operation [rendering of instrument displays] from the rendering of test objects under development).
- -timer
Generates timer and debugging information. The timer information is visible in 4 short lines in the lower left corner in red. They show the render counter, which is incremented by 1 during each frame update, the time used for the last frame update, a continuous mean value for the frame update, a maximum value; all in ms. Besides that debugging- and error information may be displayed in four green rows of length 132. Longer strings are truncated on the right side. An example output looks like this:
Count: 123456
Time: THURSDAY FEBRUARY 04, 1999, 13:13:55:00 : no network-update since 3.4260 sec.
Dt [ms]: 25.123
E[Dt] [ms]: 24.123
Max[Dt][ms]: 33.456
- -timerfontsize 2.5
Sets the font size of the timer output, default is 2.5. The actual size is proportional to the height of the display. In test mode it is 270 mm. Is the actual height correct the given value is the font size in mm.
- -timing
For each object a mean render time is measured and written to the log-file opengl.win_prototyping_main.EXE.log at program end.
- -timerdelta 1
Time increment in ms for task that generates render-events. For example 1000 (1 sec) is a reasonable value for the clock to move the second pointer each full second.
- -clock 0
A clock is displayed. Besides -clock also -test has to be given. If -clock is given with no argument shows one clock. If an earth is shown too (-earthscale > 0.0), the sun shines always perpendicular onto the earth (like xearth on Unix). If -clock is given with an argument between 1 .. 24 shows up to 24 clocks with time zone offset. If an earth is shown, the viewpoint is always perpendicular to one location in the time zone and the sun generates a shadow.
- -clock24h
Shows a clock with a 24h dialface. The meaning of the parameter is as with clock.
- -earthscale 0.0
Render the earth in the middle of the clock dialface. If 0 is given no earth is rendered.
- -earth
Render an earth/globe similar to xearth.
- -earthfile world.bmp
Bitmap to use as a 2D-texture for the earth.
- -timeoffseth 0
Time zone offset of the clock and earth in hours.
- -timefactor
1.0
Timefactor for earth-rotation. Normal angular velocity is multiplied by this number.
- -earthloc ""
A string describing the earth location that is written on top of the earth or clock to show the time zone.
- -lat 0.0 -lon 0.0
Position of the earth location.
- -anti
Antialiasing on or off.
- -mouse
Show the mouse pointer on the OpenGL screen or hide it.
- -fullwindow
If true, a full window is drawn, else the window has no border and buttons.
- -windowx
0, -windowy 0, -windoww max, -windowh max
The window coordinates and the window size at program start, X and Y refer to the upper left corner.
- -background black
Defines the background color of the Opengl screen. Has to be one of the colors given in package opengl.colors.palette.
- -nologfile
Write no log file.
- -showerrors
If Ada-exceptions are raised a popup window showing the text returned by Ada.Exceptions.Exception_Information is opened and the program pauses. Without -showerrors the program continues immediately and the text is only written to the log-file if one is open (-nologfile not set).
Attention: If ObjectAda is used Ada.Exceptions.Exception_Information contains the stack trace in readable format only if the executable is bound in debug mode. In release mode the text contains only the addresses of the call stack.
An executable generated with GNAT3.13p uses the string
Ada.Exceptions.Exception_Information(E) & Gnat.Traceback.Symbolic.Symbolic_Traceback(E) to display the exception_occurence E (see package body portable.utils).
- -fontinfo
Writes full font info comprising length and height of all characters in the font to the log file. If fontinfo is false only short info is written.
-priority idle
WinNT priority of the application process. The Realtime_Priority should not be used. It blocks the system and it's difficult to shut the main down.
Setting the command line parameters
The command line parameters can be set best in windows-connections. The following figure shows an example connection.
Implementation details
This paragraph gives a short overview of the package structure and some hints for adding new classes.
The package structure
The package structure is reflected by the following directory tree:
\ada95\source\projects\opengl\windows Microsoft-windows specific software
\ada95\source\projects\opengl\kernel reusable components
The sources for opengl.win_prototyping_main are all given in the hierarchical package opengl. The child packages of opengl.models contain all reusable graphical components. Together with other reusable parts they can be found in the kernel-directory.
The Microsoft-windows specific parts can be found in the packages opengl.win, opengl.fonts, etc. in the windows-directory which contains also the main program.
The software uses some packages from an Ada-library of reusable components given in the following directories
\ada95\source\lib\math Generics for basic vector- and matrix-algebra etc.
\ada95\source\lib\portable OS- and windows-specifics, win32-addons, posix-bindings etc.
\ada95\source\lib\utilities Some utilities and components (hash, stack, etc.)
Adding new classes
If you want to add new graphical objects you should write new child packages of opengl or opengl.models containing new types in the models.model_2d_z or model_3d class tree and render-procedures for them or you could generate sibling packages of opengl.models if appropriate.
To test these classes adapt the package-body of opengl.test_screen_prototyping, where you define all graphical objects that shall be displayed. As shown there you can define new command-line parameters to select these objects without recompiling and relinking the main.
Compiling and Linking with GNAT
When extracting the zip-files lib-src.zip and ogl-src.zip you should use the full pathnames. The following directory structure is created:
\ada95\bin\gnat -- .o,.ali,.exe
\ada95\compiler\gnat -- GNAT installation
\ada95\source\lib\math\arrays -- lib-src.zip
\ada95\source\lib\portable\posix-win\src
\ada95\source\lib\utilities
\ada95\source\projects\opengl\config-files -- ogl-src.zip
\ada95\source\projects\opengl\glut
\ada95\source\projects\opengl\kernel
\ada95\source\projects\opengl\windows
AdaGide 6.26 and GNAT 3.13p may be used. To use AdaGide open \ada95\bin\gnat\ opengl-win_prototyping_main.ads and link. The gnat.ago file is used which containes all necessary include-paths and references all object-archives. When you have installed GNAT in a different location then \ada95\compiler\gnat\ you have to adapt gnat.ago first. The link command will install all '.o', '.ali', '.exe' files in \ada95\bin\gnat.
To execute \ada95\bin\gnat\ opengl-win_prototyping_main.exe execute one of the files clock-fn, clocks, earth, in \ada95\source\projects\opengl\config-files. If you want to use the ObjectAda-executable contained in opengl.win_prototyping_main.zip instead of the GNAT one you have to adapt the 3 files before, cause the OA-exe uses a '.' in the filename instead of a '-'.
References
The bitmap that is used for the 2D texture for the earth is taken from the following source
http://www.sgi.com/fun/gallery/images/world1.jpg
and slightly modified. The Ada-Excellence image is taken from the Ada-power side.