gallium: Add a new clip_halfz rasterizer state.
[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 Linkage
11
12 clamp_vertex_color
13 ^^^^^^^^^^^^^^^^^^
14
15 If set, TGSI_SEMANTIC_COLOR registers are clamped to the [0, 1] range after
16 the execution of the vertex shader, before being passed to the geometry
17 shader or fragment shader.
18
19 OpenGL: glClampColor(GL_CLAMP_VERTEX_COLOR) in GL 3.0 or GL_ARB_color_buffer_float
20
21 D3D11: seems always disabled
22
23 Note the PIPE_CAP_VERTEX_COLOR_CLAMPED query indicates whether or not the
24 driver supports this control. If it's not supported, the state tracker may
25 have to insert extra clamping code.
26
27
28 clamp_fragment_color
29 ^^^^^^^^^^^^^^^^^^^^
30
31 Controls whether TGSI_SEMANTIC_COLOR outputs of the fragment shader
32 are clamped to [0, 1].
33
34 OpenGL: glClampColor(GL_CLAMP_FRAGMENT_COLOR) in GL 3.0 or ARB_color_buffer_float
35
36 D3D11: seems always disabled
37
38 Note the PIPE_CAP_FRAGMENT_COLOR_CLAMPED query indicates whether or not the
39 driver supports this control. If it's not supported, the state tracker may
40 have to insert extra clamping code.
41
42
43 Shading
44 -------
45
46 flatshade
47 ^^^^^^^^^
48
49 If set, the provoking vertex of each polygon is used to determine the color
50 of the entire polygon. If not set, fragment colors will be interpolated
51 between the vertex colors.
52
53 The actual interpolated shading algorithm is obviously
54 implementation-dependent, but will usually be Gourard for most hardware.
55
56 .. note::
57
58 This is separate from the fragment shader input attributes
59 CONSTANT, LINEAR and PERSPECTIVE. The flatshade state is needed at
60 clipping time to determine how to set the color of new vertices.
61
62 :ref:`Draw` can implement flat shading by copying the provoking vertex
63 color to all the other vertices in the primitive.
64
65 flatshade_first
66 ^^^^^^^^^^^^^^^
67
68 Whether the first vertex should be the provoking vertex, for most primitives.
69 If not set, the last vertex is the provoking vertex.
70
71 There are a few important exceptions to the specification of this rule.
72
73 * ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
74 vertex. If the caller wishes to change the provoking vertex, they merely
75 need to rotate the vertices themselves.
76 * ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: The option only has
77 an effect if ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION`` is true.
78 If it is not, the provoking vertex is always the last vertex.
79 * ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
80 second vertex, not the first. This permits each segment of the fan to have
81 a different color.
82
83 Polygons
84 --------
85
86 light_twoside
87 ^^^^^^^^^^^^^
88
89 If set, there are per-vertex back-facing colors. The hardware
90 (perhaps assisted by :ref:`Draw`) should be set up to use this state
91 along with the front/back information to set the final vertex colors
92 prior to rasterization.
93
94 The frontface vertex shader color output is marked with TGSI semantic
95 COLOR[0], and backface COLOR[1].
96
97 front_ccw
98 Indicates whether the window order of front-facing polygons is
99 counter-clockwise (TRUE) or clockwise (FALSE).
100
101 cull_mode
102 Indicates which faces of polygons to cull, either PIPE_FACE_NONE
103 (cull no polygons), PIPE_FACE_FRONT (cull front-facing polygons),
104 PIPE_FACE_BACK (cull back-facing polygons), or
105 PIPE_FACE_FRONT_AND_BACK (cull all polygons).
106
107 fill_front
108 Indicates how to fill front-facing polygons, either
109 PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
110 PIPE_POLYGON_MODE_POINT.
111 fill_back
112 Indicates how to fill back-facing polygons, either
113 PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
114 PIPE_POLYGON_MODE_POINT.
115
116 poly_stipple_enable
117 Whether polygon stippling is enabled.
118 poly_smooth
119 Controls OpenGL-style polygon smoothing/antialiasing
120
121 offset_point
122 If set, point-filled polygons will have polygon offset factors applied
123 offset_line
124 If set, line-filled polygons will have polygon offset factors applied
125 offset_tri
126 If set, filled polygons will have polygon offset factors applied
127
128 offset_units
129 Specifies the polygon offset bias
130 offset_scale
131 Specifies the polygon offset scale
132 offset_clamp
133 Upper (if > 0) or lower (if < 0) bound on the polygon offset result
134
135
136
137 Lines
138 -----
139
140 line_width
141 The width of lines.
142 line_smooth
143 Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
144 line_stipple_enable
145 Whether line stippling is enabled.
146 line_stipple_pattern
147 16-bit bitfield of on/off flags, used to pattern the line stipple.
148 line_stipple_factor
149 When drawing a stippled line, each bit in the stipple pattern is
150 repeated N times, where N = line_stipple_factor + 1.
151 line_last_pixel
152 Controls whether the last pixel in a line is drawn or not. OpenGL
153 omits the last pixel to avoid double-drawing pixels at the ends of lines
154 when drawing connected lines.
155
156
157 Points
158 ------
159
160 sprite_coord_enable
161 ^^^^^^^^^^^^^^^^^^^
162 The effect of this state depends on PIPE_CAP_TGSI_TEXCOORD !
163
164 Controls automatic texture coordinate generation for rendering sprite points.
165
166 If PIPE_CAP_TGSI_TEXCOORD is false:
167 When bit k in the sprite_coord_enable bitfield is set, then generic
168 input k to the fragment shader will get an automatically computed
169 texture coordinate.
170
171 If PIPE_CAP_TGSI_TEXCOORD is true:
172 The bitfield refers to inputs with TEXCOORD semantic instead of generic inputs.
173
174 The texture coordinate will be of the form (s, t, 0, 1) where s varies
175 from 0 to 1 from left to right while t varies from 0 to 1 according to
176 the state of 'sprite_coord_mode' (see below).
177
178 If any bit is set, then point_smooth MUST be disabled (there are no
179 round sprites) and point_quad_rasterization MUST be true (sprites are
180 always rasterized as quads). Any mismatch between these states should
181 be considered a bug in the state-tracker.
182
183 This feature is implemented in the :ref:`Draw` module but may also be
184 implemented natively by GPUs or implemented with a geometry shader.
185
186
187 sprite_coord_mode
188 ^^^^^^^^^^^^^^^^^
189
190 Specifies how the value for each shader output should be computed when drawing
191 point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will
192 have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left
193 vertex will have coordinates (0,0,0,1).
194 This state is used by :ref:`Draw` to generate texcoords.
195
196
197 point_quad_rasterization
198 ^^^^^^^^^^^^^^^^^^^^^^^^
199
200 Determines if points should be rasterized according to quad or point
201 rasterization rules.
202
203 OpenGL actually has quite different rasterization rules for points and
204 point sprites - hence this indicates if points should be rasterized as
205 points or according to point sprite (which decomposes them into quads,
206 basically) rules.
207
208 Additionally Direct3D will always use quad rasterization rules for
209 points, regardless of whether point sprites are enabled or not.
210
211 If this state is enabled, point smoothing and antialiasing are
212 disabled. If it is disabled, point sprite coordinates are not
213 generated.
214
215 .. note::
216
217 Some renderers always internally translate points into quads; this state
218 still affects those renderers by overriding other rasterization state.
219
220 point_smooth
221 Whether points should be smoothed. Point smoothing turns rectangular
222 points into circles or ovals.
223 point_size_per_vertex
224 Whether the vertex shader is expected to have a point size output.
225 Undefined behaviour is permitted if there is disagreement between
226 this flag and the actual bound shader.
227 point_size
228 The size of points, if not specified per-vertex.
229
230
231
232 Other Members
233 -------------
234
235 scissor
236 Whether the scissor test is enabled.
237
238 multisample
239 Whether :term:`MSAA` is enabled.
240
241 gl_rasterization_rules
242 Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
243 the rasterizer will use (0, 0) for pixel centers.
244
245 clip_halfz
246 When true clip space in the z axis goes from [0..1] (D3D). When false
247 [-1, 1] (GL)
248
249 depth_clip
250 When false, the near and far depth clipping planes of the view volume are
251 disabled and the depth value will be clamped at the per-pixel level, after
252 polygon offset has been applied and before depth testing.
253
254 clip_plane_enable
255 For each k in [0, PIPE_MAX_CLIP_PLANES), if bit k of this field is set,
256 clipping half-space k is enabled, if it is clear, it is disabled.
257 The clipping half-spaces are defined either by the user clip planes in
258 ``pipe_clip_state``, or by the clip distance outputs of the shader stage
259 preceding the fragment shader.
260 If any clip distance output is written, those half-spaces for which no
261 clip distance is written count as disabled; i.e. user clip planes and
262 shader clip distances cannot be mixed, and clip distances take precedence.