From 62eb2e59097da8b0ec312d64363e0a12b55db7b4 Mon Sep 17 00:00:00 2001
From: Keith Whitwell <keith@tungstengraphics.com>
Date: Thu, 20 Sep 2001 19:25:31 +0000
Subject: [PATCH] very brief overview of swrast

---
 src/mesa/swrast/NOTES | 55 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 src/mesa/swrast/NOTES

diff --git a/src/mesa/swrast/NOTES b/src/mesa/swrast/NOTES
new file mode 100644
index 00000000000..f906e41b955
--- /dev/null
+++ b/src/mesa/swrast/NOTES
@@ -0,0 +1,55 @@
+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( GLcontext *ctx );
+	void _swrast_DestroyContext( 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 _swrast_InvalidateState( GLcontext *ctx, GLuint new_state );
+
+There is no explicit call to put the swrast module to sleep.  
+
+
+CUSTOMIZATION
+
+   void (*choose_point)( GLcontext * );
+   void (*choose_line)( GLcontext * );
+   void (*choose_triangle)( GLcontext * );
+
+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.
\ No newline at end of file