docs/MESA_program_debug.spec

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();