Home | History | Annotate | Download | only in docs 
      1 Name
      2 
      3     MESA_shader_debug
      4 
      5 Name Strings
      6 
      7     GL_MESA_shader_debug
      8 
      9 Contact
     10 
     11     Brian Paul (brian.paul 'at' tungstengraphics.com)
     12     Michal Krol (mjkrol 'at' gmail.com)
     13 
     14 Status
     15 
     16     Obsolete.
     17 
     18 Version
     19 
     20     Last Modified Date: July 30, 2006
     21     Author Revision: 0.2
     22 
     23 Number
     24 
     25     TBD
     26 
     27 Dependencies
     28 
     29     OpenGL 1.0 is required.
     30 
     31     The ARB_shader_objects extension is required.
     32 
     33     The ARB_shading_language_100 extension is required.
     34 
     35     The extension is written against the OpenGL 1.5 specification.
     36 
     37     The extension is written against the OpenGL Shading Language 1.10
     38     Specification.
     39 
     40 Overview
     41 
     42     This extension introduces a debug object that can be attached to
     43     a program object to enable debugging. Vertex and/or fragment shader,
     44     during execution, issue diagnostic function calls that are logged
     45     to the debug object's log. A separate debug log for each shader type
     46     is maintained. A debug object can be attached, detached and queried
     47     at any time outside the Begin/End pair. Multiple debug objects can
     48     be attached to a single program object.
     49 
     50 IP Status
     51 
     52     None
     53 
     54 Issues
     55 
     56     None
     57 
     58 New Procedures and Functions
     59 
     60     handleARB CreateDebugObjectMESA(void)
     61     void ClearDebugLogMESA(handleARB obj, enum logType, enum shaderType)
     62     void GetDebugLogMESA(handleARB obj, enum logType, enum shaderType,
     63                          sizei maxLength, sizei *length,
     64                          charARB *debugLog)
     65     sizei GetDebugLogLengthMESA(handleARB obj, enum logType,
     66                                 enum shaderType)
     67 
     68 New Types
     69 
     70     None
     71 
     72 New Tokens
     73 
     74     Returned by the <params> parameter of GetObjectParameter{fi}vARB:
     75 
     76         DEBUG_OBJECT_MESA                               0x8759
     77 
     78     Accepted by the <logType> argument of ClearDebugLogMESA,
     79     GetDebugLogLengthMESA and GetDebugLogMESA:
     80 
     81         DEBUG_PRINT_MESA                                0x875A
     82         DEBUG_ASSERT_MESA                               0x875B
     83 
     84 Additions to Chapter 2 of the OpenGL 1.5 Specification
     85 (OpenGL Operation)
     86 
     87     None
     88 
     89 Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization)
     90 
     91     None
     92 
     93 Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
     94 Operations and the Frame Buffer)
     95 
     96     None
     97 
     98 Additions to Chapter 5 of the OpenGL 1.5 Specification
     99 (Special Functions)
    100 
    101     None
    102 
    103 Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
    104 Requests)
    105 
    106     None
    107 
    108 Additions to Appendix A of the OpenGL 1.5 Specification (Invariance)
    109 
    110     None
    111 
    112 Additions to Chapter 1 of the OpenGL Shading Language 1.10 Specification
    113 (Introduction)
    114 
    115     None
    116 
    117 Additions to Chapter 2 of the OpenGL Shading Language 1.10 Specification
    118 (Overview of OpenGL Shading)
    119 
    120     None
    121 
    122 Additions to Chapter 3 of the OpenGL Shading Language 1.10 Specification
    123 (Basics)
    124 
    125     None
    126 
    127 Additions to Chapter 4 of the OpenGL Shading Language 1.10 Specification
    128 (Variables and Types)
    129 
    130     None
    131 
    132 Additions to Chapter 5 of the OpenGL Shading Language 1.10 Specification
    133 (Operators and Expressions)
    134 
    135     None
    136 
    137 Additions to Chapter 6 of the OpenGL Shading Language 1.10 Specification
    138 (Statements and Structure)
    139 
    140     None
    141 
    142 Additions to Chapter 7 of the OpenGL Shading Language 1.10 Specification
    143 (Built-in Variables)
    144 
    145     None
    146 
    147 Additions to Chapter 8 of the OpenGL Shading Language 1.10 Specification
    148 (Built-in Functions)
    149 
    150     Add a new section 8.10 "Debug Functions":
    151 
    152     Debug functions are available to both fragment and vertex shaders.
    153     They are used to track the execution of a shader by logging
    154     passed-in arguments to the debug object's log. Those values can be
    155     retrieved by the application for inspection after shader execution
    156     is complete.
    157 
    158     The text, if any, produced by any of these functions is appended
    159     to each debug object that is attached to the program object.
    160     There are different debug log types
    161 
    162     Add a new section 8.10.1 "Print Function":
    163 
    164     The following printMESA prototypes are available.
    165 
    166         void printMESA(const float value)
    167         void printMESA(const int value)
    168         void printMESA(const bool value)
    169         void printMESA(const vec2 value)
    170         void printMESA(const vec3 value)
    171         void printMESA(const vec4 value)
    172         void printMESA(const ivec2 value)
    173         void printMESA(const ivec3 value)
    174         void printMESA(const ivec4 value)
    175         void printMESA(const bvec2 value)
    176         void printMESA(const bvec3 value)
    177         void printMESA(const bvec4 value)
    178         void printMESA(const mat2 value)
    179         void printMESA(const mat3 value)
    180         void printMESA(const mat4 value)
    181         void printMESA(const sampler1D value)
    182         void printMESA(const sampler2D value)
    183         void printMESA(const sampler3D value)
    184         void printMESA(const samplerCube value)
    185         void printMESA(const sampler1DShadow value)
    186         void printMESA(const sampler2DShadow value)
    187 
    188     The printMESA function writes the argument <value> to the "debug
    189     print log" (XXX DEBUG_PRINT_MESA?). Each component is written in
    190     text format (XXX format!) and is delimited by a white space (XXX 1
    191     or more?).
    192 
    193     Add a new section 8.10.2 "Assert Function":
    194 
    195     The following assertMESA prototypes are available.
    196 
    197         void assertMESA(const bool condition)
    198         void assertMESA(const bool condition, const int cookie)
    199         void assertMESA(const bool condition, const int cookie,
    200                         const int file, const int line)
    201 
    202     The assertMESA function checks if the argument <condition> is
    203     true or false. If it is true, nothing happens. If it is false,
    204     a diagnostic message is written to the "debug assert log".
    205     The message contains the argument <file>, <line>, <cookie> and
    206     implementation dependent double-quoted string, each of this
    207     delimited by a white space. If the argument <cookie> is not present,
    208     it is meant as if it was of value 0. If the arguments <file> and
    209     <line> are not present, they are meant as if they were of values
    210     __FILE__ and __LINE__, respectively. The following three calls
    211     produce the same output, assuming they were issued from the same
    212     file and line.
    213 
    214         assertMESA (false);
    215         assertMESA (false, 0);
    216         assertMESA (false, 0, __FILE__, __LINE__);
    217 
    218     The diagnostic message examples follow.
    219 
    220         1 89 0 ""
    221         1 45 333 "all (lessThanEqual (fragColor, vec4 (1.0)))"
    222         1 66 1 "assertion failed in file 1, line 66, cookie 1"
    223 
    224 Additions to Chapter 9 of the OpenGL Shading Language 1.10 Specification
    225 (Shading Language Grammar)
    226 
    227     None
    228 
    229 Additions to Chapter 10 of the OpenGL Shading Language 1.10
    230 Specification (Issues)
    231 
    232     None
    233 
    234 Additions to the AGL/EGL/GLX/WGL Specifications
    235 
    236     None
    237 
    238 GLX Protocol
    239 
    240     None
    241 
    242 Errors
    243 
    244     TBD
    245 
    246 New State
    247 
    248     TBD
    249 
    250 New Implementation Dependent State
    251 
    252     TBD
    253 
    254 Sample Code
    255 
    256     TBD
    257 
    258 Revision History
    259 
    260     29 May 2006
    261         Initial draft. (Michal Krol)
    262     30 July 2006
    263         Add Overview, New Procedures and Functions, New Tokens sections.
    264         Add sections 8.10.1, 8.10.2 to GLSL spec.
    265