| 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. |