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.