Debian Codegraph @

docs/gallium/cso/rasterizer.rst

raw
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
13 clamp_vertex_color
14 If set, TGSI_SEMANTIC_COLOR registers are clamped to the [0, 1] range after
15 the execution of the vertex shader, before being passed to the geometry
16 shader or fragment shader.
17
18 OpenGL: glClampColor(GL_CLAMP_VERTEX_COLOR) in GL 3.0 or
19 :ext:`GL_ARB_color_buffer_float`
20
21 D3D11: seems always disabled
22
23 Note pipe_caps.vertex_color_clamped indicates whether or not the
24 driver supports this control. If it's not supported, gallium frontends may
25 have to insert extra clamping code.
26
27
28 clamp_fragment_color
29 Controls whether TGSI_SEMANTIC_COLOR outputs of the fragment shader
30 are clamped to [0, 1].
31
32 OpenGL: glClampColor(GL_CLAMP_FRAGMENT_COLOR) in GL 3.0 or
33 :ext:`GL_ARB_color_buffer_float`
34
35 D3D11: seems always disabled
36
37 Note pipe_caps.fragment_color_clamped indicates whether or not the
38 driver supports this control. If it's not supported, gallium frontends may
39 have to insert extra clamping code.
40
41
42 Shading
43 -------
44
45 flatshade
46 If set, the provoking vertex of each polygon is used to determine the color
47 of the entire polygon. If not set, fragment colors will be interpolated
48 between the vertex colors.
49
50 The actual interpolated shading algorithm is obviously
51 implementation-dependent, but will usually be Gouraud for most hardware.
52
53 .. note::
54
55 This is separate from the fragment shader input attributes
56 CONSTANT, LINEAR and PERSPECTIVE. The flatshade state is needed at
57 clipping time to determine how to set the color of new vertices.
58
59 Draw can implement flat shading by copying the provoking vertex
60 color to all the other vertices in the primitive.
61
62 flatshade_first
63 Whether the first vertex should be the provoking vertex, for most primitives.
64 If not set, the last vertex is the provoking vertex.
65
66 There are a few important exceptions to the specification of this rule.
67
68 * ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
69 vertex. If the caller wishes to change the provoking vertex, they merely
70 need to rotate the vertices themselves.
71 * ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: The option only has
72 an effect if ``pipe_caps.quads_follow_provoking_vertex_convention`` is true.
73 If it is not, the provoking vertex is always the last vertex.
74 * ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
75 second vertex, not the first. This permits each segment of the fan to have
76 a different color.
77
78 Polygons
79 --------
80
81 light_twoside
82 If set, there are per-vertex back-facing colors. The hardware
83 (perhaps assisted by Draw) should be set up to use this state
84 along with the front/back information to set the final vertex colors
85 prior to rasterization.
86
87 The front-face vertex shader color output is marked with TGSI semantic
88 COLOR[0], and back-face COLOR[1].
89
90 front_ccw
91 Indicates whether the window order of front-facing polygons is
92 counter-clockwise (TRUE) or clockwise (FALSE).
93
94 cull_mode
95 Indicates which faces of polygons to cull, either PIPE_FACE_NONE
96 (cull no polygons), PIPE_FACE_FRONT (cull front-facing polygons),
97 PIPE_FACE_BACK (cull back-facing polygons), or
98 PIPE_FACE_FRONT_AND_BACK (cull all polygons).
99
100 fill_front
101 Indicates how to fill front-facing polygons, either
102 PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
103 PIPE_POLYGON_MODE_POINT.
104 fill_back
105 Indicates how to fill back-facing polygons, either
106 PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
107 PIPE_POLYGON_MODE_POINT.
108
109 poly_stipple_enable
110 Whether polygon stippling is enabled.
111 poly_smooth
112 Controls OpenGL-style polygon smoothing/antialiasing
113
114 offset_point
115 If set, point-filled polygons will have polygon offset factors applied
116 offset_line
117 If set, line-filled polygons will have polygon offset factors applied
118 offset_tri
119 If set, filled polygons will have polygon offset factors applied
120
121 offset_units
122 Specifies the polygon offset bias
123 offset_scale
124 Specifies the polygon offset scale
125 offset_clamp
126 Upper (if > 0) or lower (if < 0) bound on the polygon offset result
127
128
129
130 Lines
131 -----
132
133 line_width
134 The width of lines.
135 line_smooth
136 Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
137 line_stipple_enable
138 Whether line stippling is enabled.
139 line_stipple_pattern
140 16-bit bitfield of on/off flags, used to pattern the line stipple.
141 line_stipple_factor
142 When drawing a stippled line, each bit in the stipple pattern is
143 repeated N times, where N = line_stipple_factor + 1.
144 line_last_pixel
145 Controls whether the last pixel in a line is drawn or not. OpenGL
146 omits the last pixel to avoid double-drawing pixels at the ends of lines
147 when drawing connected lines.
148
149
150 Points
151 ------
152
153 sprite_coord_enable
154 The effect of this state depends on pipe_caps.tgsi_texcoord !
155
156 Controls automatic texture coordinate generation for rendering sprite points.
157
158 If pipe_caps.tgsi_texcoord is false:
159 When bit k in the sprite_coord_enable bitfield is set, then generic
160 input k to the fragment shader will get an automatically computed
161 texture coordinate.
162
163 If pipe_caps.tgsi_texcoord is true:
164 The bitfield refers to inputs with TEXCOORD semantic instead of generic inputs.
165
166 The texture coordinate will be of the form (s, t, 0, 1) where s varies
167 from 0 to 1 from left to right while t varies from 0 to 1 according to
168 the state of 'sprite_coord_mode' (see below).
169
170 If any bit is set, then point_smooth MUST be disabled (there are no
171 round sprites) and point_quad_rasterization MUST be true (sprites are
172 always rasterized as quads). Any mismatch between these states should
173 be considered a bug in the gallium frontend.
174
175 This feature is implemented in the Draw module but may also be
176 implemented natively by GPUs or implemented with a geometry shader.
177
178
179 sprite_coord_mode
180 Specifies how the value for each shader output should be computed when drawing
181 point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will
182 have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left
183 vertex will have coordinates (0,0,0,1).
184 This state is used by Draw to generate texcoords.
185
186
187 point_quad_rasterization
188 Determines if points should be rasterized according to quad or point
189 rasterization rules.
190
191 (Legacy-only) OpenGL actually has quite different rasterization rules
192 for points and point sprites - hence this indicates if points should be
193 rasterized as points or according to point sprite (which decomposes them
194 into quads, basically) rules. Newer GL versions no longer support the old
195 point rules at all.
196
197 Additionally Direct3D will always use quad rasterization rules for
198 points, regardless of whether point sprites are enabled or not.
199
200 If this state is enabled, point smoothing and antialiasing are
201 disabled. If it is disabled, point sprite coordinates are not
202 generated.
203
204 .. note::
205
206 Some renderers always internally translate points into quads; this state
207 still affects those renderers by overriding other rasterization state.
208
209 point_tri_clip
210 Determines if clipping of points should happen after they are converted
211 to "rectangles" (required by d3d) or before (required by OpenGL, though
212 this rule is ignored by some IHVs).
213 It is not valid to set this to enabled but have point_quad_rasterization
214 disabled.
215 point_smooth
216 Whether points should be smoothed. Point smoothing turns rectangular
217 points into circles or ovals.
218 point_size_per_vertex
219 Whether the vertex shader is expected to have a point size output.
220 Undefined behavior is permitted if there is disagreement between
221 this flag and the actual bound shader.
222 point_size
223 The size of points, if not specified per-vertex.
224
225
226
227 Other Members
228 -------------
229
230 scissor
231 Whether the scissor test is enabled.
232
233 multisample
234 Whether :term:`MSAA` is enabled.
235
236 half_pixel_center
237 When true, the rasterizer should use (0.5, 0.5) pixel centers for
238 determining pixel ownership (e.g, OpenGL, D3D10 and higher)::
239
240 0 0.5 1
241 0 +-----+
242 | |
243 0.5 | X |
244 | |
245 1 +-----+
246
247 When false, the rasterizer should use (0, 0) pixel centers for determining
248 pixel ownership (e.g., D3D9 or earlier)::
249
250 -0.5 0 0.5
251 -0.5 +-----+
252 | |
253 0 | X |
254 | |
255 0.5 +-----+
256
257 bottom_edge_rule
258 Determines what happens when a pixel sample lies precisely on a triangle
259 edge.
260
261 When true, a pixel sample is considered to lie inside of a triangle if it
262 lies on the *bottom edge* or *left edge* (e.g., OpenGL drawables)::
263
264 0 x
265 0 +--------------------->
266 |
267 | +-------------+
268 | | |
269 | | |
270 | | |
271 | +=============+
272 |
273 y V
274
275 When false, a pixel sample is considered to lie inside of a triangle if it
276 lies on the *top edge* or *left edge* (e.g., OpenGL FBOs, D3D)::
277
278 0 x
279 0 +--------------------->
280 |
281 | +=============+
282 | | |
283 | | |
284 | | |
285 | +-------------+
286 |
287 y V
288
289 Where:
290 - a *top edge* is an edge that is horizontal and is above the other edges;
291 - a *bottom edge* is an edge that is horizontal and is below the other
292 edges;
293 - a *left edge* is an edge that is not horizontal and is on the left side of
294 the triangle.
295
296 .. note::
297
298 Actually all graphics APIs use a top-left rasterization rule for pixel
299 ownership, but their notion of top varies with the axis origin (which
300 can be either at y = 0 or at y = height). Gallium instead always
301 assumes that top is always at y=0.
302
303 See also:
304 - https://learn.microsoft.com/en-us/windows/win32/direct3d11/d3d10-graphics-programming-guide-rasterizer-stage-rules
305 - https://learn.microsoft.com/en-us/windows/win32/direct3d9/rasterization-rules
306
307 clip_halfz
308 When true clip space in the z axis goes from [0..1] (D3D). When false
309 [-1, 1] (GL)
310
311 depth_clip_near
312 When false, the near depth clipping plane of the view volume is disabled.
313 depth_clip_far
314 When false, the far depth clipping plane of the view volume is disabled.
315 depth_clamp
316 Whether the depth value will be clamped to the interval defined by the
317 near and far depth range at the per-pixel level, after polygon offset has
318 been applied and before depth testing. Note that a clamp to [0,1] according
319 to GL rules should always happen even if this is disabled.
320
321 clip_plane_enable
322 For each k in [0, PIPE_MAX_CLIP_PLANES), if bit k of this field is set,
323 clipping half-space k is enabled, if it is clear, it is disabled.
324 The clipping half-spaces are defined either by the user clip planes in
325 ``pipe_clip_state``, or by the clip distance outputs of the shader stage
326 preceding the fragment shader.
327 If any clip distance output is written, those half-spaces for which no
328 clip distance is written count as disabled; i.e. user clip planes and
329 shader clip distances cannot be mixed, and clip distances take precedence.
330
331 conservative_raster_mode
332 The conservative rasterization mode. For PIPE_CONSERVATIVE_RASTER_OFF,
333 conservative rasterization is disabled. For PIPE_CONSERVATIVE_RASTER_POST_SNAP
334 or PIPE_CONSERVATIVE_RASTER_PRE_SNAP, conservative rasterization is enabled.
335 When conservative rasterization is enabled, the polygon smooth, line smooth,
336 point smooth and line stipple settings are ignored.
337 With the post-snap mode, unlike the pre-snap mode, fragments are never
338 generated for degenerate primitives. Degenerate primitives, when rasterized,
339 are considered back-facing and the vertex attributes and depth are that of
340 the provoking vertex.
341 If the post-snap mode is used with an unsupported primitive, the pre-snap
342 mode is used, if supported. Behavior is similar for the pre-snap mode.
343 If the pre-snap mode is used, fragments are generated with respect to the primitive
344 before vertex snapping.
345
346 conservative_raster_dilate
347 The amount of dilation during conservative rasterization.
348
349 subpixel_precision_x
350 A bias added to the horizontal subpixel precision during conservative rasterization.
351 subpixel_precision_y
352 A bias added to the vertical subpixel precision during conservative rasterization.