1Name
2
3    MESA_shader_debug
4
5Name Strings
6
7    GL_MESA_shader_debug
8
9Contact
10
11    Brian Paul (brian.paul 'at' tungstengraphics.com)
12    Michal Krol (mjkrol 'at' gmail.com)
13
14Status
15
16    Obsolete.
17
18Version
19
20    Last Modified Date: July 30, 2006
21    Author Revision: 0.2
22
23Number
24
25    TBD
26
27Dependencies
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
40Overview
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
50IP Status
51
52    None
53
54Issues
55
56    None
57
58New 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
68New Types
69
70    None
71
72New 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
84Additions to Chapter 2 of the OpenGL 1.5 Specification
85(OpenGL Operation)
86
87    None
88
89Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization)
90
91    None
92
93Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
94Operations and the Frame Buffer)
95
96    None
97
98Additions to Chapter 5 of the OpenGL 1.5 Specification
99(Special Functions)
100
101    None
102
103Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
104Requests)
105
106    None
107
108Additions to Appendix A of the OpenGL 1.5 Specification (Invariance)
109
110    None
111
112Additions to Chapter 1 of the OpenGL Shading Language 1.10 Specification
113(Introduction)
114
115    None
116
117Additions to Chapter 2 of the OpenGL Shading Language 1.10 Specification
118(Overview of OpenGL Shading)
119
120    None
121
122Additions to Chapter 3 of the OpenGL Shading Language 1.10 Specification
123(Basics)
124
125    None
126
127Additions to Chapter 4 of the OpenGL Shading Language 1.10 Specification
128(Variables and Types)
129
130    None
131
132Additions to Chapter 5 of the OpenGL Shading Language 1.10 Specification
133(Operators and Expressions)
134
135    None
136
137Additions to Chapter 6 of the OpenGL Shading Language 1.10 Specification
138(Statements and Structure)
139
140    None
141
142Additions to Chapter 7 of the OpenGL Shading Language 1.10 Specification
143(Built-in Variables)
144
145    None
146
147Additions 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
224Additions to Chapter 9 of the OpenGL Shading Language 1.10 Specification
225(Shading Language Grammar)
226
227    None
228
229Additions to Chapter 10 of the OpenGL Shading Language 1.10
230Specification (Issues)
231
232    None
233
234Additions to the AGL/EGL/GLX/WGL Specifications
235
236    None
237
238GLX Protocol
239
240    None
241
242Errors
243
244    TBD
245
246New State
247
248    TBD
249
250New Implementation Dependent State
251
252    TBD
253
254Sample Code
255
256    TBD
257
258Revision 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