head	1.1;
access;
symbols
	libdrm-1_0_4:1.1;
locks; strict;
comment	@# @;


1.1
date	2003.06.25.14.40.08;	author jrfonseca;	state Exp;
branches;
next	;


desc
@@


1.1
log
@Switch the source format to DocBook XML.
@
text
@<?xml version='1.0' encoding='iso-8859-1'?>

<sect1 id="implementation">
	<title>Implementation</title>

	<para>
	This section will try to give information on the implementation details of a DRI driver.
	The issues presented here follow loosely the same order by which information flows when a application is using a DRI driver,
	i.e., it mimics the graphics pipeline.
	</para>

	<sect2>
		<title>The DRI driver initialization process?</title>
		
		<para>
		This is a description of the DRI driver initialization process.
		<footnote>
			<para>
			Extracted and edited from a series of emails between Ian Romanick and Brian Paul
			</para>
		</footnote>
		</para>
		
		<itemizedlist>
			<listitem>
				<para>
				The whole process begins when an application calls <function>glXCreateContext</function>
				(<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/lib/GL/glx/glxcmds.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xc/lib/GL/glx/glxcmds.c</filename>
				</ulink>).
				<function>glXCreateContext</function> is just a stub that call
				<function>CreateContext</function>.  The real work begins when <function>CreateContext</function> calls
				<function>__glXInitialize</function>
				(<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/lib/GL/glx/glxext.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xc/lib/GL/glx/glxext.c</filename>
				</ulink>).
				</para>
			</listitem>
		
			<listitem>
				<para>
				The driver specific initialization process starts with <function>__driCreateScreen</function>.
				Once the driver is loaded (via <function>dlopen</function>), <function>dlsym</function> is used to get a pointer to
				this function.  The function pointer for each driver is stored in the
				<varname>createScreen</varname> array in the <structname>__DRIdisplay</structname> structure.  This initialization is
				done in <function>driCreateDisplay</function>
				(<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/lib/GL/dri/dri_glx.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xc/lib/GL/dri/dri_glx.c</filename>
				</ulink>), which is called by
				<function>__glXInitialize</function>.
				</para>
				
				<para>
				Note that <function>__driCreateScreen</function> really
				is the bootstrap of a DRI driver.  It's the only
				<footnote>
					<para>
					that's not really true- there's also the <function>__driRegisterExtensions</function>
					function that <filename>libGL</filename> uses to implement <function>glXGetProcAddress</function>.  That's another
					long story.
					</para>
				</footnote>
				function in a DRI driver
				that <filename>libGL</filename> directly knows about.  All the other DRI functions are accessed via
				the <structname>__DRIdisplayRec</structname>, <structname>__DRIscreenRec</structname>, 
				<structname>__DRIcontextRec</structname> and <structname>__DRIdrawableRec</structname>
				structs	defined in 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/lib/GL/glx/glxclient.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xc/lib/GL/glx/glxclient.h</filename>
				</ulink>).  Those structures are pretty well documented in the file.
				</para>
			</listitem>
			
			<listitem>
				<para>
				After performing the <function>__glXInitialize</function> step, <function>CreateContext</function> calls the
				<function>createContext</function> function for the requested screen.  Here the driver creates
				two data structures.  The first, <function>GLcontext</function> (extras/Mesa/src/mtypes.h),
				contains all of the device independent state, device dependent constants
				(i.e., texture size limits, light limits, etc.), and device dependent
				function tables.  The driver also allocates a structure that contains all
				of the device dependent state.  The GLcontext structure links to the
				device dependent structure via the DriverCtx pointer.  The device
				dependent structure also has a pointer back to the GLcontext structure.
				</para>
		
				<para>
				The device dependent structure is where the driver will store context
				specific hardware state (register settings, etc.) for when
				context (in terms of OpenGL / X context) switches occur.  This structure is
				analogous to the buffers where the OS stores CPU state where a program
				context switch occurs.
				</para>
		
				<para>
				The texture images really are stored within Mesa's
				data structures.  Mesa supports about a dozen texture formats which
				happen to satisfy what all the DRI drivers need.  So, the texture format/
				packing is dependent on the hardware, but Mesa understands all the
				common formats.  See Mesa/src/texformat.h.  Gareth and Brian spent a lot of
				time on that.
				</para>
			</listitem>
		
			<listitem>
				<para>
				<function>createScreen</function> (i.e., the driver specific initialization function) is called
				for each screen from <function>AllocAndFetchScreenConfigs</function>
				(<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/lib/GL/glx/glxext.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xc/lib/GL/glx/glxext.c</filename>
				</ulink>).
				This is also called from <function>__glXInitialize</function>.
				</para>
			</listitem>
		
			<listitem>
				<para>
				For all of the existing drivers, the <function>__driCreateScreen</function> function is just a
				wrapper that calls <function>__driUtilCreateScreen</function>
				(<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/lib/GL/dri/dri_util.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xc/lib/GL/dri/dri_util.c</filename>
				</ulink>)
				with a
				pointer to the driver's API function table (of type <structname>__DriverAPIRec</structname>).  This
				creates a <structname>__DRIscreenPrivate structure</structname> for the display and fills it in
				(mostly) with the supplied parameters (i.e., screen number, display
				information, etc.).  
				</para>
			
				<para>
				It also opens and initialized the connection to DRM.  This includes
				opening the DRM device, mapping the frame buffer (note: the DRM
				documentation says that the function used for this is called <function>drmAddMap</function>, but
				it is actually called drmMap), and mapping the SAREA.  The final step is
				to call the driver initialization function for the driver (from the
				<structfield>InitDriver</structfield> field in the <structname>__DriverAPIRec</structname> (<structfield>DriverAPI</structfield> field of the
				<structname>__DRIscreenPrivate</structname>).
				</para>
			</listitem>
		
			<listitem>
				<para>
				The <function>InitDriver</function> function does (at least in the Radeon and i810 drivers) two
				broad things.  It first verifies the version of the services (XFree86,
				DDX, and DRM) that it will use.
				</para>
		
				<para>
				The driver then creates an internal representation of the screen and
				stores it (the pointer to the structure) in the private field of the
				<structname>__DRIscreenPrivate</structname> structure.  The driver-private data may include things
				such as mappings of MMIO registers, mappings of display and texture
				memory, information about the layout if video memory, chipset version
				specific data (feature availability for the specific chip revision, etc.),
				and other similar data.  This is the handle that identifies the specific
				graphics card to the driver (in case there is more than one card in the
				system that will use the same driver).
				</para>
			</listitem>
		
			<listitem>
				<para>
				After performing the <function>__glXInitialize</function> step, <function>CreateContext</function> calls the
				<function>createContext</function> function for the requested screen.  This is where it gets
				pretty complicated.  I have only looked at the Radeon driver.
				<function>radeonCreateContext</function>
				(<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/lib/GL/mesa/src/drv/radeon/radeon_context.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xc/lib/GL/mesa/src/drv/radeon/radeon_context.c</filename>
				</ulink>)
				allocates a <structname>GLcontext</structname> structure (actually <userinput>struct __GLcontextRec</userinput> from
				extras/Mesa/src/mtypes.h).  Here it fills in function tables for virtually
				every OpenGL call.  Additionally, the <structname>__GLcontextRec</structname> has pointers to
				buffers where the driver will store context specific hardware state
				(textures, register settings, etc.) for when context (in terms of
				OpenGL / X context) switches occur. 
				</para>
		
				<para>
				The <structname>__GLcontextRec</structname> (i.e. <structname>GLcontext</structname> in Mesa) doesn't have any buffers
				of hardware-specific data (except texture image data if you want to be
				picky).  All Radeon-specific, per-context data should be hanging off
				of the struct radeon_context.
				</para>
				
				<para>
				All the DRI drivers define a hardware-specific context structure
				(such as structure radeon_context, typedef'd to be radeonContextRec, or
				structure mga_context_t typedef'd to be mgaContext).
				</para>
				
				<para>
				<structname>radeonContextRec</structname> has a pointer back to the Mesa <structname>__GLcontextRec</structname>
				and Mesa's <userinput>__GLcontextRec->DriverCtx</userinput> pointer points back to the
				<structname>radeonContextRec</structname>.
				</para>
				
				<para>
				If we were writing all this in C++ (don't laugh) we'd treat Mesa's
				<structname>__GLcontextRec</structname> as a base class and create driver-specific derived
				classes from it.
				Inheritance like this is actually pretty common in the DRI code,
				even though it's sometimes hard to spot.
				</para>
				
				<para>
				These buffers are analogous to the
				buffers where the OS stores CPU state where a program context switch occurs.
				</para>
		
				<para>
				Note that we don't do any fancy hardware context switching in our drivers.
				When we make-current a new context, we basically update all the hardware
				state with that new context's values.
				</para>
			</listitem>

			<listitem>
				<para>
				When each of the function tables is initialized (see radeonInitSpanFuncs
				for an example), an internal Mesa function is called.  This function
				(e.g., <function>_swrast_GetDeviceDriverReference</function>) both allocates the buffer and
				fills in the function pointers with the software fallbacks.  If a driver
				were to just call these allocation functions and not replace any of the
				function pointers, it would be the same as the software renderer.
				</para>
			</listitem>
		
			<listitem>
				<para>
				The next part seems to start when the createDrawable function in the
				<structname>__DRIscreenRec</structname> is called, but I don't see where this happens.
				</para>
		
				<para>
				<function>createDrawable</function> should be called via <function>glXMakeCurrent</function> since that's the
				first time we're given an X drawable handle.  Somewhere during <function>glXMakeCurrent</function> 
				we use a DRI hash lookup to translate the X Drawable handle
				into an pointer to a <structname>__DRIdrawable</structname>.  If we get a <envar>NULL</envar> pointer that means
				we've never seen that handle before and now have to allocate the
				<structname>__DRIdrawable</structname> and initialize it (and put it in the hash table).
				</para>
			</listitem>
		</itemizedlist>
	</sect2>
		
	<sect2 id="mesa-internals">
		<title>Mesa internals</title>
	
		<sect3>
			<title>How does one writes a new Mesa driver?</title>
		
			<para>
			There are two basic aspects to writing a new driver.
			</para>
		
			<para>
			First, define the public OpenGL / window system API.  In the case of GLX,
			these are the <function>glx*()</function> functions.  For OSMesa these are the <function>OSMesa*()</function> functions seen in <filename>include/GL/osmesa.h</filename>.  You'll basically need functions for specifying
			frame buffer formats (bits per rgb, bits for Z, bits for stencil, etc.),
			functions for creating/destroying contexts, binding contexts to windows. etc.
			</para>
		
			<para>
			Second, implement the internal functions needed by the "DD" interface.
			Look at the <filename>osmesa.c</filename> file and grep for <quote>ctx->Driver. = </quote>.  This
			is where the driver hooks itselft into the core of Mesa.  In many cases
			we hook in fall-back functions (like <function>_swrast_DrawPixels</function>).
			</para>
		
			<para>
			This isn't simple (or even as straight-forward as is used to be) but the system's designed for efficiently, flexibility and modularity.
			If the device driver interface were made for simplicity above all else
			there would probably only be two driver functions: <function>ReadPixel()</function> and
			<function>WritePixel()</function>.
			</para>
		
			<para>
			The OSMesa driver is pretty simple.  The only complexity comes from supporting
			all the different frame buffer formats like RGB, RGBA, BGRA, ABGR, etc.
			I think the Windows driver is in pretty good shape too.  The XMesa driver
			(upon which Mesa's GLX is layered) is rather large because of lots of
			frame buffer formats and optimized point/line/triangle rendering functions.
			</para>
		</sect3>

		<sect3 id="mesa-3.4.x-internals">
			<title>Old Mesa 3.4.x Implementation Notes</title>
			
			<para>
			This document is an overview of the internal structure of Mesa and is meant for those who are interested in modifying or enhancing Mesa, or just curious.
			</para>
			
			<note>
				<para>
				Based on the original <ulink url="http://www.mesa3d.org/docs/Implementation.html">Mesa Implementation Notes</ulink> by Brian Paul.
				</para>
			</note>
			
			<sect4>
				<title>Library State and Contexts</title>
				
				<para>
				OpenGL uses the notion of a state machine. 
				Mesa encapsulates the state in one large structure: <structname>gl_context</structname>, as seen in 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/types.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>types.h</filename>
				</ulink>
				</para>
				
				<para> 
				The <structname>gl_context</structname> structure actually contains a number of sub structures which exactly correspond to OpenGL's attribute groups. 
				This organization made <function>glPushAttrib</function> and <function>glPopAttrib</function> trivial to implement and proved to be a good way of organizing the state variables.
				</para>
			</sect4>
			
			<sect4>
				<title>Vertex buffer</title>
				
				<para>
				The vertices between <function>glBegin</function> and <function>glEnd</function> are accumulated in the
				vertex buffer (see 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/vb.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>vb.h</filename>
				</ulink>
				and
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/vb.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>vb.c</filename>
				</ulink>
				).  
				When either the vertex buffer becomes filled or a state change outside the 
				<function>glBegin</function>/<function>glEnd</function> is made, we must flush
				the buffer.
				That is, we apply the vertex transformations, compute lighting,
				fog, texture coordinates etc.  
				Then, we can render the vertices as
				points, lines or polygons by calling the <function>gl_render_vb()</function> function in
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/render.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>render.c</filename>
				</ulink>.
				</para>
		
				<para>
				When we're outside of a <function>glBegin</function>/<function>glEnd</function> pair the information in this
				structure is retained pending either of the flushing events
				described above.  
				</para>
				
				<note>
					<para>
					Originally, Mesa didn't accumulate vertices in this way. 
					Instead, <function>glVertex</function> transformed and lit then buffered each vertex as it was received. 
					When enough vertices to draw the primitive (1 for points, 2 for lines, &gt;2 for polygons) were accumulated the primitive was drawn and the buffer cleared.
					</para>
				
					<para>
					The new approach of buffering many vertices and then transforming, lighting and clip testing is faster because it's done in a <quote>vectorized</quote> manner. 
					See <function>gl_transform_points</function> in 
					<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/xform.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
						<filename>xform.c</filename>
					</ulink> 
					for an example. 
					Also, vertices shared between primitives (i.e. <varname>GL_LINE_STRIP</varname>) are only transformed once.
					</para>
				</note>
				
				<para>
				The only complication is clipping. 
				If no vertices in the vertex buffer have their clip flag set, the rasterization functions can be applied directly to the vertex buffer. 
				Otherwise, a clipping function is called before rasterizing each primitive. 
				If clipping introduces new vertices they will be stored at the end of the vertex buffer.
				</para>
				
				<para>
				For best performance Mesa clients should try to maximize the number of vertices between <function>glBegin</function>/<function>glEnd</function> pairs and used connected primitives when possible.
				</para>
			</sect4>
			
			<sect4>
				<title>Rasterization</title>
				
				<para>
				The point, line and polygon rasterizers are called via the <structfield>PointsFunc</structfield>, <structfield>LineFunc</structfield>, and <structfield>TriangleFunc</structfield> function pointers in the <structname>dd_function_table</structname> driver function pointer table. 
				Whenever the library state is changed in a significant way, the <structfield>NewState</structfield> context flag is raised. 
				When <function>glBegin</function> is called <structfield>NewState</structfield> is checked. If the flag is set we re-evaluate the state to determine what rasterizers to use. 
				Special purpose rasterizers are selected according to the status of certain state variables such as flat vs smooth shading, depth-buffered vs. non-depth- buffered, etc. 
				The <function>gl_set_point|line|polygon_function</function> functions do this analysis. 
				They in turn query the device driver for <quote>accelerated</quote> rasterizers. 
				More on that later.
				</para>
			
				<para>
				In general, typical states (depth-buffered &amp; smooth-shading) result in optimized rasterizers being selected. 
				Non-typical states (stenciling, blending, stippling) result in slower, general purpose rasterizers being selected.
				</para>
			</sect4>
			
			<sect4>
				<title>Pixel (fragment) buffer</title>
			
				<para>
				The general purpose point, line and bitmap rasterizers accumulate fragments (pixels plus color, depth, texture coordinates) in the PB (Pixel Buffer) structure seen in . 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/pb.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>pb.h</filename>
				</ulink>
				and
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/pb.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>pb.c</filename>
				</ulink>.
				When the pixel buffer is full or <function>glEnd</function> is called the pixel buffer is flushed. 
				This includes clipping the fragments against the window, depth testing, stenciling, blending, stippling, etc. 
				Finally, the pixel buffer's pixels are drawn to the display buffer by calling one of device driver functions.
				The goal is to maximize the number of pixels processed inside loops and to minimize
				the number of function calls.
				</para>
			</sect4>
			
			<sect4>
				<title>Pixel spans</title>
				
				<para>
				The polygon, <function>glDrawPixels</function>, and <function>glCopyPixels</function> functions generate horizontal runs of pixels called spans. 
				Spans are processed in 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/span.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>span.c</filename>
				</ulink>. 
				Processing includes window clipping, depth testing, stenciling, texturing, etc. 
				After processing the span is written to the frame buffer by calling a device driver function.
				</para>
			</sect4>
			
			<sect4>
				<title>Device Driver</title>
				
				<para>
				There are three Mesa data types which are meant to be used by device
				drivers:
				</para>
				
				<glosslist>
					<glossentry>
						<glossterm>GLcontext</glossterm>
						
						<glossdef>
							<para>
							this contains the Mesa rendering state
							</para>
						</glossdef>
					</glossentry>
						
					<glossentry>
						<glossterm>GLvisual</glossterm>
						
						<glossdef>
							<para>
							this describes the color buffer (rgb vs. ci), whether
							or not there's a depth buffer, stencil buffer, etc.
							</para>
						</glossdef>
					</glossentry>
		
					<glossentry>
						<glossterm>GLframebuffer</glossterm>
						
						<glossdef>
							<para>
							contains pointers to the depth buffer, stencil
							buffer, accum buffer and alpha buffers.
							</para>
						</glossdef>
					</glossentry>
				</glosslist>
				
				<para>
				These types should be encapsulated by corresponding device driver
				data types.  See 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/xmesa.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xmesa.h</filename>
				</ulink> and
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/xmesaP.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xmesaP.h</filename>
				</ulink> for an example.
				</para>
				
				<para>
				In OOP terms, <structname>GLcontext</structname>, <structname>GLvisual</structname>, and <structname>GLframebuffer</structname> are base classes
				which the device driver must derive from.
				</para>
				 
				<para>
				The structure <structname>dd_function_table</structname> seen in 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/dd.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>dd.h</filename>
				</ulink>, 
				defines the device driver functions. 
				By using a table of pointers, the device driver can be changed dynamically at runtime. 
				For example, the X/Mesa and OS/Mesa (Off-Screen rendering) device drivers can co-exist in one library and be selected at runtime. 
				</para>
				
				<para>
				In addition to the device driver table functions, each Mesa driver has its own set of unique interface functions. 
				For example, the X/Mesa driver has the <function>XMesaCreateContext</function>, <function>XMesaBindWindow</function>, and <function>XMesaSwapBuffers</function> 
				functions while the Windows/Mesa interface has <function>WMesaCreateContext</function>, <function>WMesaPaletteChange</function> and <function>WMesaSwapBuffers</function>. 
				New Mesa drivers need to both implement the <structname>dd_function_table</structname> functions and define a set of unique window system or operating system-specific interface functions.
				</para>
				
				<para>
				The device driver functions can roughly be divided into four groups:
				</para>
				
				<orderedlist>
					<listitem>
						<para>
						pixel span functions which read or write horizontal runs of RGB or color-index pixels. 
						Each function takes an array of mask flags which indicate whether or not to plot each pixel in the span.
						</para>
					</listitem>
				
					<listitem>
						<para>
						pixel array functions which are very similar to the pixel span functions except that they're used to read or write arrays of pixels at random locations rather than horizontal runs.
						</para>
					</listitem>
					
					<listitem>
						<para>
						miscellaneous functions for window clearing, setting the current drawing color, enabling/disabling dithering, returning the current frame buffer size, specifying the window clear color, synchronization, etc. 
						Most of these functions directly correspond to higher level OpenGL functions.
						</para>
					</listitem>
					
					<listitem>
						<para>
						if your graphics hardware or operating system provides accelerated point, line and polygon rendering operations, they can be utilized through the <structfield>PointsFunc</structfield>, <structfield>LineFunc</structfield>, and <structfield>TriangleFunc</structfield> functions. 
						Mesa will call these functions to <quote>ask</quote> the device driver for accelerated functions through the <function>UpdateState</function>. 
						If the device driver can provide an appropriate renderer, given the current Mesa state, then a pointer to that function can be returned. 
						Otherwise the <structfield>PointsFunc</structfield>, <structfield>LineFunc</structfield>, and <structfield>TriangleFunc</structfield> functions pointers can just be set to NULL.
						</para>
					</listitem>
				</orderedlist>
					
				<para>
				Even if hardware accelerated renderers aren't available, the device driver may implement tuned, special purpose code for common kinds of points, lines or polygons. 
				The X/Mesa device driver does this for a number of lines and polygons. 
				See the 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/xmesa3.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xmesa3.c</filename>
				</ulink> file.
				</para>
			</sect4>
				
			<sect4>
				<title>Overall Organization</title>
				
				<para>
				The overall relation of the core Mesa library, X device driver/interface, toolkits and application programs is shown in this diagram:
				</para>

<programlisting>
+-----------------------------------------------------------+
|                                                           |
|                   Application Programs                    |
|                                                           |
|          +- glu.h -+------ glut.h -------+                |
|          |         |                     |                |
|          |   GLU   |        GLUT         |                |
|          |         |      toolkits       |                |
|          |         |                     |                |
+---------- gl.h ------------+-------- glx.h ----+          |
|                            |                   |          |
|         Mesa core          |   GLX functions   |          |
|                            |                   |          |
+---------- dd.h ------------+------------- xmesa.h --------+
|                                                           |
|              XMesa* and device driver functions           |
|                                                           |
+-----------------------------------------------------------+
|                 Hardware/OS/Window System                 |
+-----------------------------------------------------------+
</programlisting>
		
			</sect4>
		</sect3>

		<sect3 id="mesa-4.x-internals">
			<title>
				Mesa 4.x
				<footnote>
					<para>
					The big changes in Mesa were made between
					Mesa 3.4.x and Mesa 3.5.  That's when Keith re-modularized the source
					code into separate modules for T&amp;L, s/w rasterization, etc.
					</para>
				</footnote>
				Implementation Notes
			</title>
			
			<para>
			This document is an overview of the internal structure of Mesa and is meant for those who are interested in modifying or enhancing Mesa, or just curious.
			</para>
			
			<note>
				<para>
				Based on the original <ulink url="http://www.mesa3d.org/docs/Implementation.html">Mesa Implementation Notes</ulink> and corrections by Brian Paul.
				</para>
			</note>
			
			<sect4>
				<title>Library State and Contexts</title>
				
				<para>
				OpenGL uses the notion of a state machine. 
				Almost all OpenGL state is contained in
				one large structure: <structname>__GLcontextRec</structname> (typedef'd to <structname>GLcontext</structname>), as seen in 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/mtypes.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>mtypes.h</filename>
				</ulink>. This is the central context data structure for Mesa.  
				</para>
				
				<para> 
				The <structname>__GLcontextRec</structname> structure actually contains a number of sub structures which exactly correspond to OpenGL's attribute groups. 
				This organization made <function>glPushAttrib</function> and <function>glPopAttrib</function> trivial to implement and proved to be a good way of organizing the state variables.
				</para>
			</sect4>
			
			<sect4>
				<title>Vertex buffer</title>
				
				<para>
				The <structname>immediate</structname> represents everything that can take 
				place between <function>glBegin</function> and <function>glEnd</function> 
				being able to represent multiple <function>glBegin</function>/<function>glEnd</function> pairs. 
				It can be used to losslessly encode this information in display lists.
				See 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/tnl/t_context.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>t_context.h</filename>
				</ulink>
				and
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/tnl/t_imm_api.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>t_imm_api.c</filename>
				</ulink>.  
				</para>
				
				<para>
				
				When either the vertex buffer becomes filled or a state change outside the 
				<function>glBegin</function>/<function>glEnd</function> is made, we must flush
				the buffer.
				That is, we apply the vertex transformations, compute lighting,
				fog, texture coordinates etc.
				The various vertex transformations are implemented as software pipeline 
				stages by the 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/tnl/t_pipeline.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>tnl/t_pipeline.c</filename>
				</ulink>
				and <filename>tnl/t_vb_*.c</filename> files.
				</para>
		
				<para>
				When we're outside of a <function>glBegin</function>/<function>glEnd</function> pair the information in this
				structure is retained pending either of the flushing events
				described above.  
				</para>
				
				<note>
					<para>
					Originally, Mesa didn't accumulate vertices in this way. 
					Instead, <function>glVertex</function> transformed and lit then buffered each vertex as it was received. 
					When enough vertices to draw the primitive (1 for points, 2 for lines, &gt;2 for polygons) were accumulated the primitive was drawn and the buffer cleared.
					</para>
				
					<para>
					The new approach of buffering many vertices and then transforming, lighting and clip testing is faster because it's done in a <quote>vectorized</quote> manner. 
					See <function>gl_transform_points</function> in 
					<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/math/m_xform.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
						<filename>math/m_xform.c</filename>
					</ulink> 
					for an example. 
					</para>
				</note>
				
				<para>
				For best performance Mesa clients should try to maximize the number of vertices between <function>glBegin</function>/<function>glEnd</function> pairs and used connected primitives when possible.
				</para>
			</sect4>
			
			<sect4>
				<title>Rasterization</title>
				
				<para>
				The point, line and polygon rasterizers are called via the <structfield>Point</structfield>, 
				<structfield>Line</structfield>, and <structfield>Triangle</structfield> function pointers in 
				the <structname>SWcontext</structname> structure in
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/swrast/s_context.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
						<filename>swrast/s_context.h</filename>
				</ulink>.
				Whenever the library state is changed in a significant way, the <structfield>NewState</structfield> context flag is raised. 
				When <function>glBegin</function> is called <structfield>NewState</structfield> is checked. If the flag is set we re-evaluate the state to determine what rasterizers to use. 
				
				Special purpose rasterizers are selected according to the status of certain state variables such as flat vs smooth shading, depth-buffered vs. non-depth- buffered, etc. 
				The <function>_swrast_choose_*</function> functions do this analysis.
				
				It's up to the device driver to choose optimized
				or accelerated rasterization functions to replace those in the general
				software rasterizer.
				</para>
			
				<para>
				In general, typical states (depth-buffered &amp; smooth-shading) result in optimized rasterizers being selected. 
				Non-typical states (stenciling, blending, stippling) result in slower, general purpose rasterizers being selected.
				</para>
			</sect4>
			
			<sect4>
				<title>Pixel spans</title>
				
				<para>
				<function>Point</function>, <function>Line</function>, <function>Triangle</function>, <function>glDrawPixel</function>, <function>glCopyPixels</function> and <function>glBitmap</function>
				all use the <structname>sw_span</structname> structure and functions 
				 in 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/swrast/s_span.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>swrast/s_span.c</filename>
				</ulink> generate horizontal runs of pixels called spans. 
				Processing includes window clipping, depth testing, stenciling, texturing, etc. 
				After processing the span is written to the frame buffer by calling a device driver function.
				The goal is to maximize the number of pixel processed inside loops and to minimize
				the number of function calls.
				</para>
				
				<note>
					<para>
					Pixel buffers are no longer present in the latest Mesa code (4.1).
					
					All fragment (pixels plus color, depth, texture coordinates) processing is done via the span functions in <filename>swrast/s_span.c</filename>.
					</para>
				</note>
				
			</sect4>
			
			<sect4>
				<title>Device Driver</title>
				
				<para>
				There are three Mesa data types which are meant to be used by device
				drivers:
				</para>
				
				<glosslist>
					<glossentry>
						<glossterm>GLcontext</glossterm>
						
						<glossdef>
							<para>
							this contains the Mesa rendering state
							</para>
						</glossdef>
					</glossentry>
						
					<glossentry>
						<glossterm>GLvisual</glossterm>
						
						<glossdef>
							<para>
							this describes the color buffer (rgb vs. ci), whether
							or not there's a depth buffer, stencil buffer, etc.
							</para>
						</glossdef>
					</glossentry>
		
					<glossentry>
						<glossterm>GLframebuffer</glossterm>
						
						<glossdef>
							<para>
							contains pointers to the depth buffer, stencil
							buffer, accum buffer and alpha buffers.
							</para>
						</glossdef>
					</glossentry>
				</glosslist>
				
				<para>
				These types should be encapsulated by corresponding device driver
				data types.  See 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/xmesa.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xmesa.h</filename>
				</ulink> and
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/extras/Mesa/src/xmesaP.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>xmesaP.h</filename>
				</ulink> for an example.
				</para>
				
				<para>
				In OOP terms, <structname>GLcontext</structname>, <structname>GLvisual</structname>, and <structname>GLframebuffer</structname> are base classes
				which the device driver must derive from.
				</para>
				 
				<para>
				The structure <structname>dd_function_table</structname> seen in 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/dd.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>dd.h</filename>
				</ulink>, 
				defines the device driver functions
				<footnote>
					<para>
					Many of the functions which used to be in the dd_function_table are
					now moved into the tnl or swrast modules.
					</para>
				</footnote>. 
				By using a table of pointers, the device driver can be changed dynamically at runtime. 
				For example, the X/Mesa and OS/Mesa (Off-Screen rendering) device drivers can co-exist in one library and be selected at runtime. 
				</para>
				
				<para>
				In addition to the device driver table functions, each Mesa driver has its own set of unique interface functions. 
				For example, the X/Mesa driver has the <function>XMesaCreateContext</function>, <function>XMesaBindWindow</function>, and <function>XMesaSwapBuffers</function> 
				functions while the Windows/Mesa interface has <function>WMesaCreateContext</function>, <function>WMesaPaletteChange</function> and <function>WMesaSwapBuffers</function>. 
				New Mesa drivers need to both implement the <structname>dd_function_table</structname> functions and define a set of unique window system or operating system-specific interface functions.
				</para>
				
				<para>
				The device driver functions can roughly be divided into four groups:
				</para>
				
				<orderedlist>
					<listitem>
						<para>
						pixel span functions which read or write horizontal runs of RGB or color-index pixels. 
						Each function takes an array of mask flags which indicate whether or not to plot each pixel in the span.
						</para>
					</listitem>
				
					<listitem>
						<para>
						miscellaneous functions for window clearing, setting the current drawing color, enabling/disabling dithering, returning the current frame buffer size, specifying the window clear color, synchronization, etc. 
						Most of these functions directly correspond to higher level OpenGL functions.
						</para>
					</listitem>
					
					<listitem>
						<para>
						if your graphics hardware or operating system provides accelerated point, line and polygon rendering operations, they can be utilized through the <structfield>PointsFunc</structfield>, <structfield>LineFunc</structfield>, and <structfield>TriangleFunc</structfield> functions. 
						Mesa will call these functions to <quote>ask</quote> the device driver for accelerated functions through the <function>UpdateState</function>. 
						If the device driver can provide an appropriate renderer, given the current Mesa state, then a pointer to that function can be returned. 
						Otherwise the <structfield>PointsFunc</structfield>, <structfield>LineFunc</structfield>, and <structfield>TriangleFunc</structfield> functions pointers can just be set to NULL.
						</para>
					</listitem>
				</orderedlist>
					
				<para>
				Even if hardware accelerated renderers aren't available, the device driver may implement tuned, special purpose code for common kinds of points, lines or polygons. 
				The X/Mesa device driver does this for a number of lines and polygons. 
				See the 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/X/xm_line.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>X/xm_line.c</filename>
				</ulink> and 
				<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/mesa3d/Mesa/src/X/xm_tri.c?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
					<filename>X/xm_tri.c</filename>
				</ulink> and files.
				</para>
			</sect4>
				
			<sect4>
				<title>Overall Organization</title>
				
				<para>
				The overall relation of the core Mesa library, X device driver/interface, toolkits and application programs is shown in this diagram:
				</para>

<programlisting>
+-----------------------------------------------------------+
|                                                           |
|                   Application Programs                    |
|                                                           |
|          +- glu.h -+------ glut.h -------+                |
|          |         |                     |                |
|          |   GLU   |        GLUT         |                |
|          |         |      toolkits       |                |
|          |         |                     |                |
+---------- gl.h ------------+-------- glx.h ----+          |
|                            |                   |          |
|         Mesa core          |   GLX functions   |          |
|                            |                   |          |
+---------- dd.h ------------+------------- xmesa.h --------+
|                                                           |
|              XMesa* and device driver functions           |
|                                                           |
+-----------------------------------------------------------+
|                 Hardware/OS/Window System                 |
+-----------------------------------------------------------+
</programlisting>
		
			</sect4>
		</sect3>

		<sect3>
			<title>Mesa's pipeline</title>
			
			<para>
			The work starts on <filename>t_pipeline.c</filename> were a driver configurable pipeline is run in response to either
			the vertex buffer filling up, or a statechange.
			</para>
			
			<para>
			 The pipeline stages operate on context variables (suchs 
			as vertices coord, colors, normals, textures coords, etc), applying the 
			necessary operations in a OpenGL pipeline (such as coord transformation, 
			lighting, etc.).
			</para>
			
			<para>
			The last stage - rendering -, calls <function>*BuildVertices</function> in <filename>*_vb.c</filename> which applies the 
			viewport transformation, perpective divide, data type convertion and packs the 
			vertex data in the context (in the arrays <structfield>tnl->vb->*Ptr->data</structfield>) into a driver 
			dependent buffer with just the information relevent for the current OpenGL 
			state (e.g., with/without texture, fog, etc). The template <filename>t_dd_vbtmp.h</filename>  does 
			this into a D3D alike vertex structure format.
			</para>
			
			<para>
			For instance, if we needed to premultiply the textures coordinates, as it is 
			done in the tdfx and mach64 driver, we will need to make a costumized version of 
			<filename>t_dd_vbtmp.h</filename> for that effect, or change it and supply a configuration 
			parameter to control that behavior.
			</para>
			
			<para>
			This buffer is then used to render the primitives in <filename>*_tris.c</filename>. This vertex data 
			is intended to be copied almost verbatim into DMA buffers, with a header 
			command, in most chips with DMA.
			</para>
			
			<para>
			But in the case of Mach64, were the commands are interleaved with each of the 
			vertex data elements, it will be necessary to use a different structure of 
			*Vertex to do the same, and probably to come up with a rather different 
			implementation of t_dd_vbtmp.h as well.
			</para>
			
			<para>
			Indeed, if the chip expects something quite different to the d3d vertices, one
			will certainly want to look at this.  In the meantime, it may be simplest to
			go with a <quote>normal-looking</quote> <filename>*_vb.c</filename> and do some extra stuff in the
			triangle/line/point functions.  The ffb and glint drivers are a bit like this,
			I think.
			</para>
			
			<para>
			All this mechanism is controlled with function pointers in the context which 
			are rechosen whenever the OpenGL state changes enough. These functions 
			pointers can also be overwritten with those in the <filename>sw_*</filename> modules to fallback to 
			software rendering.
			</para>
		</sect3>
	</sect2>

	<sect2>
		<title>
		How about the main X drawing surface?  Are 2 extra "window
		sized" buffers allocated for primary and secondary buffers in a
		page-flipping configuration?
		</title>
		
		<para>
		Right now, we don't do page flipping at all. Everything is a blit from
		back to front. The biggest problem with page flipping is detecting when
		you're in full screen mode, since OpenGL doesn't really have a concept
		of full screen mode. We want a solution that works for existing
		games. So we've been designing a solution for it. It should get
		implemented fairly soon since we need it for antialiasing on the V5.
		</para>
		
		<para>
		In the current implementation the X front buffer is the 3D front
		buffer. When we do page flipping we'll continue to do the same
		thing. Since you have an X window that covers the screen it is safe for
		us to use the X surface's memory. Then we'll do page flipping. The only
		issue will be falling back to blitting if the window is ever moved from
		covering the whole screen.
		</para>
	</sect2>

	<sect2>
		<title>Clipping</title>

		<para>
		This section gives some notions about the several concepts associated to clipping.
		<footnote>
			<para>
			Contributed by Leif Delgass.
			</para>
		</footnote>
		</para>

		<sect3>
			<title>Scissors</title>
		
			<para>
			The scissors are register settings that determine a hardware clipping rect 
			in window coords.  Any part of a primitive or other drawing operation that 
			extends beyond the scissors is not drawn.  The scissors can be set through 
			GL commands.  This has nothing to do with perspective clipping in the 
			pipeline, just the final window coordinates.
			</para>
		</sect3>
		
		<sect3>
			<title>Cliprects</title>
		
			<para>
			Cliprects are used to determine what parts of the context/window should be 
			redrawn to handle overlapping windows.  The more overlapping windows, the 
			more cliprects you have.  These need to be passed to the drm.  It does a 
			clear or swap for each cliprect.  Again these are for 2D clipping after 
			rasterization and not part of the pipeline.  Things get a bit complicated 
			by the fact that there can be separate clip rects for the front and back 
			buffers.
			</para>
			
			<para>
			The cliprects are stored in device-independent structures, hence the code is
			abstracted out of the individual drivers.
			</para>
		</sect3>
		
		<sect3>
			<title>Viewport</title> 
			 
			<para>
			The viewport array holds values to determine how to translate transformed,
			clipped, and projected vertex coordinates into window coordinates.  This
			is the last stage of the pipeline.  The values are based on the size and
			position of the <quote>drawable</quote>, also known as the drawing area of the window for the
			context.
			</para>
		</sect3>
	</sect2>

	<sect2>
		<title>Texture management</title>
		
		<para>
		What follows is a description <footnote><para>made by Ian Romanick</para></footnote> of the texture management system in the
		DRI.  This is all based on the Radeon driver in the 11-Feb-2002 CVS of the
		mesa-4-0-branch.  While it is based on the Radeon code, all drivers except
		gamma and tdfx seem to use the same scheme (and virtually identical code).
		</para>
		
		<note>
		<para>
		Just FYI: the tdfx texture memory management code is different because:
		</para>
		
		<orderedlist>
		<listitem>
		<para>
		It was originally developed before the scheme Keith implemented
		for the i810 and mga drivers (and later used for the R128 and radeon).
		</para>
		</listitem>
		
		<listitem>
		<para>
		There are some idiosynchracies with the Voodoo3 such as two separate
		banks of TRAM and needing to store alternate mipmap levels in alternate
		banks.
		</para>
		</listitem>
		
		<listitem>
		<para>
		We did everything through the Glide interface, rather than working
		directly with the hardware.
		</para>
		</listitem>
		</orderedlist>
		</note>
		
		<itemizedlist>
		<listitem>
		<para>
		Excluding the texture backing store, which is managed by Mesa, texture
		data is tracked in two places.  The per-screen (card) SAREA divides each
		type of texturable memory (on-card, AGP, etc.) into an array of fixed
		sized chunks (<structfield>RADEONSAREAPriv.texList</structfield> in
		<filename>programs/Xserver/hw/xfree86/drivers/ati/radeon_sarea.h</filename>).  The number of
		these chunks is a compile-time constant, and it cannot be changed without
		destroying the universe.  That is, any changes here will present major
		compatability issues.  Currently, this constant is 64.  So, for the new
		128MB Radeon 8500 cards, each block of memory will likely be 1MB or more.
		This is not as bad as it may first seem, see below.  The usage of each
		type of memory is also tracked per-context. 
		</para>
		</listitem>
		
		<listitem>
		<para>
		The per-context memory tracking is done using a <structname>memHeap_t</structname>.  Allocations
		from the <structname>memHeap_t</structname> (see lib/GL/mesa/src/drv/common/mm.c) are done at byte
		granularity.  When a context needs a block of texture memory, it is
		allocated from the <structname>memHeap_t</structname>.  This results in very little memory
		fragmentation (within a context).  After the allocation is made, the map
		of allocated memory in the SAREA is updated (<function>radeonUpdateTexLRU</function> in
		<filename>lib/GL/mesa/src/drv/radeon/radeon_texmem.c</filename>).  Basically, each block of
		memory in texList that corresponds to an allocated region (in the
		per-context <structname>memHeap_t</structname>) is marked as allocated.
		</para>
		</listitem>
		
		<listitem>
		<para>
		The <structname>texList</structname> isn't just an array of blocks.  It's also a priority queue
		(linked list).  As each texture is accessed, the blocks that it occupies
		are moved to the head of the queue.  In the Radeon code, each time a
		texture is uploaded or bound to a texture unit, the blocks of memory (in
		AGP space or on-card) are moved to the head of the texList queue.
		</para>
		</listitem>
		
		<listitem>
		<para>
		If an allocation (via the <structname>memHeap_t</structname>) fails when texture space is allocated
		(<function>radeonUploadTexImages</function> in <filename>lib/GL/mesa/src/drv/radeon/radeon_texmem.c</filename>),
		blocks at the end of the <structname>texList</structname> queue are freed until the allocation can
		succeed.
		</para>
		
		<note>
		<para>
		This may be an area where the algorithm could be improved.  For
		example, it might be better to find the largest free block (in the
		<structname>memHeap_t</structname>) and release memory around that block in LRU or least-often-used
		fashion until the allocation can succeed.  This may be too difficult to get
		right or too slow when done right.  Someone would have to try it and see.
		</para>
		</note>
		</listitem>
		
		<listitem>
		<para>
		Each time a direct-client detects that another client has held the
		per-screen lock, <function>radeonGetLock</function> is called.  This synchronizes the
		per-context vision of the hardware state.  Part of this synchronization is
		synchronizing the view of texture memory.  In addition to the <structname>texList</structname>, the
		SAREA holds a <structname>texAge</structname> array.  This array stores the generation number of
		each of the texture heaps.  If a client detects that the generation number
		of a heap has changed in <function>radeonGetLock</function>, it calls <function>radeonAgeTextures</function> for
		that heap.  <function>radeonAgeTextures</function> runs through the texList looking for blocks
		with a more recent generation number.  Each block that has a newer
		generation is passed to <function>radeonTexturesGone</function>.
		</para>
		</listitem>
		
		<listitem>
		<para>
		<function>radeonTexturesGone</function> searches the per-context <structname>memHeap_t</structname> for an allocated
		region matching the block with the updated generation.  When a matching
		region is found, it is freed, and if the region was for a texture in the
		local context, the local state of that texture is updated.  If the updated
		block (from the global context) is <quote>in-use</quote> (i.e., some other context has
		stolen that block from the current context), the block is re-allocated and
		marked as in-use by another context.
		</para>
		</listitem>
		
		<listitem>
		<para>
		It seems that about 2 years ago a few people (from the CVS log) had taken
		a stab at factoring the common code out and put it in
		<filename>shared_texture_lru.[ch]</filename> in <filename>lib/GL/mesa/src/drv/common</filename> but it isn't used and hasn't been touched
		(at least not in CVS) since 4-April-2000.
		</para>
		</listitem>
		</itemizedlist>
	</sect2>

	<sect2>
		<title>How often are checks done to see if things need clipped/redrawn/redisplayed?</title>
		
		<para>
		The locking system is designed to be highly efficient. It is based on a
		two tiered lock. Basically it works like this:
		</para>
		
		<para>
		The client wants the lock. The use the CAS (I was corrected that the
		instruction is compare and swap, I knew that was the functionality, but
		I got the name wrong) If the client was the last application to hold the
		lock, you're done you move on.
		</para>
		
		<para>
		If it wasn't the last one, then we use an IOCTL to the kernel to
		arbitrate the lock.
		</para>
		
		<para>
			In this case some or all of the state on the card may have
		changed. The shared memory carries a stamp number for the X server. When
		the X server does a window operation it increments the stamp. If the
		client sees that the stamp has changed, it uses a DRI X protocol request
		to get new window location and clip rects. This only happens on a window
		move. Assuming your clip rects/window position hasn't changed, the
		redisplay happens entirely in the client.
		</para>
		
		<para>
			The client may have other state to restore as well. In the case of
		the tdfx driver we have three more flags for command fifo invalid, 3D
		state invalid, textures invalid. If those are set the corresponding
		state is restored.
		</para>
		
		<para>
		So, if the X server wakes up to process input, it current grabs the lock
		but doesn't invalidate any state. I'm actually fixing this now so that
		it doesn't grab the lock for input processing.
		</para>
		
		<para>
		If the X server draws, it grabs the lock and invalidates the command
		FIFO.
		</para>
		
		<para>
		If the X server moves a window, it grabs the lock, updates the stamp,
		and invalidates the command FIFO.
		</para>
		
		<para>
		If another 3D app runs, it grabs the lock, invalidates the command FIFO,
		invalidates the 3D state and possibly invalidates the texture state.
		</para>
	</sect2>

	<sect2 id="templated-drm">
		<title>What is templated DRM code?</title>
		
		<para>
		It was first discussed in a email about what Gareth had done to bring up 
		the	mach64 kernel module.
		</para>
		
		<para>
		Not wanting to simply copy-and-paste <emphasis>another</emphasis> version of 
		<filename>_drv.[ch]</filename>,	<filename>_context.c</filename>, <filename>_bufs.s</filename>
		and so on, Gareth did some refactoring along the lines of what him and Rik Faith 
		had discussed a long time ago.
		</para>
		
		<para>
		This is very much along	the lines of a lot of Mesa code, where there 
		exists a template header file that can be customized with a few defines. 
		At the time, it was done <filename>_drv.c</filename> and <filename>_context.c</filename>, 
		creating <filename>driver_tmp.h</filename> and <filename>context_tmp.h</filename> 
		that could be used to build up the core module.
		</para>
		
		<para>
		An inspection of <filename>mach64_drv.c</filename> on the 
		mach64-0-0-1-branch reveals the	following code:
		</para>
		
<programlisting>
#define DRIVER_AUTHOR           "Gareth Hughes"

#define DRIVER_NAME             "mach64"
#define DRIVER_DESC             "DRM module for the ATI Rage Pro"
#define DRIVER_DATE             "20001203"

#define DRIVER_MAJOR            1
#define DRIVER_MINOR            0
#define DRIVER_PATCHLEVEL       0


static drm_ioctl_desc_t         mach64_ioctls[] = {
	[DRM_IOCTL_NR(DRM_IOCTL_VERSION)]       = { mach64_version,    0, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_GET_UNIQUE)]    = { drm_getunique,     0, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_GET_MAGIC)]     = { drm_getmagic,      0, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_IRQ_BUSID)]     = { drm_irq_busid,     0, 1 },

	[DRM_IOCTL_NR(DRM_IOCTL_SET_UNIQUE)]    = { drm_setunique,     1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_BLOCK)]         = { drm_block,         1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_UNBLOCK)]       = { drm_unblock,       1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_AUTH_MAGIC)]    = { drm_authmagic,     1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_ADD_MAP)]       = { drm_addmap,        1, 1 },

	[DRM_IOCTL_NR(DRM_IOCTL_ADD_BUFS)]      = { drm_addbufs,       1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_MARK_BUFS)]     = { drm_markbufs,      1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_INFO_BUFS)]     = { drm_infobufs,      1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_MAP_BUFS)]      = { drm_mapbufs,       1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_FREE_BUFS)]     = { drm_freebufs,      1, 0 },

	[DRM_IOCTL_NR(DRM_IOCTL_ADD_CTX)]       = { mach64_addctx,     1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_RM_CTX)]        = { mach64_rmctx,      1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_MOD_CTX)]       = { mach64_modctx,     1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_GET_CTX)]       = { mach64_getctx,     1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_SWITCH_CTX)]    = { mach64_switchctx,  1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_NEW_CTX)]       = { mach64_newctx,     1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_RES_CTX)]       = { mach64_resctx,     1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_ADD_DRAW)]      = { drm_adddraw,       1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_RM_DRAW)]       = { drm_rmdraw,        1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_LOCK)]          = { mach64_lock,       1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_UNLOCK)]        = { mach64_unlock,     1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_FINISH)]        = { drm_finish,        1, 0 },

