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