1XXX - Almost complete; needs GLX protocol. 2 3Name 4 5 SGIX_instruments 6 7Name Strings 8 9 GL_SGIX_instruments 10 11Version 12 13 $Date: 1997/09/18 01:12:38 $ $Revision: 1.6 $ 14 15Number 16 17 55 18 19Dependencies 20 21 None 22 23Overview 24 25 This extension allows the gathering and return of performance 26 measurements from within the graphics pipeline by adding 27 instrumentation. 28 29 There are two reasons to do this. The first is as a part of some 30 type of fixed-frame-rate load management scheme. If we know that 31 the pipeline is stalled or struggling to process the amount of 32 data we have given it so far, we can reduce the level of detail of 33 the remaining objects in the current frame or the next frame, or 34 adjust the framebuffer resolution for the next frame if we have a 35 video-zoom capability available. We can call this type of 36 instrumentation Load Monitoring. 37 38 The second is for performance tuning and debugging of an 39 application. It might tell us how many triangles were culled or 40 clipped before being rasterized. We can call this simply Tuning. 41 42 Load Monitoring requires that the instrumentation and the access 43 of the measurements be efficient, otherwise the instrumentation 44 itself will reduce performance more than any load-management 45 scheme could hope to offset. Tuning does not have the same 46 requirements. 47 48 The proposed extension adds a call to setup a measurements return 49 buffer, similar to FeedbackBuffer but with an asynchrounous 50 behavior to prevent filling the pipeline with NOP's while waiting 51 for the data to be returned. 52 53 Note that although the extension has been specified without any 54 particular instruments, defining either a device dependent or 55 device independent instrument should be as simple as introducing 56 an extension consisting primarily of a new enumerant to identify 57 the instrument. 58 59New Procedures and Functions 60 61 void InstrumentsBufferSGIX(sizei size, int *buf) 62 63 void StartInstrumentsSGIX(void) 64 65 void StopInstrumentsSGIX(int marker) 66 67 void ReadInstrumentsSGIX(int marker) 68 69 int PollInstrumentsSGIX(int *markerp) 70 71 int GetInstrumentsSGIX(void) 72 73 An example of using the calls to test the extension: 74{ 75#ifdef GL_SGIX_instruments 76 77 static GLint buffer[64]; 78 void *bufp; 79 int id, count0, count1, r; 80 81 /* define the buffer to hold the measurments */ 82 glInstrumentsBufferSGIX(sizeof(buffer)/sizeof(GLint), (GLint *) buffer); 83 84 /* enable the instruments from which one wishes to take measurements */ 85 glEnable(<an enum for instrument in use>); 86 87 glStartInstrumentsSGIX(); 88 /* insert GL commands here */ 89 glReadInstrumentsSGIX(14); 90 /* insert GL commands here */ 91 glStopInstrumentsSGIX(15); 92 93 /* the number of msrmnts since the buffer was specified can be queried */ 94 glGetIntegerv(GL_INSTRUMENT_MEASUREMENTS_SGIX,&r); /* r should be 2 */ 95 96 glGetPointervEXT(GL_INSTRUMENT_BUFFER_SGIX,&bufp); 97 /* bufp should be equal to buffer */ 98 99 /* 100 * we can do a GetInstrumentsSGIX before or after the calls to 101 * PollInstrumentsSGIX but to be sure of exactly what 102 * measurements are in the buffer, we can use PollInstrumentsSGIX. 103 */ 104 count0 = glGetInstrumentsSGIX(); 105 /* count0 will be a count of from 0 to 2 multiples of the size 106 * in words of the instrument measurement we have enabled. 107 * If buffer was overflowed, count0 will be 1. 108 */ 109 110 while (!(r = glPollInstrumentsSGIX(&id))) ; 111 /* if r is -1, we have overflowed, if it is 1, id will 112 * have the value of the marker passed in with the first 113 * measurement request (should be 14) 114 */ 115 116 while (!(r = glPollInstrumentsSGIX(&id))) ; 117 /* see the note on the first poll; id should be 15 */ 118 119 count1 = glGetInstrumentsSGIX(); 120 /* the sum of count0 and count1 should be 2 times 121 * the size in words of an instrument measurement 122 * that we have enabled. 123 */ 124 125#endif 126} 127 128 129New Tokens 130 131 Accepted by the <pname> parameter of GetIntegerv, GetFloatv, and 132 GetDoublev: 133 134 INSTRUMENT_MEASUREMENTS_SGIX 135 136 Accepted by the <pname> parameter of GetPointervEXT: 137 138 INSTRUMENT_BUFFER_POINTER_SGIX 139 140Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) 141 142 None 143 144Additions to Chapter 3 of the 1.0 Specification (Rasterization) 145 146 None 147 148Additions to Chapter 4 of the 1.0 Specification (Per-Fragment 149Operations and the Frame Buffer) 150 151 None 152 153Additions to Chapter 5 of the 1.0 Specification (Special Functions) 154 155 The following commands are not included in display lists: 156 157 InstrumentsBufferSGIX 158 PollInstrumentsSGIX 159 GetInstrumentsSGIX 160 161 Add a section 5.X entitled Instruments: 162 163 Instruments provide a method to measure performance of the GL 164 pipeline and identify possible bottlenecks. This information may 165 be useful in feedback-based load management schemes which attempt 166 to maintain a constant frame-rate. A set of functions is provided 167 which allows an asynchronous implementation such that the graphics 168 pipeline need not be stalled while measurements are returned to 169 the client. 170 171 A buffer in which to collect instrument measurements is defined 172 with InstrumentsBufferSGIX, where <size> defines the size of the 173 buffer. If <buf> has been previously defined with a prior call, 174 the buffer is reset, that is, measurements taken after the call to 175 InstrumentsBufferSGIX will be written to the start of the buffer. 176 Otherwise the buffer will be processed in a way that allows 177 asynchronous writing to the buffer from the graphics pipeline. If 178 <buf> is zero, then any resources allocated to prepare the buffer 179 for writing from the graphics pipeline from a previous call will 180 be freed. If <buf> is non-zero, but is different from a previous 181 call, the old buffer is considered to be replaced by the new 182 buffer and any allocated resources involved in preparing the old 183 buffer for writing are freed. 184 185 If <size> is negative an INVALID_VALUE is generated. 186 187 An INVALID_OPERATION is generated if InstrumentsBufferSGIX is 188 called between Begin/End. 189 190 If there are multiple instruments enabled, the measurement for 191 each enabled instrument can appear in the buffer in any order for 192 a given measurement. 193 194 The buffer address can be queried with glGetPointervEXT using 195 <pname> GL_INSTRUMENT_BUFFER_POINTER. 196 197 To start the enabled instrument(s) before taking a measurement 198 execute StartInstrumentsSGIX. To stop the enabled instruments and 199 take a measurement use StopInstrumentsSGIX. The parameter <marker> 200 is passed through the pipe and written back to the buffer to ease 201 the task of interpreting the buffer. 202 203 To take an instrument measurement use ReadInstrumentsSGIX. The 204 parameter <marker> is processed as with StopInstrumentsSGIX. 205 206 An INVALID_OPERATION is generated if StartInstrumentsSGIX is 207 executed twice without an intervening execution of 208 StopInstrumentsSGIX or InstrumentsBufferSGIX. Symetrically, an 209 INVALID_OPERATION is generated if StopInstrumentsSGIX is executed 210 twice without an intervening execution of StartInstrumentsSGIX. 211 ReadInstrumentsSGIX will generate an INVALID_OPERATION if executed 212 after an execution of StopInstruments without an intervening 213 execution of StopInstrumentsSGIX or InstrumentsBufferSGIX. 214 215 Executing any of StartInstrumentsSGIX, StopInstrumentsSGIX, 216 ReadInstruments without a successful call to InstrumentsBufferSGIX 217 to define a buffer will generate an INVALID_OPERATION. Executing 218 any of StartInstrumentsSGIX, StopInstrumentsSGIX, ReadInstruments 219 between Begin/End will generate an INVALID_OPERATION 220 221 If no instruments are enabled, executions of StartInstrumentsSGIX, 222 StopInstrumentsSGIX, ReadInstruments will not write measurements 223 to the buffer. 224 225 The number of measurements taken since the buffer was reset can be 226 queried with glGet using <pname> GL_INSTRUMENT_MEASUREMENTS. 227 228 To determine whether a measurement of the enabled instruments has 229 been written to the buffer call PollInstrumentsSGIX. If a new 230 measurement has appeared in the buffer since the last call to 231 PollInstrumentsSGIX, 1 will be returned, otherwise zero is 232 returned. If 1 is returned, the value of marker associated with 233 the measurement and passed to StopInstrumentsSGIX or 234 ReadInstrumentsSGIX is written into the integer referred to by 235 <markerp>. The measurements will appear in the buffer in the order 236 in which they were requested. If the buffer is overflowed, 237 PollInstrumentsSGIX may return -1 as soon as the overflow is 238 detected, even if the measurement being polled for did not cause 239 the overflow. An implementation may choose to delay reporting the 240 overflow until the measurement that caused the overflow is the one 241 being polled. 242 243 To get a total count of the number of new valid words written to 244 the buffer call GetInstrumentsSGIX. The value returned is the 245 number of ints that have been written to the buffer since the last 246 call to GetInstrumentsSGIX. GetInstrumentsSGIX can be used 247 independently of PollInstrumentsSGIX. If the buffer has been 248 overflowed since the last call to GetInstrumentsSGIX, -1 is 249 returned for the count. 250 251Additions to Chapter 6 of the 1.0 Specification (State and State Requests) 252 253 The GL_INSTRUMENT_BUFFER_POINTER_SGIX enum should be added to the 254 list of enum's recognized by GetPointerv. 255 256Additions to the GLX Specification 257 258 None 259 260GLX Protocol 261 262 XXX - not yet complete 263 264Errors 265 266 An INVALID_OPERATION is generated if any of the instruments 267 functions or procedures are called within Begin/End. 268 269 When calling glInstrumentsBufferSGIX, an INVALID_VALUE is 270 generated if <size> is negative. 271 272 An INVALID_OPERATION is generated if two StartInstrumentsSGIX are 273 called without an intervening call to StopInstrumentsSGIX or 274 InstrumentsBufferSGIX. Symetrically, an INVALID_OPERATION is 275 generated if StopInstrumentsSGIX is called twice without an 276 intervening StartInstrumentsSGIX. ReadInstrumentsSGIX will 277 generate an INVALID_OPERATION if called after a call to 278 StopInstruments without an intervening call to StopInstrumentsSGIX 279 or InstrumentsBufferSGIX. 280 281 Calling any of StartInstrumentsSGIX, StopInstrumentsSGIX, 282 ReadInstruments without a successful call to InstrumentsBufferSGIX 283 to define a buffer will generate an INVALID_OPERATION. 284 285New State 286 287 Initial Initial 288 Get Value Get Command Type Value Attrib 289 --------- ----------- ---- ----- ------ 290 INSTRUMENT_MEASUREMENTS_SGIX GetInteger Z 0 - 291 INSTRUMENT_BUFFER_POINTER_SGIX GetPointervEXT Y 0 - 292 293New Implementation Dependent State 294 295 None 296 297