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