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