Version 1.0 was released as part of the Special Edition of Volume 9 of the OS/2 Developer Connection. The GA code is also available from IBM at ftp://ftp.austin.ibm.com/pub/developer/os2/OpenGL/. Some Web browsers appear to have problems ftping to this site (no files are listed in the directory). If you have trouble, try ftping from the command line.
2. What compiliers are supported?
3. How do I compile the example programs under the EMX port of GCC?
Quoting our friend Suzy Deffeyes of IBM:
Here is some help for gcc users: You can also run your application using the emx linker, ld, that comes in the same package as gcc. Here's a sample makefile which compiles wave.exe: #makefile EMX_PATH=d:\rtools\emx INCLUDE=-Id:\opengl -I$(EMX_PATH)\include GCC=$(EMX_PATH)\bin\gcc wave.exe: wave.o $(GCC) -o wave wave.o -Ld:\opengl -lopengl -llibtk emxbind -dtest.def wave wave.o: wave.c $(GCC) -g $(INCLUDE) -c wave.c #end of makefile This method requires a little bit of preliminary setup. First, you must convert the .lib files shipped with opengl into .a files which ld can link. Emx comes with the tool emximp. This example uses libtk.lib and opengl.lib, so, in the opengl directory, you should: emximp -o opengl.a opengl.lib emximp -o libtk.a libtk.lib You only have to do this one time for each library. Second, ld uses the environment variable LIBRARY_PATH to determine where to find the emx libraries. Be sure that this variable points to the emx lib directory before you invoke make.4. I am using Borland 2.0 to compile the AuxDemos. I get the code to compile, but it will not link with the OpenGL libraries. What am I doing wrong?
Roger P. Descheneaux writes:
The Borland compiler, by default, generates leading underscores on all external symbols. This means bcc is sticking a leading underscore onto the names of all of the OpenGL library functions and tlink can't resolve the names. To solve this problem you should use the -u- option on the command line to bcc, which will disable the generation of leading underscores on external function names. You will have a bit of trouble with main(), which the entry code library c2.obj expects to be named "_main()", but this problem is easily circumvented by naming your entry procedure "_main" instead of "main" or by placing main in a module which you compile with "-u" (the default) instead of "-u-".
5. I've installed OS/2 Warp 4.0 but OpenGL wasn't installed. What do I do?
Selectively install OpenGL from 'Tools and Games' in the selective install utility (OS/2 System -> System Setup -> Install/Remove -> Selective Install) for Warp 4.
6. I'm running Warp 3 + fixpak 17 (or greater) or Warp 4.0 and am experiencing unexplained floating point exceptions. Is there a fix/workaround for this?
Suzy Deffeyes of IBM writes:
I have made the OS/2 base OS development team aware of the problem, but since I am not sure how long it will be before a 'fix' shows up, I want to give programmers a workaround so they can get on with their work. WarpSpace VRML browser is successfully using this workaround now.
The inside scoop:
OpenGL sets the Floating Point Control Word to turn off floating point exceptions. On the versions of OS/2 listed above, after returning from a base OS/2 call or tcp call, the floating point control word is mysteriously reset. Thus floating point exceptions will be generated when OpenGL expects them to be turned off.
The workaround:
I don't have other compilers, but I have to imagine they have similar functionality. These instructions are specific to the IBM VisualAge compiler. The floating point control word is controlled in VACPP through a call to _control87(). Since the problem people are having is that some else is resetting the FPCW, this ugly workaround will require the programmer to set the FPCW after it has been muddled. You will need to make a source code change by adding a _control87() in the right spot. It should be added in your rendering thread where you kick off rendering of your OpenGL scene. If you have a place where you make a bunch of OS/2 Win Gpi or Dos calls, you might place a _control87() call AFTER the OS/2 calls. _control87() is not an expensive call.
Here is the code, you need to include float.h, and I have defined the exceptions you need to shut off. If you are using another compiler, you should be able to decipher the defines, and look at compiler docs to see how you can control the FPCW. Here is the code:
#includeThis is not pretty, and I don't blame you if your nose wrinkles up when you read it. I just want to give programmers an option if they choose to use it.#define IGNOREFP (EM_INVALID|EM_UNDERFLOW|EM_OVERFLOW|EM_ZERODIVIDE) //above defines all the floating point exceptions we want to ignore // then in your code.... _control87(IGNOREFP,IGNOREFP);
Suzy
7. Why are some of the gluTess functions missing?
Suzy Deffeyes writes:
... Because the glu functions mentioned are not in the 1.0 specification of OpenGL (blue book), they were not in the generated opengl.lib file. But for reasons I can't recall, we did go ahead and port that level of code, which is how it ended up in the header.
I'm opening a defect to update the opengl.lib. I'm not sure how long it will take for a fix ...
8. Some simple demos run, but I get intermittent crashes in Raster.dll or OpenGL.dll.
First check to see that you have specified a very large STACKSIZE for your executable. If you are using IBM VACPP and the makefiles for the samples that ship with OpenGL, the STACKSIZE is set in the .DEF file. We usually crank it up just to be safe. Depending on what you are using OpenGL for, we allocate a lot of temporary space on the stack. If you are not using VACPP, or are using our makefiles/def files, then you need to make sure you specify a large stack when you are linking the executable.
If you are getting floating point execeptions, then you can see the ugly workaround that is in the FAQ. It is an OS2 problem, not an OpenGL one.
The OpenGL entry points in OpenGL.lib are case sensitive. In other words, GLVERTEX3F is not in OpenGL.lib, but glVertex3f is there. Also, _glVertex3f (with the underscore) is not in OpenGL.lib. The flags that we pass into the VACPP linker are explained in the AUX makefile. If you are using another compiler, you will want to peruse these, and attempt to do the same thing in your build.
10. The AUX demos that ship with OpenGL just put up a blank window.
If you look at the source code for the AUX demos, most of them request a Single buffered window. If single buffered rendering is not supported on your card, then the auxInitWindow gets confused. Several of the AUX demos take command line flags ( -db will specify double buffered).
11. How do I get OpenGL to work with IBM Open Class Libraries?
Usually the IBM Open Class Libraries like to deal in the Frame window handle, that's what people have the easiest time getting a hold of. But, OpenGL needs to bind its context to the Client window area, and not the frame window. You need to pass the client window handle into pglMakeCurrent().
12. How can I use AUX with C++???
You will need to add some 'compiler oil' to aux.h. If you look at gl.h, you can just copy these lines into aux.h:
#ifdef __cplusplus
extern "C" {
#endif
......
......
......
aux.h body in here
......
......
......
#ifdef __cplusplus
}
#endif
13. Why do I get APIENTRY redef warning when I compile?
You should make sure the symbols OS2 is defined. We pass it into the compiler with /DOS2 . Look at the makefile for the auxdemos directory.
14. pglMakeCurrent always fails, what's wrong?
You might be trying to bind to the frame window. You need to pass in the client window handle to pglMakeCurrent. Look at number 10 below for more help with PGL.
15. Why are there no single buffered visualconfigs on my system?
Single buffered rendering means that OpenGL renders directly into visible VRAM on your screen, and we were unable to support it on older cards. Specifically we were not able to support it on a lot of the ISA Attached graphics cards.
16. OpenGL is rendering outside the window, and making an unpleasant mess of my desktop. Yuck! OpenGL is not using all the right colors in 256 color mode. Yuck!
Running in 256 color mode will cause 'flashing', and the forcefulness with which OpenGL will grab color entries can be controlled. Read below.. Some graphics boards lie to us when we query what mode they are in. You should consult \os2\help\opengl.doc on Merlin systems, here is the relevant text for Warp 3.0 users:
Important Troubleshooting Tips
OpenGL makes a lot of demands on the setup of your system, and when the setup reported by the graphics device driver does not exactly match the actual one, problems can arise. If OpenGL does not render, or if the image looks incorrect, one of the following items may help. These settings will override whatever OpenGL queries from your graphics device, so do not use them unless you are having trouble.
- A "squished" OpenGL image is most likely the result of an incorrect bits-per-pixel report from your OS/2 graphics device driver when running in 24 bit. In this case, setting OGL_BIT_COUNT=32 in your environment by adding "SET OGL_BIT_COUNT=32" to the config.sys should correct the image. Please be aware that this statement should not be used when in 8 or 16 bit.
- An OpenGL rendering that has a repeated image that goes beyond the bounds of the window is probably the result of an incorrect scanline size report. Scanline sizes are usually the product of the horizontal screen resolution and the screen depth in bytes-per-pixel (a 1024x768x64k setting may use a scanline size of 2048, since 64K is 2**16 which means every pixel is comprised of 2 bytes). In this case, adding "SET OGL_SCANLINE_SIZE=2048" to the config.sys should correct the problem. Please be aware that a OGL_SCANLINE_SIZE setting that works in one screen resolution and depth setting will not work in another.
- When running with a color depth of 8 bit, OpenGL will attempt to preserve the PM colors used on the desktop, but as a result, OpenGL may not receive all of the colors in its palette. The results obtained are very graphic card dependent. If OpenGL is not receiving all of the colors it needs for an image, OpenGL can force PM to use the OpenGL colors by setting "OGL_OVERRIDE_COLORS=1" in your environment. Be aware that the PM desktop will flash and the PM colors may not be preserved when the OpenGL window has focus, but the OpenGL window will obtain all of its colors. Setting "OGL_OVERRIDE_COLORS=" will reset the overriding of PM colors. But in all cases the best visual results will be obtained when "System Setup->System->256 Colors->Workplace shell palette aware" is checked (see Helpful Information).
Helpful Information
When running in 256 color mode, the following check box should be selected for optimal visual results:
"System Setup->System->256 Colors->Workplace shell palette aware"The best OpenGL performance will be attained with a PCI graphics card that is not bank-switched at the desired screen resolution and depth. When running in 24 bit, a non packed pixel (32 bot) device driver and graphics card combination will yield better performance then a packed pixel (24 bit) one.
Running OpenGL on a Matrox Millennium in 24 bit requires that DIVE support is enabled. See the documentation that came your Matrox for information on how to enable DIVE support in 24 bit.
Summary of Settable Environment Variables
The following strings are scanned for in the current environment by OpenGL, these can be set by using the "SET" command in OS/2 (issue "help set" in an OS/2 Window for information on the "SET" command). may help. These settings will override whatever OpenGL queries from your graphics device, so do not use them unless you are having trouble.
OGL_BIT_COUNT - used by OpenGL to replace the bits-per-pixel report from the graphics device driver. Primary use is for when 32 bpp(non-packed) setup actually reports 24 bpp (packed). See "ImportantTroubleshooting Tips" section.
OGL_SCANLINE_SIZE - used by OpenGL to replace the scanline size report from the graphics device driver. See "Important Troubleshooting Tips" section.
OGL_OVERRIDE_COLORS - used by OpenGL to override the PM colors in the color palette. Only applicable when running in 8 bit. See "Important Troubleshooting Tips" section.
17. PGL? What's a PGL? How do I use it?
Every implementation of OpenGL needs a little glue to integrate it into whatever windowing system it is running on. In X windows this is called GLX, in Windows it is WGL, and in OS/2 it is called PGL. Here is a sample program.