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 12clamp_vertex_color 13^^^^^^^^^^^^^^^^^^ 14 15If set, TGSI_SEMANTIC_COLOR registers are clamped to the [0, 1] range after 16the execution of the vertex shader, before being passed to the geometry 17shader or fragment shader. 18 19OpenGL: glClampColor(GL_CLAMP_VERTEX_COLOR) in GL 3.0 or GL_ARB_color_buffer_float 20 21D3D11: seems always disabled 22 23Note the PIPE_CAP_VERTEX_COLOR_CLAMPED query indicates whether or not the 24driver supports this control. If it's not supported, the state tracker may 25have to insert extra clamping code. 26 27 28clamp_fragment_color 29^^^^^^^^^^^^^^^^^^^^ 30 31Controls whether TGSI_SEMANTIC_COLOR outputs of the fragment shader 32are clamped to [0, 1]. 33 34OpenGL: glClampColor(GL_CLAMP_FRAGMENT_COLOR) in GL 3.0 or ARB_color_buffer_float 35 36D3D11: seems always disabled 37 38Note the PIPE_CAP_FRAGMENT_COLOR_CLAMPED query indicates whether or not the 39driver supports this control. If it's not supported, the state tracker may 40have to insert extra clamping code. 41 42 43Shading 44------- 45 46flatshade 47^^^^^^^^^ 48 49If set, the provoking vertex of each polygon is used to determine the color 50of the entire polygon. If not set, fragment colors will be interpolated 51between the vertex colors. 52 53The actual interpolated shading algorithm is obviously 54implementation-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 65flatshade_first 66^^^^^^^^^^^^^^^ 67 68Whether the first vertex should be the provoking vertex, for most primitives. 69If not set, the last vertex is the provoking vertex. 70 71There 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 83Polygons 84-------- 85 86light_twoside 87^^^^^^^^^^^^^ 88 89If set, there are per-vertex back-facing colors. The hardware 90(perhaps assisted by :ref:`Draw`) should be set up to use this state 91along with the front/back information to set the final vertex colors 92prior to rasterization. 93 94The frontface vertex shader color output is marked with TGSI semantic 95COLOR[0], and backface COLOR[1]. 96 97front_ccw 98 Indicates whether the window order of front-facing polygons is 99 counter-clockwise (TRUE) or clockwise (FALSE). 100 101cull_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 107fill_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. 111fill_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 116poly_stipple_enable 117 Whether polygon stippling is enabled. 118poly_smooth 119 Controls OpenGL-style polygon smoothing/antialiasing 120 121offset_point 122 If set, point-filled polygons will have polygon offset factors applied 123offset_line 124 If set, line-filled polygons will have polygon offset factors applied 125offset_tri 126 If set, filled polygons will have polygon offset factors applied 127 128offset_units 129 Specifies the polygon offset bias 130offset_scale 131 Specifies the polygon offset scale 132offset_clamp 133 Upper (if > 0) or lower (if < 0) bound on the polygon offset result 134 135 136 137Lines 138----- 139 140line_width 141 The width of lines. 142line_smooth 143 Whether lines should be smoothed. Line smoothing is simply anti-aliasing. 144line_stipple_enable 145 Whether line stippling is enabled. 146line_stipple_pattern 147 16-bit bitfield of on/off flags, used to pattern the line stipple. 148line_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. 151line_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 157Points 158------ 159 160sprite_coord_enable 161^^^^^^^^^^^^^^^^^^^ 162 163Controls automatic texture coordinate generation for rendering sprite points. 164 165When bit k in the sprite_coord_enable bitfield is set, then generic 166input k to the fragment shader will get an automatically computed 167texture coordinate. 168 169The texture coordinate will be of the form (s, t, 0, 1) where s varies 170from 0 to 1 from left to right while t varies from 0 to 1 according to 171the state of 'sprite_coord_mode' (see below). 172 173If any bit is set, then point_smooth MUST be disabled (there are no 174round sprites) and point_quad_rasterization MUST be true (sprites are 175always rasterized as quads). Any mismatch between these states should 176be considered a bug in the state-tracker. 177 178This feature is implemented in the :ref:`Draw` module but may also be 179implemented natively by GPUs or implemented with a geometry shader. 180 181 182sprite_coord_mode 183^^^^^^^^^^^^^^^^^ 184 185Specifies how the value for each shader output should be computed when drawing 186point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will 187have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left 188vertex will have coordinates (0,0,0,1). 189This state is used by :ref:`Draw` to generate texcoords. 190 191 192point_quad_rasterization 193^^^^^^^^^^^^^^^^^^^^^^^^ 194 195Determines if points should be rasterized according to quad or point 196rasterization rules. 197 198OpenGL actually has quite different rasterization rules for points and 199point sprites - hence this indicates if points should be rasterized as 200points or according to point sprite (which decomposes them into quads, 201basically) rules. 202 203Additionally Direct3D will always use quad rasterization rules for 204points, regardless of whether point sprites are enabled or not. 205 206If this state is enabled, point smoothing and antialiasing are 207disabled. If it is disabled, point sprite coordinates are not 208generated. 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_smooth 216 Whether points should be smoothed. Point smoothing turns rectangular 217 points into circles or ovals. 218point_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. 222point_size 223 The size of points, if not specified per-vertex. 224 225 226 227Other Members 228------------- 229 230scissor 231 Whether the scissor test is enabled. 232 233multisample 234 Whether :term:`MSAA` is enabled. 235 236gl_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 240depth_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 245clip_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