glInstrumentsSGIX(3G)

glInstrumentsBufferSGIX, glStartInstrumentsSGIX, glReadInstrumentsSGIX, glStopInstrumentsSGIX, glPollInstrumentsSGIX, glGetInstrumentsSGIX - take measurements from enabled instruments in the GL

As shipped in IRIX 6.5.15. Unchanged since IRIX 6.5.

NAME
glInstrumentsBufferSGIX, glStartInstrumentsSGIX, glReadInstrumentsSGIX,
glStopInstrumentsSGIX, glPollInstrumentsSGIX, glGetInstrumentsSGIX - take
measurements from enabled instruments in the GL

C SPECIFICATION
void glInstrumentsBufferSGIX( GLsizei size,
GLint *buffer )

PARAMETERS
size specifies the number of GLints in buffer

buffer specifies a pointer to the buffer for instrument measurement
records

C SPECIFICATION
void glStartInstrumentsSGIX( void )

C SPECIFICATION
void glReadInstrumentsSGIX( GLint marker )

C SPECIFICATION
void glStopInstrumentsSGIX( GLint marker )

PARAMETERS
marker
specifies a marker value to be returned along with the measurement
record

C SPECIFICATION
GLint glPollInstrumentsSGIX( GLint *marker_p )

PARAMETERS
marker_p
specifies a pointer to the location where the marker sent with a
measurement will be written after the measurement record is written
to the instrument buffer

FUNCTION RETURN
Returns:

0 when no new measurement has been written to the buffer since the last
call to glPollInstrumentsSGIX

1 when a new measurement has been written to the instrument buffer
since the last such call

-1 when a buffer overflow has been detected

C SPECIFICATION
GLint glGetInstrumentsSGIX( void )

FUNCTION RETURN
Returns the number of GLints that have been written to the instrument
buffer since the last buffer reset or call to glGetInstrumentsSGIX.

DESCRIPTION
glInstrumentsBufferSGIX, glStartInstrumentsSGIX, glReadInstrumentsSGIX,
glStopInstrumentsSGIX, glPollInstrumentsSGIX and glGetInstrumentsSGIX are
part of the GL_SGIX_instruments extension.

Instruments allow an application 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, or in tuning an application for best
performance.

GL_SGIX_instruments provides an instrumentation framework, but no
instruments. The set of available instruments varies between OpenGL
implementations, and can be determined by querying the GL_EXTENSIONS
string returned by glGetString for the names of the extensions that
implement the instruments.

Unlike feedback and selection (see glSelectBuffer and glFeedbackBuffer),
GL_SGIX_instruments provides commands that allow measurements to be
delivered asynchronously, so that the graphics pipeline need not be
stalled while measurements are returned to the client.

A buffer in which to collect instrument measurements is specified with
glInstrumentsBufferSGIX. size specifies the size of the buffer, as a
count of GLints. The buffer will be prepared in a way that allows it to
be written asynchronously by the graphics pipeline. If the same buffer
was specified on a previous call, the buffer is reset; that is,
measurements taken after the call to glInstrumentsBufferSGIX will be
written to the start of the buffer. If buffer is zero, then any
resources allocated by a previous call to prepare the buffer for writing
will be freed. If buffer is non-zero, but is different from a previous
call, the old buffer is replaced by the new buffer and any allocated
resources involved in preparing the old buffer for writing are freed.

The buffer address can be queried with glGetPointervEXT using argument
GL_INSTRUMENT_BUFFER_POINTER_SGIX.

To enable an instrument, use glEnable with an argument that specifies the
instrument. The argument to use for a particular instrument is
determined by the OpenGL extension that supports that instrument. (See
below for an example.)

To start the currently-enabled instrument(s) call glStartInstrumentsSGIX.
To take a measurement use glReadInstrumentsSGIX. To stop the currently-
enabled instruments and take a final measurement use
glStopInstrumentsSGIX. The parameter marker will be passed through the
pipe and written to the buffer to ease the task of interpreting it.

The format of any instrument measurement in the buffer obeys certain
conventions. The first word of the measurement is the glEnable enum for
the instrument itself. The second word of the measurement is the size in
GLints of the entire measurement so that any parser can step over
measurements with which it is unfamiliar. Currently there are no
implementation independent instruments to describe. Some implementation
dependent instruments are described in the Machine Dependencies section
of this page.

In a single measurement, if multiple instruments are enabled, the data
for those instruments can appear in the buffer in any order.

If no instruments are enabled executing glStartInstrumentsSGIX,
glStopInstrumentsSGIX, or glReadInstruments will not write measurements
to the buffer.

The number of measurements taken since the buffer was reset can be
queried with glGet using GL_INSTRUMENT_MEASUREMENTS_SGIX.

To determine whether a measurement has been written to the buffer call
glPollInstrumentsSGIX. If a new measurement has appeared in the buffer
since the last call to glPollInstrumentsSGIX, 1 is returned, and the
value of marker associated with the measurement by glStopInstrumentsSGIX
or glReadInstrumentsSGIX is written into the variable referenced by
marker_p. The measurements will appear in the buffer in the order in
which they were requested. If the buffer overflows, glPollInstrumentsSGIX
may return -1 as soon as the overflow is detected, even if the
measurement being polled did not cause the overflow. (An implementation
may also choose to delay reporting the overflow until the measurement
that caused the overflow is the one being polled.) If no new measurement
has been written to the buffer, and overflow has not occurred,
glPollInstrumentsSGIX returns 0.

To get a count of the number of new valid GLints written to the buffer,
call glGetInstrumentsSGIX. The value returned is the number of GLints
that have been written to the buffer since the last call to
glGetInstrumentsSGIX or glInstrumentsBufferSGIX. If the buffer has
overflowed since the last call to glGetInstrumentsSGIX, -1 is returned
for the count. Note that glGetInstrumentsSGIX can be used independently
of glPollInstrumentsSGIX.

