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