1/** \mainpage
2
3  \section about About
4
5  Gallium3D is <a href="http://www.tungstengraphics.com/">Tungsten Graphics</a>'
6  new architecture for building 3D graphics drivers. Initially
7  supporting Mesa and Linux graphics drivers, Gallium3D is designed to allow
8  portability to all major operating systems and graphics interfaces.
9
10  Compared to existing Linux graphics drivers, Gallium3D will:
11
12  - Make drivers smaller and simpler.
13    Current DRI drivers are rather complicated. They're large, contain
14    duplicated code and are burdened with implementing many concepts tightly
15    tied to the OpenGL 1.x/2.x API.
16
17  - Model modern graphics hardware.
18    The new driver architecture is an abstraction of modern graphics hardware,
19    rather than an OpenGL->hardware translator. The new driver interface will
20    assume the presence of programmable vertex/fragment shaders and flexible
21    memory objects.
22
23  - Support multiple graphics APIs.
24    The OpenGL 3.0 API will be very different from OpenGL 1.x/2.x. We'd like a
25    driver model that is API-neutral so that it's not tied to a specific
26    graphics API.
27
28  \section contents Contents
29
30  - \ref overview
31
32  - \ref statetracker
33
34  - Pipe drivers:
35    - \ref softpipe
36    - \ref i915g
37
38  - Winsys drivers:
39    - X11 winsys driver (xm_winsys.c)
40    - Intel DRI winsys driver (intel_context.h, intel_winsys_pipe.c)
41
42  - Ancillary Modules:
43    - \ref draw
44    - \ref tgsi
45      - LLVM TGSI backend (gallivm.h)
46
47  - \ref callgraph
48
49  \section external External documentation
50
51  - <a href="http://www.tungstengraphics.com/gallium3D.htm">Gallium3D's Architectural Overview</a>
52  - <a href="http://www.tungstengraphics.com/wiki/index.php/Gallium3D">Technical Overview</a>
53  - <a href="http://www.tungstengraphics.com/wiki/files/gallium3d-xds2007.pdf">Gallium3D talk from XDS 2007</a>
54
55*/
56
57/** \page overview Overview
58
59  The public interface of a Gallium3D driver is described by the p_context.h
60  header file. The pipe_context structure is an abstract base class with
61  methods for:
62
63  - Setting rendering state (texture sampler state, vertex array info, drawing surfaces, etc.)
64
65  - Setting shader state, using the TGSI binary shader representation.
66
67  - Vertex array and indexed vertex array drawing.
68
69  - Region (memory) management for textures, renderbuffers, vertex buffers, etc.
70
71  - Hardware queries (number of texture units, max texture size, etc).
72
73  The p_state.h header defines all the state objects (such as polygon
74  rasterization options, blend modes, etc) and resources (drawing surfaces,
75  textures, memory buffers). The pipe interface uses "constant state" objects.
76  That is, state objects are created once and are immutable. State objects are
77  put into effect by binding them. This allows Gallium3D drivers to create
78  corresponding hardware state objects which can be quickly handled.
79
80  The p_defines.h header defines numerous constants and tokens (blend modes,
81  texture wrap modes, surface formats, etc.
82
83  The p_winsys.h header defines the window system and OS facilities which
84  Gallium3D drivers rely upon. For example, memory allocation is typically a
85  service the OS provides while window size/position information is provided by
86  the window system. Pipe drivers use the winsys interface to handle these
87  things.
88
89  By abstracting OS and window system services, pipe drivers are portable to
90  other platforms (e.g. embedded devices).
91*/
92
93/** \page statetracker The State Tracker
94
95  The state tracker is the piece which interfaces core Mesa to the Gallium3D
96  interface. It's responsible for translating Mesa state (blend modes, texture
97  state, etc) and drawing commands (like glDrawArrays and glDrawPixels) into
98  pipe objects and operations.
99
100  Traditional fixed-function OpenGL components (such as lighting and texture
101  combining) are implemented with shaders. OpenGL commands such as glDrawPixels
102  are translated into textured quadrilateral rendering. Basically, any
103  rendering operation that isn't directly supported by modern graphics hardware
104  is translated into a hardware-friendly form.
105
106  Future state trackers will be created for OpenGL 3.0 and OpenGL-ES 2.x.
107*/
108
109/** \page softpipe Softpipe Driver
110
111  The softpipe driver is a software implementation of the Gallium3D interface.
112  It will be used as a reference implementation and as a fallback driver when a
113  hardware driver isn't available. The softpipe driver will make extensive use
114  of run-time code generation to efficiently execute vertex, fragment and
115  rasterization operations.
116
117  \sa sp_winsys.h
118*/
119
120/** \page i915g i915 Driver
121
122  The i915 Gallium3D Driver is an initial hardware driver implementation within
123  the Gallium3D driver architecture. We expect that once complete this driver
124  will have equivalent functionality and performance to the current Mesa
125  i915tex driver, but from a much smaller codebase.
126
127  \sa i915_context.h
128  \sa i915_winsys.h
129*/
130
131/** \page draw Draw Module
132  The Draw module provides point/line/polygon rendering services such as
133  vertex transformation, polygon culling and clipping. It will be used by
134  drivers for hardware which lacks vertex transformation (such as the
135  i915/i945). It may also be instantiated and used directly by the state
136  tracker to implement some API functionality that doesn't map well to hardware
137  capabilities.
138
139  The interface of this module corresponds closely to the subset of the Gallium
140  Driver Interface which is relevent to these steps in the pipeline. Specifically
141  there are calls for:
142
143  - Vertex shader constant state objects
144  - Vertex buffer binding
145  - Vertex element layout (vertex fetch) constant state objects
146  - DrawArrays and DrawElements
147  - Rasterizer constant state objects.
148
149  The Draw module is effectively the part of \ref softpipe which is concerned with
150  vertex processing, split off into a separate module so that it can be reused
151  by drivers for rasterization-only hardware. As such it is also instantiated
152  by the \ref i915g driver.
153
154  Additionally, there are cases in the Mesa OpenGL state_tracker where it is
155  required to obtain transformed vertices and yet it is anticipated that using
156  hardware transformation even if available would reduce performance, usually
157  because the setup costs or latency are prohibitive. For this reason the Mesa
158  state_tracker also instantiates a copy of this module.
159
160  \sa draw_context.h
161*/
162
163/** \page tgsi TGSI
164
165  The TGSI module provides a universal representation of shaders and
166  CPU-based execution of shaders. All Mesa vertex/fragment programs and shaders
167  are translated into the TGSI representation before being passed to the
168  driver. In turn, the driver will convert the TGSI instructions into
169  GPU-specific instructions. For hardware that lacks vertex or fragment shader
170  support, the TGSI's executor can be used. The TGSI executor includes support
171  for SSE code generation. Support for other processors (such as Cell) will be
172  added in the future.
173
174  \sa tgsi_parse.h
175  \sa <a href="http://www.tungstengraphics.com/wiki/files/tgsi.pdf">TGSI specification</a>
176*/
177
178/** \page callgraph Glxgears callgraph example
179
180  Below is a call graph of the glxgears application together with the Gallium3D's softpipe reference driver.
181
182  \htmlonly
183  The functions in the graph below are clickable.
184  \endhtmlonly
185
186  \dot
187digraph {
188	graph [fontname=Arial, fontsize=10];
189	node [fontcolor=white, fontname=Arial, style=filled, fontsize=10, shape=box];
190	edge [fontname=Arial, fontsize=10];
191	1 [color="#ff0000", URL="\ref main", label="main\n100.00% (0.68%)\n0"];
192	1 -> 2 [color="#fe0400", fontcolor="#fe0400", label="99.32%\n1433"];
193	2 [color="#fe0400", URL="\ref do_draw", label="do_draw\n99.32% (0.00%)\n1433"];
194	2 -> 4 [color="#fa1201", fontcolor="#fa1201", label="96.67%\n4298"];
195	2 -> 39 [color="#0d4f76", fontcolor="#0d4f76", label="2.45%\n1433"];
196	3 [color="#fa1201", URL="\ref execute_list", label="execute_list\n96.67% (0.00%)\n4299"];
197	3 -> 5 [color="#f91301", fontcolor="#f91301", label="96.38%\n17196"];
198	4 [color="#fa1201", URL="\ref _mesa_CallList", label="_mesa_CallList\n96.67% (0.00%)\n4299"];
199	4 -> 3 [color="#fa1201", fontcolor="#fa1201", label="96.67%\n4299"];
200	5 [color="#f91301", URL="\ref vbo_save_playback_vertex_list", label="vbo_save_playback_vertex_list\n96.38% (0.10%)\n17196"];
201	5 -> 6 [color="#f91501", fontcolor="#f91501", label="96.09%\n17196"];
202	6 [color="#f91501", URL="\ref st_draw_vbo", label="st_draw_vbo\n96.09% (0.00%)\n17196"];
203	6 -> 10 [color="#ec3f03", fontcolor="#ec3f03", label="87.48%\n30093"];
204	6 -> 33 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
205	6 -> 34 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
206	6 -> 47 [color="#0d3a74", fontcolor="#0d3a74", label="1.17%\n17196"];
207	7 [color="#f71d01", URL="\ref draw_do_flush", label="draw_do_flush\n94.52% (0.20%)\n101744"];
208	7 -> 13 [color="#e74e04", fontcolor="#e74e04", label="84.25%\n1146400"];
209	7 -> 8 [color="#0d7d6c", fontcolor="#0d7d6c", label="8.32%\n114640"];
210	7 -> 46 [color="#0d4175", fontcolor="#0d4175", label="1.57%\n97444"];
211	8 [color="#f32702", URL="\ref clip_tri", label="clip_tri\n92.37% (0.49%)\n1261040"];
212	8 -> 9 [color="#f32a02", fontcolor="#f32a02", label="91.88%\n1261040"];
213	9 [color="#f32a02", URL="\ref cull_tri", label="cull_tri\n91.88% (0.20%)\n1261040"];
214	9 -> 15 [color="#e35d04", fontcolor="#e35d04", label="81.12%\n560810"];
215	9 -> 12 [color="#0d805e", fontcolor="#0d805e", label="10.57%\n560810"];
216	10 [color="#ec3f03", URL="\ref softpipe_draw_arrays", label="softpipe_draw_arrays\n87.48% (0.00%)\n30093"];
217	10 -> 11 [color="#ec3f03", fontcolor="#ec3f03", label="87.48%\n30093"];
218	11 [color="#ec3f03", URL="\ref softpipe_draw_elements", label="softpipe_draw_elements\n87.48% (0.10%)\n30093"];
219	11 -> 17 [color="#cf9507", fontcolor="#cf9507", label="67.61%\n30093"];
220	11 -> 27 [color="#0d844f", fontcolor="#0d844f", label="13.01%\n120372"];
221	11 -> 36 [color="#0d5a77", fontcolor="#0d5a77", label="3.33%\n30093"];
222	11 -> 23 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n30093"];
223	12 [color="#ea4703", URL="\ref flush_spans", label="flush_spans\n85.91% (4.60%)\n4586176"];
224	12 -> 14 [color="#e35c04", fontcolor="#e35c04", label="81.31%\n15910811"];
225	13 [color="#e74e04", URL="\ref flatshade_tri", label="flatshade_tri\n84.25% (0.29%)\n1146400"];
226	13 -> 8 [color="#e75004", fontcolor="#e75004", label="83.95%\n1146400"];
227	14 [color="#e35c04", URL="\ref shade_quad", label="shade_quad\n81.31% (7.73%)\n15910811"];
228	14 -> 21 [color="#c0bb09", fontcolor="#c0bb09", label="57.24%\n13903725"];
229	14 -> 26 [color="#0c883c", fontcolor="#0c883c", label="16.24%\n15910811"];
230	15 [color="#e35d04", URL="\ref setup_tri", label="setup_tri\n81.12% (1.47%)\n560810"];
231	15 -> 16 [color="#e06505", fontcolor="#e06505", label="79.26%\n1121620"];
232	16 [color="#e06505", URL="\ref subtriangle", label="subtriangle\n79.26% (3.91%)\n1121620"];
233	16 -> 12 [color="#da7606", fontcolor="#da7606", label="75.34%\n4025366"];
234	17 [color="#cf9507", URL="\ref draw_arrays", label="draw_arrays\n67.61% (0.00%)\n30093"];
235	17 -> 19 [color="#cf9607", fontcolor="#cf9607", label="67.42%\n630520"];
236	18 [color="#cf9607", URL="\ref do_ef_triangle", label="do_ef_triangle\n67.42% (0.49%)\n1261040"];
237	18 -> 20 [color="#ce9807", fontcolor="#ce9807", label="66.83%\n1261040"];
238	19 [color="#cf9607", URL="\ref do_quad", label="do_quad\n67.42% (0.00%)\n630520"];
239	19 -> 18 [color="#cf9607", fontcolor="#cf9607", label="67.42%\n1261040"];
240	20 [color="#ce9807", URL="\ref get_queued_prim", label="get_queued_prim\n66.83% (0.10%)\n1261040"];
241	20 -> 7 [color="#cd9907", fontcolor="#cd9907", label="66.54%\n71650"];
242	21 [color="#c0bb09", URL="\ref depth_test_quad", label="depth_test_quad\n57.24% (1.08%)\n13903725"];
243	21 -> 22 [color="#40a00b", fontcolor="#40a00b", label="34.54%\n13074127"];
244	21 -> 24 [color="#0c8f1e", fontcolor="#0c8f1e", label="21.62%\n13903725"];
245	22 [color="#40a00b", URL="\ref output_quad", label="output_quad\n34.54% (3.91%)\n13074127"];
246	22 -> 25 [color="#0c8c2b", fontcolor="#0c8c2b", label="19.28%\n13074127"];
247	22 -> 28 [color="#0d8159", fontcolor="#0d8159", label="11.35%\n7223435"];
248	23 [color="#1c970c", URL="\ref draw_flush", label="draw_flush\n27.98% (0.00%)\n257944"];
249	23 -> 7 [color="#1c970c", fontcolor="#1c970c", label="27.98%\n30093"];
250	24 [color="#0c8f1e", URL="\ref sp_depth_test_quad", label="sp_depth_test_quad\n21.62% (16.14%)\n13903725"];
251	24 -> 37 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n13903725"];
252	24 -> 44 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n13903725"];
253	25 [color="#0c8c2b", URL="\ref write_quad_f_swz", label="write_quad_f_swz\n19.28% (16.14%)\n13074127"];
254	25 -> 38 [color="#0d5877", fontcolor="#0d5877", label="3.13%\n26148254"];
255	26 [color="#0c883a", URL="\ref tgsi_exec_machine_init", label="tgsi_exec_machine_init\n16.73% (10.27%)\n16326381"];
256	26 -> 30 [color="#0d6178", fontcolor="#0d6178", label="3.91%\n16326381"];
257	26 -> 45 [color="#0d4475", fontcolor="#0d4475", label="1.76%\n16326381"];
258	26 -> 52 [color="#0d3174", fontcolor="#0d3174", label="0.78%\n16326381"];
259	27 [color="#0d844f", URL="\ref draw_set_mapped_vertex_buffer", label="draw_set_mapped_vertex_buffer\n13.01% (0.00%)\n120372"];
260	27 -> 23 [color="#0d844f", fontcolor="#0d844f", label="13.01%\n120372"];
261	28 [color="#0d8159", URL="\ref read_quad_f_swz", label="read_quad_f_swz\n11.35% (5.87%)\n7223435"];
262	28 -> 29 [color="#0d737a", fontcolor="#0d737a", label="5.48%\n14446870"];
263	29 [color="#0d737a", URL="\ref get_row_rgba", label="get_row_rgba\n5.48% (5.48%)\n14446870"];
264	30 [color="#0d6178", URL="\ref tgsi_parse_init", label="tgsi_parse_init\n3.91% (3.52%)\n16326383"];
265	31 [color="#0d5f78", URL="\ref draw_set_vertex_buffer", label="draw_set_vertex_buffer\n3.72% (0.00%)\n34392"];
266	31 -> 23 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
267	32 [color="#0d5f78", URL="\ref draw_set_vertex_element", label="draw_set_vertex_element\n3.72% (0.00%)\n34392"];
268	32 -> 23 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
269	33 [color="#0d5f78", URL="\ref softpipe_set_vertex_buffer", label="softpipe_set_vertex_buffer\n3.72% (0.00%)\n34392"];
270	33 -> 31 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
271	34 [color="#0d5f78", URL="\ref softpipe_set_vertex_element", label="softpipe_set_vertex_element\n3.72% (0.00%)\n34392"];
272	34 -> 32 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
273	35 [color="#0d5d77", URL="\ref __i686.get_pc_thunk.bx", label="__i686.get_pc_thunk.bx\n3.52% (3.52%)\n0"];
274	36 [color="#0d5a77", URL="\ref draw_set_mapped_constant_buffer", label="draw_set_mapped_constant_buffer\n3.33% (0.10%)\n30093"];
275	36 -> 23 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n30093"];
276	37 [color="#0d5977", URL="\ref s8z24_read_quad_z", label="s8z24_read_quad_z\n3.23% (3.23%)\n13903725"];
277	38 [color="#0d5877", URL="\ref put_row_8R8G8B_ximage", label="put_row_8R8G8B_ximage\n3.13% (3.13%)\n26148254"];
278	39 [color="#0d4f76", URL="\ref _mesa_Clear", label="_mesa_Clear\n2.45% (0.00%)\n1433"];
279	39 -> 40 [color="#0d4f76", fontcolor="#0d4f76", label="2.45%\n1433"];
280	40 [color="#0d4f76", URL="\ref st_clear", label="st_clear\n2.45% (0.00%)\n1433"];
281	40 -> 41 [color="#0d4d76", fontcolor="#0d4d76", label="2.35%\n2866"];
282	41 [color="#0d4d76", URL="\ref xmesa_clear", label="xmesa_clear\n2.35% (0.00%)\n2866"];
283	41 -> 42 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n1433"];
284	42 [color="#0d4c76", URL="\ref softpipe_clear", label="softpipe_clear\n2.25% (0.00%)\n1433"];
285	42 -> 43 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n1433"];
286	43 [color="#0d4c76", URL="\ref sp_region_fill", label="sp_region_fill\n2.25% (2.25%)\n1433"];
287	44 [color="#0d4c76", URL="\ref s8z24_write_quad_z", label="s8z24_write_quad_z\n2.25% (2.25%)\n13903725"];
288	45 [color="#0d4475", URL="\ref tgsi_parse_free", label="tgsi_parse_free\n1.76% (0.78%)\n16326383"];
289	45 -> 49 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n16326383"];
290	46 [color="#0d4175", URL="\ref draw_vertex_shader_queue_flush", label="draw_vertex_shader_queue_flush\n1.57% (0.49%)\n97444"];
291	46 -> 53 [color="#0d2f74", fontcolor="#0d2f74", label="0.68%\n415570"];
292	46 -> 26 [color="#0d2973", fontcolor="#0d2973", label="0.49%\n415570"];
293	47 [color="#0d3b74", URL="\ref st_validate_state", label="st_validate_state\n1.27% (0.00%)\n18629"];
294	47 -> 48 [color="#0d3874", fontcolor="#0d3874", label="1.08%\n8599"];
295	48 [color="#0d3874", URL="\ref update_raster_state", label="update_raster_state\n1.08% (0.10%)\n8599"];
296	48 -> 51 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
297	49 [color="#0d3674", URL="\ref tgsi_full_token_free", label="tgsi_full_token_free\n0.98% (0.98%)\n16326412"];
298	50 [color="#0d3674", URL="\ref draw_set_rasterizer_state", label="draw_set_rasterizer_state\n0.98% (0.00%)\n8599"];
299	50 -> 23 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
300	51 [color="#0d3674", URL="\ref softpipe_bind_rasterizer_state", label="softpipe_bind_rasterizer_state\n0.98% (0.00%)\n8599"];
301	51 -> 50 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
302	52 [color="#0d3174", URL="\ref tgsi_align_128bit", label="tgsi_align_128bit\n0.78% (0.78%)\n16326381"];
303	53 [color="#0d2f74", URL="\ref draw_vertex_fetch", label="draw_vertex_fetch\n0.68% (0.68%)\n415570"];
304}
305
306  \enddot
307
308  The graph above was generated by the <a href="http://code.google.com/p/jrfonseca/wiki/Gprof2Dot">gprof2dot.py script</a>.
309*/
310