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 Specifies if a texture unit has its texture coordinates replaced or not. This
 128 is a packed bitfield containing the enable for all texcoords -- if all bits
 129 are zero, point sprites are effectively disabled.
 130
 131 If any bit is set, then point_smooth MUST be disabled (there are no
 132 round sprites) and point_quad_rasterization MUST be true (sprites are
 133 always rasterized as quads).  Any mismatch between these states should
 134 be considered a bug in the state-tracker.
 135
 136 If enabled, the four vertices of the resulting quad will be assigned
 137 texture coordinates, according to sprite_coord_mode.
 138
 139 sprite_coord_mode
 140 ^^^^^^^^^^^^^^^^^
 141
 142 Specifies how the value for each shader output should be computed when drawing
 143 point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will
 144 have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left
 145 vertex will have coordinates (0,0,0,1).
 146 This state is used by :ref:`Draw` to generate texcoords.
 147
 148 point_quad_rasterization
 149 ^^^^^^^^^^^^^^^^^^^^^^^^
 150
 151 Determines if points should be rasterized according to quad or point
 152 rasterization rules.
 153
 154 OpenGL actually has quite different rasterization rules for points and
 155 point sprites - hence this indicates if points should be rasterized as
 156 points or according to point sprite (which decomposes them into quads,
 157 basically) rules.
 158
 159 Additionally Direct3D will always use quad rasterization rules for
 160 points, regardless of whether point sprites are enabled or not.
 161
 162 If this state is enabled, point smoothing and antialiasing are
 163 disabled. If it is disabled, point sprite coordinates are not
 164 generated.
 165
 166 .. note::
 167
 168    Some renderers always internally translate points into quads; this state
 169    still affects those renderers by overriding other rasterization state.
 170
 171 point_smooth
 172     Whether points should be smoothed. Point smoothing turns rectangular
 173     points into circles or ovals.
 174 point_size_per_vertex
 175     Whether the vertex shader is expected to have a point size output.
 176     Undefined behaviour is permitted if there is disagreement between
 177     this flag and the actual bound shader.
 178 point_size
 179     The size of points, if not specified per-vertex.
 180
 181
 182
 183 Other Members
 184 -------------
 185
 186 scissor
 187     Whether the scissor test is enabled.
 188
 189 multisample
 190     Whether :term:`MSAA` is enabled.
 191
 192 gl_rasterization_rules
 193     Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
 194     the rasterizer will use (0, 0) for pixel centers.
 195