EXAMPLES
#ifdef GL_SGIX_instruments
#define MARKER1 1001
#define MARKER2 1002
{
static GLint buffer[64];
GLvoid *bufp;
int id, count0, count1, r;

/* define the buffer to hold the measurements */
glInstrumentsBufferSGIX(sizeof(buffer)/sizeof(GLint), buffer);

/* enable the instruments from which one wishes to take measurements */
glEnable(<an enum for a supported instrument, such as GL_IR_INSTRUMENT1_SGIX>);

glStartInstrumentsSGIX();
/* insert GL commands here */
glReadInstrumentsSGIX(MARKER1);
/* insert GL commands here */
glStopInstrumentsSGIX(MARKER2);

/* query the number of measurements since the buffer was specified */
glGetIntegerv(GL_INSTRUMENT_MEASUREMENTS_SGIX,&r);
/* now r should equal 2 */

/* query the pointer to the instrument buffer */
glGetPointervEXT(GL_INSTRUMENT_BUFFER_SGIX,&bufp);
/* now 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();
/* Since 0, 1, or 2 measurements might have been returned to
* the buffer at this point, count0 will be 0, 1, or 2 times
* the size in GLints of the records returned from the
* currently-enabled instruments.
* If the buffer 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 MARKER1). While it is 0,
* no measurement has been returned (yet).
*/

while (!(r = glPollInstrumentsSGIX(&id))) ;
/* see the note on the first poll; id now should equal MARKER2 */

count1 = glGetInstrumentsSGIX();
/* the sum of count0 and count1 should be 2 times the size in GLints
* of the records returned for all instruments that we have enabled.
*/
}
#endif

NOTES
glInstrumentsBufferSGIX, glStartInstrumentsSGIX, glReadInstrumentsSGIX,
glStopInstrumentsSGIX, glPollInstrumentsSGIX and glGetInstrumentsSGIX are
part of the GL_SGIX_instruments extension, not part of the core GL
command set. See glIntro for information about using extensions.

ERRORS
If size is negative, GL_INVALID_VALUE is generated.

GL_INVALID_OPERATION is generated if glStartInstrumentsSGIX is executed
twice without an intervening execution of glStopInstrumentsSGIX or
glInstrumentsBufferSGIX. Symmetrically, GL_INVALID_OPERATION is generated
if glStopInstrumentsSGIX is executed twice without an intervening
glStartInstrumentsSGIX. glReadInstrumentsSGIX will generate
GL_INVALID_OPERATION if executed after an execution of glStopInstruments
without an intervening execution of glStopInstrumentsSGIX or
glInstrumentsBufferSGIX. Executing any of glStartInstrumentsSGIX,
glStopInstrumentsSGIX, or glReadInstruments without a successful
execution of glInstrumentsBufferSGIX to define a buffer will generate
GL_INVALID_OPERATION.

GL_INVALID_OPERATION is generated if any of glInstrumentsBufferSGIX,
glStartInstrumentsSGIX, glReadInstrumentsSGIX, glStopInstrumentsSGIX,
glPollInstrumentsSGIX or glGetInstrumentsSGIX is executed between the
execution of glBegin and the corresponding execution of glEnd.

ASSOCIATED GETS
glGet with argument GL_INSTRUMENT_MEASUREMENTS_SGIX
glGetPointerv with argument GL_INSTRUMENT_BUFFER_POINTER_SGIX
glGetString with argument GL_EXTENSIONS

MACHINE DEPENDENCIES
The SGIX_instruments extension is supported only on InfiniteReality
systems.

The GL_IR_INSTRUMENT1_SGIX instrument is implemented only on
InfiniteReality systems. Each measurement uses 10 words of the buffer.
The first (index 0) will be GL_IR_INSTRUMENT1_SGIX itself. The second
word (index 1) will be 10. The following words are:

COUNTEMPTY (index 2) Increments each clock cycle for which a word of
screen-space geometry, pixel, or texel data was not transferred from
the GE board to the RM board. A high value could indicate that
rendering is geometry-limited or host-limited (because the GE is not
delivering commands to the RM as fast as the RM can process them),
or that rendering is rasterization-limited (because the RM is
working on previous commands and is refusing to accept new data from
the GE). Unfortunately there is no simple way to distinguish
between these two cases. The counter is set to zero by
glStartInstrumentsSGIX, and by glReadInstrumentsSGIX after its value
has been written to the buffer.

COUNTDRAW (index 3) Increments each clock cycle for which a word of
screen-space geometry or pixel data (but not texel data) is
transferred from the GE board to the RM board. The counter is set
to zero by glStartInstrumentsSGIX, and by glReadInstrumentsSGIX
after its value has been written to the buffer.

COUNTLOAD (index 4) Increments each clock cycle for which a word of
texture data is written to the texture memory. The counter is set
to zero by glStartInstrumentsSGIX, and by glReadInstrumentsSGIX
after its value has been written to the buffer.

MAILBOX_TIMESTAMP (index 5) Contains the value of COUNTALL (see
below) at the time glStartInstrumentsSGIX or glReadInstrumentsSGIX
was called.

COUNTALL (index 6) Increments every clock cycle. No effort is made
to prevent wrapping.

PAD (index 7) Unused.

MARKER (index 8) Holds the value of the marker passed to
glStopInstrumentsSGIX or glReadInstrumentsSGIX for this measurement.

MAILBOX (index 9) Holds a value that is used by the implementation.
Typically a sequence identifier, set after the buffer has been
specified, starting at 1 with the first measurement and incrementing
by 1 for each successive measurement.