diff options
| -rw-r--r-- | docs/MESA_program_debug.spec | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/docs/MESA_program_debug.spec b/docs/MESA_program_debug.spec new file mode 100644 index 00000000000..67115532c25 --- /dev/null +++ b/docs/MESA_program_debug.spec @@ -0,0 +1,285 @@ +Name + + MESA_program_debug + +Name Strings + + GL_MESA_program_debug + +Contact + + Brian Paul (brian_e_paul 'at' yahoo.com) + +Status + + XXX - Not complete yet!!! + +Version + + Last Modified Date: July 20, 2003 + Author Revision: 1.0 + $Date: 2003/07/21 04:23:32 $ $Revision: 1.1 $ + +Number + + TBD + +Dependencies + + OpenGL 1.4 is required + The extension is written against the OpenGL 1.4 specification. + ARB_vertex_program or ARB_fragment_program or NV_vertex_program + or NV_fragment_program is required. + +Overview + + The extension provides facilities for implementing debuggers for + vertex and fragment programs. + + The concept is that vertex and fragment program debuggers will be + implemented outside of the GL as a utility package. This extension + only provides the minimal hooks required to implement a debugger. + + There are facilities to do the following: + 1. Query the current values of input, output and temporary registers. + 2. Query the current program position during execution. + 3. Have the GL call a user-specified function prior to executing + each vertex or fragment instruction. + + The main feature is the ProgramCallbackMESA function. It allows the + user to register a callback function with the GL. The callback will + be called prior to executing each vertex or fragment program instruction. + The callback function can determine whether to return immediately (to + continue program execution) or stop and process user commands. + + From within the callback, the user may issue glGet* commands to + query current GL state. The GetProgramRegisterfvMESA function allows + all program register values to be queried (such as temporaries, + input attributes, and result registers). + + There are flags for enabling/disabling the program callbacks. + + The current execution position (as an offset from the start of the + program string) can be queried with + GetIntegerv(GL_FRAGMENT_PROGRAM_POSITION_MESA, &pos) or + GetIntegerv(GL_VERTEX_PROGRAM_POSITION_MESA, &pos). + + +IP Status + + None + +Issues + + 1. Is this the right model for a debugger? + + It seems prudent to minimize the scope of this extension and leave + it up to the developer (or developer community) to write (a) + debugger(s) that layer on top of this extension. + + If the debugger were fully implemented within the GL it's not + clear how terminal and GUI-based interfaces would work, for + example. + + 2. There aren't any other extensions that register callbacks with + the GL. Isn't there another solution? + + If we want to be able to single-step through vertex/fragment + programs I don't see another way to do it. + + 3. How do we prevent the user from doing something crazy in the + callback function, like trying to call glBegin? + + The rule is that the callback function can only issue glGet*() + functions and no other GL commands. It could be difficult to + enforce this, however. Therefore, calling any non-get GL + command from within the callback will result in undefined + results. + + 4. Is this extension amenable to hardware implementation? + + Unresolved, but we'd hope so. Perhaps the GL implementation + will have to fall back to a software path when debugging. + + +New Procedures and Functions (and datatypes) + + typedef void (*programcallbackMESA)(enum target, void *data) + + void ProgramCallbackMESA(enum target, programcallbackMESA callback, + void *data) + + void GetProgramRegisterfvMESA(enum target, sizei len, + const ubyte *registerName, float *v) + +New Tokens + + Accepted by the <cap> parameter of Enable, Disable, IsEnabled, + GetBooleanv, GetDoublev, GetFloatv and GetIntegerv: + + FRAGMENT_PROGRAM_CALLBACK_MESA 0x???? + VERTEX_PROGRAM_CALLBACK_MESA 0x???? + + Accepted by the <pname> parameter GetBooleanv, GetDoublev, + GetFloatv and GetIntegerv: + + FRAGMENT_PROGRAM_POSITION_MESA 0x???? + VERTEX_PROGRAM_POSITION_MESA 0x???? + + Accepted by the <pname> parameter of GetPointerv: + + FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x???? + FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x???? + VERTEX_PROGRAM_CALLBACK_FUNC_MESA 0x???? + VERTEX_PROGRAM_CALLBACK_DATA_MESA 0x???? + +Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation) + + None. + +Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization) + + None. + +Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment +Operations and the Frame Buffer) + + None. + +Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions) + + XXX Document ProgramCallbackMESA here + + Add to the list of functions which cannot be included in display + lists: ProgramCallbackMESA. + + +Additions to Chapter 6 of the OpenGL 1.4 Specification (State and +State Requests) + + XXX document GetProgramRegisterfvMESA here + + + +Additions to Appendix A of the OpenGL 1.4 Specification (Invariance) + + None. + +Additions to the AGL/GLX/WGL Specifications + + None. + +GLX Protocol + + XXX TBD + +Dependencies on NV_vertex_program and NV_fragment_program + + If NV_vertex_program and/or NV_fragment_program are supported, + vertex and/or fragment programs defined by those extensions may + be debugged as well. Register queries will use the syntax used + by those extensions (i.e. "v[X]" to query vertex attributes, + "o[X]" for vertex outputs, etc.) + +Errors + + INVALID_OPERATION is generated if ProgramCallbackMESA is called + between Begin and End. + + INVALID_ENUM is generated by ProgramCallbackMESA if <target> is not + a supported vertex or fragment program type. + + Note: INVALID_OPERAION IS NOT generated by GetProgramRegisterfvMESA, + GetBooleanv, GetDoublev, GetFloatv, or GetIntegerv if called between + Begin and End. + These functions may be called from the user-provided callback function + which is called between Begin/End. + + INVALID_ENUM is generated by ProgramCallbackMESA, + GetProgramRegisterfvMESA if <target> is not a program target supported + by ARB_vertex_program, ARB_fragment_program (or NV_vertex_program or + NV_fragment_program). + + INVALID_VALUE is generated by GetProgramRegisterfvMESA if <registerName> + is not a recognized program register. + + INVALID_OPERATION is generated by GetProgramRegisterfvMESA when a + register query is attempted for a program target that's not currently + being executed. + + +New State + + XXX finish + +(table 6.N, p. ###) + Initial + Get Value Type Get Command Value Description Sec. Attribute + --------- ---- ----------- ----- ----------- ---- --------- + FRAGMENT_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable + VERTEX_PROGRAM_CALLBACK_MESA B IsEnabled FALSE XXX XXX enable + FRAGMENT_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX - + VERTEX_PROGRAM_POSITION_MESA Z+ GetIntegerv -1 XXX XXX - + FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX - + VERTEX_PROGRAM_CALLBACK_FUNC_MESA P GetPointerv NULL XXX XXX - + FRAGMENT_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX - + VERTEX_PROGRAM_CALLBACK_DATA_MESA P GetPointerv NULL XXX XXX - + + XXX more? + +New Implementation Dependent State + + None. + +Revision History + + 8 July 2003 + Initial draft. (Brian Paul) + 11 July 2003 + Second draft. (Brian Paul) + 20 July 2003 + Third draft. Lots of fundamental changes. (Brian Paul) + +Example Usage + +/* This is called by the GL when the vertex program is executing. + * We can only make glGet* calls from within this function! + */ +void DebugCallback(GLenum target, GLvoid *data) +{ + GLint pos; + GLuint i; + + /* Get PC and current instruction string */ + glGetIntegerv(GL_VERTEX_PROGRAM_POSITION_ARB, &pos); + + printf("Current position: %d\n", pos); + + printf("Current temporary registers:\n"); + for (i = 0; i < 4; i++) { + GLfloat v[4]; + char s[10]; + sprintf(s, "R%d", i); + glGetProgramRegisterfvMESA(GL_VERTEX_PROGRAM_ARB, strlen(s), s, v); + printf("R%d = %g, %g, %g, %g\n", i, v[0], v[1], v[2], v[3]); + } +} + + + /* + * elsewhere... + */ + + /* Register our debugger callback function */ + glProgramCallbackMESA(GL_VERTEX_PROGRAM_ARB, DebugCallback, NULL); + glEnable(GL_VERTEX_PROGRAM_CALLBACK_MESA); + + /* define/bind a vertex program */ + + glEnable(GL_VERTEX_PROGRAM); + + /* render something */ + glBegin(GL_POINTS); + glVertex2f(0, 0); + glEnd(); + |