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 bypass_vs_clip_and_viewport
  14 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  15
  16 Whether the entire TCL pipeline should be bypassed. This implies that
  17 vertices are pre-transformed for the viewport, and will not be run
  18 through the vertex shader.
  19
  20 .. note::
  21
  22    Implementations may still clip away vertices that are not in the viewport
  23    when this is set.
  24
  25 flatshade
  26 ^^^^^^^^^
  27
  28 If set, the provoking vertex of each polygon is used to determine the color
  29 of the entire polygon.  If not set, fragment colors will be interpolated
  30 between the vertex colors.
  31
  32 The actual interpolated shading algorithm is obviously
  33 implementation-dependent, but will usually be Gourard for most hardware.
  34
  35 .. note::
  36
  37     This is separate from the fragment shader input attributes
  38     CONSTANT, LINEAR and PERSPECTIVE. The flatshade state is needed at
  39     clipping time to determine how to set the color of new vertices.
  40
  41     :ref:`Draw` can implement flat shading by copying the provoking vertex
  42     color to all the other vertices in the primitive.
  43
  44 flatshade_first
  45 ^^^^^^^^^^^^^^^
  46
  47 Whether the first vertex should be the provoking vertex, for most primitives.
  48 If not set, the last vertex is the provoking vertex.
  49
  50 There are several important exceptions to the specification of this rule.
  51
  52 * ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
  53   vertex. If the caller wishes to change the provoking vertex, they merely
  54   need to rotate the vertices themselves.
  55 * ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: This option has no
  56   effect; the provoking vertex is always the last vertex.
  57 * ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
  58   second vertex, not the first. This permits each segment of the fan to have
  59   a different color.
  60
  61 Other Members
  62 ^^^^^^^^^^^^^
  63
  64 light_twoside
  65     If set, there are per-vertex back-facing colors. :ref:`Draw`
  66     uses this state along with the front/back information to set the
  67     final vertex colors prior to rasterization.
  68
  69 front_winding
  70     Indicates the window order of front-facing polygons, either
  71     PIPE_WINDING_CW or PIPE_WINDING_CCW
  72
  73 cull_mode
  74     Indicates which polygons to cull, either PIPE_WINDING_NONE (cull no
  75     polygons), PIPE_WINDING_CW (cull clockwise-winding polygons),
  76     PIPE_WINDING_CCW (cull counter clockwise-winding polygons), or
  77     PIPE_WINDING_BOTH (cull all polygons).
  78
  79 fill_cw
  80     Indicates how to fill clockwise polygons, either PIPE_POLYGON_MODE_FILL,
  81     PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT.
  82 fill_ccw
  83     Indicates how to fill counter clockwise polygons, either
  84     PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT.
  85
  86 poly_stipple_enable
  87     Whether polygon stippling is enabled.
  88 poly_smooth
  89     Controls OpenGL-style polygon smoothing/antialiasing
  90 offset_cw
  91     If set, clockwise polygons will have polygon offset factors applied
  92 offset_ccw
  93     If set, counter clockwise polygons will have polygon offset factors applied
  94 offset_units
  95     Specifies the polygon offset bias
  96 offset_scale
  97     Specifies the polygon offset scale
  98
  99 line_width
 100     The width of lines.
 101 line_smooth
 102     Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
 103 line_stipple_enable
 104     Whether line stippling is enabled.
 105 line_stipple_pattern
 106     16-bit bitfield of on/off flags, used to pattern the line stipple.
 107 line_stipple_factor
 108     When drawing a stippled line, each bit in the stipple pattern is
 109     repeated N times, where N = line_stipple_factor + 1.
 110 line_last_pixel
 111     Controls whether the last pixel in a line is drawn or not.  OpenGL
 112     omits the last pixel to avoid double-drawing pixels at the ends of lines
 113     when drawing connected lines.
 114
 115 point_smooth
 116     Whether points should be smoothed. Point smoothing turns rectangular
 117     points into circles or ovals.
 118 point_size_per_vertex
 119     Whether vertices have a point size element.
 120 point_size
 121     The size of points, if not specified per-vertex.
 122 point_size_min
 123     The minimum size of points.
 124 point_size_max
 125     The maximum size of points.
 126 point_sprite
 127     Whether points are drawn as sprites (textured quads)
 128 sprite_coord_mode
 129     Specifies how the value for each shader output should be computed when
 130     drawing sprites.  If PIPE_SPRITE_COORD_NONE, don't change the vertex
 131     shader output.  Otherwise, the four vertices of the resulting quad will
 132     be assigned texture coordinates.  For PIPE_SPRITE_COORD_LOWER_LEFT, the
 133     lower left vertex will have coordinate (0,0,0,1).
 134     For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left vertex will have
 135     coordinate (0,0,0,1).
 136     This state is needed by :ref:`Draw` because that's where each
 137     point vertex is converted into four quad vertices.  There's no other
 138     place to emit the new vertex texture coordinates which are required for
 139     sprite rendering.
 140     Note that when geometry shaders are available, this state could be
 141     removed.  A special geometry shader defined by the state tracker could
 142     converts the incoming points into quads with the proper texture coords.
 143
 144 scissor
 145     Whether the scissor test is enabled.
 146
 147 multisample
 148     Whether :term:`MSAA` is enabled.
 149
 150 gl_rasterization_rules
 151     Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
 152     the rasterizer will use (0, 0) for pixel centers.
 153