blob: efc6db016c3254842af9011fadfe5a48a60b0b2c [file] [log] [blame]
José Fonsecaf971bdc2007-09-28 18:48:15 +01001/** \mainpage
2
José Fonseca87e35662007-12-11 18:10:41 +00003 \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
Zack Rusin59ae3d52009-10-06 12:38:47 -040036 - \ref i915g
José Fonseca87e35662007-12-11 18:10:41 +000037
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>
José Fonsecaf971bdc2007-09-28 18:48:15 +010054
55*/
56
José Fonseca87e35662007-12-11 18:10:41 +000057/** \page overview Overview
José Fonsecaf971bdc2007-09-28 18:48:15 +010058
José Fonseca87e35662007-12-11 18:10:41 +000059 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.
José Fonsecaf971bdc2007-09-28 18:48:15 +0100116
José Fonseca87e35662007-12-11 18:10:41 +0000117 \sa sp_winsys.h
118*/
José Fonsecaf971bdc2007-09-28 18:48:15 +0100119
Zack Rusin59ae3d52009-10-06 12:38:47 -0400120/** \page i915g i915 Driver
José Fonseca87e35662007-12-11 18:10:41 +0000121
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
José Fonseca25e658a2007-12-11 18:18:25 +0000127 \sa i915_context.h
José Fonseca87e35662007-12-11 18:10:41 +0000128 \sa i915_winsys.h
129*/
130
José Fonseca87e35662007-12-11 18:10:41 +0000131/** \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
Zack Rusin59ae3d52009-10-06 12:38:47 -0400152 by the \ref i915g driver.
José Fonseca87e35662007-12-11 18:10:41 +0000153
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
José Fonsecaf971bdc2007-09-28 18:48:15 +0100186 \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
José Fonseca87e35662007-12-11 18:10:41 +0000308 The graph above was generated by the <a href="http://code.google.com/p/jrfonseca/wiki/Gprof2Dot">gprof2dot.py script</a>.
309*/