OSDN Git Service

Merge branch 'mesa_7_7_branch'
[android-x86/external-mesa.git] / src / gallium / docs / source / cso / rasterizer.rst
1 .. _rasterizer:
2
3 Rasterizer
4 ==========
5
6 The rasterizer state controls the rendering of points, lines and triangles.
7 Attributes include polygon culling state, line width, line stipple,
8 multisample state, scissoring and flat/smooth shading.
9
10
11 Members
12 -------
13
14 flatshade
15     If set, the provoking vertex of each polygon is used to determine the
16     color of the entire polygon.  If not set, fragment colors will be
17     interpolated between the vertex colors.
18     Note that this is separate from the fragment shader input attributes
19     CONSTANT, LINEAR and PERSPECTIVE.  We need the flatshade state at
20     clipping time to determine how to set the color of new vertices.
21     Also note that the draw module can implement flat shading by copying
22     the provoking vertex color to all the other vertices in the primitive.
23
24 flatshade_first
25     Whether the first vertex should be the provoking vertex, for most
26     primitives. If not set, the last vertex is the provoking vertex.
27
28 light_twoside
29     If set, there are per-vertex back-facing colors.  The draw module
30     uses this state along with the front/back information to set the
31     final vertex colors prior to rasterization.
32
33 front_winding
34     Indicates the window order of front-facing polygons, either
35     PIPE_WINDING_CW or PIPE_WINDING_CCW
36 cull_mode
37     Indicates which polygons to cull, either PIPE_WINDING_NONE (cull no
38     polygons), PIPE_WINDING_CW (cull clockwise-winding polygons),
39     PIPE_WINDING_CCW (cull counter clockwise-winding polygons), or
40     PIPE_WINDING_BOTH (cull all polygons).
41
42 fill_cw
43     Indicates how to fill clockwise polygons, either PIPE_POLYGON_MODE_FILL,
44     PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT.
45 fill_ccw
46     Indicates how to fill counter clockwise polygons, either
47     PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT.
48
49 poly_stipple_enable
50     Whether polygon stippling is enabled.
51 poly_smooth
52     Controls OpenGL-style polygon smoothing/antialiasing
53 offset_cw
54     If set, clockwise polygons will have polygon offset factors applied
55 offset_ccw
56     If set, counter clockwise polygons will have polygon offset factors applied
57 offset_units
58     Specifies the polygon offset bias
59 offset_scale
60     Specifies the polygon offset scale
61
62 line_width
63     The width of lines.
64 line_smooth
65     Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
66 line_stipple_enable
67     Whether line stippling is enabled.
68 line_stipple_pattern
69     16-bit bitfield of on/off flags, used to pattern the line stipple.
70 line_stipple_factor
71     When drawinga stippled line, each bit in the stipple pattern is
72     repeated N times, where N = line_stipple_factor + 1.
73 line_last_pixel
74     Controls whether the last pixel in a line is drawn or not.  OpenGL
75     omits the last pixel to avoid double-drawing pixels at the ends of lines
76     when drawing connected lines.
77
78 point_smooth
79     Whether points should be smoothed. Point smoothing turns rectangular
80     points into circles or ovals.
81 point_size_per_vertex
82     Whether vertices have a point size element.
83 point_size
84     The size of points, if not specified per-vertex.
85 point_size_min
86     The minimum size of points.
87 point_size_max
88     The maximum size of points.
89 point_sprite
90     Whether points are drawn as sprites (textured quads)
91 sprite_coord_mode
92     Specifies how the value for each shader output should be computed when
93     drawing sprites.  If PIPE_SPRITE_COORD_NONE, don't change the vertex
94     shader output.  Otherwise, the four vertices of the resulting quad will
95     be assigned texture coordinates.  For PIPE_SPRITE_COORD_LOWER_LEFT, the
96     lower left vertex will have coordinate (0,0,0,1).
97     For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left vertex will have
98     coordinate (0,0,0,1).
99     This state is needed by the 'draw' module because that's where each
100     point vertex is converted into four quad vertices.  There's no other
101     place to emit the new vertex texture coordinates which are required for
102     sprite rendering.
103     Note that when geometry shaders are available, this state could be
104     removed.  A special geometry shader defined by the state tracker could
105     converts the incoming points into quads with the proper texture coords.
106
107 scissor
108     Whether the scissor test is enabled.
109
110 multisample
111     Whether :ref:`MSAA` is enabled.
112
113 bypass_vs_clip_and_viewport
114     Whether the entire TCL pipeline should be bypassed. This implies that
115     vertices are pre-transformed for the viewport, and will not be run
116     through the vertex shader. Note that implementations may still clip away
117     vertices that are not in the viewport.
118
119 gl_rasterization_rules
120     Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
121     the rasterizer will use (0, 0) for pixel centers.
122
123
124 Notes
125 -----
126
127 flatshade
128 ^^^^^^^^^
129
130 The actual interpolated shading algorithm is obviously
131 implementation-dependent, but will usually be Gourard for most hardware.
132
133 bypass_vs_clip_and_viewport
134 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
135
136 When set, this implies that vertices are pre-transformed for the viewport, and
137 will not be run through the vertex shader. Note that implementations may still
138 clip away vertices that are not visible.
139
140 flatshade_first
141 ^^^^^^^^^^^^^^^
142
143 There are several important exceptions to the specification of this rule.
144
145 * ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
146   vertex. If the caller wishes to change the provoking vertex, they merely
147   need to rotate the vertices themselves.
148 * ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: This option has no
149   effect; the provoking vertex is always the last vertex.
150 * ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
151   second vertex, not the first. This permits each segment of the fan to have
152   a different color.