xref: /xsrc/external/mit/MesaLib/dist/src/mesa/swrast_setup/NOTES

INTRODUCTION

A helper module which provides glue to bind the software rasterizer to
the software t&l module.  The main task of this module is to build
swrast vertices from the t&l vertex_buffer structs, and to use them to
perform triangle setup functions not implemented in the software
rasterizer.

The module implements a full set of functions to plug into the
t_vb_render.c driver interface (tnl->Driver.Render.*).  

There are strong advantages to decoupling the software rasterizer from
the t&l module, primarily allowing hardware drivers better control
over fallbacks, the removal of implicit knowledge about the software
rasterizer in the t&l module, allowing the two modules to evolve
independently and allowing either to be substituted with equivalent
functionality from another codebase.

This module implements triangle/quad setup for offset, unfilled and
twoside-lit triangles.  The software rasterizer doesn't handle these
primitives directly.

Hardware rasterization drivers typically use this module in situations
where no hardware rasterization is possible, ie during total
fallbacks. 

STATE

To create and destroy the module:

	GLboolean _swsetup_CreateContext( struct gl_context *ctx );
	void _swsetup_DestroyContext( struct gl_context *ctx );

The module is not active by default, and must be installed by calling
_swrast_Wakeup().  This function installs internal swrast_setup
functions into all the tnl->Driver.Render driver hooks, thus taking
over the task of rasterization entirely:

        void _swrast_Wakeup( struct gl_context *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 _swsetup_InvalidateState( struct gl_context *ctx, GLuint new_state );

There is no explicit call to put the swsetup module to sleep.  Simply
install other function pointers into all the tnl->Driver.Render.*
hooks, and (optionally) cease calling _swsetup_InvalidateState().

DRIVER INTERFACE

The module offers a minimal driver interface:

	 void (*Start)( struct gl_context *ctx );
	 void (*Finish)( struct gl_context *ctx );
	 
These are called before and after the completion of all swrast drawing
activity.  As swrast doesn't call callbacks during triangle, line or
point rasterization, these are necessary to provide locking hooks for
some drivers.  They may otherwise be left null.