/** \mainpage
\section about About
Gallium3D is Tungsten Graphics'
new architecture for building 3D graphics drivers. Initially
supporting Mesa and Linux graphics drivers, Gallium3D is designed to allow
portability to all major operating systems and graphics interfaces.
Compared to existing Linux graphics drivers, Gallium3D will:
- Make drivers smaller and simpler.
Current DRI drivers are rather complicated. They're large, contain
duplicated code and are burdened with implementing many concepts tightly
tied to the OpenGL 1.x/2.x API.
- Model modern graphics hardware.
The new driver architecture is an abstraction of modern graphics hardware,
rather than an OpenGL->hardware translator. The new driver interface will
assume the presence of programmable vertex/fragment shaders and flexible
memory objects.
- Support multiple graphics APIs.
The OpenGL 3.0 API will be very different from OpenGL 1.x/2.x. We'd like a
driver model that is API-neutral so that it's not tied to a specific
graphics API.
\section contents Contents
- \ref overview
- \ref statetracker
- Pipe drivers:
- \ref softpipe
- \ref i915g
- Cell driver (cell_context.h, cell_winsys.h)
- \ref failover
- Winsys drivers:
- X11 winsys driver (xm_winsys.c)
- Intel DRI winsys driver (intel_context.h, intel_winsys_pipe.c)
- Ancillary Modules:
- \ref draw
- \ref tgsi
- LLVM TGSI backend (gallivm.h)
- \ref callgraph
\section external External documentation
- Gallium3D's Architectural Overview
- Technical Overview
- Gallium3D talk from XDS 2007
*/
/** \page overview Overview
The public interface of a Gallium3D driver is described by the p_context.h
header file. The pipe_context structure is an abstract base class with
methods for:
- Setting rendering state (texture sampler state, vertex array info, drawing surfaces, etc.)
- Setting shader state, using the TGSI binary shader representation.
- Vertex array and indexed vertex array drawing.
- Region (memory) management for textures, renderbuffers, vertex buffers, etc.
- Hardware queries (number of texture units, max texture size, etc).
The p_state.h header defines all the state objects (such as polygon
rasterization options, blend modes, etc) and resources (drawing surfaces,
textures, memory buffers). The pipe interface uses "constant state" objects.
That is, state objects are created once and are immutable. State objects are
put into effect by binding them. This allows Gallium3D drivers to create
corresponding hardware state objects which can be quickly handled.
The p_defines.h header defines numerous constants and tokens (blend modes,
texture wrap modes, surface formats, etc.
The p_winsys.h header defines the window system and OS facilities which
Gallium3D drivers rely upon. For example, memory allocation is typically a
service the OS provides while window size/position information is provided by
the window system. Pipe drivers use the winsys interface to handle these
things.
By abstracting OS and window system services, pipe drivers are portable to
other platforms (e.g. embedded devices).
*/
/** \page statetracker The State Tracker
The state tracker is the piece which interfaces core Mesa to the Gallium3D
interface. It's responsible for translating Mesa state (blend modes, texture
state, etc) and drawing commands (like glDrawArrays and glDrawPixels) into
pipe objects and operations.
Traditional fixed-function OpenGL components (such as lighting and texture
combining) are implemented with shaders. OpenGL commands such as glDrawPixels
are translated into textured quadrilateral rendering. Basically, any
rendering operation that isn't directly supported by modern graphics hardware
is translated into a hardware-friendly form.
Future state trackers will be created for OpenGL 3.0 and OpenGL-ES 2.x.
*/
/** \page softpipe Softpipe Driver
The softpipe driver is a software implementation of the Gallium3D interface.
It will be used as a reference implementation and as a fallback driver when a
hardware driver isn't available. The softpipe driver will make extensive use
of run-time code generation to efficiently execute vertex, fragment and
rasterization operations.
\sa sp_winsys.h
*/
/** \page i915g i915 Driver
The i915 Gallium3D Driver is an initial hardware driver implementation within
the Gallium3D driver architecture. We expect that once complete this driver
will have equivalent functionality and performance to the current Mesa
i915tex driver, but from a much smaller codebase.
\sa i915_context.h
\sa i915_winsys.h
*/
/** \page failover Failover Module
The failover module acts as a selector between a hardware driver and the
softpipe driver. When the hardware can't implement a particular rendering
operation, the failover module will pass the request to the softpipe driver.
This is a different solution to the "software fallbacks" scheme of previous
Mesa drivers.
\sa fo_winsys.h
*/
/** \page draw Draw Module
The Draw module provides point/line/polygon rendering services such as
vertex transformation, polygon culling and clipping. It will be used by
drivers for hardware which lacks vertex transformation (such as the
i915/i945). It may also be instantiated and used directly by the state
tracker to implement some API functionality that doesn't map well to hardware
capabilities.
The interface of this module corresponds closely to the subset of the Gallium
Driver Interface which is relevent to these steps in the pipeline. Specifically
there are calls for:
- Vertex shader constant state objects
- Vertex buffer binding
- Vertex element layout (vertex fetch) constant state objects
- DrawArrays and DrawElements
- Rasterizer constant state objects.
The Draw module is effectively the part of \ref softpipe which is concerned with
vertex processing, split off into a separate module so that it can be reused
by drivers for rasterization-only hardware. As such it is also instantiated
by the \ref i915g driver.
Additionally, there are cases in the Mesa OpenGL state_tracker where it is
required to obtain transformed vertices and yet it is anticipated that using
hardware transformation even if available would reduce performance, usually
because the setup costs or latency are prohibitive. For this reason the Mesa
state_tracker also instantiates a copy of this module.
\sa draw_context.h
*/
/** \page tgsi TGSI
The TGSI module provides a universal representation of shaders and
CPU-based execution of shaders. All Mesa vertex/fragment programs and shaders
are translated into the TGSI representation before being passed to the
driver. In turn, the driver will convert the TGSI instructions into
GPU-specific instructions. For hardware that lacks vertex or fragment shader
support, the TGSI's executor can be used. The TGSI executor includes support
for SSE code generation. Support for other processors (such as Cell) will be
added in the future.
\sa tgsi_parse.h
\sa TGSI specification
*/
/** \page callgraph Glxgears callgraph example
Below is a call graph of the glxgears application together with the Gallium3D's softpipe reference driver.
\htmlonly
The functions in the graph below are clickable.
\endhtmlonly
\dot
digraph {
graph [fontname=Arial, fontsize=10];
node [fontcolor=white, fontname=Arial, style=filled, fontsize=10, shape=box];
edge [fontname=Arial, fontsize=10];
1 [color="#ff0000", URL="\ref main", label="main\n100.00% (0.68%)\n0"];
1 -> 2 [color="#fe0400", fontcolor="#fe0400", label="99.32%\n1433"];
2 [color="#fe0400", URL="\ref do_draw", label="do_draw\n99.32% (0.00%)\n1433"];
2 -> 4 [color="#fa1201", fontcolor="#fa1201", label="96.67%\n4298"];
2 -> 39 [color="#0d4f76", fontcolor="#0d4f76", label="2.45%\n1433"];
3 [color="#fa1201", URL="\ref execute_list", label="execute_list\n96.67% (0.00%)\n4299"];
3 -> 5 [color="#f91301", fontcolor="#f91301", label="96.38%\n17196"];
4 [color="#fa1201", URL="\ref _mesa_CallList", label="_mesa_CallList\n96.67% (0.00%)\n4299"];
4 -> 3 [color="#fa1201", fontcolor="#fa1201", label="96.67%\n4299"];
5 [color="#f91301", URL="\ref vbo_save_playback_vertex_list", label="vbo_save_playback_vertex_list\n96.38% (0.10%)\n17196"];
5 -> 6 [color="#f91501", fontcolor="#f91501", label="96.09%\n17196"];
6 [color="#f91501", URL="\ref st_draw_vbo", label="st_draw_vbo\n96.09% (0.00%)\n17196"];
6 -> 10 [color="#ec3f03", fontcolor="#ec3f03", label="87.48%\n30093"];
6 -> 33 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
6 -> 34 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
6 -> 47 [color="#0d3a74", fontcolor="#0d3a74", label="1.17%\n17196"];
7 [color="#f71d01", URL="\ref draw_do_flush", label="draw_do_flush\n94.52% (0.20%)\n101744"];
7 -> 13 [color="#e74e04", fontcolor="#e74e04", label="84.25%\n1146400"];
7 -> 8 [color="#0d7d6c", fontcolor="#0d7d6c", label="8.32%\n114640"];
7 -> 46 [color="#0d4175", fontcolor="#0d4175", label="1.57%\n97444"];
8 [color="#f32702", URL="\ref clip_tri", label="clip_tri\n92.37% (0.49%)\n1261040"];
8 -> 9 [color="#f32a02", fontcolor="#f32a02", label="91.88%\n1261040"];
9 [color="#f32a02", URL="\ref cull_tri", label="cull_tri\n91.88% (0.20%)\n1261040"];
9 -> 15 [color="#e35d04", fontcolor="#e35d04", label="81.12%\n560810"];
9 -> 12 [color="#0d805e", fontcolor="#0d805e", label="10.57%\n560810"];
10 [color="#ec3f03", URL="\ref softpipe_draw_arrays", label="softpipe_draw_arrays\n87.48% (0.00%)\n30093"];
10 -> 11 [color="#ec3f03", fontcolor="#ec3f03", label="87.48%\n30093"];
11 [color="#ec3f03", URL="\ref softpipe_draw_elements", label="softpipe_draw_elements\n87.48% (0.10%)\n30093"];
11 -> 17 [color="#cf9507", fontcolor="#cf9507", label="67.61%\n30093"];
11 -> 27 [color="#0d844f", fontcolor="#0d844f", label="13.01%\n120372"];
11 -> 36 [color="#0d5a77", fontcolor="#0d5a77", label="3.33%\n30093"];
11 -> 23 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n30093"];
12 [color="#ea4703", URL="\ref flush_spans", label="flush_spans\n85.91% (4.60%)\n4586176"];
12 -> 14 [color="#e35c04", fontcolor="#e35c04", label="81.31%\n15910811"];
13 [color="#e74e04", URL="\ref flatshade_tri", label="flatshade_tri\n84.25% (0.29%)\n1146400"];
13 -> 8 [color="#e75004", fontcolor="#e75004", label="83.95%\n1146400"];
14 [color="#e35c04", URL="\ref shade_quad", label="shade_quad\n81.31% (7.73%)\n15910811"];
14 -> 21 [color="#c0bb09", fontcolor="#c0bb09", label="57.24%\n13903725"];
14 -> 26 [color="#0c883c", fontcolor="#0c883c", label="16.24%\n15910811"];
15 [color="#e35d04", URL="\ref setup_tri", label="setup_tri\n81.12% (1.47%)\n560810"];
15 -> 16 [color="#e06505", fontcolor="#e06505", label="79.26%\n1121620"];
16 [color="#e06505", URL="\ref subtriangle", label="subtriangle\n79.26% (3.91%)\n1121620"];
16 -> 12 [color="#da7606", fontcolor="#da7606", label="75.34%\n4025366"];
17 [color="#cf9507", URL="\ref draw_arrays", label="draw_arrays\n67.61% (0.00%)\n30093"];
17 -> 19 [color="#cf9607", fontcolor="#cf9607", label="67.42%\n630520"];
18 [color="#cf9607", URL="\ref do_ef_triangle", label="do_ef_triangle\n67.42% (0.49%)\n1261040"];
18 -> 20 [color="#ce9807", fontcolor="#ce9807", label="66.83%\n1261040"];
19 [color="#cf9607", URL="\ref do_quad", label="do_quad\n67.42% (0.00%)\n630520"];
19 -> 18 [color="#cf9607", fontcolor="#cf9607", label="67.42%\n1261040"];
20 [color="#ce9807", URL="\ref get_queued_prim", label="get_queued_prim\n66.83% (0.10%)\n1261040"];
20 -> 7 [color="#cd9907", fontcolor="#cd9907", label="66.54%\n71650"];
21 [color="#c0bb09", URL="\ref depth_test_quad", label="depth_test_quad\n57.24% (1.08%)\n13903725"];
21 -> 22 [color="#40a00b", fontcolor="#40a00b", label="34.54%\n13074127"];
21 -> 24 [color="#0c8f1e", fontcolor="#0c8f1e", label="21.62%\n13903725"];
22 [color="#40a00b", URL="\ref output_quad", label="output_quad\n34.54% (3.91%)\n13074127"];
22 -> 25 [color="#0c8c2b", fontcolor="#0c8c2b", label="19.28%\n13074127"];
22 -> 28 [color="#0d8159", fontcolor="#0d8159", label="11.35%\n7223435"];
23 [color="#1c970c", URL="\ref draw_flush", label="draw_flush\n27.98% (0.00%)\n257944"];
23 -> 7 [color="#1c970c", fontcolor="#1c970c", label="27.98%\n30093"];
24 [color="#0c8f1e", URL="\ref sp_depth_test_quad", label="sp_depth_test_quad\n21.62% (16.14%)\n13903725"];
24 -> 37 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n13903725"];
24 -> 44 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n13903725"];
25 [color="#0c8c2b", URL="\ref write_quad_f_swz", label="write_quad_f_swz\n19.28% (16.14%)\n13074127"];
25 -> 38 [color="#0d5877", fontcolor="#0d5877", label="3.13%\n26148254"];
26 [color="#0c883a", URL="\ref tgsi_exec_machine_init", label="tgsi_exec_machine_init\n16.73% (10.27%)\n16326381"];
26 -> 30 [color="#0d6178", fontcolor="#0d6178", label="3.91%\n16326381"];
26 -> 45 [color="#0d4475", fontcolor="#0d4475", label="1.76%\n16326381"];
26 -> 52 [color="#0d3174", fontcolor="#0d3174", label="0.78%\n16326381"];
27 [color="#0d844f", URL="\ref draw_set_mapped_vertex_buffer", label="draw_set_mapped_vertex_buffer\n13.01% (0.00%)\n120372"];
27 -> 23 [color="#0d844f", fontcolor="#0d844f", label="13.01%\n120372"];
28 [color="#0d8159", URL="\ref read_quad_f_swz", label="read_quad_f_swz\n11.35% (5.87%)\n7223435"];
28 -> 29 [color="#0d737a", fontcolor="#0d737a", label="5.48%\n14446870"];
29 [color="#0d737a", URL="\ref get_row_rgba", label="get_row_rgba\n5.48% (5.48%)\n14446870"];
30 [color="#0d6178", URL="\ref tgsi_parse_init", label="tgsi_parse_init\n3.91% (3.52%)\n16326383"];
31 [color="#0d5f78", URL="\ref draw_set_vertex_buffer", label="draw_set_vertex_buffer\n3.72% (0.00%)\n34392"];
31 -> 23 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
32 [color="#0d5f78", URL="\ref draw_set_vertex_element", label="draw_set_vertex_element\n3.72% (0.00%)\n34392"];
32 -> 23 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
33 [color="#0d5f78", URL="\ref softpipe_set_vertex_buffer", label="softpipe_set_vertex_buffer\n3.72% (0.00%)\n34392"];
33 -> 31 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
34 [color="#0d5f78", URL="\ref softpipe_set_vertex_element", label="softpipe_set_vertex_element\n3.72% (0.00%)\n34392"];
34 -> 32 [color="#0d5f78", fontcolor="#0d5f78", label="3.72%\n34392"];
35 [color="#0d5d77", URL="\ref __i686.get_pc_thunk.bx", label="__i686.get_pc_thunk.bx\n3.52% (3.52%)\n0"];
36 [color="#0d5a77", URL="\ref draw_set_mapped_constant_buffer", label="draw_set_mapped_constant_buffer\n3.33% (0.10%)\n30093"];
36 -> 23 [color="#0d5977", fontcolor="#0d5977", label="3.23%\n30093"];
37 [color="#0d5977", URL="\ref s8z24_read_quad_z", label="s8z24_read_quad_z\n3.23% (3.23%)\n13903725"];
38 [color="#0d5877", URL="\ref put_row_8R8G8B_ximage", label="put_row_8R8G8B_ximage\n3.13% (3.13%)\n26148254"];
39 [color="#0d4f76", URL="\ref _mesa_Clear", label="_mesa_Clear\n2.45% (0.00%)\n1433"];
39 -> 40 [color="#0d4f76", fontcolor="#0d4f76", label="2.45%\n1433"];
40 [color="#0d4f76", URL="\ref st_clear", label="st_clear\n2.45% (0.00%)\n1433"];
40 -> 41 [color="#0d4d76", fontcolor="#0d4d76", label="2.35%\n2866"];
41 [color="#0d4d76", URL="\ref xmesa_clear", label="xmesa_clear\n2.35% (0.00%)\n2866"];
41 -> 42 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n1433"];
42 [color="#0d4c76", URL="\ref softpipe_clear", label="softpipe_clear\n2.25% (0.00%)\n1433"];
42 -> 43 [color="#0d4c76", fontcolor="#0d4c76", label="2.25%\n1433"];
43 [color="#0d4c76", URL="\ref sp_region_fill", label="sp_region_fill\n2.25% (2.25%)\n1433"];
44 [color="#0d4c76", URL="\ref s8z24_write_quad_z", label="s8z24_write_quad_z\n2.25% (2.25%)\n13903725"];
45 [color="#0d4475", URL="\ref tgsi_parse_free", label="tgsi_parse_free\n1.76% (0.78%)\n16326383"];
45 -> 49 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n16326383"];
46 [color="#0d4175", URL="\ref draw_vertex_shader_queue_flush", label="draw_vertex_shader_queue_flush\n1.57% (0.49%)\n97444"];
46 -> 53 [color="#0d2f74", fontcolor="#0d2f74", label="0.68%\n415570"];
46 -> 26 [color="#0d2973", fontcolor="#0d2973", label="0.49%\n415570"];
47 [color="#0d3b74", URL="\ref st_validate_state", label="st_validate_state\n1.27% (0.00%)\n18629"];
47 -> 48 [color="#0d3874", fontcolor="#0d3874", label="1.08%\n8599"];
48 [color="#0d3874", URL="\ref update_raster_state", label="update_raster_state\n1.08% (0.10%)\n8599"];
48 -> 51 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
49 [color="#0d3674", URL="\ref tgsi_full_token_free", label="tgsi_full_token_free\n0.98% (0.98%)\n16326412"];
50 [color="#0d3674", URL="\ref draw_set_rasterizer_state", label="draw_set_rasterizer_state\n0.98% (0.00%)\n8599"];
50 -> 23 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
51 [color="#0d3674", URL="\ref softpipe_bind_rasterizer_state", label="softpipe_bind_rasterizer_state\n0.98% (0.00%)\n8599"];
51 -> 50 [color="#0d3674", fontcolor="#0d3674", label="0.98%\n8599"];
52 [color="#0d3174", URL="\ref tgsi_align_128bit", label="tgsi_align_128bit\n0.78% (0.78%)\n16326381"];
53 [color="#0d2f74", URL="\ref draw_vertex_fetch", label="draw_vertex_fetch\n0.68% (0.68%)\n415570"];
}
\enddot
The graph above was generated by the gprof2dot.py script.
*/