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 163 Controls automatic texture coordinate generation for rendering sprite points. 164 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 The texture coordinate will be of the form (s, t, 0, 1) where s varies 170 from 0 to 1 from left to right while t varies from 0 to 1 according to 171 the state of 'sprite_coord_mode' (see below). 172 173 If any bit is set, then point_smooth MUST be disabled (there are no 174 round sprites) and point_quad_rasterization MUST be true (sprites are 175 always rasterized as quads). Any mismatch between these states should 176 be considered a bug in the state-tracker. 177 178 This feature is implemented in the :ref:`Draw` module but may also be 179 implemented natively by GPUs or implemented with a geometry shader. 180 181 182 sprite_coord_mode 183 ^^^^^^^^^^^^^^^^^ 184 185 Specifies how the value for each shader output should be computed when drawing 186 point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will 187 have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left 188 vertex will have coordinates (0,0,0,1). 189 This state is used by :ref:`Draw` to generate texcoords. 190 191 192 point_quad_rasterization 193 ^^^^^^^^^^^^^^^^^^^^^^^^ 194 195 Determines if points should be rasterized according to quad or point 196 rasterization rules. 197 198 OpenGL actually has quite different rasterization rules for points and 199 point sprites - hence this indicates if points should be rasterized as 200 points or according to point sprite (which decomposes them into quads, 201 basically) rules. 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 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 behaviour 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 gl_rasterization_rules 237 Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set, 238 the rasterizer will use (0, 0) for pixel centers. 239 240 depth_clip 241 When false, the near and far depth clipping planes of the view volume are 242 disabled and the depth value will be clamped at the per-pixel level, after 243 polygon offset has been applied and before depth testing. 244 245 clip_plane_enable 246 For each k in [0, PIPE_MAX_CLIP_PLANES), if bit k of this field is set, 247 clipping half-space k is enabled, if it is clear, it is disabled. 248 The clipping half-spaces are defined either by the user clip planes in 249 ``pipe_clip_state``, or by the clip distance outputs of the shader stage 250 preceding the fragment shader. 251 If any clip distance output is written, those half-spaces for which no 252 clip distance is written count as disabled; i.e. user clip planes and 253 shader clip distances cannot be mixed, and clip distances take precedence. 254
