docs/MESA_program_debug.spec

   1 Name
   2
   3     MESA_program_debug
   4
   5 Name Strings
   6
   7     GL_MESA_program_debug
   8
   9 Contact
  10
  11     Brian Paul (brian.paul 'at' tungstengraphics.com)
  12
  13 Status
  14
  15     XXX - Not complete yet!!!
  16
  17 Version
  18
  19     Last Modified Date: July 20, 2003
  20     Author Revision: 1.0
  21     $Date: 2004/03/25 01:42:41 $ $Revision: 1.4 $
  22
  23 Number
  24
  25     TBD
  26
  27 Dependencies
  28
  29     OpenGL 1.4 is required
  30     The extension is written against the OpenGL 1.4 specification.
  31     ARB_vertex_program or ARB_fragment_program or NV_vertex_program
  32     or NV_fragment_program is required.
  33
  34 Overview
  35
  36     The extension provides facilities for implementing debuggers for
  37     vertex and fragment programs.
  38
  39     The concept is that vertex and fragment program debuggers will be
  40     implemented outside of the GL as a utility package.  This extension
  41     only provides the minimal hooks required to implement a debugger.
  42
  43     There are facilities to do the following:
  44     1. Have the GL call a user-specified function prior to executing
  45        each vertex or fragment instruction.
  46     2. Query the current program string's execution position.
  47     3. Query the current values of intermediate program values.
  48
  49     The main feature is the ProgramCallbackMESA function.  It allows the
  50     user to register a callback function with the GL.  The callback will
  51     be called prior to executing each vertex or fragment program instruction.
  52
  53     From within the callback, the user may issue Get* commands to
  54     query current GL state.  The GetProgramRegisterfvMESA function allows
  55     current program values to be queried (such as temporaries, input
  56     attributes, and result registers).
  57
  58     There are flags for enabling/disabling the program callbacks.
  59
  60     The current execution position (as an offset from the start of the
  61     program string) can be queried with
  62     GetIntegerv(GL_FRAGMENT_PROGRAM_POSITION_MESA, &pos) or
  63     GetIntegerv(GL_VERTEX_PROGRAM_POSITION_MESA, &pos).
  64
  65
  66 IP Status
  67
  68     None
  69
  70 Issues
  71
  72     1. Is this the right model for a debugger?
  73
  74        It seems prudent to minimize the scope of this extension and leave
  75        it up to the developer (or developer community) to write debuggers
  76        that layer on top of this extension.
  77
  78        If the debugger were fully implemented within the GL it's not
  79        clear how terminal and GUI-based interfaces would work, for
  80        example.
  81
  82     2. There aren't any other extensions that register callbacks with
  83        the GL.  Isn't there another solution?
  84
  85        If we want to be able to single-step through vertex/fragment
  86        programs I don't see another way to do it.
  87
  88     3. How do we prevent the user from doing something crazy in the
  89        callback function, like trying to call glBegin (leading to
  90        recursion)?
  91
  92        The rule is that the callback function can only issue glGet*()
  93        functions and no other GL commands.  It could be difficult to
  94        enforce this, however.  Therefore, calling any non-get GL
  95        command from within the callback will result in undefined
  96        results.
  97
  98     4. Is this extension amenable to hardware implementation?
  99
 100        Hopefully, but if not, the GL implementation will have to fall
 101        back to a software path when debugging.  This may be acceptable
 102        for debugging.
 103
 104     5. What's the <data> parameter to ProgramCallbackMESA for?
 105
 106        It's a common programming practice to associate a user-supplied
 107        value with callback functions.
 108
 109     6. Debuggers often allow one to modify intermediate program values,
 110        then continue.  Does this extension support that?
 111
 112        No.
 113
 114
 115 New Procedures and Functions (and datatypes)
 116
 117     typedef void (*programcallbackMESA)(enum target, void *data)
 118
 119     void ProgramCallbackMESA(enum target, programcallbackMESA callback,
 120                              void *data)
 121
 122     void GetProgramRegisterfvMESA(enum target, sizei len,
 123                                   const ubyte *registerName, float *v)
 124
 125 New Tokens
 126
 127     Accepted by the <cap> parameter of Enable, Disable, IsEnabled,
 128     GetBooleanv, GetDoublev, GetFloatv and GetIntegerv:
 129
 130         FRAGMENT_PROGRAM_CALLBACK_MESA      0x8bb1
 131         VERTEX_PROGRAM_CALLBACK_MESA        0x8bb4
 132
 133     Accepted by the <pname> parameter GetBooleanv, GetDoublev,
 134     GetFloatv and GetIntegerv:
 135
 136         FRAGMENT_PROGRAM_POSITION_MESA      0x8bb0
 137         VERTEX_PROGRAM_POSITION_MESA        0x8bb4
 138
 139     Accepted by the <pname> parameter of GetPointerv:
 140
 141         FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x8bb2
 142         FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x8bb3
 143         VERTEX_PROGRAM_CALLBACK_FUNC_MESA   0x8bb6
 144         VERTEX_PROGRAM_CALLBACK_DATA_MESA   0x8bb7
 145
 146 Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
 147
 148     None.
 149
 150 Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
 151
 152     None.
 153
 154 Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
 155 Operations and the Frame Buffer)
 156
 157     None.
 158
 159 Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
 160
 161     In section 5.4 "Display Lists", page 202, add the following command
 162     to the list of those that are not compiled into display lists:
 163
 164         ProgramCallbackMESA.
 165
 166
 167     Add a new section 5.7 "Callback Functions"
 168
 169     The function
 170
 171         void ProgramCallbackMESA(enum target, programcallbackMESA callback,
 172                                  void *data)
 173
 174     registers a user-defined callback function with the GL.  <target>
 175     may be FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB.  The enabled
 176     callback functions registered with these targets will be called
 177     prior to executing each instruction in the current fragment or
 178     vertex program, respectively.  The callbacks are enabled and
 179     disabled by calling Enable or Disable with <cap>
 180     FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB.
 181
 182     The callback function's signature must match the typedef
 183
 184         typedef void (*programcallbackMESA)(enum target, void *data)
 185
 186     When the callback function is called, <target> will either be
 187     FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which
 188     program is currently executing and <data> will be the value
 189     specified when ProgramCallbackMESA was called.
 190
 191     From within the callback function, only the following GL commands
 192     may be called:
 193
 194         GetBooleanv
 195         GetDoublev
 196         GetFloatv
 197         GetIntegerv
 198         GetProgramLocalParameter
 199         GetProgramEnvParameter
 200         GetProgramRegisterfvMESA
 201         GetProgramivARB
 202         GetProgramStringARB
 203         GetError
 204
 205     Calling any other command from within the callback results in
 206     undefined behaviour.
 207
 208
 209 Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
 210 State Requests)
 211
 212     Add a new section 6.1.3 "Program Value Queries":
 213
 214     The command
 215
 216         void GetProgramRegisterfvMESA(enum target, sizei len,
 217                                       const ubyte *registerName,
 218                                       float *v)
 219
 220     Is used to query the value of program variables and registers
 221     during program execution.  GetProgramRegisterfvMESA may only be
 222     called from within a callback function registered with
 223     ProgramCallbackMESA.
 224
 225     <registerName> and <len> specify the name a variable, input
 226     attribute, temporary, or result register in the program string.
 227     The current value of the named variable is returned as four
 228     values in <v>.  If <name> doesn't exist in the program string,
 229     the error INVALID_OPERATION is generated.
 230
 231 Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
 232
 233     None.
 234
 235 Additions to the AGL/GLX/WGL Specifications
 236
 237     None.
 238
 239 GLX Protocol
 240
 241     XXX TBD
 242
 243 Dependencies on NV_vertex_program and NV_fragment_program
 244
 245     If NV_vertex_program and/or NV_fragment_program are supported,
 246     vertex and/or fragment programs defined by those extensions may
 247     be debugged as well.  Register queries will use the syntax used
 248     by those extensions (i.e. "v[X]" to query vertex attributes,
 249     "o[X]" for vertex outputs, etc.)
 250
 251 Errors
 252
 253     INVALID_OPERATION is generated if ProgramCallbackMESA is called
 254     between Begin and End.
 255
 256     INVALID_ENUM is generated by ProgramCallbackMESA if <target> is not
 257     a supported vertex or fragment program type.
 258
 259     Note: INVALID_OPERAION IS NOT generated by GetProgramRegisterfvMESA,
 260     GetBooleanv, GetDoublev, GetFloatv, or GetIntegerv if called between
 261     Begin and End when a vertex or fragment program is currently executing.
 262
 263     INVALID_ENUM is generated by ProgramCallbackMESA,
 264     GetProgramRegisterfvMESA if <target> is not a program target supported
 265     by ARB_vertex_program, ARB_fragment_program (or NV_vertex_program or
 266     NV_fragment_program).
 267
 268     INVALID_VALUE is generated by GetProgramRegisterfvMESA if <registerName>
 269     does not name a known program register or variable.
 270
 271     INVALID_OPERATION is generated by GetProgramRegisterfvMESA when a
 272     register query is attempted for a program target that's not currently
 273     being executed.
 274
 275
 276 New State
 277
 278     XXX finish
 279
 280 (table 6.N, p. ###)
 281                                                             Initial
 282     Get Value                            Type Get Command   Value    Description  Sec.  Attribute
 283     ---------                            ---- -----------   -----    -----------  ----  ---------
 284     FRAGMENT_PROGRAM_CALLBACK_MESA        B   IsEnabled     FALSE    XXX          XXX   enable
 285     VERTEX_PROGRAM_CALLBACK_MESA          B   IsEnabled     FALSE    XXX          XXX   enable
 286     FRAGMENT_PROGRAM_POSITION_MESA        Z+  GetIntegerv   -1       XXX          XXX   -
 287     VERTEX_PROGRAM_POSITION_MESA          Z+  GetIntegerv   -1       XXX          XXX   -
 288     FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA   P   GetPointerv   NULL     XXX          XXX   -
 289     VERTEX_PROGRAM_CALLBACK_FUNC_MESA     P   GetPointerv   NULL     XXX          XXX   -
 290     FRAGMENT_PROGRAM_CALLBACK_DATA_MESA   P   GetPointerv   NULL     XXX          XXX   -
 291     VERTEX_PROGRAM_CALLBACK_DATA_MESA     P   GetPointerv   NULL     XXX          XXX   -
 292
 293     XXX more?
 294
 295 New Implementation Dependent State
 296
 297     None.
 298
 299 Revision History
 300
 301     8 July 2003
 302         Initial draft. (Brian Paul)
 303     11 July 2003
 304         Second draft. (Brian Paul)
 305     20 July 2003
 306         Third draft.  Lots of fundamental changes. (Brian Paul)
 307     23 July 2003
 308         Added chapter 5 and 6 spec language. (Brian Paul)
 309
 310 Example Usage
 311
 312    The following is a very simple example of how this extension may
 313    be used to print the values of R0, R1, R2 and R3 while executing
 314    vertex programs.
 315
 316
 317     /* This is called by the GL when the vertex program is executing.
 318      * We can only make glGet* calls from within this function!
 319      */
 320     void DebugCallback(GLenum target, GLvoid *data)
 321     {
 322        GLint pos;
 323        GLuint i;
 324
 325        /* Get PC and current instruction string */
 326        glGetIntegerv(GL_VERTEX_PROGRAM_POSITION_ARB, &pos);
 327
 328        printf("Current position: %d\n", pos);
 329
 330        printf("Current temporary registers:\n");
 331        for (i = 0; i < 4; i++) {
 332           GLfloat v[4];
 333           char s[10];
 334           sprintf(s, "R%d", i);
 335           glGetProgramRegisterfvMESA(GL_VERTEX_PROGRAM_ARB, strlen(s), s, v);
 336           printf("R%d = %g, %g, %g, %g\n", i, v[0], v[1], v[2], v[3]);
 337        }
 338     }
 339
 340
 341     /*
 342      * elsewhere...
 343      */
 344
 345     /* Register our debugger callback function */
 346     glProgramCallbackMESA(GL_VERTEX_PROGRAM_ARB, DebugCallback, NULL);
 347     glEnable(GL_VERTEX_PROGRAM_CALLBACK_MESA);
 348
 349     /* define/bind a vertex program */
 350
 351     glEnable(GL_VERTEX_PROGRAM);
 352
 353     /* render something */
 354     glBegin(GL_POINTS);
 355     glVertex2f(0, 0);
 356     glEnd();
 357