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