src/gallium/docs/source/cso/rasterizer.rst

   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 clamp_fragment_color
  24 ^^^^^^^^^^^^^^^^^^^^
  25
  26 Controls whether TGSI_SEMANTIC_COLOR outputs of the fragment shader
  27 are clamped to [0, 1].
  28
  29 OpenGL: glClampColor(GL_CLAMP_FRAGMENT_COLOR) in GL 3.0 or ARB_color_buffer_float
  30
  31 D3D11: seems always disabled
  32
  33
  34 Shading
  35 -------
  36
  37 flatshade
  38 ^^^^^^^^^
  39
  40 If set, the provoking vertex of each polygon is used to determine the color
  41 of the entire polygon.  If not set, fragment colors will be interpolated
  42 between the vertex colors.
  43
  44 The actual interpolated shading algorithm is obviously
  45 implementation-dependent, but will usually be Gourard for most hardware.
  46
  47 .. note::
  48
  49     This is separate from the fragment shader input attributes
  50     CONSTANT, LINEAR and PERSPECTIVE. The flatshade state is needed at
  51     clipping time to determine how to set the color of new vertices.
  52
  53     :ref:`Draw` can implement flat shading by copying the provoking vertex
  54     color to all the other vertices in the primitive.
  55
  56 flatshade_first
  57 ^^^^^^^^^^^^^^^
  58
  59 Whether the first vertex should be the provoking vertex, for most primitives.
  60 If not set, the last vertex is the provoking vertex.
  61
  62 There are a few important exceptions to the specification of this rule.
  63
  64 * ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
  65   vertex. If the caller wishes to change the provoking vertex, they merely
  66   need to rotate the vertices themselves.
  67 * ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: The option only has
  68   an effect if ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION`` is true.
  69   If it is not, the provoking vertex is always the last vertex.
  70 * ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
  71   second vertex, not the first. This permits each segment of the fan to have
  72   a different color.
  73
  74 Polygons
  75 --------
  76
  77 light_twoside
  78 ^^^^^^^^^^^^^
  79
  80 If set, there are per-vertex back-facing colors.  The hardware
  81 (perhaps assisted by :ref:`Draw`) should be set up to use this state
  82 along with the front/back information to set the final vertex colors
  83 prior to rasterization.
  84
  85 The frontface vertex shader color output is marked with TGSI semantic
  86 COLOR[0], and backface COLOR[1].
  87
  88 front_ccw
  89     Indicates whether the window order of front-facing polygons is
  90     counter-clockwise (TRUE) or clockwise (FALSE).
  91
  92 cull_mode
  93     Indicates which faces of polygons to cull, either PIPE_FACE_NONE
  94     (cull no polygons), PIPE_FACE_FRONT (cull front-facing polygons),
  95     PIPE_FACE_BACK (cull back-facing polygons), or
  96     PIPE_FACE_FRONT_AND_BACK (cull all polygons).
  97
  98 fill_front
  99     Indicates how to fill front-facing polygons, either
 100     PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
 101     PIPE_POLYGON_MODE_POINT.
 102 fill_back
 103     Indicates how to fill back-facing polygons, either
 104     PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
 105     PIPE_POLYGON_MODE_POINT.
 106
 107 poly_stipple_enable
 108     Whether polygon stippling is enabled.
 109 poly_smooth
 110     Controls OpenGL-style polygon smoothing/antialiasing
 111
 112 offset_point
 113     If set, point-filled polygons will have polygon offset factors applied
 114 offset_line
 115     If set, line-filled polygons will have polygon offset factors applied
 116 offset_tri
 117     If set, filled polygons will have polygon offset factors applied
 118
 119 offset_units
 120     Specifies the polygon offset bias
 121 offset_scale
 122     Specifies the polygon offset scale
 123 offset_clamp
 124     Upper (if > 0) or lower (if < 0) bound on the polygon offset result
 125
 126
 127
 128 Lines
 129 -----
 130
 131 line_width
 132     The width of lines.
 133 line_smooth
 134     Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
 135 line_stipple_enable
 136     Whether line stippling is enabled.
 137 line_stipple_pattern
 138     16-bit bitfield of on/off flags, used to pattern the line stipple.
 139 line_stipple_factor
 140     When drawing a stippled line, each bit in the stipple pattern is
 141     repeated N times, where N = line_stipple_factor + 1.
 142 line_last_pixel
 143     Controls whether the last pixel in a line is drawn or not.  OpenGL
 144     omits the last pixel to avoid double-drawing pixels at the ends of lines
 145     when drawing connected lines.
 146
 147
 148 Points
 149 ------
 150
 151 sprite_coord_enable
 152 ^^^^^^^^^^^^^^^^^^^
 153
 154 Controls automatic texture coordinate generation for rendering sprite points.
 155
 156 When bit k in the sprite_coord_enable bitfield is set, then generic
 157 input k to the fragment shader will get an automatically computed
 158 texture coordinate.
 159
 160 The texture coordinate will be of the form (s, t, 0, 1) where s varies
 161 from 0 to 1 from left to right while t varies from 0 to 1 according to
 162 the state of 'sprite_coord_mode' (see below).
 163
 164 If any bit is set, then point_smooth MUST be disabled (there are no
 165 round sprites) and point_quad_rasterization MUST be true (sprites are
 166 always rasterized as quads).  Any mismatch between these states should
 167 be considered a bug in the state-tracker.
 168
 169 This feature is implemented in the :ref:`Draw` module but may also be
 170 implemented natively by GPUs or implemented with a geometry shader.
 171
 172
 173 sprite_coord_mode
 174 ^^^^^^^^^^^^^^^^^
 175
 176 Specifies how the value for each shader output should be computed when drawing
 177 point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will
 178 have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left
 179 vertex will have coordinates (0,0,0,1).
 180 This state is used by :ref:`Draw` to generate texcoords.
 181
 182
 183 point_quad_rasterization
 184 ^^^^^^^^^^^^^^^^^^^^^^^^
 185
 186 Determines if points should be rasterized according to quad or point
 187 rasterization rules.
 188
 189 OpenGL actually has quite different rasterization rules for points and
 190 point sprites - hence this indicates if points should be rasterized as
 191 points or according to point sprite (which decomposes them into quads,
 192 basically) rules.
 193
 194 Additionally Direct3D will always use quad rasterization rules for
 195 points, regardless of whether point sprites are enabled or not.
 196
 197 If this state is enabled, point smoothing and antialiasing are
 198 disabled. If it is disabled, point sprite coordinates are not
 199 generated.
 200
 201 .. note::
 202
 203    Some renderers always internally translate points into quads; this state
 204    still affects those renderers by overriding other rasterization state.
 205
 206 point_smooth
 207     Whether points should be smoothed. Point smoothing turns rectangular
 208     points into circles or ovals.
 209 point_size_per_vertex
 210     Whether the vertex shader is expected to have a point size output.
 211     Undefined behaviour is permitted if there is disagreement between
 212     this flag and the actual bound shader.
 213 point_size
 214     The size of points, if not specified per-vertex.
 215
 216
 217
 218 Other Members
 219 -------------
 220
 221 scissor
 222     Whether the scissor test is enabled.
 223
 224 multisample
 225     Whether :term:`MSAA` is enabled.
 226
 227 gl_rasterization_rules
 228     Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
 229     the rasterizer will use (0, 0) for pixel centers.
 230
 231 depth_clip
 232     When false, the near and far depth clipping planes of the view volume are
 233     disabled and the depth value will be clamped at the per-pixel level, after
 234     polygon offset has been applied and before depth testing.
 235
 236 clip_plane_enable
 237     For each k in [0, PIPE_MAX_CLIP_PLANES), if bit k of this field is set,
 238     clipping half-space k is enabled, if it is clear, it is disabled.
 239     The clipping half-spaces are defined either by the user clip planes in
 240     ``pipe_clip_state``, or by the clip distance outputs of the shader stage
 241     preceding the fragment shader.
 242     If any clip distance output is written, those half-spaces for which no
 243     clip distance is written count as disabled; i.e. user clip planes and
 244     shader clip distances cannot be mixed, and clip distances take precedence.