home *** CD-ROM | disk | FTP | other *** search
- INTRODUCTION
-
- A generic, configurable software implementation of GL transformation &
- lighting.
-
- This module provides an implementation of the routines required by the
- 'vtxfmt' mechanism of core mesa for tnl functionality in all
- combinations of compile and execute modes.
-
- Most current drivers use the tnl module exclusively to provide this
- functionality, though there is an experimental alternate
- implementation provided by the tnl_dd/t_dd_imm_* files which can
- handle a small subset of GL states in execute mode only.
-
-
- STATE
-
- To create and destroy the module:
-
- GLboolean _tnl_CreateContext( GLcontext *ctx );
- void _tnl_DestroyContext( GLcontext *ctx );
-
- The module is not active by default, and must be installed by calling
- _tnl_Wakeup(). This function installs internal tnl functions into all
- the vtxfmt dispatch hooks, thus taking over the task of transformation
- and lighting entirely:
-
- void _tnl_wakeup_exec( GLcontext *ctx );
- void _tnl_wakeup_save_exec( GLcontext *ctx );
-
-
- This module tracks state changes internally and maintains derived
- values based on the current state. For this to work, the driver
- ensure the following funciton is called whenever the state changes and
- the swsetup module is 'awake':
-
- void _tnl_InvalidateState( GLcontext *ctx, GLuint new_state );
-
- There is no explicit call to put the tnl module to sleep. Simply
- install other function pointers into all the vtxfmt dispatch slots,
- and (optionally) cease calling _tnl_InvalidateState().
-
- CUSTOMIZATION
-
- The module provides customizability through several mechanisms. The
- most important is by allowing drivers to specify the pipeline through
- which vertex data is passed, including its eventual transfer to
- rasterization hardware (or software).
-
- The default pipeline is specified in t_pipeline.c, and is usually a
- starting point for driver pipelines. Some drivers will remove a stage
- where hardware provides support for the implemented operation (for
- instance fog where per-pixel hardware fog is available, as in the dri
- tdfx driver), or add stages to shortcircuit latter operations (for
- example taking advantage of hardware support for strips and other
- higher-level primitives (for example the radeon driver).
-
- In addition, the following functions provide further tweaks:
-
- extern void
- _tnl_need_projected_coords( GLcontext *ctx, GLboolean flag );
-
- - Direct the default vertex transformation stage to
- produce/not produce projected clip coordinates.
-
- extern void
- _tnl_need_dlist_loopback( GLcontext *ctx, GLboolean flag );
-
- - Direct the display list component of the tnl module to
- replay display lists as 'glVertex' type calls, rather than
- passing the display list data directly into the tnl pipeline
- mechanism.
-
- This allows display lists to be replayed by the tnl module
- even when the module is not strictly active.
-
-
- extern void
- _tnl_need_dlist_norm_lengths( GLcontext *ctx, GLboolean flag );
-
- - Direct the display list component to enable/disable caching
- 1/length values for display list normals. Doing so is
- ususally helpful when lighting is performed in software, but
- wasteful otherwise.
-
-
- DRIVER INTERFACE
-
- The module itself offers a minimal driver interface:
-
- void (*RunPipeline)( GLcontext *ctx );
-
- Normally this is set to _tnl_RunPipeline(), however the driver can use
- this hook to wrap checks or other code around this call.
-
- In addition, the driver interface for the default render pipeline
- stage is housed in the tnl context struct (this could be cleaner).
-
-
- RENDER DRIVER INTERFACE
-
- See t_context.h for the definition and explanation of this.