============================================================ GLIntercept v0.5 Copyright (c) 2005 Damian Trebilco All rights reserved. ============================================================ Contents: 1) Quick start guide 2) Output 2.1) Function Log 2.2) Error Log 2.3) Image Log 2.4) Shader Log 2.5) Frame/Render Log 2.6) Display List Log 2.7) Timer Log 3) Plugins 3.1) Shader editor 3.2) Free Camera 3.3) Extension/Version override 3.4) Frame Ping 3.5) Function Stats 4) Known bugs 5) Adding OpenGL extensions 6) Contact 7) Disclaimer ============================================================ 1) Quick start guide After installation, simply copy the opengl32.dll and a gliConfig.ini file from the install directory to the executable folder of the application you want to intercept OpenGL calls. Then edit the gliConfig.ini file and enable the options required then run the application. Several pre-configured *.ini files are provided demostrating different options. Rename the file to gliConfig.ini before use: gliConfig.ini - Basic text logging with image/shader/display list dumping. gliConfig_XMLFrame.ini - XML per-frame logging (on ctrl-shift-f) with image/shader/dlist/frame buffer dumping. gliConfig_FullDebug.ini - Text logging with full debug checking and log flushing. Can be slow, but useful for finding OpenGL errors or the OpenGL function the app crashed on. gliConfig_ExtOverride.ini - Demonstrates how to use the OpenGL extension/version override plugin. gliConfig_FreeCam.ini - Demonstrates how to use the OpenGL free camera plugin. (ctrl-shift-c starts the free camera see below for other key bindings) gliConfig_ShaderEdit.ini - Demonstrates how to use the OpenGL shader editor plugin. (ctrl-shift-s starts the shader editor) gliConfig_AuthorStd.ini - Authors' preferred settings when developing. If the interception was successful, a gliLog.txt will be generated in the same directory as the opengl32.dll. (this is the error log). The results of the interception are also stored in the same directory by default. (ie. gliInterceptLog.txt) It is important to note that GLIntercept is NOT safe when multiple render contexts are active at the same time on different threads. (ie you will probably experience crashes/ bad data) This restriction may be lifted in the future however, very few OpenGL applications use multiple render contexts at once. GLIntercept will currently report a warning if this is attempted. ============================================================ 2) Output 2.1) Function Log The GLIntercept function log simply records incoming OpenGL calls and saves them to a file. The logger can store functions in flat .txt files or in a .xml format that can use a xsl file to present the data in a web browser. Only OpenGL functions known by GLIntercept will have parameters of the function logged. Unknown functions will have a ???? in the parameter field. 2.2) Error Log Every execution of GLIntercept produces a gliLog.txt file in the directory of the opengl32.dll. This file contains a record of any abnormal states or errors that are detected during execution. If the image or shader logs are enabled, texture and shader memory leaks are also recorded here. 2.3) Image Log The image log enables the saving of any OpenGL textures that are used in the application. Texture types include 1D,2D,3D,CUBE,NV_RECT and p-buffer bound textures. See the gliConfig.ini file for full options. 2.4) Shader Log The shader log enables the saving of OpenGL shaders/programs that are used in the application. Only ARB/NV/GLSL vertex and fragment programs/shaders are currently supported. See the gliConfig.ini file for full options. 2.5) Frame/Render Log The frame log enables the saving of the OpenGL frame buffer pre and post render calls. The ability to save the "diff" of pre and post images is also available. The frame logger will not work correctly if you use WGL_ARB_make_current_read in your application. Also currently, the pixel transfer options will affect the buffers read back. (ie the colors values returned may be different from what is actually on the buffer. This may be fixed in future versions. See the gliConfig.ini file for full options. 2.6) Display List Log The display list log enables the tracking and saving of OpenGL commands that occur inside a display list. This includes reporting memory leaks on shutdown. See the gliConfig.ini file for full options. 2.7) Timer Log The timer log is a logger the writes to the function log and flags how long each function took to execuite. WARNING - This option is only for advanced OpenGL users and novice OpenGL programmers should not try to optimize programs based on these results. See gliConfig.ini file for full options and a listing of special conditions for this logger. ============================================================ 3) Plugins GLIntercept supports plugins loaded from external DLLs. These plugins simply register what function updates they want to receive, and GLI will call the plugin when the OpenGL call is made. Each plugin is added as a line in the gliConfig.ini file and plugin specific options can also be provided. Each plugin typically has a config.ini file that specifies the default global setting for all its' options. These files can be located: (\Plugins\\config.ini) Specifying any of these options in the main gliConfig.ini file will override the defaults. 3.1) Shader editor The shader editor allows the editing of ARB/NV VP/FP/GLSL shaders/programs at run time. By pressing (by default) ctrl-shift-s during the execuition, a shader editor (based on SciTE) will open as a seperate process with a listing of all currently active shaders. Edits on these shaders can then be performed and compiled back into the OpenGL application. Standard VC6 commands are used in the editor. Commands of note are: F3 - Search F4 - Next error F7 - Compile ctrl + space - Listing of all api commands (GLSL only) ctrl + shift + space - Tool tip for the current function (GLSL only) The fonts and color scheme of the editor can be configured by editing the *.properties files in the plugin directory. Note: You can also run the editor without a OpenGL application as it includes full syntax and tooltips as well as the GLSL validator. (run GLISciTE.exe from the plugin folder) Add the following lines to the gliConfig.ini to use the shader editor. PluginData { .... Plugins { OpenGLShaderEdit = ("GLShaderEdit/GLShaderEdit.dll") } } 3.2) Free Camera The "free" camera allows the user to "fly" around the rendered scene to view what actual geometry is sent to the graphics card. This plugin relies on correct usage of the modelview matrix and its usage in all vertex programs. (Some applications with reverse perspective matrices may need to change the key combinations as the controls will be flipped) Many other options are also provided to aid in debugging. (see the plugins' config.ini file for full details) Default key options of note: ctrl,shift,c - Enable/Disable the free camera keys p - Reset camera position o - Reset camera orientation ctrl,shift,u - Enable/Disable back face culling ctrl,shift,w - Enable/Disable wire frame mode ctrl,shift,v - Enable/Disable rendering of the view frustum i,k,j,l, - Forward/Back/Left/Right movement when in free cam mode Num pad keys - Pith/Roll/Yaw movement when in free cam mode Shift - Movement multiplier (settable value - default = 10x) Add the following lines to the gliConfig.ini to use the free camera plugin. PluginData { .... Plugins { OpenGLFreeCamera = ("GLFreeCam/GLFreeCam.dll") } } 3.3) Extension/Version override The extension override plugin allows the user to add/remove/replace OpenGL reported extensions. This plugin also allows the overiding of version/vender/renderer etc strings. In addition, the string marker interface extension GL_GREMEDY_string_marker can be enabled/disabled via this plugin. This extension allows the insertion of plain text strings inside the GLIntercept log. (eg "Drawing room 1") This extension is enabled by default and can be toggled via the EnableStringMarker option. See http://oss.sgi.com/projects/ogl-sample/registry/GREMEDY/string_marker.txt for full details on this extension. (see the plugins' config.ini file for full details of options) Add the following lines to the gliConfig.ini to use the extension override plugin. PluginData { .... Plugins { ExtensionOverride = ("GLExtOverride/GLExtOverride.dll") { //Override options } } } 3.4) Frame Ping The "ping" plugin will attempt to force a refresh of the OpenGL windows if the framerate is too low. This is mostly useful for OpenGL apps that do not continually update. (ie. only update via windows "paint" messages.) Other functionality of GLIntercept requires a continued framerate to function correctly (ie frame-grabber and shader editor) Use this plugin when these functionality is required in applications that do not continually update. (see the plugins' config.ini file for full details) Add the following lines to the gliConfig.ini to use the plugin. PluginData { .... Plugins { PingPlugin = ("GLFramePing/GLFramePing.dll") { //Other options } } } 3.5) Function Stats The function statistics plugin will write to the GLIntercept log (gliLog.txt) the call counts for each OpenGL function called (on shutdown). (see the plugins' config.ini file for full details) Add the following lines to the gliConfig.ini to use the plugin. PluginData { .... Plugins { FunctionStats = ("GLFuncStats/GLFuncStats.dll"); { //Other options } } } ============================================================ 4) Known bugs NOTE: GLIntercept will currently not handle multiple render contexts running on multiple threads at the same time. See the above note in section 1. There are currently no known bugs in GLIntercept, however, the advanced loggers (ie.image,shader) assume that all function calls are valid. For this reason, ensure the application is free of OpenGL errors for correct usage of these loggers. Possible bugs are expected in the advanced loggers if "unusual" work is done in display lists. (ie texture/shader creation or general operations that will not get compiled into the list) This is especially true if the "compile and execute" option is used when creating the display list. GLIntercept will also have trouble determining if a display list performs render calls if it calls another display list internally to perform the render. (This will affect the frame logger) ARB GLSL Interface - The GLSL logger and editor have been updated to the OpenGL 2.0 interfaces. As a result, a OpenGL 2.0 implementation is now needed to run these features. If the old ARB interface is used, GLIntercept will still work as long as the OpenGL 2.0 implementation will interact with the ARB implementation. (both Nvidia and ATI do this) Windows XP with SP2 - Generated xml logs that use xsl will not display correctly using Internet Explorer (security warning). Either use an alternate browser (firefox) or enable enable java scripts to be run from the local harddrive: (Tools->Internet Options->Advanced->Security->Allow active content to run in files on My Computer) A IEViewLog.hta application has been provided for IE users to use instead of opening the main log file. Internet Explorer has no problems if you view the logs from a website. (ie. from glintercept.nutty.org) GLIntercept also relies on a conformant OpenGL implementation. Current known driver issues are: Nvidia 69.xx - The GLSL reporting of uniform rectangle samplers is broken. Nvidia have stated a fix will be in later drivers. Nvidia also have a bug where every uniform array value is reported as a seperate uniform. GLIntercept currently works around this issue. Nvidia 59.xx and earlier - The GLSL shader logger will crash the driver if you attempt to log the current uniforms. This has been fixed in the 61.xx drivers. ATI Radeon Cat 4.1-5.10: - The GLSL shader logger will report GL errors if uniform logging is turned on and samplers are contained inside the shaders. For some reason glGetUniform does not work for sampler values and reports an error upon calling. Also note that due to this, the sampler values reported in the log will be incorrect. This bug also affects the GLSL shader editor and logger but has been worked around in the latest GLIntercept. ATI Radeon Cat 4.1: - glGetTexImage does not return the correct faces when retrieving cube maps. This has been fixed in Cat 5.1 - when using WGL_ARB_render_texture, calls to glGetIntegerv(GL_TEXTURE_BINDING_2D,&retVal); do not return the currently bound texture id when the texture is bound to a p-buffer. It seems the driver is allocating a new texture internally when the texture is bound to a p-buffer. GLIntercept will complain about a texture ID that is being used that was not created. The state of what textures are bound during a render call is also wrong in the log output because of this. This has been fixed in Cat 5.1 ============================================================ 5) Adding OpenGL extensions While GLIntercept does cover most common extensions, adding new extensions is trivial. To add a new OpenGL extension, access the GLFunctions folder in the install directory and add a file containing the new tokens/functions to the folder. The syntax of these files is very close to standard C so reference the existing files for syntax. Then add a #include directive to the gliIncludes.h file. GLIntercept will log any parse errors in the file to the gliLog.txt file next time you run a OpenGL app. (no re-compiling is necessary) ============================================================ 6) Contact Any questions/bug reports/feature requests can be sent to: dtrebilco@techie.com This account is usually only checked on weekends so allow about a week if you expect a reply. ============================================================ 7) Disclaimer This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.