CsGL - C# graphics library

Navigation Overview

How to use C#? with CsGL?
I wrote a simple C# for Dummy tutorial which rapidly explain you how to create & use DLL and even normal DLL (as opposed to .NET assembly).
If any of you have ideas to improve this tutorial send the improved version here lloyd@galador.net
What are these DLLS?
There is 2 DLL for CsGL: csgl.dll & csgl.native.dll.
csgl.dll is a .NET assembly providing some OpenGL class and utility. It should either be installed with install.bat in libinstall directory or in the same directory as your app.
csgl.native.dll is not an assembly, it's an ordinary DLL performing some native and private work for CsGL to work. it should be in your path or in the same directory as csgl.dll
How do I install / deploy CsGL?
There are two flavors of the precompiled library, one in the lib directory and another in the libinstall directory. In libinstall the DLL is strongly named and compiled as optimized. This DLL could be installed into the global assembly cache or distributed with your program. This DLL is recommended for the end-user. It also come with a install.bat files. clic on it to install it. In lib the DLL is not strongly named and is compiled with debug information. This DLL should be in your development directory, as it is recommended for the CsGL hacker.
Where did the SDL wrapper go?
Well, I gave it away, it was too time consuming. It can now be found at http://cs-sdl.sourceforge.net. However, there seems to be little activity with it.
What are the differences between the original API's and the CsGL ones?
We try to imitate the original API's as closely as possible. There are very few differences in usage. Since C# is a modern, object-oriented language, we have also added some classes that wrap the "loose" functions, hide pointer arithmetic, and eliminate some of the procedural aspects that come from plain C.
Why does CsGL wrap #define's using class variables instead of enums?
Simply because we found class variables to be the best imitation for #define's. But we additionally put them into enums for the use in the improved object-oriented classes.
How are the various float*, void* translated into CsGL?
OpenGL, a C API often takes pointers as parameters. In order to have "safe" (without pointers) managed code the following translation rule applies:
type* -> type[]

Two problems remain though.
- The void* cannot be translated like this.
- Sometimes OpenGL retains the pointer address.
(glColorPointer(..), glSelectBuffer(..), etc.) and a managed array could move..

To address these problems, these functions take a pointer argument (System.IntPtr) and second there is a class CsGL.Pointers.PVoid which could allocate and return an unmoving pointer. Though you generally use one of its child's CsGL.Pointers.PType, such as PFloat, PUInt32, etc... like this:
```
 PUInt32 p = new PUInt32(N);
 for(i=0; p.Length; i++)
 	p[i] = whatever();
 glSelectBuffer(p.Length /*N*/, p);
```

How do I create a customized pixelformat?
How do I share display list between context?
How do I create a customized OpenGLContext?
You could choose the pixelformat when creating the OpenGLContext. The OpenGLControl create its context in CreateContext(), override this method to return a customized context. When creating a context you could choose its pixel format and whith which other context it will eventually share it's data. it's a simple 2 step creation process show below:

 protected override OpenGLContext CreateContext()
 {
 // choose your pixel format here
 DisplayType mydisplay = new DisplayType(8, 8); 
 mydisplay.Flags = ...
 // init your display
 ControlGLContext ctxt = new ControlGLContext(this);
 // here eventually display the list of available format
 for(int i=0,n=ctxt.NumPixelFormat; i<n; i++)
 	Console.WriteLine(ctxt.GetPixelFormatAt(i));
 // if one please you create with it with => ctxt.Create(i, null);
 // toShare is an OpenGLContext with which ctxt share its display list, or null
 ctxt.Create(mydisplay, toShare); 
 return ctxt;
 }

How to build it?
Well you could use the GNUmakefile provided ? If you don't have it there is a <csgl>/src/buildcs.bat file which build csgl.dll (double clic on it). You could even build the instalable version with "buildcs install".
For csgl.native.dll you will at last need gcc (http://www.mingw.org) and you could either make it or tape:
gcc -I ../include -shared -o csgl.dll *.c -lOPENGL32 -lgdi32 strip csgl.native.dll
How to use with Visual Studio .NET?
Well if you install it (in <csgl>/libinstall there is an instalable version with an install.bat) you could add it in your toolbox in VS.NET and it work just fine !...
How do I use OpenGL extensions?
Just use them! It just works. GL.myExtensionFunction()...
You should check first if it is supported by the driver, with call like Info.IsPresent("MyWonderfullExtension") or parse glGetString(GL_EXTENSION) yourself, or simply check if the function is present with GL.GetProc("funcName").
It could also happen that the extension is not already implemented in CsGL, so.. generate it with glgenerator.exe in <CsGL>extras\generator directory.
One last recommandation, remember that extensions are OpenGLContext dependant
How can I manage the keyboard efficiently?
Well, if you too encounter some arrow key problems and other problems using the Key Events from .Net...
There is a solution! CsGL.Util.Keyboard class manages any key.
Just write a subclass or use the GetKeyState and Hook methods...
How can I get a nice cursor for my control?
You have a nice bitmap, which could be a good mouse cursor? (like the hand in <csgl>\examples\CS\drawimage example ?), well, just create a Sustem.Drawing.Cursor from it with the CreateCursor(..) method in CsGL.Util.Mouse class. Don't forget to destroy it when it's no longer needed with the DestroyCursor(..) method. Sorry about this fussy obligation but the Cursor class being sealed, I can't help ...
How can I manage the mouse efficiently?
There is a CsGL.Util.Mouse class which permits you to do anything with the mouse. :-)
How can I use fonts?
Well, I didn't manage to have wglFont/glxFont working but, using some tricks, I created CsGL.OpenGL.GDITextureFont which do a decent job.
Take a look at <csgl>/examples/CS/gdifont.cs
What about multithreading, multiple views?
An OpenGLContext can be current to only one thread at a time. (OpenGLContext ensures your OpenGL calls got somewhere). So if you have a thread trying to Draw on a view which is also drawn in the main event loop you will end up with an "OpenGLException(..) resource already in use". There are four solutions. Use this view only in this thread or customize the OpenGLControl code to suit your needs or write your own using you own ControlGLContext or tag your Main() method with [STAThread].
BTW, with multiple views/threads you would probably have multiple calls to ctxt.Grab() (this function makes the context current), however, this call has some perfomance cost...
Where did the NeHe lessons go?
The examples are released as a separate package, containing the examples, their data, and a small basecode layer, allowing you to quickly write examples/demos using CsGL.
I have an uncatched exception coming from nowhere, what could I do?
At the end of OpenGLControl.OnPaint() there is a call to OpenGLException.Assert() which ensure all OpenGL call went without error. This method being at the top of the hierarchy you probably can't catch it in a standart event driven application. maybe it's a design error. I have to think about it.
In the mean time you have 2 solution:
- override OnPaint() and put a try/catch around base.OnPaint()
- call glGetError() yourself to test & clear eventual GL error