src/mesa/tnl/NOTES

   1 INTRODUCTION
   2
   3 A generic, configurable software implementation of GL transformation &
   4 lighting.
   5
   6 This module provides an implementation of the routines required by the
   7 'vtxfmt' mechanism of core mesa for tnl functionality in all
   8 combinations of compile and execute modes.
   9
  10 Most current drivers use the tnl module exclusively to provide this
  11 functionality, though there is an experimental alternate
  12 implementation provided by the tnl_dd/t_dd_imm_* files which can
  13 handle a small subset of GL states in execute mode only.
  14
  15
  16 STATE
  17
  18 To create and destroy the module:
  19
  20         GLboolean _tnl_CreateContext( GLcontext *ctx );
  21         void _tnl_DestroyContext( GLcontext *ctx );
  22
  23 The module is not active by default, and must be installed by calling
  24 _tnl_Wakeup().  This function installs internal tnl functions into all
  25 the vtxfmt dispatch hooks, thus taking over the task of transformation
  26 and lighting entirely:
  27
  28         void _tnl_wakeup_exec( GLcontext *ctx );
  29         void _tnl_wakeup_save_exec( GLcontext *ctx );
  30
  31
  32 This module tracks state changes internally and maintains derived
  33 values based on the current state.  For this to work, the driver
  34 ensure the following funciton is called whenever the state changes and
  35 the swsetup module is 'awake':
  36
  37         void _tnl_InvalidateState( GLcontext *ctx, GLuint new_state );
  38
  39 There is no explicit call to put the tnl module to sleep.  Simply
  40 install other function pointers into all the vtxfmt dispatch slots,
  41 and (optionally) cease calling _tnl_InvalidateState().
  42
  43 CUSTOMIZATION
  44
  45 The module provides customizability through several mechanisms.  The
  46 most important is by allowing drivers to specify the pipeline through
  47 which vertex data is passed, including its eventual transfer to
  48 rasterization hardware (or software).
  49
  50 The default pipeline is specified in t_pipeline.c, and is usually a
  51 starting point for driver pipelines.  Some drivers will remove a stage
  52 where hardware provides support for the implemented operation (for
  53 instance fog where per-pixel hardware fog is available, as in the dri
  54 tdfx driver), or add stages to shortcircuit latter operations (for
  55 example taking advantage of hardware support for strips and other
  56 higher-level primitives (for example the radeon driver).
  57
  58 In addition, the following functions provide further tweaks:
  59
  60 extern void
  61 _tnl_need_projected_coords( GLcontext *ctx, GLboolean flag );
  62
  63         - Direct the default vertex transformation stage to
  64           produce/not produce projected clip coordinates.
  65
  66 extern void
  67 _tnl_need_dlist_loopback( GLcontext *ctx, GLboolean flag );
  68
  69         - Direct the display list component of the tnl module to
  70           replay display lists as 'glVertex' type calls, rather than
  71           passing the display list data directly into the tnl pipeline
  72           mechanism.
  73
  74           This allows display lists to be replayed by the tnl module
  75           even when the module is not strictly active.
  76
  77
  78 extern void
  79 _tnl_need_dlist_norm_lengths( GLcontext *ctx, GLboolean flag );
  80
  81         - Direct the display list component to enable/disable caching
  82           1/length values for display list normals.  Doing so is
  83           ususally helpful when lighting is performed in software, but
  84           wasteful otherwise.
  85
  86
  87 DRIVER INTERFACE
  88
  89 The module itself offers a minimal driver interface:
  90
  91          void (*RunPipeline)( GLcontext *ctx );
  92
  93 Normally this is set to _tnl_RunPipeline(), however the driver can use
  94 this hook to wrap checks or other code around this call.
  95
  96 In addition, the driver interface for the default render pipeline
  97 stage is housed in the tnl context struct (this could be cleaner).
  98
  99
 100 RENDER DRIVER INTERFACE
 101
 102 See t_context.h for the definition and explanation of this.