GLSim & GLTrace

GLSim is an instrumented implementation of OpenGL. It was written by Ian Buck and Kekoa Proudfoot for students who wish to modify or study the OpenGL pipeline for their projects. GLTrace is a tracing package written by Kekoa Proudfoot for recording and playing back OpenGL traces.

For Linux: glsim.tar.gz
For Windows: glsim.zip

UPDATE 11/12/01.
Fixed texture blending and single buffer mode
For Linux: glsim_v1.1.tar.gz
For Windows: glsim_v1.1.zip

Trace of Quake3 Demo001 walkthrough: quake3demo001.tlg.gz (62 Megs)
Trace of Unreal walkthrough: unreal.glt.gz (12 Megs)

UPDATE 11/15/01.
Fixed opengl32.lib for windows build. Patch below is for files in "gl" directory.
For Linux: glsim_patch1.tar.gz
For Windows: glsim_patch1.zip

GLSim

Directory structure

glcontext
This directory contains the state tracker for OpenGL. All of the GL functions which modify the state are implemented in this directory. Most of the GL calls are defined here.
glcore
This directory contains the actual rasterizer. It implements only a few calls needed for rasterization: Begin, End, Vertex4f, Flush, Finish, Clear, and SwapBuffers.
gl
This directory contains the "font end" which defines the interface between the application and the rest of the implementation defined in glcontext and glcore. It contains the OS specific code, window mangangement code, and the function pointer redirection table.
glt
The OpenGL tracing package. More information in the GLTrace section below.
bin
This directory is were the final compiled executables end up including the compiled GL library. Running OpenGL applications from this directory should cause the application to use the glsim OpenGL library instead of the system library.

Building GLsim

GLsim builds under Linux and Win32. For Linux, type make in the root directory. For Windows, load glsim.dsw in Visual Studio 6.0. Right click on opengl32 project and select build. A successful build will result in libglsim.so (for Linux) or opengl32.dll (for Win32) in the bin directory.

Testing GLsim

Running application using the GLSim OpenGL library other than the system's opengl implementation requires only that you run application from the bin directory. Copy a test application into the bin directory or create a link to the application in the bin directory (Linux only). Also in Linux, make sure that "." is in the beginning of your LD_LIBRARY_PATH which can be checked by running the printenv command. "." can be added by running:

setenv LD_LIBRARY_PATH .:$LD_LIBRARY_PATH

In the bin directory is simple OpenGL application called atlantis. Running this application (or any other GL application) in this directory, you should notice the following text appearing on the command line:

*********************************
Using GLSim OpenGL Implementation
*********************************

This indicates that you are using GLsim. Another indicator is speed since rendering with GLSim should be much slower than running with hardware.

Known Issues

GLSim is not a complete OpenGL implementation. The following GL functions are known to be broken:

CopyPixels, CopyTexImage1D, CopyTexImage2D, CopyTexSubImage1D, CopyTexSubImage2D
EvalCoord1d , EvalCoord1dv , EvalCoord1f , EvalCoord1fv , EvalCoord2d , EvalCoord2dv , EvalCoord2f , EvalCoord2fv , EvalMesh1 , EvalMesh2 , EvalPoint1 , EvalPoint2
FeedbackBuffer, SelectBuffer, IsTexture, InitNames, LoadName, PassThrough
PopAttrib, PopClientAttrib, PopName, PushAttrib, PushClientAttrib, PushName
ReadPixels, DrawPixels
CallLists, CallList, NewList, EndList
Bitmap
Accum
RenderMode

In addition, below are some known issues with GLSim:

Only a single OpenGL context is allowed.
Pixel operations are not supported, ie glDrawPixels.
Display lists are not implemented.
Uncommon texture formats like R3_G3_B2 are not supported.

Modifing GLSim

For projects which would like to modify the GLSim implementation to do something new, you should first contact the authors at cs448a@graphics.stanford.edu. We are here to help you with your projects and can offer advice how to add things like programmable shading, texture caches, etc.

To demonstrate how to add new functionality to GLsim, we implemented a new toy function to the OpenGL api called glMyFunc. glMyFunc keeps two ints around with the OpenGL state for use by the rasterizer. Currently the rasterizer doesn't even look at these values so glMyFunc is quite useless. However it does show how to add a new function to OpenGL.

The files which are effected are:

gl/myfunc.c:
This is the definition of the glMyFunc call. All this does is get the current context variable and update two values.
gl/defs.pl (Windows only):
Added glMyFunc to the export list. This exports the function so it is visible by the application
glcontext/glmystate.h:
The state declaration. This defines GLmystate structure which is the data to be associated with a context.
glcontext/glmystate.c:
Define an init routine which gets called on context creation.
glcontext/glcontext.c:
Add the init routine to the create context call.
glcontext/glcontext.h:
Add glmystate.h to the header file.

The state variables defined in glmystate.h are accessible in the renderer code by simply looking into the g->mystate structure.

GLTrace

Directory structure

The glt folder contains the executables for recording and playing traces. It also contains a few sample traces.

glplay:
GL trace player. To run type:
```
 glplay file.glt 
```
Trace files are either .glt or .tlg. The order of the extension determines the byte endian of the trace. Traces made on x86 should have .tlg extension (little-endian), while MIPS or PPC traces should be .glt (big-endian). glplay can play either format so you probably don't have to worry about this. Also, glplay will play compressed (.gz) files so you can run file.glt.gz without needing to decompress it.
Important options:
- -scale factor: Scales the output window to some factor.
- -unwind: Unwinds display lists into origional calls. Needed to play traces with display lists with GLSim OpenGL.
trace:
GL tracer program. This program will create a trace of a GL application. To trace a file on an x86, type:
```
trace application > mytrace.tlg 
```
NOTE: trace doesn't seem to work with Linux NVIDIA OpenGL drivers. If you need to make a trace on Linux, use a Linux machine with Mesa drivers.
dump:
Dump will print out all of the glcommands in a trace to standard out.
quake-4.glt.gz
Trace of a Quake walk through. Note this trace was made on an IRIX machine which may generate a few warnings about unimplemented SGI extensions.
qtvr.glt.gz
Trace of QTVR application.
head.glt.gz
Trace of a simple model viewer with lights. NOTE: Be sure to run with -unwind option since it contains display lists.

Playing traces through the GLSim OpenGL implementation is useful for testing with a known stream of OpenGL commands. To play a trace through the GLSim OpenGL implementation, launch the glplay application from the bin directory. Copy (or link) the trace to the bin directory and run the glplay application inside the bin directory.

Need Help?

Please email cs448a@graphics.stanford.edu for any questions or help with this code. If your project will be expanding the functionality of this code, you are encouraged to contact us for how you might implement it.

Good luck!