Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 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 | |
Brian Paul | 69e07bd | 2009-03-07 11:53:18 -0700 | [diff] [blame] | 16 | Obsolete. |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 17 | |
| 18 | Version |
| 19 | |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 20 | Last Modified Date: July 30, 2006 |
| 21 | Author Revision: 0.2 |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 22 | |
| 23 | Number |
| 24 | |
| 25 | TBD |
| 26 | |
| 27 | Dependencies |
| 28 | |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 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 | |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 35 | The extension is written against the OpenGL 1.5 specification. |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 36 | |
| 37 | The extension is written against the OpenGL Shading Language 1.10 |
| 38 | Specification. |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 39 | |
| 40 | Overview |
| 41 | |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 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. |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 49 | |
| 50 | IP Status |
| 51 | |
| 52 | None |
| 53 | |
| 54 | Issues |
| 55 | |
| 56 | None |
| 57 | |
| 58 | New Procedures and Functions |
| 59 | |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 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) |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 67 | |
| 68 | New Types |
| 69 | |
| 70 | None |
| 71 | |
| 72 | New Tokens |
| 73 | |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 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 |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 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 |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 154 | passed-in arguments to the debug object's log. Those values can be |
| 155 | retrieved by the application for inspection after shader execution |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 156 | is complete. |
| 157 | |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 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" |
Michal Krol | 44d5c86 | 2006-05-30 09:35:36 +0000 | [diff] [blame] | 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) |
Michal Krol | d2ac9ab | 2006-07-30 14:28:38 +0000 | [diff] [blame] | 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. |