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 Linkage
  11
  12 clamp_vertex_color
  13 ^^^^^^^^^^^^^^^^^^
  14
  15 If set, TGSI_SEMANTIC_COLOR registers are clamped to the [0, 1] range after
  16 the execution of the vertex shader, before being passed to the geometry
  17 shader or fragment shader.
  18
  19 OpenGL: glClampColor(GL_CLAMP_VERTEX_COLOR) in GL 3.0 or GL_ARB_color_buffer_float
  20
  21 D3D11: seems always disabled
  22
  23 Note the PIPE_CAP_VERTEX_COLOR_CLAMPED query indicates whether or not the
  24 driver supports this control.  If it's not supported, the state tracker may
  25 have to insert extra clamping code.
  26
  27
  28 clamp_fragment_color
  29 ^^^^^^^^^^^^^^^^^^^^
  30
  31 Controls whether TGSI_SEMANTIC_COLOR outputs of the fragment shader
  32 are clamped to [0, 1].
  33
  34 OpenGL: glClampColor(GL_CLAMP_FRAGMENT_COLOR) in GL 3.0 or ARB_color_buffer_float
  35
  36 D3D11: seems always disabled
  37
  38 Note the PIPE_CAP_FRAGMENT_COLOR_CLAMPED query indicates whether or not the
  39 driver supports this control.  If it's not supported, the state tracker may
  40 have to insert extra clamping code.
  41
  42
  43 Shading
  44 -------
  45
  46 flatshade
  47 ^^^^^^^^^
  48
  49 If set, the provoking vertex of each polygon is used to determine the color
  50 of the entire polygon.  If not set, fragment colors will be interpolated
  51 between the vertex colors.
  52
  53 The actual interpolated shading algorithm is obviously
  54 implementation-dependent, but will usually be Gourard for most hardware.
  55
  56 .. note::
  57
  58     This is separate from the fragment shader input attributes
  59     CONSTANT, LINEAR and PERSPECTIVE. The flatshade state is needed at
  60     clipping time to determine how to set the color of new vertices.
  61
  62     :ref:`Draw` can implement flat shading by copying the provoking vertex
  63     color to all the other vertices in the primitive.
  64
  65 flatshade_first
  66 ^^^^^^^^^^^^^^^
  67
  68 Whether the first vertex should be the provoking vertex, for most primitives.
  69 If not set, the last vertex is the provoking vertex.
  70
  71 There are a few important exceptions to the specification of this rule.
  72
  73 * ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
  74   vertex. If the caller wishes to change the provoking vertex, they merely
  75   need to rotate the vertices themselves.
  76 * ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: The option only has
  77   an effect if ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION`` is true.
  78   If it is not, the provoking vertex is always the last vertex.
  79 * ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
  80   second vertex, not the first. This permits each segment of the fan to have
  81   a different color.
  82
  83 Polygons
  84 --------
  85
  86 light_twoside
  87 ^^^^^^^^^^^^^
  88
  89 If set, there are per-vertex back-facing colors.  The hardware
  90 (perhaps assisted by :ref:`Draw`) should be set up to use this state
  91 along with the front/back information to set the final vertex colors
  92 prior to rasterization.
  93
  94 The frontface vertex shader color output is marked with TGSI semantic
  95 COLOR[0], and backface COLOR[1].
  96
  97 front_ccw
  98     Indicates whether the window order of front-facing polygons is
  99     counter-clockwise (TRUE) or clockwise (FALSE).
 100
 101 cull_mode
 102     Indicates which faces of polygons to cull, either PIPE_FACE_NONE
 103     (cull no polygons), PIPE_FACE_FRONT (cull front-facing polygons),
 104     PIPE_FACE_BACK (cull back-facing polygons), or
 105     PIPE_FACE_FRONT_AND_BACK (cull all polygons).
 106
 107 fill_front
 108     Indicates how to fill front-facing polygons, either
 109     PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
 110     PIPE_POLYGON_MODE_POINT.
 111 fill_back
 112     Indicates how to fill back-facing polygons, either
 113     PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
 114     PIPE_POLYGON_MODE_POINT.
 115
 116 poly_stipple_enable
 117     Whether polygon stippling is enabled.
 118 poly_smooth
 119     Controls OpenGL-style polygon smoothing/antialiasing
 120
 121 offset_point
 122     If set, point-filled polygons will have polygon offset factors applied
 123 offset_line
 124     If set, line-filled polygons will have polygon offset factors applied
 125 offset_tri
 126     If set, filled polygons will have polygon offset factors applied
 127
 128 offset_units
 129     Specifies the polygon offset bias
 130 offset_scale
 131     Specifies the polygon offset scale
 132 offset_clamp
 133     Upper (if > 0) or lower (if < 0) bound on the polygon offset result
 134
 135
 136
 137 Lines
 138 -----
 139
 140 line_width
 141     The width of lines.
 142 line_smooth
 143     Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
 144 line_stipple_enable
 145     Whether line stippling is enabled.
 146 line_stipple_pattern
 147     16-bit bitfield of on/off flags, used to pattern the line stipple.
 148 line_stipple_factor
 149     When drawing a stippled line, each bit in the stipple pattern is
 150     repeated N times, where N = line_stipple_factor + 1.
 151 line_last_pixel
 152     Controls whether the last pixel in a line is drawn or not.  OpenGL
 153     omits the last pixel to avoid double-drawing pixels at the ends of lines
 154     when drawing connected lines.
 155
 156
 157 Points
 158 ------
 159
 160 sprite_coord_enable
 161 ^^^^^^^^^^^^^^^^^^^
 162 The effect of this state depends on PIPE_CAP_TGSI_TEXCOORD !
 163
 164 Controls automatic texture coordinate generation for rendering sprite points.
 165
 166 If PIPE_CAP_TGSI_TEXCOORD is false:
 167 When bit k in the sprite_coord_enable bitfield is set, then generic
 168 input k to the fragment shader will get an automatically computed
 169 texture coordinate.
 170
 171 If PIPE_CAP_TGSI_TEXCOORD is true:
 172 The bitfield refers to inputs with TEXCOORD semantic instead of generic inputs.
 173
 174 The texture coordinate will be of the form (s, t, 0, 1) where s varies
 175 from 0 to 1 from left to right while t varies from 0 to 1 according to
 176 the state of 'sprite_coord_mode' (see below).
 177
 178 If any bit is set, then point_smooth MUST be disabled (there are no
 179 round sprites) and point_quad_rasterization MUST be true (sprites are
 180 always rasterized as quads).  Any mismatch between these states should
 181 be considered a bug in the state-tracker.
 182
 183 This feature is implemented in the :ref:`Draw` module but may also be
 184 implemented natively by GPUs or implemented with a geometry shader.
 185
 186
 187 sprite_coord_mode
 188 ^^^^^^^^^^^^^^^^^
 189
 190 Specifies how the value for each shader output should be computed when drawing
 191 point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will
 192 have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left
 193 vertex will have coordinates (0,0,0,1).
 194 This state is used by :ref:`Draw` to generate texcoords.
 195
 196
 197 point_quad_rasterization
 198 ^^^^^^^^^^^^^^^^^^^^^^^^
 199
 200 Determines if points should be rasterized according to quad or point
 201 rasterization rules.
 202
 203 (Legacy-only) OpenGL actually has quite different rasterization rules
 204 for points and point sprites - hence this indicates if points should be
 205 rasterized as points or according to point sprite (which decomposes them
 206 into quads, basically) rules. Newer GL versions no longer support the old
 207 point rules at all.
 208
 209 Additionally Direct3D will always use quad rasterization rules for
 210 points, regardless of whether point sprites are enabled or not.
 211
 212 If this state is enabled, point smoothing and antialiasing are
 213 disabled. If it is disabled, point sprite coordinates are not
 214 generated.
 215
 216 .. note::
 217
 218    Some renderers always internally translate points into quads; this state
 219    still affects those renderers by overriding other rasterization state.
 220
 221 point_tri_clip
 222     Determines if clipping of points should happen after they are converted
 223     to "rectangles" (required by d3d) or before (required by OpenGL, though
 224     this rule is ignored by some IHVs).
 225     It is not valid to set this to enabled but have point_quad_rasterization
 226     disabled.
 227 point_smooth
 228     Whether points should be smoothed. Point smoothing turns rectangular
 229     points into circles or ovals.
 230 point_size_per_vertex
 231     Whether the vertex shader is expected to have a point size output.
 232     Undefined behaviour is permitted if there is disagreement between
 233     this flag and the actual bound shader.
 234 point_size
 235     The size of points, if not specified per-vertex.
 236
 237
 238
 239 Other Members
 240 -------------
 241
 242 scissor
 243     Whether the scissor test is enabled.
 244
 245 multisample
 246     Whether :term:`MSAA` is enabled.
 247
 248 half_pixel_center
 249     When true, the rasterizer should use (0.5, 0.5) pixel centers for
 250     determining pixel ownership (e.g, OpenGL, D3D10 and higher)::
 251
 252            0 0.5 1
 253         0  +-----+
 254            |     |
 255        0.5 |  X  |
 256            |     |
 257         1  +-----+
 258
 259     When false, the rasterizer should use (0, 0) pixel centers for determining
 260     pixel ownership (e.g., D3D9 or ealier)::
 261
 262          -0.5 0 0.5
 263       -0.5 +-----+
 264            |     |
 265         0  |  X  |
 266            |     |
 267        0.5 +-----+
 268
 269 bottom_edge_rule
 270     Determines what happens when a pixel sample lies precisely on a triangle
 271     edge.
 272
 273     When true, a pixel sample is considered to lie inside of a triangle if it
 274     lies on the *bottom edge* or *left edge* (e.g., OpenGL drawables)::
 275
 276         0                    x
 277       0 +--------------------->
 278         |
 279         |  +-------------+
 280         |  |             |
 281         |  |             |
 282         |  |             |
 283         |  +=============+
 284         |
 285       y V
 286
 287     When false, a pixel sample is considered to lie inside of a triangle if it
 288     lies on the *top edge* or *left edge* (e.g., OpenGL FBOs, D3D)::
 289
 290         0                    x
 291       0 +--------------------->
 292         |
 293         |  +=============+
 294         |  |             |
 295         |  |             |
 296         |  |             |
 297         |  +-------------+
 298         |
 299       y V
 300
 301     Where:
 302      - a *top edge* is an edge that is horizontal and is above the other edges;
 303      - a *bottom edge* is an edge that is horizontal and is below the other
 304        edges;
 305      - a *left edge* is an edge that is not horizontal and is on the left side of
 306        the triangle.
 307
 308     .. note::
 309
 310         Actually all graphics APIs use a top-left rasterization rule for pixel
 311         ownership, but their notion of top varies with the axis origin (which
 312         can be either at y = 0 or at y = height).  Gallium instead always
 313         assumes that top is always at y=0.
 314
 315     See also:
 316      - http://msdn.microsoft.com/en-us/library/windows/desktop/cc627092.aspx
 317      - http://msdn.microsoft.com/en-us/library/windows/desktop/bb147314.aspx
 318
 319 clip_halfz
 320     When true clip space in the z axis goes from [0..1] (D3D).  When false
 321     [-1, 1] (GL)
 322
 323 depth_clip
 324     When false, the near and far depth clipping planes of the view volume are
 325     disabled and the depth value will be clamped at the per-pixel level, after
 326     polygon offset has been applied and before depth testing.
 327
 328 clip_plane_enable
 329     For each k in [0, PIPE_MAX_CLIP_PLANES), if bit k of this field is set,
 330     clipping half-space k is enabled, if it is clear, it is disabled.
 331     The clipping half-spaces are defined either by the user clip planes in
 332     ``pipe_clip_state``, or by the clip distance outputs of the shader stage
 333     preceding the fragment shader.
 334     If any clip distance output is written, those half-spaces for which no
 335     clip distance is written count as disabled; i.e. user clip planes and
 336     shader clip distances cannot be mixed, and clip distances take precedence.