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