Back to the OpenGL extension cross reference
GL_SGIX_instruments
XXX - Almost complete; needs GLX protocol.
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.
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];
GLvoid *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
}
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
Implementation Support
List of OpenGL implementations supporting the GL_SGIX_instruments extension
Original File
Original text file for the GL_SGIX_instruments extension
Page generated on Sun Nov 20 18:38:40 2005