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 Members
  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 Other Members
  50 ^^^^^^^^^^^^^
  51
  52 light_twoside
  53     If set, there are per-vertex back-facing colors. :ref:`Draw`
  54     uses this state along with the front/back information to set the
  55     final vertex colors prior to rasterization.
  56
  57 front_winding
  58     Indicates the window order of front-facing polygons, either
  59     PIPE_WINDING_CW or PIPE_WINDING_CCW
  60
  61 cull_mode
  62     Indicates which polygons to cull, either PIPE_WINDING_NONE (cull no
  63     polygons), PIPE_WINDING_CW (cull clockwise-winding polygons),
  64     PIPE_WINDING_CCW (cull counter clockwise-winding polygons), or
  65     PIPE_WINDING_BOTH (cull all polygons).
  66
  67 fill_cw
  68     Indicates how to fill clockwise polygons, either PIPE_POLYGON_MODE_FILL,
  69     PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT.
  70 fill_ccw
  71     Indicates how to fill counter clockwise polygons, either
  72     PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT.
  73
  74 poly_stipple_enable
  75     Whether polygon stippling is enabled.
  76 poly_smooth
  77     Controls OpenGL-style polygon smoothing/antialiasing
  78 offset_cw
  79     If set, clockwise polygons will have polygon offset factors applied
  80 offset_ccw
  81     If set, counter clockwise polygons will have polygon offset factors applied
  82 offset_units
  83     Specifies the polygon offset bias
  84 offset_scale
  85     Specifies the polygon offset scale
  86
  87 line_width
  88     The width of lines.
  89 line_smooth
  90     Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
  91 line_stipple_enable
  92     Whether line stippling is enabled.
  93 line_stipple_pattern
  94     16-bit bitfield of on/off flags, used to pattern the line stipple.
  95 line_stipple_factor
  96     When drawing a stippled line, each bit in the stipple pattern is
  97     repeated N times, where N = line_stipple_factor + 1.
  98 line_last_pixel
  99     Controls whether the last pixel in a line is drawn or not.  OpenGL
 100     omits the last pixel to avoid double-drawing pixels at the ends of lines
 101     when drawing connected lines.
 102
 103 point_smooth
 104     Whether points should be smoothed. Point smoothing turns rectangular
 105     points into circles or ovals.
 106 point_size_per_vertex
 107     Whether vertices have a point size element.
 108 point_size
 109     The size of points, if not specified per-vertex.
 110 sprite_coord_enable
 111     Specifies if a coord has its texture coordinates replaced or not. This
 112     is a packed bitfield containing the enable for all coords - if all are 0
 113     point sprites are effectively disabled, though points may still be
 114     rendered slightly different according to point_quad_rasterization.
 115     If any coord is non-zero, point_smooth should be disabled, and
 116     point_quad_rasterization enabled.
 117     If enabled, the four vertices of the resulting quad will be assigned
 118     texture coordinates, according to sprite_coord_mode.
 119 sprite_coord_mode
 120     Specifies how the value for each shader output should be computed when
 121     drawing sprites, for each coord which has sprite_coord_enable set.
 122     For PIPE_SPRITE_COORD_LOWER_LEFT, the lower left vertex will have
 123     coordinate (0,0,0,1).
 124     For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left vertex will have
 125     coordinate (0,0,0,1).
 126     This state is needed by :ref:`Draw` because that's where each
 127     point vertex is converted into four quad vertices.  There's no other
 128     place to emit the new vertex texture coordinates which are required for
 129     sprite rendering.
 130     Note that when geometry shaders are available, this state could be
 131     removed.  A special geometry shader defined by the state tracker could
 132     convert the incoming points into quads with the proper texture coords.
 133 point_quad_rasterization
 134     This determines if points should be rasterized as quads or points.
 135     d3d always uses quad rasterization for points, regardless if point sprites
 136     are enabled or not, but OGL has different rules. If point_quad_rasterization
 137     is set, point_smooth should be disabled, and points will be rendered as
 138     squares even if multisample is enabled.
 139     sprite_coord_enable should be zero if point_quad_rasterization is not
 140     enabled.
 141
 142 scissor
 143     Whether the scissor test is enabled.
 144
 145 multisample
 146     Whether :term:`MSAA` is enabled.
 147
 148 gl_rasterization_rules
 149     Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
 150     the rasterizer will use (0, 0) for pixel centers.
 151