Installation

OGLE functions as a plugin to the fantastic and aptly named OpenGL DLL Proxy GLIntercept (specifically, version 0.5). Thus, much of the installation and usage of OGLE is described by the GLIntercept documentation.

1. Download and install GLIntercept 0.5 from http://glintercept.nutty.org/download.html
2. Read all of its documentation, and make sure it works -- try to log OpenGL function calls for the application you will be capturing 3D data from.
3. In using GLIntercept, the author has noticed some problems you may also encounter:
   • Some applications do not seem to want to function (i.e. they crash!) with GLIntercept if the real OpenGL32.dll is in the system location. If you are having wierd problems, try the following:
     1. Copy the sytem dll (most likely C:\WINDOWS\system32\opengl32.dll) to your app's directory (name it opengl32.orig.dll or some such)
     2. Set GLSystemLib = "opengl32.orig.dll"; in your gliConfig.ini file.
   • The Error Checking functionality of GLIntercept can cause applications to run very slowly. Typically we set all of the Error Checking flags (GLErrorChecking, ThreadChecking, BreakOnError, LogOnError, ExtendedErrorLog, DebuggerErrorLog) to False.
   • Same goes for Frame(Buffer) logging. We highly recommend setting FrameLog::LogEnabled to False.
   • Same also goes for per-frame function call logging. We highly recommend setting LogPerFrame::Enabled to True so that GLIntercept only logs when you tell it to, not throughout the whole run of your application.
4. If you do not already have it, download the compiled OGLE plugin from http://ogle.eyebeamresearch.org/download/ (note: you want the most recent .bin distribution, not the .src).
5. Copy the whole OGLE distribution (i.e. the directory that contains the OGLE.dll file) into the Plugins directory for your GLIntercept installation, typically
   C:\Program Files\GLIntercept0_5\Plugins\, and rename the directory to OGLE (i.e. change the name from ogle_* to OGLE).
6. That's it, installed! To use OGLE, keep reading the USAGE section below.

Usage

Most of the work in getting OGLE to capture 3D data is in the configuration of GLIntercept. There are a number of settings that must be made to ensure OGLE functions properly. Since you have already tested the basic GLIntercept functionality, you already know by now that these changes must be made in the gliConfig.ini file in the same directory as your OpenGL-using application.

Configuration:

