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