gallium: change comments to remove 'state tracker'
[mesa.git] / src / gallium / docs / source / cso / rasterizer.rst
index d547055096fc318f8e534e5e45ad7f954aacc1e2..064360079e3566554bd92b627c68895a747801ed 100644 (file)
@@ -7,6 +7,39 @@ The rasterizer state controls the rendering of points, lines and triangles.
 Attributes include polygon culling state, line width, line stipple,
 multisample state, scissoring and flat/smooth shading.
 
 Attributes include polygon culling state, line width, line stipple,
 multisample state, scissoring and flat/smooth shading.
 
+Linkage
+
+clamp_vertex_color
+^^^^^^^^^^^^^^^^^^
+
+If set, TGSI_SEMANTIC_COLOR registers are clamped to the [0, 1] range after
+the execution of the vertex shader, before being passed to the geometry
+shader or fragment shader.
+
+OpenGL: glClampColor(GL_CLAMP_VERTEX_COLOR) in GL 3.0 or GL_ARB_color_buffer_float
+
+D3D11: seems always disabled
+
+Note the PIPE_CAP_VERTEX_COLOR_CLAMPED query indicates whether or not the
+driver supports this control.  If it's not supported, gallium frontends may
+have to insert extra clamping code.
+
+
+clamp_fragment_color
+^^^^^^^^^^^^^^^^^^^^
+
+Controls whether TGSI_SEMANTIC_COLOR outputs of the fragment shader
+are clamped to [0, 1].
+
+OpenGL: glClampColor(GL_CLAMP_FRAGMENT_COLOR) in GL 3.0 or ARB_color_buffer_float
+
+D3D11: seems always disabled
+
+Note the PIPE_CAP_FRAGMENT_COLOR_CLAMPED query indicates whether or not the
+driver supports this control.  If it's not supported, gallium frontends may
+have to insert extra clamping code.
+
+
 Shading
 -------
 
 Shading
 -------
 
@@ -35,13 +68,14 @@ flatshade_first
 Whether the first vertex should be the provoking vertex, for most primitives.
 If not set, the last vertex is the provoking vertex.
 
 Whether the first vertex should be the provoking vertex, for most primitives.
 If not set, the last vertex is the provoking vertex.
 
-There are several important exceptions to the specification of this rule.
+There are a few important exceptions to the specification of this rule.
 
 * ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
   vertex. If the caller wishes to change the provoking vertex, they merely
   need to rotate the vertices themselves.
 
 * ``PIPE_PRIMITIVE_POLYGON``: The provoking vertex is always the first
   vertex. If the caller wishes to change the provoking vertex, they merely
   need to rotate the vertices themselves.
-* ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: This option has no
-  effect; the provoking vertex is always the last vertex.
+* ``PIPE_PRIMITIVE_QUAD``, ``PIPE_PRIMITIVE_QUAD_STRIP``: The option only has
+  an effect if ``PIPE_CAP_QUADS_FOLLOW_PROVOKING_VERTEX_CONVENTION`` is true.
+  If it is not, the provoking vertex is always the last vertex.
 * ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
   second vertex, not the first. This permits each segment of the fan to have
   a different color.
 * ``PIPE_PRIMITIVE_TRIANGLE_FAN``: When set, the provoking vertex is the
   second vertex, not the first. This permits each segment of the fan to have
   a different color.
@@ -93,8 +127,16 @@ offset_tri
 
 offset_units
     Specifies the polygon offset bias
 
 offset_units
     Specifies the polygon offset bias
+offset_units_unscaled
+    Specifies the unit of the polygon offset bias. If false, use the
+    GL/D3D1X behaviour. If true, offset_units is a floating point offset
+    which isn't scaled (D3D9). Note that GL/D3D1X behaviour has different
+    formula whether the depth buffer is unorm or float, which is not
+    the case for D3D9.
 offset_scale
     Specifies the polygon offset scale
 offset_scale
     Specifies the polygon offset scale
+offset_clamp
+    Upper (if > 0) or lower (if < 0) bound on the polygon offset result
 
 
 
 
 
 
@@ -123,13 +165,18 @@ Points
 
 sprite_coord_enable
 ^^^^^^^^^^^^^^^^^^^
 
 sprite_coord_enable
 ^^^^^^^^^^^^^^^^^^^
