doxygen/gallium.doc - platform/external/mesa3d - Gitiles

 /** \mainpage

   \section about About

   Gallium3D is <a href="http://www.tungstengraphics.com/">Tungsten Graphics</a>'
   new architecture for building 3D graphics drivers. Initially
   supporting Mesa and Linux graphics drivers, Gallium3D is designed to allow
   portability to all major operating systems and graphics interfaces.

   Compared to existing Linux graphics drivers, Gallium3D will:

   - Make drivers smaller and simpler.
     Current DRI drivers are rather complicated. They're large, contain
     duplicated code and are burdened with implementing many concepts tightly
     tied to the OpenGL 1.x/2.x API.

   - Model modern graphics hardware.
     The new driver architecture is an abstraction of modern graphics hardware,
     rather than an OpenGL->hardware translator. The new driver interface will
     assume the presence of programmable vertex/fragment shaders and flexible
     memory objects.

   - Support multiple graphics APIs.
     The OpenGL 3.0 API will be very different from OpenGL 1.x/2.x. We'd like a
     driver model that is API-neutral so that it's not tied to a specific
     graphics API.

   \section contents Contents

   - \ref overview

   - \ref statetracker

   - Pipe drivers:
     - \ref softpipe
     - \ref i915g
     - Cell driver (cell_context.h, cell_winsys.h)
     - \ref failover

   - Winsys drivers:
     - X11 winsys driver (xm_winsys.c)
     - Intel DRI winsys driver (intel_context.h, intel_winsys_pipe.c)

   - Ancillary Modules:
     - \ref draw
     - \ref tgsi
       - LLVM TGSI backend (gallivm.h)

   - \ref callgraph

   \section external External documentation

   - <a href="http://www.tungstengraphics.com/gallium3D.htm">Gallium3D's Architectural Overview</a>
   - <a href="http://www.tungstengraphics.com/wiki/index.php/Gallium3D">Technical Overview</a>
   - <a href="http://www.tungstengraphics.com/wiki/files/gallium3d-xds2007.pdf">Gallium3D talk from XDS 2007</a>

 */

 /** \page overview Overview

   The public interface of a Gallium3D driver is described by the p_context.h
   header file. The pipe_context structure is an abstract base class with
   methods for:

   - Setting rendering state (texture sampler state, vertex array info, drawing surfaces, etc.)

   - Setting shader state, using the TGSI binary shader representation.

   - Vertex array and indexed vertex array drawing.

   - Region (memory) management for textures, renderbuffers, vertex buffers, etc.

   - Hardware queries (number of texture units, max texture size, etc).

   The p_state.h header defines all the state objects (such as polygon
   rasterization options, blend modes, etc) and resources (drawing surfaces,
   textures, memory buffers). The pipe interface uses "constant state" objects.
   That is, state objects are created once and are immutable. State objects are
   put into effect by binding them. This allows Gallium3D drivers to create
   corresponding hardware state objects which can be quickly handled.

   The p_defines.h header defines numerous constants and tokens (blend modes,
   texture wrap modes, surface formats, etc.

   The p_winsys.h header defines the window system and OS facilities which
   Gallium3D drivers rely upon. For example, memory allocation is typically a
   service the OS provides while window size/position information is provided by
   the window system. Pipe drivers use the winsys interface to handle these
   things.

   By abstracting OS and window system services, pipe drivers are portable to
   other platforms (e.g. embedded devices).
 */

 /** \page statetracker The State Tracker

   The state tracker is the piece which interfaces core Mesa to the Gallium3D
   interface. It's responsible for translating Mesa state (blend modes, texture
   state, etc) and drawing commands (like glDrawArrays and glDrawPixels) into
   pipe objects and operations.

   Traditional fixed-function OpenGL components (such as lighting and texture
   combining) are implemented with shaders. OpenGL commands such as glDrawPixels
   are translated into textured quadrilateral rendering. Basically, any
   rendering operation that isn't directly supported by modern graphics hardware
   is translated into a hardware-friendly form.

   Future state trackers will be created for OpenGL 3.0 and OpenGL-ES 2.x.
 */

 /** \page softpipe Softpipe Driver

   The softpipe driver is a software implementation of the Gallium3D interface.
   It will be used as a reference implementation and as a fallback driver when a
   hardware driver isn't available. The softpipe driver will make extensive use
   of run-time code generation to efficiently execute vertex, fragment and
   rasterization operations.

   \sa sp_winsys.h
 */

 /** \page i915g i915 Driver

   The i915 Gallium3D Driver is an initial hardware driver implementation within
   the Gallium3D driver architecture. We expect that once complete this driver
   will have equivalent functionality and performance to the current Mesa
   i915tex driver, but from a much smaller codebase.

   \sa i915_context.h
   \sa i915_winsys.h
 */

 /** \page failover Failover Module

   The failover module acts as a selector between a hardware driver and the
   softpipe driver. When the hardware can't implement a particular rendering
   operation, the failover module will pass the request to the softpipe driver.
   This is a different solution to the "software fallbacks" scheme of previous
   Mesa drivers.

   \sa fo_winsys.h
 */

 /** \page draw Draw Module
   The Draw module provides point/line/polygon rendering services such as
   vertex transformation, polygon culling and clipping. It will be used by
   drivers for hardware which lacks vertex transformation (such as the
   i915/i945). It may also be instantiated and used directly by the state
   tracker to implement some API functionality that doesn't map well to hardware
   capabilities.

   The interface of this module corresponds closely to the subset of the Gallium
   Driver Interface which is relevent to these steps in the pipeline. Specifically
   there are calls for:

   - Vertex shader constant state objects
   - Vertex buffer binding
   - Vertex element layout (vertex fetch) constant state objects
   - DrawArrays and DrawElements
   - Rasterizer constant state objects.

   The Draw module is effectively the part of \ref softpipe which is concerned with
   vertex processing, split off into a separate module so that it can be reused
   by drivers for rasterization-only hardware. As such it is also instantiated
   by the \ref i915g driver.

   Additionally, there are cases in the Mesa OpenGL state_tracker where it is
   required to obtain transformed vertices and yet it is anticipated that using
   hardware transformation even if available would reduce performance, usually
   because the setup costs or latency are prohibitive. For this reason the Mesa
   state_tracker also instantiates a copy of this module.

   \sa draw_context.h
 */

 /** \page tgsi TGSI

   The TGSI module provides a universal representation of shaders and
   CPU-based execution of shaders. All Mesa vertex/fragment programs and shaders
   are translated into the TGSI representation before being passed to the
   driver. In turn, the driver will convert the TGSI instructions into
   GPU-specific instructions. For hardware that lacks vertex or fragment shader
   support, the TGSI's executor can be used. The TGSI executor includes support
   for SSE code generation. Support for other processors (such as Cell) will be
   added in the future.

   \sa tgsi_parse.h
   \sa <a href="http://www.tungstengraphics.com/wiki/files/tgsi.pdf">TGSI specification</a>
 */

 /** \page callgraph Glxgears callgraph example

   Below is a call graph of the glxgears application together with the Gallium3D's softpipe reference driver.

   \htmlonly
   The functions in the graph below are clickable.
   \endhtmlonly

   \dot
 digraph {
 	graph [fontname=Arial, fontsize=10];
 	node [fontcolor=white, fontname=Arial, style=filled, fontsize=10, shape=box];
 	edge [fontname=Arial, fontsize=10];
 	1 [color="#ff0000", URL="\ref main", label="main\n100.00% (0.68%)\n0"];
 	1 -> 2 [color="#fe0400", fontcolor="#fe0400", label="99.32%\n1433"];
 	2 [color="#fe0400", URL="\ref do_draw", label="do_draw\n99.32% (0.00%)\n1433"];
 	2 -> 4 [color="#fa1201", fontcolor="#fa1201", label="96.67%\n4298"];
 	2 -> 39 [color="#0d4f76", fontcolor="#0d4f76", label="2.45%\n1433"];
 	3 [color="#fa1201", URL="\ref execute_list", label="execute_list\n96.67% (0.00%)\n4299"];
 	3 -> 5 [color="#f91301", fontcolor="#f91301", label="96.38%\n17196"];
 	4 [color="#fa1201", URL="\ref _mesa_CallList", label="_mesa_CallList\n96.67% (0.00%)\n4299"];
 	4 -> 3 [color="#fa1201", fontcolor="#fa1201", label="96.67%\n4299"];
 	5 [color="#f91301", URL="\ref vbo_save_playback_vertex_list", label="vbo_save_playback_vertex_list\n96.38% (0.10%)\n17196"];
 	5 -> 6 [color="#f91501", fontcolor="#f91501", label="96.09%\n17196"];
 	6 [color="#f91501", URL="\ref st_draw_vbo", label="st_draw_vbo\n96.09% (0.00%)\n17196"];
 	6 -> 10 [color="#ec3f03", fontcolor="#ec3f03", label="87.48%\n30093"];
 	6 -> 33 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
 	6 -> 34 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
 	6 -> 47 [color="#0d3a74", fontcolor="#0d3a74", label="1.17%\n17196"];
 	7 [color="#f71d01", URL="\ref draw_do_flush", label="draw_do_flush\n94.52% (0.20%)\n101744"];
 	7 -> 13 [color="#e74e04", fontcolor="#e74e04", label="84.25%\n1146400"];
 	7 -> 8 [color="#0d7d6c", fontcolor="#0d7d6c", label="8.32%\n114640"];
 	7 -> 46 [color="#0d4175", fontcolor="#0d4175", label="1.57%\n97444"];
 	8 [color="#f32702", URL="\ref clip_tri", label="clip_tri\n92.37% (0.49%)\n1261040"];
 	8 -> 9 [color="#f32a02", fontcolor="#f32a02", label="91.88%\n1261040"];
 	9 [color="#f32a02", URL="\ref cull_tri", label="cull_tri\n91.88% (0.20%)\n1261040"];
 	9 -> 15 [color="#e35d04", fontcolor="#e35d04", label="81.12%\n560810"];
 	9 -> 12 [color="#0d805e", fontcolor="#0d805e", label="10.57%\n560810"];
 	10 [color="#ec3f03", URL="\ref softpipe_draw_arrays", label="softpipe_draw_arrays\n87.48% (0.00%)\n30093"];
 	10 -> 11 [color="#ec3f03", fontcolor="#ec3f03", label="87.48%\n30093"];
 	11 [color="#ec3f03", URL="\ref softpipe_draw_elements", label="softpipe_draw_elements\n87.48% (0.10%)\n30093"];
 	11 -> 17 [color="#cf9507", fontcolor="#cf9507", label="67.61%\n30093"];
 	11 -> 27 [color="#0d844f", fontcolor="#0d844f", label="13.01%\n120372"];
 	11 -> 36 [color="#0d5a77", fontcolor="#0d5a77", label="3.33%\n30093"];
 	11 -> 23 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n30093"];
 	12 [color="#ea4703", URL="\ref flush_spans", label="flush_spans\n85.91% (4.60%)\n4586176"];
 	12 -> 14 [color="#e35c04", fontcolor="#e35c04", label="81.31%\n15910811"];
 	13 [color="#e74e04", URL="\ref flatshade_tri", label="flatshade_tri\n84.25% (0.29%)\n1146400"];
 	13 -> 8 [color="#e75004", fontcolor="#e75004", label="83.95%\n1146400"];
 	14 [color="#e35c04", URL="\ref shade_quad", label="shade_quad\n81.31% (7.73%)\n15910811"];
 	14 -> 21 [color="#c0bb09", fontcolor="#c0bb09", label="57.24%\n13903725"];
 	14 -> 26 [color="#0c883c", fontcolor="#0c883c", label="16.24%\n15910811"];
 	15 [color="#e35d04", URL="\ref setup_tri", label="setup_tri\n81.12% (1.47%)\n560810"];
 	15 -> 16 [color="#e06505", fontcolor="#e06505", label="79.26%\n1121620"];
 	16 [color="#e06505", URL="\ref subtriangle", label="subtriangle\n79.26% (3.91%)\n1121620"];
 	16 -> 12 [color="#da7606", fontcolor="#da7606", label="75.34%\n4025366"];
 	17 [color="#cf9507", URL="\ref draw_arrays", label="draw_arrays\n67.61% (0.00%)\n30093"];
 	17 -> 19 [color="#cf9607", fontcolor="#cf9607", label="67.42%\n630520"];
 	18 [color="#cf9607", URL="\ref do_ef_triangle", label="do_ef_triangle\n67.42% (0.49%)\n1261040"];
 	18 -> 20 [color="#ce9807", fontcolor="#ce9807", label="66.83%\n1261040"];
 	19 [color="#cf9607", URL="\ref do_quad", label="do_quad\n67.42% (0.00%)\n630520"];
 	19 -> 18 [color="#cf9607", fontcolor="#cf9607", label="67.42%\n1261040"];
 	20 [color="#ce9807", URL="\ref get_queued_prim", label="get_queued_prim\n66.83% (0.10%)\n1261040"];
 	20 -> 7 [color="#cd9907", fontcolor="#cd9907", label="66.54%\n71650"];
 	21 [color="#c0bb09", URL="\ref depth_test_quad", label="depth_test_quad\n57.24% (1.08%)\n13903725"];
 	21 -> 22 [color="#40a00b", fontcolor="#40a00b", label="34.54%\n13074127"];
 	21 -> 24 [color="#0c8f1e", fontcolor="#0c8f1e", label="21.62%\n13903725"];
 	22 [color="#40a00b", URL="\ref output_quad", label="output_quad\n34.54% (3.91%)\n13074127"];
 	22 -> 25 [color="#0c8c2b", fontcolor="#0c8c2b", label="19.28%\n13074127"];
 	22 -> 28 [color="#0d8159", fontcolor="#0d8159", label="11.35%\n7223435"];
 	23 [color="#1c970c", URL="\ref draw_flush", label="draw_flush\n27.98% (0.00%)\n257944"];
 	23 -> 7 [color="#1c970c", fontcolor="#1c970c", label="27.98%\n30093"];
 	24 [color="#0c8f1e", URL="\ref sp_depth_test_quad", label="sp_depth_test_quad\n21.62% (16.14%)\n13903725"];
 	24 -> 37 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n13903725"];
 	24 -> 44 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n13903725"];
 	25 [color="#0c8c2b", URL="\ref write_quad_f_swz", label="write_quad_f_swz\n19.28% (16.14%)\n13074127"];
 	25 -> 38 [color="#0d5877", fontcolor="#0d5877", label="3.13%\n26148254"];
 	26 [color="#0c883a", URL="\ref tgsi_exec_machine_init", label="tgsi_exec_machine_init\n16.73% (10.27%)\n16326381"];
 	26 -> 30 [color="#0d6178", fontcolor="#0d6178", label="3.91%\n16326381"];
 	26 -> 45 [color="#0d4475", fontcolor="#0d4475", label="1.76%\n16326381"];
 	26 -> 52 [color="#0d3174", fontcolor="#0d3174", label="0.78%\n16326381"];
 	27 [color="#0d844f", URL="\ref draw_set_mapped_vertex_buffer", label="draw_set_mapped_vertex_buffer\n13.01% (0.00%)\n120372"];
 	27 -> 23 [color="#0d844f", fontcolor="#0d844f", label="13.01%\n120372"];
 	28 [color="#0d8159", URL="\ref read_quad_f_swz", label="read_quad_f_swz\n11.35% (5.87%)\n7223435"];
 	28 -> 29 [color="#0d737a", fontcolor="#0d737a", label="5.48%\n14446870"];
 	29 [color="#0d737a", URL="\ref get_row_rgba", label="get_row_rgba\n5.48% (5.48%)\n14446870"];
 	30 [color="#0d6178", URL="\ref tgsi_parse_init", label="tgsi_parse_init\n3.91% (3.52%)\n16326383"];
 	31 [color="#0d5f78", URL="\ref draw_set_vertex_buffer", label="draw_set_vertex_buffer\n3.72% (0.00%)\n34392"];
 	31 -> 23 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
 	32 [color="#0d5f78", URL="\ref draw_set_vertex_element", label="draw_set_vertex_element\n3.72% (0.00%)\n34392"];
 	32 -> 23 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
 	33 [color="#0d5f78", URL="\ref softpipe_set_vertex_buffer", label="softpipe_set_vertex_buffer\n3.72% (0.00%)\n34392"];
 	33 -> 31 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
 	34 [color="#0d5f78", URL="\ref softpipe_set_vertex_element", label="softpipe_set_vertex_element\n3.72% (0.00%)\n34392"];
 	34 -> 32 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
 	35 [color="#0d5d77", URL="\ref __i686.get_pc_thunk.bx", label="__i686.get_pc_thunk.bx\n3.52% (3.52%)\n0"];
 	36 [color="#0d5a77", URL="\ref draw_set_mapped_constant_buffer", label="draw_set_mapped_constant_buffer\n3.33% (0.10%)\n30093"];
 	36 -> 23 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n30093"];
 	37 [color="#0d5977", URL="\ref s8z24_read_quad_z", label="s8z24_read_quad_z\n3.23% (3.23%)\n13903725"];
 	38 [color="#0d5877", URL="\ref put_row_8R8G8B_ximage", label="put_row_8R8G8B_ximage\n3.13% (3.13%)\n26148254"];
 	39 [color="#0d4f76", URL="\ref _mesa_Clear", label="_mesa_Clear\n2.45% (0.00%)\n1433"];
 	39 -> 40 [color="#0d4f76", fontcolor="#0d4f76", label="2.45%\n1433"];
 	40 [color="#0d4f76", URL="\ref st_clear", label="st_clear\n2.45% (0.00%)\n1433"];
 	40 -> 41 [color="#0d4d76", fontcolor="#0d4d76", label="2.35%\n2866"];
 	41 [color="#0d4d76", URL="\ref xmesa_clear", label="xmesa_clear\n2.35% (0.00%)\n2866"];
 	41 -> 42 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n1433"];
 	42 [color="#0d4c76", URL="\ref softpipe_clear", label="softpipe_clear\n2.25% (0.00%)\n1433"];
 	42 -> 43 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n1433"];
 	43 [color="#0d4c76", URL="\ref sp_region_fill", label="sp_region_fill\n2.25% (2.25%)\n1433"];
 	44 [color="#0d4c76", URL="\ref s8z24_write_quad_z", label="s8z24_write_quad_z\n2.25% (2.25%)\n13903725"];
 	45 [color="#0d4475", URL="\ref tgsi_parse_free", label="tgsi_parse_free\n1.76% (0.78%)\n16326383"];
 	45 -> 49 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n16326383"];
 	46 [color="#0d4175", URL="\ref draw_vertex_shader_queue_flush", label="draw_vertex_shader_queue_flush\n1.57% (0.49%)\n97444"];
 	46 -> 53 [color="#0d2f74", fontcolor="#0d2f74", label="0.68%\n415570"];
 	46 -> 26 [color="#0d2973", fontcolor="#0d2973", label="0.49%\n415570"];
 	47 [color="#0d3b74", URL="\ref st_validate_state", label="st_validate_state\n1.27% (0.00%)\n18629"];
 	47 -> 48 [color="#0d3874", fontcolor="#0d3874", label="1.08%\n8599"];
 	48 [color="#0d3874", URL="\ref update_raster_state", label="update_raster_state\n1.08% (0.10%)\n8599"];
 	48 -> 51 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
 	49 [color="#0d3674", URL="\ref tgsi_full_token_free", label="tgsi_full_token_free\n0.98% (0.98%)\n16326412"];
 	50 [color="#0d3674", URL="\ref draw_set_rasterizer_state", label="draw_set_rasterizer_state\n0.98% (0.00%)\n8599"];
 	50 -> 23 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
 	51 [color="#0d3674", URL="\ref softpipe_bind_rasterizer_state", label="softpipe_bind_rasterizer_state\n0.98% (0.00%)\n8599"];
 	51 -> 50 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
 	52 [color="#0d3174", URL="\ref tgsi_align_128bit", label="tgsi_align_128bit\n0.78% (0.78%)\n16326381"];
 	53 [color="#0d2f74", URL="\ref draw_vertex_fetch", label="draw_vertex_fetch\n0.68% (0.68%)\n415570"];
 }

   \enddot

   The graph above was generated by the <a href="http://code.google.com/p/jrfonseca/wiki/Gprof2Dot">gprof2dot.py script</a>.
 */
	/** \mainpage

	\section about About

	Gallium3D is <a href="http://www.tungstengraphics.com/">Tungsten Graphics</a>'
	new architecture for building 3D graphics drivers. Initially
	supporting Mesa and Linux graphics drivers, Gallium3D is designed to allow
	portability to all major operating systems and graphics interfaces.

	Compared to existing Linux graphics drivers, Gallium3D will:

	- Make drivers smaller and simpler.
	Current DRI drivers are rather complicated. They're large, contain
	duplicated code and are burdened with implementing many concepts tightly
	tied to the OpenGL 1.x/2.x API.

	- Model modern graphics hardware.
	The new driver architecture is an abstraction of modern graphics hardware,
	rather than an OpenGL->hardware translator. The new driver interface will
	assume the presence of programmable vertex/fragment shaders and flexible
	memory objects.

	- Support multiple graphics APIs.
	The OpenGL 3.0 API will be very different from OpenGL 1.x/2.x. We'd like a
	driver model that is API-neutral so that it's not tied to a specific
	graphics API.

	\section contents Contents

	- \ref overview

	- \ref statetracker

	- Pipe drivers:
	- \ref softpipe
	- \ref i915g
	- Cell driver (cell_context.h, cell_winsys.h)
	- \ref failover

	- Winsys drivers:
	- X11 winsys driver (xm_winsys.c)
	- Intel DRI winsys driver (intel_context.h, intel_winsys_pipe.c)

	- Ancillary Modules:
	- \ref draw
	- \ref tgsi
	- LLVM TGSI backend (gallivm.h)

	- \ref callgraph

	\section external External documentation

	- <a href="http://www.tungstengraphics.com/gallium3D.htm">Gallium3D's Architectural Overview</a>
	- <a href="http://www.tungstengraphics.com/wiki/index.php/Gallium3D">Technical Overview</a>
	- <a href="http://www.tungstengraphics.com/wiki/files/gallium3d-xds2007.pdf">Gallium3D talk from XDS 2007</a>

	*/

	/** \page overview Overview

	The public interface of a Gallium3D driver is described by the p_context.h
	header file. The pipe_context structure is an abstract base class with
	methods for:

	- Setting rendering state (texture sampler state, vertex array info, drawing surfaces, etc.)

	- Setting shader state, using the TGSI binary shader representation.

	- Vertex array and indexed vertex array drawing.

	- Region (memory) management for textures, renderbuffers, vertex buffers, etc.

	- Hardware queries (number of texture units, max texture size, etc).

	The p_state.h header defines all the state objects (such as polygon
	rasterization options, blend modes, etc) and resources (drawing surfaces,
	textures, memory buffers). The pipe interface uses "constant state" objects.
	That is, state objects are created once and are immutable. State objects are
	put into effect by binding them. This allows Gallium3D drivers to create
	corresponding hardware state objects which can be quickly handled.

	The p_defines.h header defines numerous constants and tokens (blend modes,
	texture wrap modes, surface formats, etc.

	The p_winsys.h header defines the window system and OS facilities which
	Gallium3D drivers rely upon. For example, memory allocation is typically a
	service the OS provides while window size/position information is provided by
	the window system. Pipe drivers use the winsys interface to handle these
	things.

	By abstracting OS and window system services, pipe drivers are portable to
	other platforms (e.g. embedded devices).
	*/

	/** \page statetracker The State Tracker

	The state tracker is the piece which interfaces core Mesa to the Gallium3D
	interface. It's responsible for translating Mesa state (blend modes, texture
	state, etc) and drawing commands (like glDrawArrays and glDrawPixels) into
	pipe objects and operations.

	Traditional fixed-function OpenGL components (such as lighting and texture
	combining) are implemented with shaders. OpenGL commands such as glDrawPixels
	are translated into textured quadrilateral rendering. Basically, any
	rendering operation that isn't directly supported by modern graphics hardware
	is translated into a hardware-friendly form.

	Future state trackers will be created for OpenGL 3.0 and OpenGL-ES 2.x.
	*/

	/** \page softpipe Softpipe Driver

	The softpipe driver is a software implementation of the Gallium3D interface.
	It will be used as a reference implementation and as a fallback driver when a
	hardware driver isn't available. The softpipe driver will make extensive use
	of run-time code generation to efficiently execute vertex, fragment and
	rasterization operations.

	\sa sp_winsys.h
	*/

	/** \page i915g i915 Driver

	The i915 Gallium3D Driver is an initial hardware driver implementation within
	the Gallium3D driver architecture. We expect that once complete this driver
	will have equivalent functionality and performance to the current Mesa
	i915tex driver, but from a much smaller codebase.

	\sa i915_context.h
	\sa i915_winsys.h
	*/

	/** \page failover Failover Module

	The failover module acts as a selector between a hardware driver and the
	softpipe driver. When the hardware can't implement a particular rendering
	operation, the failover module will pass the request to the softpipe driver.
	This is a different solution to the "software fallbacks" scheme of previous
	Mesa drivers.

	\sa fo_winsys.h
	*/

	/** \page draw Draw Module
	The Draw module provides point/line/polygon rendering services such as
	vertex transformation, polygon culling and clipping. It will be used by
	drivers for hardware which lacks vertex transformation (such as the
	i915/i945). It may also be instantiated and used directly by the state
	tracker to implement some API functionality that doesn't map well to hardware
	capabilities.

	The interface of this module corresponds closely to the subset of the Gallium
	Driver Interface which is relevent to these steps in the pipeline. Specifically
	there are calls for:

	- Vertex shader constant state objects
	- Vertex buffer binding
	- Vertex element layout (vertex fetch) constant state objects
	- DrawArrays and DrawElements
	- Rasterizer constant state objects.

	The Draw module is effectively the part of \ref softpipe which is concerned with
	vertex processing, split off into a separate module so that it can be reused
	by drivers for rasterization-only hardware. As such it is also instantiated
	by the \ref i915g driver.

	Additionally, there are cases in the Mesa OpenGL state_tracker where it is
	required to obtain transformed vertices and yet it is anticipated that using
	hardware transformation even if available would reduce performance, usually
	because the setup costs or latency are prohibitive. For this reason the Mesa
	state_tracker also instantiates a copy of this module.

	\sa draw_context.h
	*/

	/** \page tgsi TGSI

	The TGSI module provides a universal representation of shaders and
	CPU-based execution of shaders. All Mesa vertex/fragment programs and shaders
	are translated into the TGSI representation before being passed to the
	driver. In turn, the driver will convert the TGSI instructions into
	GPU-specific instructions. For hardware that lacks vertex or fragment shader
	support, the TGSI's executor can be used. The TGSI executor includes support
	for SSE code generation. Support for other processors (such as Cell) will be
	added in the future.

	\sa tgsi_parse.h
	\sa <a href="http://www.tungstengraphics.com/wiki/files/tgsi.pdf">TGSI specification</a>
	*/

	/** \page callgraph Glxgears callgraph example

	Below is a call graph of the glxgears application together with the Gallium3D's softpipe reference driver.

	\htmlonly
	The functions in the graph below are clickable.
	\endhtmlonly

	\dot
	digraph {
	graph [fontname=Arial, fontsize=10];
	node [fontcolor=white, fontname=Arial, style=filled, fontsize=10, shape=box];
	edge [fontname=Arial, fontsize=10];
	1 [color="#ff0000", URL="\ref main", label="main\n100.00% (0.68%)\n0"];
	1 -> 2 [color="#fe0400", fontcolor="#fe0400", label="99.32%\n1433"];
	2 [color="#fe0400", URL="\ref do_draw", label="do_draw\n99.32% (0.00%)\n1433"];
	2 -> 4 [color="#fa1201", fontcolor="#fa1201", label="96.67%\n4298"];
	2 -> 39 [color="#0d4f76", fontcolor="#0d4f76", label="2.45%\n1433"];
	3 [color="#fa1201", URL="\ref execute_list", label="execute_list\n96.67% (0.00%)\n4299"];
	3 -> 5 [color="#f91301", fontcolor="#f91301", label="96.38%\n17196"];
	4 [color="#fa1201", URL="\ref _mesa_CallList", label="_mesa_CallList\n96.67% (0.00%)\n4299"];
	4 -> 3 [color="#fa1201", fontcolor="#fa1201", label="96.67%\n4299"];
	5 [color="#f91301", URL="\ref vbo_save_playback_vertex_list", label="vbo_save_playback_vertex_list\n96.38% (0.10%)\n17196"];
	5 -> 6 [color="#f91501", fontcolor="#f91501", label="96.09%\n17196"];
	6 [color="#f91501", URL="\ref st_draw_vbo", label="st_draw_vbo\n96.09% (0.00%)\n17196"];
	6 -> 10 [color="#ec3f03", fontcolor="#ec3f03", label="87.48%\n30093"];
	6 -> 33 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
	6 -> 34 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
	6 -> 47 [color="#0d3a74", fontcolor="#0d3a74", label="1.17%\n17196"];
	7 [color="#f71d01", URL="\ref draw_do_flush", label="draw_do_flush\n94.52% (0.20%)\n101744"];
	7 -> 13 [color="#e74e04", fontcolor="#e74e04", label="84.25%\n1146400"];
	7 -> 8 [color="#0d7d6c", fontcolor="#0d7d6c", label="8.32%\n114640"];
	7 -> 46 [color="#0d4175", fontcolor="#0d4175", label="1.57%\n97444"];
	8 [color="#f32702", URL="\ref clip_tri", label="clip_tri\n92.37% (0.49%)\n1261040"];
	8 -> 9 [color="#f32a02", fontcolor="#f32a02", label="91.88%\n1261040"];
	9 [color="#f32a02", URL="\ref cull_tri", label="cull_tri\n91.88% (0.20%)\n1261040"];
	9 -> 15 [color="#e35d04", fontcolor="#e35d04", label="81.12%\n560810"];
	9 -> 12 [color="#0d805e", fontcolor="#0d805e", label="10.57%\n560810"];
	10 [color="#ec3f03", URL="\ref softpipe_draw_arrays", label="softpipe_draw_arrays\n87.48% (0.00%)\n30093"];
	10 -> 11 [color="#ec3f03", fontcolor="#ec3f03", label="87.48%\n30093"];
	11 [color="#ec3f03", URL="\ref softpipe_draw_elements", label="softpipe_draw_elements\n87.48% (0.10%)\n30093"];
	11 -> 17 [color="#cf9507", fontcolor="#cf9507", label="67.61%\n30093"];
	11 -> 27 [color="#0d844f", fontcolor="#0d844f", label="13.01%\n120372"];
	11 -> 36 [color="#0d5a77", fontcolor="#0d5a77", label="3.33%\n30093"];
	11 -> 23 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n30093"];
	12 [color="#ea4703", URL="\ref flush_spans", label="flush_spans\n85.91% (4.60%)\n4586176"];
	12 -> 14 [color="#e35c04", fontcolor="#e35c04", label="81.31%\n15910811"];
	13 [color="#e74e04", URL="\ref flatshade_tri", label="flatshade_tri\n84.25% (0.29%)\n1146400"];
	13 -> 8 [color="#e75004", fontcolor="#e75004", label="83.95%\n1146400"];
	14 [color="#e35c04", URL="\ref shade_quad", label="shade_quad\n81.31% (7.73%)\n15910811"];
	14 -> 21 [color="#c0bb09", fontcolor="#c0bb09", label="57.24%\n13903725"];
	14 -> 26 [color="#0c883c", fontcolor="#0c883c", label="16.24%\n15910811"];
	15 [color="#e35d04", URL="\ref setup_tri", label="setup_tri\n81.12% (1.47%)\n560810"];
	15 -> 16 [color="#e06505", fontcolor="#e06505", label="79.26%\n1121620"];
	16 [color="#e06505", URL="\ref subtriangle", label="subtriangle\n79.26% (3.91%)\n1121620"];
	16 -> 12 [color="#da7606", fontcolor="#da7606", label="75.34%\n4025366"];
	17 [color="#cf9507", URL="\ref draw_arrays", label="draw_arrays\n67.61% (0.00%)\n30093"];
	17 -> 19 [color="#cf9607", fontcolor="#cf9607", label="67.42%\n630520"];
	18 [color="#cf9607", URL="\ref do_ef_triangle", label="do_ef_triangle\n67.42% (0.49%)\n1261040"];
	18 -> 20 [color="#ce9807", fontcolor="#ce9807", label="66.83%\n1261040"];
	19 [color="#cf9607", URL="\ref do_quad", label="do_quad\n67.42% (0.00%)\n630520"];
	19 -> 18 [color="#cf9607", fontcolor="#cf9607", label="67.42%\n1261040"];
	20 [color="#ce9807", URL="\ref get_queued_prim", label="get_queued_prim\n66.83% (0.10%)\n1261040"];
	20 -> 7 [color="#cd9907", fontcolor="#cd9907", label="66.54%\n71650"];
	21 [color="#c0bb09", URL="\ref depth_test_quad", label="depth_test_quad\n57.24% (1.08%)\n13903725"];
	21 -> 22 [color="#40a00b", fontcolor="#40a00b", label="34.54%\n13074127"];
	21 -> 24 [color="#0c8f1e", fontcolor="#0c8f1e", label="21.62%\n13903725"];
	22 [color="#40a00b", URL="\ref output_quad", label="output_quad\n34.54% (3.91%)\n13074127"];
	22 -> 25 [color="#0c8c2b", fontcolor="#0c8c2b", label="19.28%\n13074127"];
	22 -> 28 [color="#0d8159", fontcolor="#0d8159", label="11.35%\n7223435"];
	23 [color="#1c970c", URL="\ref draw_flush", label="draw_flush\n27.98% (0.00%)\n257944"];
	23 -> 7 [color="#1c970c", fontcolor="#1c970c", label="27.98%\n30093"];
	24 [color="#0c8f1e", URL="\ref sp_depth_test_quad", label="sp_depth_test_quad\n21.62% (16.14%)\n13903725"];
	24 -> 37 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n13903725"];
	24 -> 44 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n13903725"];
	25 [color="#0c8c2b", URL="\ref write_quad_f_swz", label="write_quad_f_swz\n19.28% (16.14%)\n13074127"];
	25 -> 38 [color="#0d5877", fontcolor="#0d5877", label="3.13%\n26148254"];
	26 [color="#0c883a", URL="\ref tgsi_exec_machine_init", label="tgsi_exec_machine_init\n16.73% (10.27%)\n16326381"];
	26 -> 30 [color="#0d6178", fontcolor="#0d6178", label="3.91%\n16326381"];
	26 -> 45 [color="#0d4475", fontcolor="#0d4475", label="1.76%\n16326381"];
	26 -> 52 [color="#0d3174", fontcolor="#0d3174", label="0.78%\n16326381"];
	27 [color="#0d844f", URL="\ref draw_set_mapped_vertex_buffer", label="draw_set_mapped_vertex_buffer\n13.01% (0.00%)\n120372"];
	27 -> 23 [color="#0d844f", fontcolor="#0d844f", label="13.01%\n120372"];
	28 [color="#0d8159", URL="\ref read_quad_f_swz", label="read_quad_f_swz\n11.35% (5.87%)\n7223435"];
	28 -> 29 [color="#0d737a", fontcolor="#0d737a", label="5.48%\n14446870"];
	29 [color="#0d737a", URL="\ref get_row_rgba", label="get_row_rgba\n5.48% (5.48%)\n14446870"];
	30 [color="#0d6178", URL="\ref tgsi_parse_init", label="tgsi_parse_init\n3.91% (3.52%)\n16326383"];
	31 [color="#0d5f78", URL="\ref draw_set_vertex_buffer", label="draw_set_vertex_buffer\n3.72% (0.00%)\n34392"];
	31 -> 23 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
	32 [color="#0d5f78", URL="\ref draw_set_vertex_element", label="draw_set_vertex_element\n3.72% (0.00%)\n34392"];
	32 -> 23 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
	33 [color="#0d5f78", URL="\ref softpipe_set_vertex_buffer", label="softpipe_set_vertex_buffer\n3.72% (0.00%)\n34392"];
	33 -> 31 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
	34 [color="#0d5f78", URL="\ref softpipe_set_vertex_element", label="softpipe_set_vertex_element\n3.72% (0.00%)\n34392"];
	34 -> 32 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
	35 [color="#0d5d77", URL="\ref __i686.get_pc_thunk.bx", label="__i686.get_pc_thunk.bx\n3.52% (3.52%)\n0"];
	36 [color="#0d5a77", URL="\ref draw_set_mapped_constant_buffer", label="draw_set_mapped_constant_buffer\n3.33% (0.10%)\n30093"];
	36 -> 23 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n30093"];
	37 [color="#0d5977", URL="\ref s8z24_read_quad_z", label="s8z24_read_quad_z\n3.23% (3.23%)\n13903725"];
	38 [color="#0d5877", URL="\ref put_row_8R8G8B_ximage", label="put_row_8R8G8B_ximage\n3.13% (3.13%)\n26148254"];
	39 [color="#0d4f76", URL="\ref _mesa_Clear", label="_mesa_Clear\n2.45% (0.00%)\n1433"];
	39 -> 40 [color="#0d4f76", fontcolor="#0d4f76", label="2.45%\n1433"];
	40 [color="#0d4f76", URL="\ref st_clear", label="st_clear\n2.45% (0.00%)\n1433"];
	40 -> 41 [color="#0d4d76", fontcolor="#0d4d76", label="2.35%\n2866"];
	41 [color="#0d4d76", URL="\ref xmesa_clear", label="xmesa_clear\n2.35% (0.00%)\n2866"];
	41 -> 42 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n1433"];
	42 [color="#0d4c76", URL="\ref softpipe_clear", label="softpipe_clear\n2.25% (0.00%)\n1433"];
	42 -> 43 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n1433"];
	43 [color="#0d4c76", URL="\ref sp_region_fill", label="sp_region_fill\n2.25% (2.25%)\n1433"];
	44 [color="#0d4c76", URL="\ref s8z24_write_quad_z", label="s8z24_write_quad_z\n2.25% (2.25%)\n13903725"];
	45 [color="#0d4475", URL="\ref tgsi_parse_free", label="tgsi_parse_free\n1.76% (0.78%)\n16326383"];
	45 -> 49 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n16326383"];
	46 [color="#0d4175", URL="\ref draw_vertex_shader_queue_flush", label="draw_vertex_shader_queue_flush\n1.57% (0.49%)\n97444"];
	46 -> 53 [color="#0d2f74", fontcolor="#0d2f74", label="0.68%\n415570"];
	46 -> 26 [color="#0d2973", fontcolor="#0d2973", label="0.49%\n415570"];
	47 [color="#0d3b74", URL="\ref st_validate_state", label="st_validate_state\n1.27% (0.00%)\n18629"];
	47 -> 48 [color="#0d3874", fontcolor="#0d3874", label="1.08%\n8599"];
	48 [color="#0d3874", URL="\ref update_raster_state", label="update_raster_state\n1.08% (0.10%)\n8599"];
	48 -> 51 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
	49 [color="#0d3674", URL="\ref tgsi_full_token_free", label="tgsi_full_token_free\n0.98% (0.98%)\n16326412"];
	50 [color="#0d3674", URL="\ref draw_set_rasterizer_state", label="draw_set_rasterizer_state\n0.98% (0.00%)\n8599"];
	50 -> 23 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
	51 [color="#0d3674", URL="\ref softpipe_bind_rasterizer_state", label="softpipe_bind_rasterizer_state\n0.98% (0.00%)\n8599"];
	51 -> 50 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
	52 [color="#0d3174", URL="\ref tgsi_align_128bit", label="tgsi_align_128bit\n0.78% (0.78%)\n16326381"];
	53 [color="#0d2f74", URL="\ref draw_vertex_fetch", label="draw_vertex_fetch\n0.68% (0.68%)\n415570"];
	}

	\enddot

	The graph above was generated by the <a href="http://code.google.com/p/jrfonseca/wiki/Gprof2Dot">gprof2dot.py script</a>.
	*/