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

INTRODUCTION

Mesa's native software rasterizer.  This module provides the fallback
paths for rasterization operations and states that aren't accelerated
in hardware drivers, and as the full rasterization engine in software
drivers.

The swrast module 'stands alone', relying only on interfaces to core
mesa and it's own driver interface.  It knows nothing about the tnl or
other modules, allowing it to be used for fallback paths in future tnl
schemes without modification.

As well as providing triangle/line/point rasterization functionality,
the module provides implementations of the pixel operations
(ReadPixels, etc), and texture operations (CopyTexSubImage) which may
be plugged in to the core Mesa driver interface where accelerated
versions of these operations are unavailable.


STATE

To create and destroy the module:

	GLboolean _swrast_CreateContext( struct gl_context *ctx );
	void _swrast_DestroyContext( 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 _swrast_InvalidateState( struct gl_context *ctx, GLuint new_state );

There is no explicit call to put the swrast module to sleep.  


CUSTOMIZATION

   void (*choose_point)( struct gl_context * );
   void (*choose_line)( struct gl_context * );
   void (*choose_triangle)( struct gl_context * );

Drivers may add additional triangle/line/point functions to swrast by
overriding these functions.  It is necessary for the driver to be very
careful that it doesn't return an inappropriate function, eg a
rasterization function in feedback mode.  See the X11 driver for
examples.

DRIVER INTERFACE

The swrast device driver provides swrast primarily with span- and
pixel- level interfaces to a framebuffer, with a few additional hooks
for locking and setting the read buffer.

See the definition of struct swrast_device_driver in swrast.h.