| XXX - Almost complete; needs GLX protocol. |
| |
| Name |
| |
| SGIX_instruments |
| |
| Name Strings |
| |
| GL_SGIX_instruments |
| |
| Version |
| |
| $Date: 1997/09/18 01:12:38 $ $Revision: 1.6 $ |
| |
| Number |
| |
| 55 |
| |
| Dependencies |
| |
| None |
| |
| Overview |
| |
| This extension allows the gathering and return of performance |
| measurements from within the graphics pipeline by adding |
| instrumentation. |
| |
| There are two reasons to do this. The first is as a part of some |
| type of fixed-frame-rate load management scheme. If we know that |
| the pipeline is stalled or struggling to process the amount of |
| data we have given it so far, we can reduce the level of detail of |
| the remaining objects in the current frame or the next frame, or |
| adjust the framebuffer resolution for the next frame if we have a |
| video-zoom capability available. We can call this type of |
| instrumentation Load Monitoring. |
| |
| The second is for performance tuning and debugging of an |
| application. It might tell us how many triangles were culled or |
| clipped before being rasterized. We can call this simply Tuning. |
| |
| Load Monitoring requires that the instrumentation and the access |
| of the measurements be efficient, otherwise the instrumentation |
| itself will reduce performance more than any load-management |
| scheme could hope to offset. Tuning does not have the same |
| requirements. |
| |
| The proposed extension adds a call to setup a measurements return |
| buffer, similar to FeedbackBuffer but with an asynchrounous |
| behavior to prevent filling the pipeline with NOP's while waiting |
| for the data to be returned. |
| |
| Note that although the extension has been specified without any |
| particular instruments, defining either a device dependent or |
| device independent instrument should be as simple as introducing |
| an extension consisting primarily of a new enumerant to identify |
| the instrument. |
| |
| New Procedures and Functions |
| |
| void InstrumentsBufferSGIX(sizei size, int *buf) |
| |
| void StartInstrumentsSGIX(void) |
| |
| void StopInstrumentsSGIX(int marker) |
| |
| void ReadInstrumentsSGIX(int marker) |
| |
| int PollInstrumentsSGIX(int *markerp) |
| |
| int GetInstrumentsSGIX(void) |
| |
| An example of using the calls to test the extension: |
| { |
| #ifdef GL_SGIX_instruments |
| |
| static GLint buffer[64]; |
| void *bufp; |
| int id, count0, count1, r; |
| |
| /* define the buffer to hold the measurments */ |
| glInstrumentsBufferSGIX(sizeof(buffer)/sizeof(GLint), (GLint *) buffer); |
| |
| /* enable the instruments from which one wishes to take measurements */ |
| glEnable(<an enum for instrument in use>); |
| |
| glStartInstrumentsSGIX(); |
| /* insert GL commands here */ |
| glReadInstrumentsSGIX(14); |
| /* insert GL commands here */ |
| glStopInstrumentsSGIX(15); |
| |
| /* the number of msrmnts since the buffer was specified can be queried */ |
| glGetIntegerv(GL_INSTRUMENT_MEASUREMENTS_SGIX,&r); /* r should be 2 */ |
| |
| glGetPointervEXT(GL_INSTRUMENT_BUFFER_SGIX,&bufp); |
| /* bufp should be equal to buffer */ |
| |
| /* |
| * we can do a GetInstrumentsSGIX before or after the calls to |
| * PollInstrumentsSGIX but to be sure of exactly what |
| * measurements are in the buffer, we can use PollInstrumentsSGIX. |
| */ |
| count0 = glGetInstrumentsSGIX(); |
| /* count0 will be a count of from 0 to 2 multiples of the size |
| * in words of the instrument measurement we have enabled. |
| * If buffer was overflowed, count0 will be 1. |
| */ |
| |
| while (!(r = glPollInstrumentsSGIX(&id))) ; |
| /* if r is -1, we have overflowed, if it is 1, id will |
| * have the value of the marker passed in with the first |
| * measurement request (should be 14) |
| */ |
| |
| while (!(r = glPollInstrumentsSGIX(&id))) ; |
| /* see the note on the first poll; id should be 15 */ |
| |
| count1 = glGetInstrumentsSGIX(); |
| /* the sum of count0 and count1 should be 2 times |
| * the size in words of an instrument measurement |
| * that we have enabled. |
| */ |
| |
| #endif |
| } |
| |
| |
| New Tokens |
| |
| Accepted by the <pname> parameter of GetIntegerv, GetFloatv, and |
| GetDoublev: |
| |
| INSTRUMENT_MEASUREMENTS_SGIX |
| |
| Accepted by the <pname> parameter of GetPointervEXT: |
| |
| INSTRUMENT_BUFFER_POINTER_SGIX |
| |
| Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) |
| |
| None |
| |
| Additions to Chapter 3 of the 1.0 Specification (Rasterization) |
| |
| None |
| |
| Additions to Chapter 4 of the 1.0 Specification (Per-Fragment |
| Operations and the Frame Buffer) |
| |
| None |
| |
| Additions to Chapter 5 of the 1.0 Specification (Special Functions) |
| |
| The following commands are not included in display lists: |
| |
| InstrumentsBufferSGIX |
| PollInstrumentsSGIX |
| GetInstrumentsSGIX |
| |
| Add a section 5.X entitled Instruments: |
| |
| Instruments provide a method to measure performance of the GL |
| pipeline and identify possible bottlenecks. This information may |
| be useful in feedback-based load management schemes which attempt |
| to maintain a constant frame-rate. A set of functions is provided |
| which allows an asynchronous implementation such that the graphics |
| pipeline need not be stalled while measurements are returned to |
| the client. |
| |
| A buffer in which to collect instrument measurements is defined |
| with InstrumentsBufferSGIX, where <size> defines the size of the |
| buffer. If <buf> has been previously defined with a prior call, |
| the buffer is reset, that is, measurements taken after the call to |
| InstrumentsBufferSGIX will be written to the start of the buffer. |
| Otherwise the buffer will be processed in a way that allows |
| asynchronous writing to the buffer from the graphics pipeline. If |
| <buf> is zero, then any resources allocated to prepare the buffer |
| for writing from the graphics pipeline from a previous call will |
| be freed. If <buf> is non-zero, but is different from a previous |
| call, the old buffer is considered to be replaced by the new |
| buffer and any allocated resources involved in preparing the old |
| buffer for writing are freed. |
| |
| If <size> is negative an INVALID_VALUE is generated. |
| |
| An INVALID_OPERATION is generated if InstrumentsBufferSGIX is |
| called between Begin/End. |
| |
| If there are multiple instruments enabled, the measurement for |
| each enabled instrument can appear in the buffer in any order for |
| a given measurement. |
| |
| The buffer address can be queried with glGetPointervEXT using |
| <pname> GL_INSTRUMENT_BUFFER_POINTER. |
| |
| To start the enabled instrument(s) before taking a measurement |
| execute StartInstrumentsSGIX. To stop the enabled instruments and |
| take a measurement use StopInstrumentsSGIX. The parameter <marker> |
| is passed through the pipe and written back to the buffer to ease |
| the task of interpreting the buffer. |
| |
| To take an instrument measurement use ReadInstrumentsSGIX. The |
| parameter <marker> is processed as with StopInstrumentsSGIX. |
| |
| An INVALID_OPERATION is generated if StartInstrumentsSGIX is |
| executed twice without an intervening execution of |
| StopInstrumentsSGIX or InstrumentsBufferSGIX. Symetrically, an |
| INVALID_OPERATION is generated if StopInstrumentsSGIX is executed |
| twice without an intervening execution of StartInstrumentsSGIX. |
| ReadInstrumentsSGIX will generate an INVALID_OPERATION if executed |
| after an execution of StopInstruments without an intervening |
| execution of StopInstrumentsSGIX or InstrumentsBufferSGIX. |
| |
| Executing any of StartInstrumentsSGIX, StopInstrumentsSGIX, |
| ReadInstruments without a successful call to InstrumentsBufferSGIX |
| to define a buffer will generate an INVALID_OPERATION. Executing |
| any of StartInstrumentsSGIX, StopInstrumentsSGIX, ReadInstruments |
| between Begin/End will generate an INVALID_OPERATION |
| |
| If no instruments are enabled, executions of StartInstrumentsSGIX, |
| StopInstrumentsSGIX, ReadInstruments will not write measurements |
| to the buffer. |
| |
| The number of measurements taken since the buffer was reset can be |
| queried with glGet using <pname> GL_INSTRUMENT_MEASUREMENTS. |
| |
| To determine whether a measurement of the enabled instruments has |
| been written to the buffer call PollInstrumentsSGIX. If a new |
| measurement has appeared in the buffer since the last call to |
| PollInstrumentsSGIX, 1 will be returned, otherwise zero is |
| returned. If 1 is returned, the value of marker associated with |
| the measurement and passed to StopInstrumentsSGIX or |
| ReadInstrumentsSGIX is written into the integer referred to by |
| <markerp>. The measurements will appear in the buffer in the order |
| in which they were requested. If the buffer is overflowed, |
| PollInstrumentsSGIX may return -1 as soon as the overflow is |
| detected, even if the measurement being polled for did not cause |
| the overflow. An implementation may choose to delay reporting the |
| overflow until the measurement that caused the overflow is the one |
| being polled. |
| |
| To get a total count of the number of new valid words written to |
| the buffer call GetInstrumentsSGIX. The value returned is the |
| number of ints that have been written to the buffer since the last |
| call to GetInstrumentsSGIX. GetInstrumentsSGIX can be used |
| independently of PollInstrumentsSGIX. If the buffer has been |
| overflowed since the last call to GetInstrumentsSGIX, -1 is |
| returned for the count. |
| |
| Additions to Chapter 6 of the 1.0 Specification (State and State Requests) |
| |
| The GL_INSTRUMENT_BUFFER_POINTER_SGIX enum should be added to the |
| list of enum's recognized by GetPointerv. |
| |
| Additions to the GLX Specification |
| |
| None |
| |
| GLX Protocol |
| |
| XXX - not yet complete |
| |
| Errors |
| |
| An INVALID_OPERATION is generated if any of the instruments |
| functions or procedures are called within Begin/End. |
| |
| When calling glInstrumentsBufferSGIX, an INVALID_VALUE is |
| generated if <size> is negative. |
| |
| An INVALID_OPERATION is generated if two StartInstrumentsSGIX are |
| called without an intervening call to StopInstrumentsSGIX or |
| InstrumentsBufferSGIX. Symetrically, an INVALID_OPERATION is |
| generated if StopInstrumentsSGIX is called twice without an |
| intervening StartInstrumentsSGIX. ReadInstrumentsSGIX will |
| generate an INVALID_OPERATION if called after a call to |
| StopInstruments without an intervening call to StopInstrumentsSGIX |
| or InstrumentsBufferSGIX. |
| |
| Calling any of StartInstrumentsSGIX, StopInstrumentsSGIX, |
| ReadInstruments without a successful call to InstrumentsBufferSGIX |
| to define a buffer will generate an INVALID_OPERATION. |
| |
| New State |
| |
| Initial Initial |
| Get Value Get Command Type Value Attrib |
| --------- ----------- ---- ----- ------ |
| INSTRUMENT_MEASUREMENTS_SGIX GetInteger Z 0 - |
| INSTRUMENT_BUFFER_POINTER_SGIX GetPointervEXT Y 0 - |
| |
| New Implementation Dependent State |
| |
| None |
| |