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     - Cell driver (cell_context.h, cell_winsys.h)
  38     - \ref failover
  39
  40   - Winsys drivers:
  41     - X11 winsys driver (xm_winsys.c)
  42     - Intel DRI winsys driver (intel_context.h, intel_winsys_pipe.c)
  43
  44   - Ancillary Modules:
  45     - \ref draw
  46     - \ref tgsi
  47       - LLVM TGSI backend (gallivm.h)
  48
  49   - \ref callgraph
  50
  51   \section external External documentation
  52
  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>
  56
  57 */
  58
  59 /** \page overview Overview
  60
  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:
  64
  65   - Setting rendering state (texture sampler state, vertex array info, drawing surfaces, etc.)
  66
  67   - Setting shader state, using the TGSI binary shader representation.
  68
  69   - Vertex array and indexed vertex array drawing.
  70
  71   - Region (memory) management for textures, renderbuffers, vertex buffers, etc.
  72
  73   - Hardware queries (number of texture units, max texture size, etc).
  74
  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.
  81
  82   The p_defines.h header defines numerous constants and tokens (blend modes,
  83   texture wrap modes, surface formats, etc.
  84
  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.
  90
  91   By abstracting OS and window system services, pipe drivers are portable to
  92   other platforms (e.g. embedded devices).
  93 */
  94
  95 /** \page statetracker The State Tracker
  96
  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.
 101
 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.
 107
 108   Future state trackers will be created for OpenGL 3.0 and OpenGL-ES 2.x.
 109 */
 110
 111 /** \page softpipe Softpipe Driver
 112
 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.
 118
 119   \sa sp_winsys.h
 120 */
 121
 122 /** \page i915g i915 Driver
 123
 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.
 128
 129   \sa i915_context.h
 130   \sa i915_winsys.h
 131 */
 132
 133 /** \page failover Failover Module
 134
 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.
 140
 141   \sa fo_winsys.h
 142 */
 143
 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.
 151
 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:
 155
 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.
 161
 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.
 166
 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.
 172
 173   \sa draw_context.h
 174 */
 175
 176 /** \page tgsi TGSI
 177
 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.
 186
 187   \sa tgsi_parse.h
 188   \sa <a href="http://www.tungstengraphics.com/wiki/files/tgsi.pdf">TGSI specification</a>
 189 */
 190
 191 /** \page callgraph Glxgears callgraph example
 192
 193   Below is a call graph of the glxgears application together with the Gallium3D's softpipe reference driver.
 194
 195   \htmlonly
 196   The functions in the graph below are clickable.
 197   \endhtmlonly
 198
 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 }
 318
 319   \enddot
 320
 321   The graph above was generated by the <a href="http://code.google.com/p/jrfonseca/wiki/Gprof2Dot">gprof2dot.py script</a>.
 322 */