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