xref: /third_party/openGLES/extensions/SGIX/SGIX_fragments_instrument.txt

XXX - incomplete (needs number, glx protocol)

Name

    SGIX_fragments_instrument

Name Strings

    GL_SGIX_fragments_instrument

Version

    $Date: 1999/04/27 01:20:04 $  $Revision: 1.5 $

Number

    180

Dependencies

    SGIX_instruments is required

Overview

    This extension defines an instrument that uses the API defined in
    SGIX_instruments.  The instrument specified by this extension is a
    counter of the number of fragments generated during pixel and
    geometry rasterization.  The maximum value of the counter is an
    implementation-dependent constant.

    Some systems may maintain counters on different parts of the
    system.  For example, a system with rasterization distributed
    across multiple chips may maintain a count of the fragments
    generated on each individual chip.  In this extension, a queriable
    constant is defined that indicates the number of responses to
    expect when a measurement is taken.  This mechanism allows GL
    implementations to be as efficient as possible.

Issues

    *   If an operation such as a clear is implemented
        internally as a draw operation but according to the GL spec
        does not generate any fragments, should the counter be
        updated?  Updating would give a less accurate idea of
        fragments generated from a GL spec point of view, but would
        give a more accurate idea of rasterizer load during a given
        interval. 

        A:  It's better to keep the single meaning of GL fragments
            generated.  Counting internal fragments wouldn't always be
            a good measure of rasterizer load and more accurate
            mechanisms can be imagined easily.
            
    *   Having each counter response appear as an independent
        instrument is awkward and wastes space in the buffer.  Could
        we have GL combine them?

        A:  See explanation in depth_pass_instrument spec.

    *   We say that invisible fragments culled early as an
        implementation optimization do not need to be counted.  For
        example, if an entire triangle is not visible an
        implementation can not rasterize it and not count the
        fragments it contains.  From a GL point of view, these
        fragments *were* generated, but counting them would require
        really generating them (in most implementations anyway).  

        A:  This extension is aimed at performance-sensitive applications,
            so slowing stuff down is not a good idea.  Just don't
            count them.

    *   Is the name for this extension ok?  It's not very descriptive
        but the more descriptive names suggested all came out rather
        long (eg FRAGMENTS_GENERATED_INSTRUMENT_SGIX).

New Tokens

    Accepted by the <cap> parameter of Enable, Disable and IsEnabled:

        FRAGMENTS_INSTRUMENT_SGIX			0x8313

    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
    GetFloatv, and GetDoublev:

	FRAGMENTS_INSTRUMENT_COUNTERS_SGIX		0x8314
	FRAGMENTS_INSTRUMENT_MAX_SGIX			0x8315

Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation)

    None

Additions to Chapter 3 of the 1.0 Specification (Rasterization)

    Add a section 3.X (The Fragment Instrument) after the section 3.1
    (Invariance):

    If FRAGMENTS_INSTRUMENT_SGIX is enabled and instruments have been
    started via a call to StartInstrumentSGIX, a counter or counters
    of the number of fragments generated by rasterization (geometry or
    pixel rectangle) is maintained.  The number of counters can be
    queried using the token FRAGMENTS_INSTRUMENT_COUNTERS_SGIX.  The
    fragments are counted at the end of the rasterization stage just
    before per-fragment operations are applied.  For each fragment,
    the counter is incremented by one.  If the increment would have
    caused the counter to go beyond is maximum representable value,
    the count is clamped to the maximum.  The maximum value of the
    counters may be queried using FRAGMENTS_INSTRUMENT_MAX_SGIX.  The
    counter values are unsigned, so FRAGMENTS_INSTRUMENT_MAX_SGIX may
    be as high as the maximum value of an unsigned integer.

    Some GL implementations may detect early that a fragment or set of
    fragments will not effect the contents of the frame buffer and
    therefore will get a performance increase by not generating them.
    For example, an entire triangle may be in a region of the frame
    buffer that is covered by another window.  Previously, this type of
    optimization had been invisible from a GL spec point of view and
    could be detected by the application only as a change in
    performance.  It is legal for an implementation to not increment
    the counter for fragments that have been eliminated due to this
    sort of optimization.  However, a fragment must be counted if it
    will effect frame buffer contents.

    If an implementation can detect during rasterization that a
    fragment (or set of fragments) will not
    effect the contents of the frame buffer, the implementation can
    transparently avoid rasterizing the .  It is legal for an implementation to not increment the
    fragment counter in this case.  

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)

    Add to the end of section 5.X entitled Instruments:

    The instrument FRAGMENTS_INSTRUMENT_SGIX returns for each
    measurement a system-dependent constant number of responses to the
    buffer.  The constant may be queried using the Get with an
    argument of FRAGMENTS_INSTRUMENT_COUNTERS_SGIX.  Each response is
    formatted as though it came from an independent instrument.  If
    more than one instrument is enabled, the responses from the depth
    pass instrument will be placed successively (as opposed to
    possibly being interrupted by responses from other instruments).
    
    FRAGMENTS_INSTRUMENT_SGIX responses are formatted as follows
    (starting at the first word):

	FRAGMENTS_INSTRUMENT_SGIX
	Number of int's in the response (4)
	Counter value
	Marker value

    The counter value is padded to the size of an int if necessary by
    zero-filling the most significant bits.

    Assuming that none of the counters overflowed, the total number of
    fragments generated while the instrument was enabled is equal to
    the sum of all the counter values.

    Although different responses come from different hardware
    counters, they should be considered identical by the software and
    no guarantee is made about how the responses for each counter are
    ordered within a single query response.  For example, a hardware
    implementation may maintain a counter for each quadrant of the
    screen, but which response in the buffer came from which counter
    is not exposed to the application.


Additions to Chapter 6 of the 1.0 Specification (State and State Requests)

    None

Additions to the GLX Specification

    XXX

Errors

    None

New State

    Get Value				Get Command		Type	Initial Value		Attribute
    ---------				-----------		----	-------------		---------
    FRAGMENTS_INSTRUMENT_SGIX		ReadInstrumentsSGIX	1*xZ+	0			-

New Implementation Dependent State

    Get Value				Get Command		Type	Minimum Value
    ---------				-----------		----	-------------
    FRAGMENTS_INSTRUMENT_COUNTERS_SGIX	GetIntegerv		Z+      1