1.. _rasterizer: 2 3Rasterizer 4========== 5 6The rasterizer state controls the rendering of points, lines and triangles. 7Attributes include polygon culling state, line width, line stipple, 8multisample state, scissoring and flat/smooth shading. 9 10Linkage 11------- 12 13clamp_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 the PIPE_CAP_VERTEX_COLOR_CLAMPED query 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 28clamp_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 the PIPE_CAP_FRAGMENT_COLOR_CLAMPED query 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 42Shading 43------- 44 45flatshade 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 :ref:`Draw` can implement flat shading by copying the provoking vertex 60 color to all the other vertices in the primitive. 61 62flatshade_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_CAP_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 78Polygons 79-------- 80 81light_twoside 82 If set, there are per-vertex back-facing colors. The hardware 83 (perhaps assisted by :ref:`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 90front_ccw 91 Indicates whether the window order of front-facing polygons is 92 counter-clockwise (TRUE) or clockwise (FALSE). 93 94cull_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 100fill_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. 104fill_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 109poly_stipple_enable 110 Whether polygon stippling is enabled. 111poly_smooth 112 Controls OpenGL-style polygon smoothing/antialiasing 113 114offset_point 115 If set, point-filled polygons will have polygon offset factors applied 116offset_line 117 If set, line-filled polygons will have polygon offset factors applied 118offset_tri 119 If set, filled polygons will have polygon offset factors applied 120 121offset_units 122 Specifies the polygon offset bias 123offset_units_unscaled 124 Specifies the unit of the polygon offset bias. If false, use the 125 GL/D3D1X behavior. If true, offset_units is a floating point offset 126 which isn't scaled (D3D9). Note that GL/D3D1X behavior has different 127 formula whether the depth buffer is unorm or float, which is not 128 the case for D3D9. 129offset_scale 130 Specifies the polygon offset scale 131offset_clamp 132 Upper (if > 0) or lower (if < 0) bound on the polygon offset result 133 134 135 136Lines 137----- 138 139line_width 140 The width of lines. 141line_smooth 142 Whether lines should be smoothed. Line smoothing is simply anti-aliasing. 143line_stipple_enable 144 Whether line stippling is enabled. 145line_stipple_pattern 146 16-bit bitfield of on/off flags, used to pattern the line stipple. 147line_stipple_factor 148 When drawing a stippled line, each bit in the stipple pattern is 149 repeated N times, where N = line_stipple_factor + 1. 150line_last_pixel 151 Controls whether the last pixel in a line is drawn or not. OpenGL 152 omits the last pixel to avoid double-drawing pixels at the ends of lines 153 when drawing connected lines. 154 155 156Points 157------ 158 159sprite_coord_enable 160 The effect of this state depends on PIPE_CAP_TGSI_TEXCOORD ! 161 162 Controls automatic texture coordinate generation for rendering sprite points. 163 164 If PIPE_CAP_TGSI_TEXCOORD is false: 165 When bit k in the sprite_coord_enable bitfield is set, then generic 166 input k to the fragment shader will get an automatically computed 167 texture coordinate. 168 169 If PIPE_CAP_TGSI_TEXCOORD is true: 170 The bitfield refers to inputs with TEXCOORD semantic instead of generic inputs. 171 172 The texture coordinate will be of the form (s, t, 0, 1) where s varies 173 from 0 to 1 from left to right while t varies from 0 to 1 according to 174 the state of 'sprite_coord_mode' (see below). 175 176 If any bit is set, then point_smooth MUST be disabled (there are no 177 round sprites) and point_quad_rasterization MUST be true (sprites are 178 always rasterized as quads). Any mismatch between these states should 179 be considered a bug in the gallium frontend. 180 181 This feature is implemented in the :ref:`Draw` module but may also be 182 implemented natively by GPUs or implemented with a geometry shader. 183 184 185sprite_coord_mode 186 Specifies how the value for each shader output should be computed when drawing 187 point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will 188 have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left 189 vertex will have coordinates (0,0,0,1). 190 This state is used by :ref:`Draw` to generate texcoords. 191 192 193point_quad_rasterization 194 Determines if points should be rasterized according to quad or point 195 rasterization rules. 196 197 (Legacy-only) OpenGL actually has quite different rasterization rules 198 for points and point sprites - hence this indicates if points should be 199 rasterized as points or according to point sprite (which decomposes them 200 into quads, basically) rules. Newer GL versions no longer support the old 201 point rules at all. 202 203 Additionally Direct3D will always use quad rasterization rules for 204 points, regardless of whether point sprites are enabled or not. 205 206 If this state is enabled, point smoothing and antialiasing are 207 disabled. If it is disabled, point sprite coordinates are not 208 generated. 209 210 .. note:: 211 212 Some renderers always internally translate points into quads; this state 213 still affects those renderers by overriding other rasterization state. 214 215point_tri_clip 216 Determines if clipping of points should happen after they are converted 217 to "rectangles" (required by d3d) or before (required by OpenGL, though 218 this rule is ignored by some IHVs). 219 It is not valid to set this to enabled but have point_quad_rasterization 220 disabled. 221point_smooth 222 Whether points should be smoothed. Point smoothing turns rectangular 223 points into circles or ovals. 224point_size_per_vertex 225 Whether the vertex shader is expected to have a point size output. 226 Undefined behavior is permitted if there is disagreement between 227 this flag and the actual bound shader. 228point_size 229 The size of points, if not specified per-vertex. 230 231 232 233Other Members 234------------- 235 236scissor 237 Whether the scissor test is enabled. 238 239multisample 240 Whether :term:`MSAA` is enabled. 241 242half_pixel_center 243 When true, the rasterizer should use (0.5, 0.5) pixel centers for 244 determining pixel ownership (e.g, OpenGL, D3D10 and higher):: 245 246 0 0.5 1 247 0 +-----+ 248 | | 249 0.5 | X | 250 | | 251 1 +-----+ 252 253 When false, the rasterizer should use (0, 0) pixel centers for determining 254 pixel ownership (e.g., D3D9 or earlier):: 255 256 -0.5 0 0.5 257 -0.5 +-----+ 258 | | 259 0 | X | 260 | | 261 0.5 +-----+ 262 263bottom_edge_rule 264 Determines what happens when a pixel sample lies precisely on a triangle 265 edge. 266 267 When true, a pixel sample is considered to lie inside of a triangle if it 268 lies on the *bottom edge* or *left edge* (e.g., OpenGL drawables):: 269 270 0 x 271 0 +---------------------> 272 | 273 | +-------------+ 274 | | | 275 | | | 276 | | | 277 | +=============+ 278 | 279 y V 280 281 When false, a pixel sample is considered to lie inside of a triangle if it 282 lies on the *top edge* or *left edge* (e.g., OpenGL FBOs, D3D):: 283 284 0 x 285 0 +---------------------> 286 | 287 | +=============+ 288 | | | 289 | | | 290 | | | 291 | +-------------+ 292 | 293 y V 294 295 Where: 296 - a *top edge* is an edge that is horizontal and is above the other edges; 297 - a *bottom edge* is an edge that is horizontal and is below the other 298 edges; 299 - a *left edge* is an edge that is not horizontal and is on the left side of 300 the triangle. 301 302 .. note:: 303 304 Actually all graphics APIs use a top-left rasterization rule for pixel 305 ownership, but their notion of top varies with the axis origin (which 306 can be either at y = 0 or at y = height). Gallium instead always 307 assumes that top is always at y=0. 308 309 See also: 310 - https://learn.microsoft.com/en-us/windows/win32/direct3d11/d3d10-graphics-programming-guide-rasterizer-stage-rules 311 - https://learn.microsoft.com/en-us/windows/win32/direct3d9/rasterization-rules 312 313clip_halfz 314 When true clip space in the z axis goes from [0..1] (D3D). When false 315 [-1, 1] (GL) 316 317depth_clip_near 318 When false, the near depth clipping plane of the view volume is disabled. 319depth_clip_far 320 When false, the far depth clipping plane of the view volume is disabled. 321depth_clamp 322 Whether the depth value will be clamped to the interval defined by the 323 near and far depth range at the per-pixel level, after polygon offset has 324 been applied and before depth testing. Note that a clamp to [0,1] according 325 to GL rules should always happen even if this is disabled. 326 327clip_plane_enable 328 For each k in [0, PIPE_MAX_CLIP_PLANES), if bit k of this field is set, 329 clipping half-space k is enabled, if it is clear, it is disabled. 330 The clipping half-spaces are defined either by the user clip planes in 331 ``pipe_clip_state``, or by the clip distance outputs of the shader stage 332 preceding the fragment shader. 333 If any clip distance output is written, those half-spaces for which no 334 clip distance is written count as disabled; i.e. user clip planes and 335 shader clip distances cannot be mixed, and clip distances take precedence. 336 337conservative_raster_mode 338 The conservative rasterization mode. For PIPE_CONSERVATIVE_RASTER_OFF, 339 conservative rasterization is disabled. For PIPE_CONSERVATIVE_RASTER_POST_SNAP 340 or PIPE_CONSERVATIVE_RASTER_PRE_SNAP, conservative rasterization is enabled. 341 When conservative rasterization is enabled, the polygon smooth, line smooth, 342 point smooth and line stipple settings are ignored. 343 With the post-snap mode, unlike the pre-snap mode, fragments are never 344 generated for degenerate primitives. Degenerate primitives, when rasterized, 345 are considered back-facing and the vertex attributes and depth are that of 346 the provoking vertex. 347 If the post-snap mode is used with an unsupported primitive, the pre-snap 348 mode is used, if supported. Behavior is similar for the pre-snap mode. 349 If the pre-snap mode is used, fragments are generated with respect to the primitive 350 before vertex snapping. 351 352conservative_raster_dilate 353 The amount of dilation during conservative rasterization. 354 355subpixel_precision_x 356 A bias added to the horizontal subpixel precision during conservative rasterization. 357subpixel_precision_y 358 A bias added to the vertical subpixel precision during conservative rasterization. 359