#if defined(CONFIG_AGP) || defined(CONFIG_AGP_MODULE)
	[DRM_IOCTL_NR(DRM_IOCTL_AGP_ACQUIRE)]   = { drm_agp_acquire,   1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_AGP_RELEASE)]   = { drm_agp_release,   1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_AGP_ENABLE)]    = { drm_agp_enable,    1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_AGP_INFO)]      = { drm_agp_info,      1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_AGP_ALLOC)]     = { drm_agp_alloc,     1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_AGP_FREE)]      = { drm_agp_free,      1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_AGP_BIND)]      = { drm_agp_bind,      1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_AGP_UNBIND)]    = { drm_agp_unbind,    1, 1 },
#endif

	[DRM_IOCTL_NR(DRM_IOCTL_MACH64_INIT)]   = { mach64_dma_init,   1, 1 },
	[DRM_IOCTL_NR(DRM_IOCTL_MACH64_CLEAR)]  = { mach64_dma_clear,  1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_MACH64_SWAP)]   = { mach64_dma_swap,   1, 0 },
	[DRM_IOCTL_NR(DRM_IOCTL_MACH64_IDLE)]   = { mach64_dma_idle,   1, 0 },
};

#define DRIVER_IOCTL_COUNT      DRM_ARRAY_SIZE( mach64_ioctls )

