User Guide

The glBugger gui consists of six main screens:

●    The Main Window - The glBugger main window.

●    The Configuration Screen - In which you can configure the application settings, the output files paths and the Text editor to use.

●    The Function State Dialog - In which you can go over the OpenGL function list and trace a specific function, change it's state and pause the application every time it calls this function.

●    The State Window - In which you can go over the OpenGL states, change their status and protect/unprotect them.

●    The Value Window - In which you can observe a specific value - as a matrix , a bit mask or as a GLEnum.

●    Matrix Stacks Window - In which you can perform a constant number of operations on OpenGL matrix's.

●    3DModeling Window - In which you can parse the glBugger modeling file into IRIT model files and to VRML modeling files.

The Main Window

    This is the main glBugger interface which connects to the running application using shared memory between the two processes. This windows allows you to control running status of your debugged application. You can "Open" a new project, start a "New" project and "Save" the current project you are working on.

    After configuring glBugger for the application you want to debug using the "Configure glBugger" button (see configuration window documentation), you will be able to :

1. Run the application which you want to debug ("Run app" button).

2. Pause and Resume the application, in order to inspect OpenGL states currently used by the application ("Paused Ogl" and "unPaused OGL" buttons). The current application status is indicated in the

    "Write Buffer", gives you the ability to write current state of one of the image buffers to a bmp file, in order to view its content. we would advice you to pause the application in order to do this action.

    This Dialog also provides you the ability to force your application to use a single buffer drawing (force not drawing to the back buffer while looking at the front one). in order to turn this option on, just click on the check box provided on this dialog ("Draw only to front buffer").

    "Outputs" section gives you an easy access to the debugging data which is prepared for you by glBugger. By choosing one of the options from the provided list and pressing the "Open" button, you can open your defined text viewer with the file you chose.
 

Back ->


 

The Configuration Screen

    This dialog must be configured for every application you would like to debug. All o these configurations are well known from Visual Studio concept (running application, working directory, program arguments).

    Use the "Copy Dlls To Working Directory" button in order to copy all the needed Dlls to  your new working directory.

    The output files you define here, if enabled, will be created by glBugger in order to produce debugging information.

• Images Directory : please stated here where you want the textures used by running application be saved. This option provides you an option to write the textures used by your running application to this directory as a BMP files. This is very useful to make sure you are passing the right textures at the right time to your glTexImage2d() funtion.
   

• 3D Modeling File : this files will contain all the information needed to debug your 3D models produced by your application. which means, glBugger will log here all the 3D data used to produce the models presented by the application (display lists info, polygons, lines , quads ... ). use this option in order inspect what kind of modeling is done by the application.
   

• Errors File : will let you know, if glBugger had any problems running itself for example:
  failing opening a shared memory to the GUI program, or allocating texture files.
   

• Messages Files : will provide you all sorts of possitive messages, for example which texture has been written last.
   

• Functions Logging File : is the main file produced by glBugger, it gives you a general view on OpenGL function calls.
  This File also provides you the information about , glErrors. every time an error accors (OpenGL error) a message is logged in this file as well as in glBuggerErrorFile. This might be very useful, you can always use notepad.exe in order to seek for the word "Error" in order to know, whether an error has ever accored while running the application.

       You can define the program to use your own text viewer in order to view the outputs (see main window documantation). Just enter the path to your text viewer utility in the "Text Edittor" section.
 

Back ->


 

    The Function State Dialog

    This Dialog provides you some very useful information and status of OpenGL functions status. This dialog concept is very similar to ConfigureStates dialog, so please make sure you understand it before you read all about this one.

    In current glBuuger version, you can change Functions states to :

1. Trace - which will log function calls to this function to glBuggerLogging file.
    

2. Trace and Stop - this will cause glBugger to pause your application every time a function call to this function has been made. Please don't forget that paused application don't run :) which mean, every call to a "Trace and Stop" function, you will have to press Pause button placed on the Main glBugger dialog
    

3. Don't trace, and Don't Stop, means glBugger won't log , and won't pause the application on this for this function.

    In order to change a function's state, select the relevant function from the functions list and change it's status using the "Change Trace Status" button until a wanted function state appears in the table.
    In order to update the changes to the DLL, click on the "Upload Data Tp OpenGL dll" button.

IMPORTANT : please don't forget to update the DLL by pressing UpdateDll button so your changes will by written to the DLL.

Back ->


 

The State Window

    Inspecting OpenGL states :

    This dialog is what this project is all about. It should provide you the ability to view all and control (some of) OpenGL state while running your application in RealTime.

    In order to inspect OpenGL states you should have you application get on pause, you can do this in any of the follwing ways :

1. Putting a glBugger breakpoint in your application code, please see details in .\include\glBuggerStop.h file for further details.
    

2. Pressing Pause button on the main glBugger window.
    

3. Configuring one of the functions in Functions Dialog to TRACE_AND_STOP for further details see Functions Dialog documentations.

    After setting you application on pause mode, you can ispect OpenGL states by pressing "Update" button on this dialog. Wait a couple of seconds, and you will see the table on this dialog filled with OpenGL states and their current state. in order to ispect the states, you can use Value button which will present the chosen state in a different more detailed dialog (don't forget to choose a state before you press the button).

    In this version of glBugger it's also possible to change the current state of OpenGL states. In current version you are able to change only states like GL_TEXTURE_2D or GL_BLEND, in other word, states which can be either enabled or disabled. in order to make a change in a state:

1. Pick a state from the table.
    

2. Click "Value" button, and update the state you want to be active (see Value Window documentation).
    

3. IMPORTANT : Press protect button, which means, you don't allow your OpenGL applicaion to change this state anymore while it's protected.
    

4. Press UpdateDll button in order to write new defined states to the running OpenGL DLL so the application will start using these states

    After releasing the application from Pause mode, you new defined states should take place. For example, if you set GL_TEXTURE_2D to protected and false, you won't be able to see the textures in your running application.

    Another option provided by this dialog is to inspect current state of OpenGL Matrixs Stacks. You can do this by updating the dialog and clicking "MatrixStacks" button.

    The dialog supports updating variable’s state change on the fly (updating OpenGL states on the fly). This can be done by changing state value and then press “Upload States To OpenGl.dll” in order to update the state with the new value.

    PROTECTED mode Is used for each state in order to force the running application NOT TO change OpenGL state in hand, Thus protecting the value set by glBugger User. In order to use this mode, highlight the relevant state and press the "Protect" button.

Back ->


 

The Value Window

    In this window you can change the state values using the following buttons. In order to change the value, just change the relevant field and press "OK".
   

  Click the button if you want to see the state as a GLEnum (Enum text filed will befilled).

                 Click the button if you want to see the state as a matrix (The matrix on the dialog will be filled).

  This will show the state as a bit mask (bit mask text field will be filled).

  This will show the state as a hexadecimal mask (HEX mask text field will be filled).
 

Back ->

 

Matrix Stacks Window

3DModeling Window

In order to open this dialog one should choose the “glBugger3DModeling” option from the outputs section.

This dialog is used in order to parse the glBugger modeling file into IRIT model files and to VRML modeling files that are partitially supported for current glBugger version.

The "Output Directory" is set in the Configuration window. In order to view the files that are in the output directory press the "Open Directory" button.

In order to parse the glBugger modeling file into IRIT model files just press the "Parse to IRIT" button.
In order to parse the glBugger modeling file into VRML model files just press the "Parse to VRML" button.
The relevant model files will be created in the output directory.

Back ->


 

All rights reserved © 2005 glBugger