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. 12 13 14 STATE 15 16 To create and destroy the module: 17 18 GLboolean _tnl_CreateContext( struct gl_context *ctx ); 19 void _tnl_DestroyContext( struct gl_context *ctx ); 20 21 The module is not active by default, and must be installed by calling 22 _tnl_Wakeup(). This function installs internal tnl functions into all 23 the vtxfmt dispatch hooks, thus taking over the task of transformation 24 and lighting entirely: 25 26 void _tnl_wakeup_exec( struct gl_context *ctx ); 27 void _tnl_wakeup_save_exec( struct gl_context *ctx ); 28 29 30 This module tracks state changes internally and maintains derived 31 values based on the current state. For this to work, the driver 32 ensure the following funciton is called whenever the state changes and 33 the swsetup module is 'awake': 34 35 void _tnl_InvalidateState( struct gl_context *ctx, GLuint new_state ); 36 37 There is no explicit call to put the tnl module to sleep. Simply 38 install other function pointers into all the vtxfmt dispatch slots, 39 and (optionally) cease calling _tnl_InvalidateState(). 40 41 CUSTOMIZATION 42 43 The module provides customizability through several mechanisms. The 44 most important is by allowing drivers to specify the pipeline through 45 which vertex data is passed, including its eventual transfer to 46 rasterization hardware (or software). 47 48 The default pipeline is specified in t_pipeline.c, and is usually a 49 starting point for driver pipelines. Some drivers will remove a stage 50 where hardware provides support for the implemented operation (for 51 instance fog where per-pixel hardware fog is available), 52 or add stages to shortcircuit latter operations (for 53 example taking advantage of hardware support for strips and other 54 higher-level primitives (for example the radeon driver). 55 56 In addition, the following functions provide further tweaks: 57 58 extern 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 64 extern 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 76 extern 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 85 DRIVER INTERFACE 86 87 The module itself offers a minimal driver interface: 88 89 void (*RunPipeline)( struct gl_context *ctx ); 90 91 Normally this is set to _tnl_RunPipeline(), however the driver can use 92 this hook to wrap checks or other code around this call. 93 94 In addition, the driver interface for the default render pipeline 95 stage is housed in the tnl context struct (this could be cleaner). 96 97 98 RENDER DRIVER INTERFACE 99 100 See t_context.h for the definition and explanation of this.
