docs/MESA_shader_debug.spec

   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.