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 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
 187 digraph {
 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 */