#define HAVE_CTX_BITMAP         1

#define TAG(x) mach64_##x
#include "driver_tmp.h"
</programlisting>
		
		<para>
		And that's all you need.  A trivial amount of code is needed for the
		context handling:
		</para>
		
<programlisting>
#define __NO_VERSION__
#include "drmP.h"
#include "mach64_drv.h"

#define TAG(x) mach64_##x
#include "context_tmp.h"
</programlisting>
		
		<para>
		And as far as I can tell, the only thing that's keeping this out of
		<filename>mach64_drv.c</filename> is the <envar>__NO_VERSION__</envar>, 
		which is a 2.2 thing and is not used in 2.4 (right?).
		</para>
		
		<para>
		To enable all the context bitmap code, we see the
<programlisting>
#define HAVE_CTX_BITMAP 1
</programlisting>
		To enable things like &AGP;, 
		&MTRR;s and 
		&DMA;	management, the author 
		simply needs to define the correct symbols. With less than five minutes 
		of mach64-specific coding, I had a full	kernel module that would do 
		everything a basic driver requires &mdash; enough	to bring up a 
		software-fallback driver.  The above code is all that is needed for the 
		tdfx driver, with appropriate name changes.  Indeed, any card that doesn't 
		do kernel-based &DMA; can have a 
		fully functional &DRM; module with 
		the above code.  &DMA;-based 
		drivers will need more, of course.
		</para>
		
		<para>
		The plan is to extend this to basic 
		&DMA; setup and buffer management, 
		so that the creation of PCI or 
		&AGP;
		&DMA; buffers, installation of 
		<hardware>IRQs</hardware> and so on is as trivial as this.  What will then 
		be left is the hardware-specific parts of the 
		&DRM; module that deal with 
		actually programming the card to do things, such as setting state for 
		rendering	or kicking off &DMA; 
		buffers.  That is, the interesting stuff.
		</para>
		
		<para>
		A couple of points:
		</para>
		
		<itemizedlist>
			<listitem>
				<para>
				Why was it done like this, and not with C++ features like virtual
				functions (i.e. why don't I do it in C++)?  Because it's the Linux
				kernel, dammit!  No offense to any C++ fan who may be	reading this :-)  
				Besides, a lot of the initialization is	order-dependent, so 
				inserting or removing blocks of code with 
				<userinput>#defines</userinput>	is a nice way to achieve the desired 
				result, at least in this situation.
				</para>
			</listitem>
			
			<listitem>
				<para>
				Much of the core &DRM; code 
				(like <filename>bufs.c</filename>, <filename>context.c</filename> and 
				<filename>dma.c</filename>) will essentially move into these template 
				headers.  I feel that this is a	better way to handle the common code. 
				Take <filename>context.c</filename> as a trivial example &mdash; the 
				i810, mga, tdfx, r128 and mach64 drivers have 
				<emphasis>exactly</emphasis> the same code, with name changes. Take 
				<filename>bufs.c</filename> as a slightly more	interesting example 
				&mdash; some drivers map only 
				&AGP; buffers, some do both
				&AGP; and PCI, some map 
				differently depending on their 
				&DMA; queue	management and so 
				on.  Again, rather than cutting and pasting the code from 
				<function>drm_addbufs</function> into my driver, removing the sections 
				I don't need and leaving it at that, I think keeping the core 
				functionality in <filename>bufs_tmp.h</filename> and allowing this to 
				be customized at compile time is a cleaner and more	maintainable 
				solution.
				</para>
			</listitem>
		</itemizedlist>
		
		<para>
		This it has the possibility to make keeping the
		other OSs code up to date a lot easier.
		</para>

		<para>
		The current mach64 branch is only using one template in the driver.
		</para>
		
		<para>
		Check out the r128 driver from the trunk, for a good example.  Notice 
		there are files in there such as <filename>r128_tritmp.h</filename>.  
		This is a template that gets included in <filename>r128_tris.c</filename>. 
		What it does basically is consolidate code that is largely reproduced over
		several functions, so that you set a few macros.  For example:
		</para>
		
<programlisting>
#define IND (R128_TWOSIDE_BIT)
#define TAG(x) x##_twoside
</programlisting>
		
		<para>
		followed by
		</para>
		
<programlisting>
#include "r128_tritmp.h"
</programlisting>
		
		<para>
		Notice the inline function's name defined in 
		<filename>r128_tritmp.h</filename> is the result of the 
		<function>TAG</function> macro, as well the function's content is 
		dependent on what <function>IND</function> value is defined. So 
		essentially the inline function is a template for various	functions that 
		have a bit in common.  That way you consolidate common code and keep 
		things consistent.
		</para>
		
		<para>
		Look at e.g. 
		<ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/dri/xc/xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel/r128.h?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup">
			<filename class="directory">xc/programs/Xserver/hw/xfree86/os-support/linux/drm/kernel/r128.h</filename>
		</ulink>
		though. That's the template architecture at its beauty. Most of the code 
		is shared between the drivers, customized with a few defines. Compare that 
		to the duplication and inconsistency before.
		</para>
	</sect2>
</sect1>
@