doxygen/gallium.doc

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