src/mesa/tnl_dd/imm/NOTES.imm

   1
   2 NOTE:
   3
   4 These files are incomplete.  They do not yet form a working
   5 implementation of hte concepts discused below.
   6
   7
   8 OVERVIEW
   9
  10 The t_dd_imm_* files form a set of templates to produce driver -
  11 specific software tnl modules for a small subset of transformation and
  12 lighting states.
  13
  14 The approach is quite different to the large vertex buffers of the
  15 src/tnl module, and is based around a cache of four recent vertices
  16 and a 'current' vertex which is updated directly from the Color,
  17 Normal, Texcoord, SecondaryColor and Fog entrypoints.
  18
  19 The current vertex is actually a composite of the ctx->Current values
  20 and a partial hardware vertex maintained where the hardware values
  21 differ from those in ctx->Current.  For example, clamped color values
  22 are kept in the hardware vertex, while texcoords remain in
  23 ctx->Current.
  24
  25 A crude diagram:
  26
  27                 +--------------+        +-------------------+
  28                 | ctx->Current |        | Current-HW-vertex |
  29                 +--------------+        +-------------------+
  30                        \                          /
  31                         \                        /
  32                          \                      /
  33                           \                    /
  34                            ---------   --------
  35                                    |   |
  36                                    v   v
  37         +--------+   +--------+  +--------+  +--------+
  38         | vert-0 |   | vert-1 |  | vert-2 |  | vert-3 |
  39         +--------+   +--------+  +--------+  +--------+
  40                                      |
  41                                      |
  42                                      v
  43
  44                                     DMA
  45
  46
  47 Here values from ctx->Current and current-HW-vertex are merged to
  48 build vert-2, which is then dumped to hardware (DMA).  A state machine
  49 determines which vertex is built in turn, and how the vertices are
  50 used to present primitives to hardware.  These actions all occur
  51 during a call to Vertex{234}f{v}.
  52
  53 Each vert-n includes clip coordinates and a clipmask in addition to
  54 the hardware (window) coordinates.  This information allows clipping
  55 to take place directly on these vertices, if need be.
  56
  57 t_dd_imm_capi.h
  58
  59         Color{34}{fub}{v}() implementations.  These update both
  60         ctx->Current (unclamped float colors) and current-HW-vertex
  61         with hardware-specific color values (typically unsigned
  62         bytes).
  63
  64         When lighting is enabled, the functions from src/api_noop.c
  65         should be used, which just update ctx->Current.  (The
  66         current-hw-vertex colors are produced from lighting, which is
  67         keyed to Normal3f).
  68
  69 t_dd_imm_vb.c
  70
  71         Support functions for clipping and fallback.  See
  72         t_dd_imm_primtmp.h.
  73
  74 t_dd_imm_napi.c
  75 t_dd_imm_napi.h
  76
  77         Versions of Normal3f{v} to perform lighting with one or more
  78         infinite lights.  Updates ctx->Current.Normal and the current
  79         HW colors.
  80
  81         When lighting is disabled, use the functions from api_noop.c
  82         instead.
  83
  84
  85 t_dd_imm_primtmp.h
  86
  87         State machine to control emission of vertices and primitives
  88         to hardware.  Called indirectly from Vertex{234}f{v}.  Capable
  89         of supporting hardware strip and fan primitives, and of
  90         decomposing to discreet primitives for clipping or fallback,
  91         or where the native primitive is unavailable.
  92
  93 t_dd_imm_tapi.h
  94
  95         Implementations of TexCoord{v} and MultiTexCoord4f{v}ARB to
  96         fire a callback when transitioning to projective texture.
  97         Most drivers will need to change vertex format at this point,
  98         some may need to enable a software rasterization fallback.
  99
 100 t_dd_imm_vapi.h
 101
 102         Implementations of Vertex{234}f{v}.  These perform
 103         transformation and cliptesting on their arguments, then jump
 104         into the state machine implemented in primtmp.h.
 105
 106 t_dd_imm_vertex.h
 107
 108         Support functions for building and clip-interpolating hardware
 109         vertices.  Called from primtmp.h.
 110
 111
 112 Keith Whitwell, June 2001.