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