+The effect of this state depends on PIPE_CAP_TGSI_TEXCOORD !
 
 Controls automatic texture coordinate generation for rendering sprite points.
 
 
 Controls automatic texture coordinate generation for rendering sprite points.
 
+If PIPE_CAP_TGSI_TEXCOORD is false:
 When bit k in the sprite_coord_enable bitfield is set, then generic
 input k to the fragment shader will get an automatically computed
 texture coordinate.
 
 When bit k in the sprite_coord_enable bitfield is set, then generic
 input k to the fragment shader will get an automatically computed
 texture coordinate.
 
+If PIPE_CAP_TGSI_TEXCOORD is true:
+The bitfield refers to inputs with TEXCOORD semantic instead of generic inputs.
+
 The texture coordinate will be of the form (s, t, 0, 1) where s varies
 from 0 to 1 from left to right while t varies from 0 to 1 according to
 the state of 'sprite_coord_mode' (see below).
 The texture coordinate will be of the form (s, t, 0, 1) where s varies
 from 0 to 1 from left to right while t varies from 0 to 1 according to
 the state of 'sprite_coord_mode' (see below).
@@ -137,7 +184,7 @@ the state of 'sprite_coord_mode' (see below).
 If any bit is set, then point_smooth MUST be disabled (there are no
 round sprites) and point_quad_rasterization MUST be true (sprites are
 always rasterized as quads).  Any mismatch between these states should
 If any bit is set, then point_smooth MUST be disabled (there are no
 round sprites) and point_quad_rasterization MUST be true (sprites are
 always rasterized as quads).  Any mismatch between these states should
-be considered a bug in the state-tracker.
+be considered a bug in the gallium frontend.
 
 This feature is implemented in the :ref:`Draw` module but may also be
 implemented natively by GPUs or implemented with a geometry shader.
 
 This feature is implemented in the :ref:`Draw` module but may also be
 implemented natively by GPUs or implemented with a geometry shader.
@@ -159,10 +206,11 @@ point_quad_rasterization
 Determines if points should be rasterized according to quad or point
 rasterization rules.
 
 Determines if points should be rasterized according to quad or point
 rasterization rules.
 
-OpenGL actually has quite different rasterization rules for points and
-point sprites - hence this indicates if points should be rasterized as
-points or according to point sprite (which decomposes them into quads,
-basically) rules.
+(Legacy-only) OpenGL actually has quite different rasterization rules
+for points and point sprites - hence this indicates if points should be
+rasterized as points or according to point sprite (which decomposes them
+into quads, basically) rules. Newer GL versions no longer support the old
+point rules at all.
 
 Additionally Direct3D will always use quad rasterization rules for
 points, regardless of whether point sprites are enabled or not.
 
 Additionally Direct3D will always use quad rasterization rules for
 points, regardless of whether point sprites are enabled or not.
@@ -176,6 +224,12 @@ generated.
    Some renderers always internally translate points into quads; this state
    still affects those renderers by overriding other rasterization state.
 
    Some renderers always internally translate points into quads; this state
    still affects those renderers by overriding other rasterization state.
 
+point_tri_clip
+    Determines if clipping of points should happen after they are converted
+    to "rectangles" (required by d3d) or before (required by OpenGL, though
+    this rule is ignored by some IHVs).
+    It is not valid to set this to enabled but have point_quad_rasterization
+    disabled.
 point_smooth
     Whether points should be smoothed. Point smoothing turns rectangular
     points into circles or ovals.
 point_smooth
     Whether points should be smoothed. Point smoothing turns rectangular
     points into circles or ovals.
@@ -197,7 +251,115 @@ scissor
 multisample
     Whether :term:`MSAA` is enabled.
 
 multisample
     Whether :term:`MSAA` is enabled.
 
