Subversion Repositories shark

NOTE:

These files are incomplete.  They do not yet form a working
implementation of hte concepts discused below.


OVERVIEW

The t_dd_imm_* files form a set of templates to produce driver -
specific software tnl modules for a small subset of transformation and
lighting states.

The approach is quite different to the large vertex buffers of the
src/tnl module, and is based around a cache of four recent vertices
and a 'current' vertex which is updated directly from the Color,
Normal, Texcoord, SecondaryColor and Fog entrypoints.

The current vertex is actually a composite of the ctx->Current values
and a partial hardware vertex maintained where the hardware values
differ from those in ctx->Current.  For example, clamped color values
are kept in the hardware vertex, while texcoords remain in
ctx->Current.

A crude diagram:

                +--------------+        +-------------------+
                | ctx->Current |        | Current-HW-vertex |
                +--------------+        +-------------------+
                       \                          /
                        \                        /
                         \                      /
                          \                    /
                           ---------   --------
                                   |   |      
                                   v   v     
        +--------+   +--------+  +--------+  +--------+ 
        | vert-0 |   | vert-1 |  | vert-2 |  | vert-3 |                  
        +--------+   +--------+  +--------+  +--------+                  
                                     |
                                     |
                                     v
                                     
                                    DMA


Here values from ctx->Current and current-HW-vertex are merged to
build vert-2, which is then dumped to hardware (DMA).  A state machine
determines which vertex is built in turn, and how the vertices are
used to present primitives to hardware.  These actions all occur
during a call to Vertex{234}f{v}.

Each vert-n includes clip coordinates and a clipmask in addition to
the hardware (window) coordinates.  This information allows clipping
to take place directly on these vertices, if need be.

t_dd_imm_capi.h
        
        Color{34}{fub}{v}() implementations.  These update both
        ctx->Current (unclamped float colors) and current-HW-vertex
        with hardware-specific color values (typically unsigned
        bytes).

        When lighting is enabled, the functions from src/api_noop.c
        should be used, which just update ctx->Current.  (The
        current-hw-vertex colors are produced from lighting, which is
        keyed to Normal3f).

t_dd_imm_vb.c

        Support functions for clipping and fallback.  See
        t_dd_imm_primtmp.h.

t_dd_imm_napi.c
t_dd_imm_napi.h

        Versions of Normal3f{v} to perform lighting with one or more
        infinite lights.  Updates ctx->Current.Normal and the current
        HW colors.

        When lighting is disabled, use the functions from api_noop.c
        instead.


t_dd_imm_primtmp.h

        State machine to control emission of vertices and primitives
        to hardware.  Called indirectly from Vertex{234}f{v}.  Capable
        of supporting hardware strip and fan primitives, and of
        decomposing to discreet primitives for clipping or fallback,
        or where the native primitive is unavailable.

t_dd_imm_tapi.h

        Implementations of TexCoord{v} and MultiTexCoord4f{v}ARB to
        fire a callback when transitioning to projective texture.
        Most drivers will need to change vertex format at this point,
        some may need to enable a software rasterization fallback.

t_dd_imm_vapi.h

        Implementations of Vertex{234}f{v}.  These perform
        transformation and cliptesting on their arguments, then jump
        into the state machine implemented in primtmp.h.

t_dd_imm_vertex.h

        Support functions for building and clip-interpolating hardware
        vertices.  Called from primtmp.h.


Keith Whitwell, June 2001.