1Name
2
3    GREMEDY_string_marker
4
5Name Strings
6
7    GL_GREMEDY_string_marker
8
9Contributors
10
11    Dirk Reiners
12    Yaki Tebeka
13
14Contact
15
16    Dirk Reiners, Iowa State University (dreiners 'at' iastate.edu)
17    Yaki Tebeka, Graphic Remedy (yaki 'at' gremedy.com)
18
19Status
20
21    Implemented by gDEBugger (Version 1.2.1 or later)
22
23Version
24
25    Last Modified Date: October 16, 2007
26    Author Revision: 1.4
27
28Number
29
30    311
31
32Dependencies
33
34    OpenGL 1.0 is required.
35    
36    The extension is written against the OpenGL 1.5 Specification.
37
38Overview
39
40    This extension defines a mechanism to insert textual markers into
41    the OpenGL stream. 
42
43    When debugging or profiling an OpenGL application some of the most
44    important tools are stream loggers, which just output a list of the
45    called OpenGL commands, and profilers, which show at which points
46    the pipeline is bottlenecked for a given part of the frame. The
47    problem in using these is that there is a definite loss of
48    information between the application and the used debugger/profiler.
49    The application generally has a pretty good idea what is rendered
50    when (e.g. rendering background, landscape, building, players,
51    particle effects, bullets etc.), but the debugger/profiler only
52    sees the OpenGL stream. To analyze the stream developers have to
53    guess what is done when by following the program code and the log
54    output in parallel, which can get difficult for systems that
55    restructure their internal pipeline or do lazy changes.
56
57    This extension is really only useful for these debuggers and
58    profilers, and not for actual drivers. In fact, it is not expected
59    that any standard driver would ever implement this extension. The
60    main point of having this extension is to allow applications to have a
61    clean way of accessing this functionality only when they are run
62    under the control of a debugger/profiler, without having to
63    recompile or change the application source code.
64
65
66IP Status
67
68    No known IP claims
69
70Issues
71
72   (1) Should the extension use \0-terminated strings to simplify use?
73    
74    RESOLVED: yes.
75
76    This extension follows the latest precedent for strings, which is the ShaderSource().
77    It uses strings that are given as a list of ubytes with explicit length. However, If 
78    lengths is 0, then the string is assumed to be null-terminated.
79
80
81   (2) Should it be legal to call this inside Begin/End?
82    
83    RESOLVED: no.
84    
85    The benefit is questionable, and it would probably add
86    overhead to a very critical path.
87        
88   (3) Should this be supported by GLX?
89    
90    UNRESOLVED
91    
92    Not strictly necessary, as most debugging is done locally. It would
93    be cleaner, but I don't see a case for the effort. 
94    
95    
96New Procedures and Functions
97
98    void StringMarkerGREMEDY(sizei len, const void *string);
99
100New Types
101
102    None
103
104New Tokens
105
106    None
107
108Additions to Chapter 2 of the OpenGL 1.5 Specification
109(OpenGL Operation)
110
111    None
112
113Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization)
114
115    None
116
117Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
118Operations and the Frame Buffer)
119
120    None
121
122Additions to Chapter 5 of the OpenGL 1.5 Specification
123(Special Functions)
124
125    Add section 5.7 on page 212
126    
127    5.7 Markers
128    
129    The command
130    
131        void StringMarkerGREMEDY(sizei len, const void *string);
132    
133    can be used to insert arbitrary marker strings into the command
134    stream that can be recorded by appropriate debugging tools / profiling tools /
135    drivers. They have no influence on the rendered image or the OpenGL state.
136    <string> is a pointer to the array of bytes representing the marker being
137    inserted, which need not be null-terminated.  The length of the array is given
138    by <len>.  If <string> is null-terminated, <len> should not include the terminator.
139    If lengths is 0, then the string is assumed to be null-terminated.
140
141Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
142Requests)
143
144    None
145
146Additions to Appendix A of the OpenGL 1.5 Specification (Invariance)
147
148    None
149
150Additions to the AGL/EGL/GLX/WGL Specifications
151
152    None
153
154GLX Protocol
155
156    None
157
158Dependencies on EXT_extension_name
159
160    None
161
162Errors
163
164    The error INVALID_OPERATION is generated if any of the commands
165    defined in this extension is executed between the execution of Begin
166    and the corresponding execution of End.
167
168New State
169
170    None
171
172New Implementation Dependent State
173
174    None
175
176Sample Code
177
178    None
179
180Revision History
181
182    1.4, 10/16/07 yt:   - Minor text changes.
183    1.3, 06/08/05 yt:   - Enable the use of \0-terminated strings by specifying 
184                          a 0 string length.
185    1.2, 02/01/05 dr:   - Change the extension Status
186                        - Change the name of the extension 
187    1.1, 01/20/05 dr:     (Thanks to Yaki Tebeka for suggestions!)
188                        - Switched to programString style
189                        - renamed to marker_string  
190    1.0, 01/17/05 dr:   - Initial revision
191