Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
4358 | Serge | 1 | Name |
2 | |||
3 | MESA_trace |
||
4 | |||
5 | Name Strings |
||
6 | |||
7 | GL_MESA_trace |
||
8 | |||
9 | Contact |
||
10 | |||
11 | Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com |
||
12 | Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com |
||
13 | |||
14 | Status |
||
15 | |||
16 | Obsolete. |
||
17 | |||
18 | Version |
||
19 | |||
20 | |||
21 | Number |
||
22 | |||
23 | none yet |
||
24 | |||
25 | Dependencies |
||
26 | |||
27 | OpenGL 1.2 is required. |
||
28 | The extension is written against the OpenGL 1.2 Specification |
||
29 | |||
30 | Overview |
||
31 | |||
32 | Provides the application with means to enable and disable logging |
||
33 | of GL calls including parameters as readable text. The verbosity |
||
34 | of the generated log can be controlled. The resulting logs are |
||
35 | valid (but possibly incomplete) C code and can be compiled and |
||
36 | linked for standalone test programs. The set of calls and the |
||
37 | amount of static data that is logged can be controlled at runtime. |
||
38 | The application can add comments and enable or disable tracing of GL |
||
39 | operations at any time. The data flow from the application to GL |
||
40 | and back is unaffected except for timing. |
||
41 | |||
42 | Application-side implementation of these features raises namespace |
||
43 | and linkage issues. In the driver dispatch table a simple |
||
44 | "chain of responsibility" pattern (aka "composable piepline") |
||
45 | can be added. |
||
46 | |||
47 | IP Status |
||
48 | |||
49 | The extension spec is in the public domain. The current implementation |
||
50 | in Mesa is covered by Mesa's XFree86-style copyright by the authors above. |
||
51 | This extension is partially inspired by the Quake2 QGL wrapper. |
||
52 | |||
53 | Issues |
||
54 | |||
55 | |||
56 | (1) Is this Extension obsolete because it can |
||
57 | be implemented as a wrapper DLL? |
||
58 | |||
59 | RESOLVED: No. While certain operating systems (Win32) provide linkers |
||
60 | that facilitate this kind of solution, other operating systems |
||
61 | (Linux) do not support hierarchical linking, so a wrapper solution |
||
62 | would result in symbol collisions. |
||
63 | Further, IHV's might have builtin support for tracing GL execution |
||
64 | that enjoys privileged access, or that they do not wish to separate |
||
65 | the tracing code from their driver code base. |
||
66 | |||
67 | (2) Should the Trace API explicitely support the notion of "frames? |
||
68 | This would require hooking into glXSwapBuffers calls as well. |
||
69 | |||
70 | RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA |
||
71 | and TraceComment along with external parsing tools to split the |
||
72 | trace into frames, in whatever way considered adequate. |
||
73 | |||
74 | (2a) Should GLX calls be traced? |
||
75 | |||
76 | PBuffers and other render-to-texture solutions demonstrate that |
||
77 | context level commands beyond SwapBuffers might have to be |
||
78 | traced. The GL DLL exports the entry points, so this would not |
||
79 | be out of the question. |
||
80 | |||
81 | (3) Should the specification mandate the actual output format? |
||
82 | |||
83 | RESOLVED: No. It is sufficient to guarantee that all data and commands |
||
84 | will be traced as requested by Enable/DisableTraceMESA, in the order |
||
85 | encountered. Whether the resulting trace is available as a readable |
||
86 | text file, binary metafile, compilable source code, much less which |
||
87 | indentation and formatting has been used, is up to the implementation. |
||
88 | For the same reason this specification does not enforce or prohibit |
||
89 | additional information added to the trace (statistics, profiling/timing, |
||
90 | warnings on possible error conditions). |
||
91 | |||
92 | (4) Should the comment strings associated with names and pointer (ranges) |
||
93 | be considered persistent state? |
||
94 | |||
95 | RESOLVED: No. The implementation is not forced to use this information |
||
96 | on subsequent occurences of name/pointer, and is free to consider it |
||
97 | transient state. |
||
98 | |||
99 | (5) Should comment commands be prohibited between Begin/End? |
||
100 | |||
101 | RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA |
||
102 | is transient, the other commands might cause storage of persistent |
||
103 | data in the context. There is no need to have the ability mark names |
||
104 | or pointers between Begin and End. |
||
105 | |||
106 | |||
107 | New Procedures and Functions |
||
108 | |||
109 | void NewTraceMESA( bitfield mask, const ubyte * traceName ) |
||
110 | |||
111 | void EndTraceMESA( void ) |
||
112 | |||
113 | void EnableTraceMESA( bitfield mask ) |
||
114 | |||
115 | void DisableTraceMESA( bitfield mask ) |
||
116 | |||
117 | void TraceAssertAttribMESA( bitfield attribMask ) |
||
118 | |||
119 | void TraceCommentMESA( const ubyte* comment ) |
||
120 | |||
121 | void TraceTextureMESA( uint name, const ubyte* comment ) |
||
122 | |||
123 | void TraceListMESA( uint name, const ubyte* comment ) |
||
124 | |||
125 | void TracePointerMESA( void* pointer, const ubyte* comment ) |
||
126 | |||
127 | void TracePointerRangeMESA( const void* first, |
||
128 | const void* last, |
||
129 | const ubyte* comment ) |
||
130 | |||
131 | New Tokens |
||
132 | |||
133 | Accepted by the |
||
134 | |||
135 | TRACE_ALL_BITS_MESA 0xFFFF |
||
136 | TRACE_OPERATIONS_BIT_MESA 0x0001 |
||
137 | TRACE_PRIMITIVES_BIT_MESA 0x0002 |
||
138 | TRACE_ARRAYS_BIT_MESA 0x0004 |
||
139 | TRACE_TEXTURES_BIT_MESA 0x0008 |
||
140 | TRACE_PIXELS_BIT_MESA 0x0010 |
||
141 | TRACE_ERRORS_BIT_MESA 0x0020 |
||
142 | |||
143 | Accepted by the |
||
144 | GetFloatv, and GetDoublev: |
||
145 | |||
146 | TRACE_MASK_MESA 0x8755 |
||
147 | |||
148 | Accepted by the |
||
149 | |||
150 | TRACE_NAME_MESA 0x8756 |
||
151 | |||
152 | |||
153 | Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) |
||
154 | |||
155 | None. |
||
156 | |||
157 | Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation) |
||
158 | |||
159 | None. |
||
160 | |||
161 | Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation) |
||
162 | |||
163 | None. |
||
164 | |||
165 | Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) |
||
166 | |||
167 | Add a new section: |
||
168 | |||
169 | 5.7 Tracing |
||
170 | |||
171 | The tracing facility is used to record the execution of a GL program |
||
172 | to a human-readable log. The log appears as a sequence of GL commands |
||
173 | using C syntax. The primary intention of tracing is to aid in program |
||
174 | debugging. |
||
175 | |||
176 | A trace is started with the command |
||
177 | |||
178 | void NewTraceMESA( bitfield mask, const GLubyte * traceName ) |
||
179 | |||
180 |
|
||
181 | attribute groups. The state values included in those attribute groups |
||
182 | is written to the trace as a sequence of GL commands. |
||
183 | |||
184 |
|
||
185 | that |
||
186 | |||
187 | A trace is ended by calling the command |
||
188 | |||
189 | void EndTraceMESA( void ) |
||
190 | |||
191 | It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End. |
||
192 | |||
193 | The commands |
||
194 | |||
195 | void EnableTraceMESA( bitfield mask ) |
||
196 | void DisableTraceMESA( bitfield mask ) |
||
197 | |||
198 | enable or disable tracing of different classes of GL commands. |
||
199 |
|
||
200 | TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA, |
||
201 | and TRACE_PIXELS_BIT_MESA. The special token TRACE_ALL_BITS_MESA |
||
202 | indicates all classes of commands are to be logged. |
||
203 | |||
204 | TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of |
||
205 | Begin/End, including Begin/End. |
||
206 | |||
207 | TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of |
||
208 | Begin/End, including Begin/End. |
||
209 | |||
210 | TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer, |
||
211 | ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands. |
||
212 | |||
213 | TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by |
||
214 | TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and |
||
215 | TexSubImage3D commands. |
||
216 | |||
217 | TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by |
||
218 | Bitmap and DrawPixels commands. |
||
219 | |||
220 | TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is |
||
221 | set, GetError will be executed whereever applicable, and the result will |
||
222 | be added to the trace as a comment. The error returns are cached and |
||
223 | returned to the application on its GetError calls. If the user does not |
||
224 | wish the additional GetError calls to be performed, this bit should not |
||
225 | be set. |
||
226 | |||
227 | The command |
||
228 | |||
229 | void TraceCommentMESA( const ubyte* comment ) |
||
230 | |||
231 | immediately adds the |
||
232 | by C-style comment delimiters. |
||
233 | |||
234 | The commands |
||
235 | |||
236 | void TraceTextureMESA( uint name, const ubyte* comment ) |
||
237 | void TraceListMESA( uint name, const ubyte* comment ) |
||
238 | |||
239 | associates |
||
240 | by |
||
241 | display list will be annotated with |
||
242 | IsList(name) fail (respectively) the command is quietly ignored. |
||
243 | |||
244 | The commands |
||
245 | |||
246 | void TracePointerMESA( void* pointer, const ubyte* comment ) |
||
247 | |||
248 | void TracePointerRangeMESA( const void* first, |
||
249 | const void* last, |
||
250 | const ubyte* comment ) |
||
251 | |||
252 | associate |
||
253 | a range of addresses specified by |
||
254 | Any logged commands which reference |
||
255 |
|
||
256 | |||
257 | The command |
||
258 | |||
259 | void TraceAssertAttribMESA( bitfield attribMask ) |
||
260 | |||
261 | will add GL state queries and assertion statements to the log to |
||
262 | confirm that the current state at the time TraceAssertAttrib is |
||
263 | executed matches the current state when the trace log is executed |
||
264 | in the future. |
||
265 | |||
266 |
|
||
267 | the groups of state variables which are to be asserted. |
||
268 | |||
269 | The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA, |
||
270 | TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA, |
||
271 | TracePointerMESA and TracePointerRangeMESA are not compiled into display lists. |
||
272 | |||
273 | |||
274 | Examples: |
||
275 | |||
276 | The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state |
||
277 | variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE |
||
278 | to get the values |
||
279 | Statements equivalent to the following will then be logged: |
||
280 | |||
281 | glEnable(GL_DEPTH_TEST); (if |
||
282 | glDisable(GL_DEPTH_TEST); (if |
||
283 | glDepthFunc( |
||
284 | glDepthMask( |
||
285 | glClearDepth( |
||
286 | |||
287 | |||
288 | The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state |
||
289 | variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE |
||
290 | to get the values |
||
291 | The resulting trace might then look will like this: |
||
292 | |||
293 | { |
||
294 | GLboolean b; |
||
295 | GLint i; |
||
296 | GLfloat f; |
||
297 | b = glIsEnabled(GL_DEPTH_TEST); |
||
298 | assert(b == |
||
299 | glGetIntegerv(GL_DEPTH_FUNC, &i); |
||
300 | assert(i == |
||
301 | glGetIntegerv(GL_DEPTH_MASK, &i); |
||
302 | assert(i == |
||
303 | glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f); |
||
304 | assert(f == |
||
305 | } |
||
306 | |||
307 | |||
308 | Additions to Chapter 6 of the OpenGL 1.2.1 Specification |
||
309 | (State and State Requests) |
||
310 | |||
311 | Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or |
||
312 | GetDoublev returns the current command class trace mask. |
||
313 | |||
314 | Querying TRACE_NAME_MESA with GetString returns the current trace name. |
||
315 | |||
316 | |||
317 | Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance) |
||
318 | |||
319 | The MESA_trace extension can be used in a way that does not affect data |
||
320 | flow from application to OpenGL, as well as data flow from OpenGL to |
||
321 | application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA |
||
322 | will add additional GetError queries. Setting a trace mask with NewTraceMESA |
||
323 | as well as use of TraceAssertAttribMESA might cause additional state queries. |
||
324 | With the possible exception of performance, OpenGL rendering should not be |
||
325 | affected at all by a properly chosen logging operation. |
||
326 | |||
327 | Additions to the AGL/GLX/WGL Specifications |
||
328 | |||
329 | None. |
||
330 | |||
331 | GLX Protocol |
||
332 | |||
333 | None. The logging operation is carried out client-side, by exporting |
||
334 | entry points to the wrapper functions that execute the logging operation. |
||
335 | |||
336 | Errors |
||
337 | |||
338 | INVALID_OPERATION is generated if any trace command except TraceCommentMESA |
||
339 | is called between Begin and End. |
||
340 | |||
341 | New State |
||
342 | |||
343 | The current trace name and current command class mask are stored |
||
344 | per-context. |
||
345 | |||
346 | New Implementation Dependent State |
||
347 | |||
348 | None. |
||
349 | |||
350 | Revision History |
||
351 | |||
352 | * Revision 0.1 - Initial draft from template (bk000415) |
||
353 | * Revision 0.2 - Draft (bk000906) |
||
354 | * Revision 0.3 - Draft (bk000913) |
||
355 | * Revision 0.4 - Reworked text, fixed typos (bp000914) |
||
356 | * Revision 0.5 - Assigned final GLenum values (bp001103) |
||
357 | * Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916) |
||
358 | * Revision 0.7 - Added MESA postfix (bk010126) |
||
359 |