fglInstrumentsSGIX(3G)

fglInstrumentsBufferSGIX, fglStartInstrumentsSGIX, fglReadInstrumentsSGIX, fglStopInstrumentsSGIX, fglPollInstrumentsSGIX, fglGetInstrumentsSGIX - take measurements from enabled instruments in the GL

Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.

NAME
fglInstrumentsBufferSGIX, fglStartInstrumentsSGIX,
fglReadInstrumentsSGIX, fglStopInstrumentsSGIX, fglPollInstrumentsSGIX,
fglGetInstrumentsSGIX - take measurements from enabled instruments in the
GL

FORTRAN SPECIFICATION
SUBROUTINE fglInstrumentsBufferSGIX( INTEGER*4 size,
CHARACTER*8 buffer )

PARAMETERS
size specifies the number of GLints in buffer

buffer specifies a pointer to the buffer for instrument measurement
records

FORTRAN SPECIFICATION
SUBROUTINE fglStartInstrumentsSGIX( )

FORTRAN SPECIFICATION
SUBROUTINE fglReadInstrumentsSGIX( INTEGER*4 marker )

FORTRAN SPECIFICATION
SUBROUTINE fglStopInstrumentsSGIX( INTEGER*4 marker )

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

FORTRAN SPECIFICATION
INTEGER*4 fglPollInstrumentsSGIX( CHARACTER*8 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 fglPollInstrumentsSGIX

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

FORTRAN SPECIFICATION
INTEGER*4 fglGetInstrumentsSGIX( )

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

DESCRIPTION
fglInstrumentsBufferSGIX, fglStartInstrumentsSGIX,
fglReadInstrumentsSGIX, fglStopInstrumentsSGIX, fglPollInstrumentsSGIX
and fglGetInstrumentsSGIX 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 fglGetString for the names of the extensions that
implement the instruments.

Unlike feedback and selection (see fglSelectBuffer and
fglFeedbackBuffer), 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
fglInstrumentsBufferSGIX. 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 fglInstrumentsBufferSGIX 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 fglGetPointervEXT using argument
GL_INSTRUMENT_BUFFER_POINTER_SGIX.

To enable an instrument, use fglEnable 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
fglStartInstrumentsSGIX. To take a measurement use
fglReadInstrumentsSGIX. To stop the currently-enabled instruments and
take a final measurement use fglStopInstrumentsSGIX. 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 fglEnable 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 fglStartInstrumentsSGIX,
fglStopInstrumentsSGIX, or fglReadInstruments will not write measurements
to the buffer.

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

To determine whether a measurement has been written to the buffer call
fglPollInstrumentsSGIX. If a new measurement has appeared in the buffer
since the last call to fglPollInstrumentsSGIX, 1 is returned, and the
value of marker associated with the measurement by fglStopInstrumentsSGIX
or fglReadInstrumentsSGIX 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,
fglPollInstrumentsSGIX 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, fglPollInstrumentsSGIX returns 0.

To get a count of the number of new valid GLints written to the buffer,
call fglGetInstrumentsSGIX. The value returned is the number of GLints
that have been written to the buffer since the last call to
fglGetInstrumentsSGIX or fglInstrumentsBufferSGIX. If the buffer has
overflowed since the last call to fglGetInstrumentsSGIX, -1 is returned
for the count. Note that fglGetInstrumentsSGIX can be used independently
of fglPollInstrumentsSGIX.
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
fglInstrumentsBufferSGIX, fglStartInstrumentsSGIX,
fglReadInstrumentsSGIX, fglStopInstrumentsSGIX, fglPollInstrumentsSGIX
and fglGetInstrumentsSGIX are part of the GL_SGIX_instruments extension,
not part of the core GL command set. See fglIntro for information about
using extensions.

ERRORS
If size is negative, GL_INVALID_VALUE is generated.

GL_INVALID_OPERATION is generated if fglStartInstrumentsSGIX is executed
twice without an intervening execution of fglStopInstrumentsSGIX or
fglInstrumentsBufferSGIX. Symmetrically, GL_INVALID_OPERATION is
generated if fglStopInstrumentsSGIX is executed twice without an
intervening fglStartInstrumentsSGIX. fglReadInstrumentsSGIX will
generate GL_INVALID_OPERATION if executed after an execution of
fglStopInstruments without an intervening execution of
fglStopInstrumentsSGIX or fglInstrumentsBufferSGIX. Executing any of
fglStartInstrumentsSGIX, fglStopInstrumentsSGIX, or fglReadInstruments
without a successful execution of fglInstrumentsBufferSGIX to define a
buffer will generate GL_INVALID_OPERATION.

GL_INVALID_OPERATION is generated if any of fglInstrumentsBufferSGIX,
fglStartInstrumentsSGIX, fglReadInstrumentsSGIX, fglStopInstrumentsSGIX,
fglPollInstrumentsSGIX or fglGetInstrumentsSGIX is executed between the
execution of fglBegin and the corresponding execution of fglEnd.

ASSOCIATED GETS
fglGet with argument GL_INSTRUMENT_MEASUREMENTS_SGIX
fglGetPointerv with argument GL_INSTRUMENT_BUFFER_POINTER_SGIX
fglGetString 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
fglStartInstrumentsSGIX, and by fglReadInstrumentsSGIX 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 fglStartInstrumentsSGIX, and by fglReadInstrumentsSGIX
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 fglStartInstrumentsSGIX, and by fglReadInstrumentsSGIX
after its value has been written to the buffer.

MAILBOX_TIMESTAMP (index 5) Contains the value of COUNTALL (see
below) at the time fglStartInstrumentsSGIX or fglReadInstrumentsSGIX
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
fglStopInstrumentsSGIX or fglReadInstrumentsSGIX 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.