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

XXX - incomplete

Name

    SGIX_bali_r_instruments

Name Strings

    GL_SGIX_bali_r_instruments

Version

    $Date: 1998/06/17 19:59:07 $  $Revision: 1.4 $

Number

    XXX

Dependencies

    SGIX_instruments is required
    SGIX_multisample affects the definition of this extension.

Overview

    This extension defines behavior for instruments which are
    maintained on the Bali R chips.  The behavior is different from
    standard instruments behavior since each system may contain more
    than one R chip.

    Additionally, this extension defines two such instruments:  one to
    count the number of fragments generated and a second to count the
    number of fragments which passed the depth test.

Issues

    *	Should fragments generated by internal pixel operations be
	counted?  From a GL point of view they don't exist, but from
	an R usage point of view they do.

    *	Should we expose the texture cache wait counter?  What could
	the user do about a bottleneck caused by texture cache misses?

    *	Currently we count only fragments which passed the depth test
	and do not count fragments which were drawn when the depth
	test was disabled.  Is this the correct behavior?

    *	Are there any other R instruments we should add?

New Procedures and Functions

    None

New Tokens

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

        BALI_FRAGMENTS_GENERATED_INSTRUMENT	0x6090
        BALI_DEPTH_PASS_INSTRUMENT		0x6091

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

        BALI_R_CHIP_COUNT			0x6092

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)

    Add to section 4.1 after the introductory paragraph and prior to
    section 4.1.1 (Pixel Ownership Test):

    If BALI_FRAGMENTS_GENERATED_INSTRUMENT is enabled and the
    instruments have been started via a call to StartInstrumentsSGIX,
    a counter of the number of fragments generated is maintained.
    This counter is incremented by one for each fragment.  The GL
    implementation is not guaranteed to generate a fragment for every
    screen pixel which the primitive touched as long as this
    optimization will not affect the final image.  For example, if a
    region of the primitive only contains fragments which the GL has
    determined will fail the Z test, the fragments may not be
    generated.  Therefore, the count of fragments generated may be
    smaller than but may not be greater than the screen space area of
    the primitive as determined by the number of pixels touched by the
    primitive.

    Added to subsection 4.1.5 (Depth buffer test) at the end of the
    paragraph which begins "If the depth buffer test fails...":

    If BALI_DEPTH_PASS_INSTRUMENT is enabled and instruments have been
    started via a call to StartInstrumentSGIX, a counter of the number
    of fragments which have passed the depth test is maintained.  This
    counter is incremented by one for each fragment which passes the
    depth test.  If MULTISAMPLE_SGIS is enabled, the counter is
    incremented by one for each fragment containing at least one
    sample for which the depth test passed.

Additions to Chapter 5 of the 1.0 Specification (Special Functions)

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

    For instruments which are computed on the Bali R chip, one
    response will be returned to the buffer per R chip.  The number of
    R chips is queried using the enum BALI_R_CHIP_COUNT (see Chapter
    6).  From the point of view of this extension, the R chips are
    considered to be completely interchangable and no mechanism for
    identifying which response came from which R chip is provided.
    Generally, the application should combine the results from all the
    R chips together (for example, by adding them) before using the
    information.

    Each call to StopInstrumentsSGIX or ReadInstrumentsSGIX will
    generate one response per R chip for each enabled R chip
    instrument.  This count will be reflected in the return values of
    glGetInstrumentSGIX.  The values from each R chip do not
    necessarily return at the same time, so the glGetInstrumentsSGIX
    call may return a value from 0 to BALI_R_CHIP_COUNT times the sum
    in words of the size of the instrument.  However, the values from
    each R are returned atomically from the point of view of
    glGetInstrumentsSGIX so the return value must be a multiple of the
    size in words of the instrument.  

    If more than one R instrument is enabled and ReadInstrumentsSGIX
    or StopInstrumentsSGIX is called, no guarantees are made with
    regard to the ordering and interleaving of the reply packets from
    the R chips.  The instrument response packets from a single R chip
    may or may not be placed consecutively in the buffer.  Conversely,
    the responses from different R chips for a single instrument may
    or may not be placed consecutively in the buffer.  Also, no
    assumptions may be made about which R chip generated which
    response.

    Each R chip response from BALI_FRAGMENTS_GENERATED_INSTRUMENT_SGIX
    and BALI_DEPTH_PASS_INSTRUMENT_SGIX instruments uses 4 words of
    the buffer.  The first word (index 0) will be the enum name of the
    instrument (BALI_FRAGMENTS_GENERATED_INSTRUMENT_SGIX or
    BALI_DEPTH_PASS_INSTRUMENT_SGIX).  The second word (index 1) of
    the instrument is the size in words of all the data returned by
    the instrument, which is four for the instruments defined in this
    extension.  The third word (index 2) will be the instrument
    value.  Computation of the instrument values is described in
    Chapter 3 (Rasterization).  The fourth word (index 3) will contain
    the marker passed to StopInstrumentsSGIX or ReadInstrumentsSGIX.

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

    XXX    

Additions to the GLX Specification

    XXX

Errors

    None

New State

    XXX

New Implementation Dependent State

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