patch to import Jon Smirl's work from Bitkeeper

1 files changed, 112 insertions, 0 deletions

diff --git a/src/mesa/tnl_dd/imm/NOTES.imm b/src/mesa/tnl_dd/imm/NOTES.imm
new file mode 100644
index 00000000000..9b2bd65e4bf
--- /dev/null
+++ b/src/mesa/tnl_dd/imm/NOTES.imm
@@ -0,0 +1,112 @@
+
+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.
\ No newline at end of file