• Modify the glConfig.ini file that you are using to work with OGLE.
  • The OGLE/config/gliConfig_OGLE.ini file that comes with this distribution works well for the author, so you can try just copying that over your gliConfig.ini file.
  • OR, you can make the following specific isolated configuration changes:

    LogEnabled = True;
    ...
    LogPerFrame
    {
      Enabled = True;
      ...
      OneFrameOnly = True; 
    }
    ...	    	    
    PluginData
    {
      ...
      Plugins
      {
        ...
        OGLE = ("OGLE/OGLE.dll") 
        {
    	Scale = 1.0;
    	FlipPolygonStrips = True;
    	CaptureNormals = False;
    	CaptureTextureCoords = False;
    	LogFunctions = False;
    	ObjFileName = "ogle";
            FilePerFrame = False;
            FileInFrameDir = False;
    
    	TRIANGLES = True;
    	TRIANGLE_STRIP = True;
    	TRIANGLE_FAN = True;
    	QUADS = True;
    	QUAD_STRIP = True;
    	POLYGON = True;
        }
    	  

• OGLE has a number of custom settings that can be set in the Plugins section of gliConfig.ini or in the Plugins\OGLE\config.ini file:
  • Scale
    Scale all vertices by some value. This is a convenience feature for use when the application you are capturing from uses absurdly small or large scales for no particular reason (you may recognize the need for this if the result file is very difficult to look at in your 3D modeling software).
  • FlipPolygonStrips
    Flip (re-orient) every other polygon drawn with the TRIANGLE_STRIP or QUAD_STRIP primitive. This mimics OpenGL's behavior to get all the polygons facing the right way. Defaults to True.
  • CaptureNormals
    Capture vertex normals. Currently this defaults to False because there is a suspected bug in the code that does it.
  • CaptureTextureCoords
    Capture texture coordinates (UV). Currently this defaults to False because there is a suspected bug in the code that does it. If you are going to use this option to try to re-assign the texture maps that GLIntercept writes to disk, you will need to flip those textures, or just use the ImageLog::FlipXAxis option for GLIntercept.
  • LogFunctions
    Log all the function calls that OGLE sees (a select subset of what GLIntercept logs) to the ogle.log file.
  • ObjFileName
    name of the actual .obj file to be outputted. This file will be written in the directory from which you run your application.
  • FileInFrameDir
    flag whether or not to attempt to place the ouput OBJ file into the Frame_###### directory that GLIntercept creates.
  • FilePerFrame
    flag whether or not to name your output file with the current frame #. this allows you to capture more than one data set per run of your application.
  • TRIANGLES, TRIANGLE_STRIP, TRIANGLE_FAN, QUADS, QUAD_STRIP, POLYGON
    flags for whether or not to capture polygons rendered by each of the specific OpenGL primitives. This is configurable because you may want to disregard data drawn as a certain type of polygon for certain applications. See http://www.eecs.tulane.edu/www/Terry/OpenGL/Primitives.html for more info about the OpenGL primitive types.
• The OGLE GUI: Someone has put together a Windows GUI app that supposedly makes all tihs copying and configuring a lot easier. You can try it at your own risk at: http://members.chello.at/alexan/ and give the creator feedback on the SourceForge forum.

Data Capture Activation:

1. Run your OpenGL application with GLIntercept configured to use the OGLE plugin (as seen above).
2. Activate frame logging using whatever keystrokes you have configured with the LogPerFrame::FrameStartKeys variable.
3. Be patient -- your app will freeze and it can take a number of seconds or minutes for GLIntercept to log all of the data for that frame and OGLE to generate the 3D object file for the on-screen geometry. You will know that it is done when your application becomes interactive again.
4. Find the .obj file in the directory where your application runs. Open it in Blender (free!), ArtOfIllusion (also free!), Maya (not free), or whatever other 3D editing/viewing/modelling application you use. See the tools section of this site for links/recommendations.
5. If the data capture appears to work, but the data you actually see in your 3D modelling software seems busted, you might want to play around with some of the above configuration options for OGLE -- try changing the Scale, turning on CaptureNormals, or disabling some of the primitive types.

FAQ:

• My program crashes off the bat whenever I try to run it with OGLE: You probably missed the pointers in the GLIntercept problems section of this page (step 3 of the Installation instructions).
• OGLE runs, but doesn't appear to capture any useful data when I open the .obj file in my 3D modeler:
  It is possible that the application works on a scale that so big or so small that it's hard to view the data. Try playing with the Scale configuration option.
  
• OGLE runs, but all the objects appear to be smushed around the origin:
  Your application is probably using Vertex Programs to do positioning (see the Limitations page). But, you can disable that functionality from OpenGL using the GLExtOverride plugin that comes with GLIntercept (described in the forums) by making the following additions to your glConfig.ini file:

  ...	    	    
  PluginData
  {
    ...
    Plugins
    {
      ...
  
        ExtensionOverride = ("GLExtOverride/GLExtOverride.dll") 
        { 
  	RemoveExtensions = (GL_ARB_vertex_program, GL_ARB_fragment_program); 
        }
  

• OGLE runs, but the capture is really a complete mess:
  It is possible that your application does something extra funky with Vertex Buffer Objects that confuses OGLE. We recommend attempting to disable Vertex Buffer Objects much the same way that we disabled Vertex Programs above:

   
    ...
  	RemoveExtensions = (GL_ARB_vertex_buffer_object); 
    ...
  
  

  Note: you will probably want to remove Vertex Programs as well as Vertex Buffer Objects, as such:
  RemoveExtensions = (GL_ARB_vertex_program, GL_ARB_fragment_program, GL_ARB_vertex_buffer_object)