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