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_e_paul 'at' yahoo.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: 2003/07/21 04:23:32 $ $Revision: 1.1 $
  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. Query the current values of input, output and temporary registers.
  45     2. Query the current program position during execution.
  46     3. Have the GL call a user-specified function prior to executing
  47        each vertex or fragment instruction.
  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     The callback function can determine whether to return immediately (to
  53     continue program execution) or stop and process user commands.
  54
  55     From within the callback, the user may issue glGet* commands to
  56     query current GL state.  The GetProgramRegisterfvMESA function allows
  57     all program register values to be queried (such as temporaries,
  58     input attributes, and result registers).
  59
  60     There are flags for enabling/disabling the program callbacks.
  61
  62     The current execution position (as an offset from the start of the
  63     program string) can be queried with
  64     GetIntegerv(GL_FRAGMENT_PROGRAM_POSITION_MESA, &pos) or
  65     GetIntegerv(GL_VERTEX_PROGRAM_POSITION_MESA, &pos).
  66
  67
  68 IP Status
  69
  70     None
  71
  72 Issues
  73
  74     1. Is this the right model for a debugger?
  75
  76        It seems prudent to minimize the scope of this extension and leave
  77        it up to the developer (or developer community) to write (a)
  78        debugger(s) that layer on top of this extension.
  79
  80        If the debugger were fully implemented within the GL it's not
  81        clear how terminal and GUI-based interfaces would work, for
  82        example.
  83
  84     2. There aren't any other extensions that register callbacks with
  85        the GL.  Isn't there another solution?
  86
  87        If we want to be able to single-step through vertex/fragment
  88        programs I don't see another way to do it.
  89
  90     3. How do we prevent the user from doing something crazy in the
  91        callback function, like trying to call glBegin?
  92
  93        The rule is that the callback function can only issue glGet*()
  94        functions and no other GL commands.  It could be difficult to
  95        enforce this, however.  Therefore, calling any non-get GL
  96        command from within the callback will result in undefined
  97        results.
  98
  99     4. Is this extension amenable to hardware implementation?
 100
 101        Unresolved, but we'd hope so.  Perhaps the GL implementation
 102        will have to fall back to a software path when debugging.
 103
 104
 105 New Procedures and Functions (and datatypes)
 106
 107     typedef void (*programcallbackMESA)(enum target, void *data)
 108
 109     void ProgramCallbackMESA(enum target, programcallbackMESA callback,
 110                              void *data)
 111
 112     void GetProgramRegisterfvMESA(enum target, sizei len,
 113                                   const ubyte *registerName, float *v)
 114
 115 New Tokens
 116
 117     Accepted by the <cap> parameter of Enable, Disable, IsEnabled,
 118     GetBooleanv, GetDoublev, GetFloatv and GetIntegerv:
 119
 120         FRAGMENT_PROGRAM_CALLBACK_MESA      0x????
 121         VERTEX_PROGRAM_CALLBACK_MESA        0x????
 122
 123     Accepted by the <pname> parameter GetBooleanv, GetDoublev,
 124     GetFloatv and GetIntegerv:
 125
 126         FRAGMENT_PROGRAM_POSITION_MESA      0x????
 127         VERTEX_PROGRAM_POSITION_MESA        0x????
 128
 129     Accepted by the <pname> parameter of GetPointerv:
 130
 131         FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x????
 132         FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x????
 133         VERTEX_PROGRAM_CALLBACK_FUNC_MESA   0x????
 134         VERTEX_PROGRAM_CALLBACK_DATA_MESA   0x????
 135
 136 Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
 137
 138     None.
 139
 140 Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
 141
 142     None.
 143
 144 Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
 145 Operations and the Frame Buffer)
 146
 147     None.
 148
 149 Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
 150
 151     XXX Document ProgramCallbackMESA here
 152
 153     Add to the list of functions which cannot be included in display
 154     lists:  ProgramCallbackMESA.
 155
 156
 157 Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
 158 State Requests)
 159
 160     XXX document GetProgramRegisterfvMESA here
 161
 162
 163
 164 Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
 165
 166     None.
 167
 168 Additions to the AGL/GLX/WGL Specifications
 169
 170     None.
 171
 172 GLX Protocol
 173
 174     XXX TBD
 175
 176 Dependencies on NV_vertex_program and NV_fragment_program
 177
 178     If NV_vertex_program and/or NV_fragment_program are supported,
 179     vertex and/or fragment programs defined by those extensions may
 180     be debugged as well.  Register queries will use the syntax used
 181     by those extensions (i.e. "v[X]" to query vertex attributes,
 182     "o[X]" for vertex outputs, etc.)
 183
 184 Errors
 185
 186     INVALID_OPERATION is generated if ProgramCallbackMESA is called
 187     between Begin and End.
 188
 189     INVALID_ENUM is generated by ProgramCallbackMESA if <target> is not
 190     a supported vertex or fragment program type.
 191
 192     Note: INVALID_OPERAION IS NOT generated by GetProgramRegisterfvMESA,
 193     GetBooleanv, GetDoublev, GetFloatv, or GetIntegerv if called between
 194     Begin and End.
 195     These functions may be called from the user-provided callback function
 196     which is called between Begin/End.
 197
 198     INVALID_ENUM is generated by ProgramCallbackMESA,
 199     GetProgramRegisterfvMESA if <target> is not a program target supported
 200     by ARB_vertex_program, ARB_fragment_program (or NV_vertex_program or
 201     NV_fragment_program).
 202
 203     INVALID_VALUE is generated by GetProgramRegisterfvMESA if <registerName>
 204     is not a recognized program register.
 205
 206     INVALID_OPERATION is generated by GetProgramRegisterfvMESA when a
 207     register query is attempted for a program target that's not currently
 208     being executed.
 209
 210
 211 New State
 212
 213     XXX finish
 214
 215 (table 6.N, p. ###)
 216                                                             Initial
 217     Get Value                            Type Get Command   Value    Description  Sec.  Attribute
 218     ---------                            ---- -----------   -----    -----------  ----  ---------
 219     FRAGMENT_PROGRAM_CALLBACK_MESA        B   IsEnabled     FALSE    XXX          XXX   enable
 220     VERTEX_PROGRAM_CALLBACK_MESA          B   IsEnabled     FALSE    XXX          XXX   enable
 221     FRAGMENT_PROGRAM_POSITION_MESA        Z+  GetIntegerv   -1       XXX          XXX   -
 222     VERTEX_PROGRAM_POSITION_MESA          Z+  GetIntegerv   -1       XXX          XXX   -
 223     FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA   P   GetPointerv   NULL     XXX          XXX   -
 224     VERTEX_PROGRAM_CALLBACK_FUNC_MESA     P   GetPointerv   NULL     XXX          XXX   -
 225     FRAGMENT_PROGRAM_CALLBACK_DATA_MESA   P   GetPointerv   NULL     XXX          XXX   -
 226     VERTEX_PROGRAM_CALLBACK_DATA_MESA     P   GetPointerv   NULL     XXX          XXX   -
 227
 228     XXX more?
 229
 230 New Implementation Dependent State
 231
 232     None.
 233
 234 Revision History
 235
 236     8 July 2003
 237         Initial draft. (Brian Paul)
 238     11 July 2003
 239         Second draft. (Brian Paul)
 240     20 July 2003
 241         Third draft.  Lots of fundamental changes. (Brian Paul)
 242
 243 Example Usage
 244
 245 /* This is called by the GL when the vertex program is executing.
 246  * We can only make glGet* calls from within this function!
 247  */
 248 void DebugCallback(GLenum target, GLvoid *data)
 249 {
 250    GLint pos;
 251    GLuint i;
 252
 253    /* Get PC and current instruction string */
 254    glGetIntegerv(GL_VERTEX_PROGRAM_POSITION_ARB, &pos);
 255
 256    printf("Current position: %d\n", pos);
 257
 258    printf("Current temporary registers:\n");
 259    for (i = 0; i < 4; i++) {
 260       GLfloat v[4];
 261       char s[10];
 262       sprintf(s, "R%d", i);
 263       glGetProgramRegisterfvMESA(GL_VERTEX_PROGRAM_ARB, strlen(s), s, v);
 264       printf("R%d = %g, %g, %g, %g\n", i, v[0], v[1], v[2], v[3]);
 265    }
 266 }
 267
 268
 269    /*
 270     * elsewhere...
 271     */
 272
 273    /* Register our debugger callback function */
 274    glProgramCallbackMESA(GL_VERTEX_PROGRAM_ARB, DebugCallback, NULL);
 275    glEnable(GL_VERTEX_PROGRAM_CALLBACK_MESA);
 276
 277    /* define/bind a vertex program */
 278
 279    glEnable(GL_VERTEX_PROGRAM);
 280
 281    /* render something */
 282    glBegin(GL_POINTS);
 283    glVertex2f(0, 0);
 284    glEnd();
 285