-gl_rasterization_rules
-    Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
-    the rasterizer will use (0, 0) for pixel centers.
-
+half_pixel_center
+    When true, the rasterizer should use (0.5, 0.5) pixel centers for
+    determining pixel ownership (e.g, OpenGL, D3D10 and higher)::
+
+           0 0.5 1
+        0  +-----+
+           |     |
+       0.5 |  X  |
+           |     |
+        1  +-----+
+
+    When false, the rasterizer should use (0, 0) pixel centers for determining
+    pixel ownership (e.g., D3D9 or ealier)::
+
+         -0.5 0 0.5
+      -0.5 +-----+
+           |     |
+        0  |  X  |
+           |     |
+       0.5 +-----+
+
+bottom_edge_rule
+    Determines what happens when a pixel sample lies precisely on a triangle
+    edge.
+
+    When true, a pixel sample is considered to lie inside of a triangle if it
+    lies on the *bottom edge* or *left edge* (e.g., OpenGL drawables)::
+
+        0                    x
+      0 +--------------------->
+        |
+        |  +-------------+
+        |  |             |
+        |  |             |
+        |  |             |
+        |  +=============+
+        |
+      y V
+
+    When false, a pixel sample is considered to lie inside of a triangle if it
+    lies on the *top edge* or *left edge* (e.g., OpenGL FBOs, D3D)::
+
+        0                    x
+      0 +--------------------->
+        |
+        |  +=============+
+        |  |             |
+        |  |             |
+        |  |             |
+        |  +-------------+
+        |
+      y V
+
+    Where:
+     - a *top edge* is an edge that is horizontal and is above the other edges;
+     - a *bottom edge* is an edge that is horizontal and is below the other
+       edges;
+     - a *left edge* is an edge that is not horizontal and is on the left side of
+       the triangle.
+
+    .. note::
+
+        Actually all graphics APIs use a top-left rasterization rule for pixel
+        ownership, but their notion of top varies with the axis origin (which
+        can be either at y = 0 or at y = height).  Gallium instead always
+        assumes that top is always at y=0.
+
+    See also:
+     - http://msdn.microsoft.com/en-us/library/windows/desktop/cc627092.aspx
+     - http://msdn.microsoft.com/en-us/library/windows/desktop/bb147314.aspx
+
+clip_halfz
+    When true clip space in the z axis goes from [0..1] (D3D).  When false
+    [-1, 1] (GL)
+
+depth_clip
+    When false, the near and far depth clipping planes of the view volume are
+    disabled and the depth value will be clamped at the per-pixel level, after
+    polygon offset has been applied and before depth testing.
+
+clip_plane_enable
+    For each k in [0, PIPE_MAX_CLIP_PLANES), if bit k of this field is set,
+    clipping half-space k is enabled, if it is clear, it is disabled.
+    The clipping half-spaces are defined either by the user clip planes in
+    ``pipe_clip_state``, or by the clip distance outputs of the shader stage
+    preceding the fragment shader.
+    If any clip distance output is written, those half-spaces for which no
+    clip distance is written count as disabled; i.e. user clip planes and
+    shader clip distances cannot be mixed, and clip distances take precedence.
+
+conservative_raster_mode
+    The conservative rasterization mode.  For PIPE_CONSERVATIVE_RASTER_OFF,
+    conservative rasterization is disabled.  For IPE_CONSERVATIVE_RASTER_POST_SNAP
+    or PIPE_CONSERVATIVE_RASTER_PRE_SNAP, conservative rasterization is nabled.
+    When conservative rasterization is enabled, the polygon smooth, line mooth,
+    point smooth and line stipple settings are ignored.
+    With the post-snap mode, unlike the pre-snap mode, fragments are never
+    generated for degenerate primitives.  Degenerate primitives, when rasterized,
+    are considered back-facing and the vertex attributes and depth are that of
+    the provoking vertex.
+    If the post-snap mode is used with an unsupported primitive, the pre-snap
+    mode is used, if supported.  Behavior is similar for the pre-snap mode.
+    If the pre-snap mode is used, fragments are generated with respect to the primitive
+    before vertex snapping.
+
+conservative_raster_dilate
+    The amount of dilation during conservative rasterization.
+
+subpixel_precision_x
+    A bias added to the horizontal subpixel precision during conservative rasterization.
+subpixel_precision_y
+    A bias added to the vertical subpixel precision during conservative rasterization.