gallium: add TGSI_SEMANTIC_TEXCOORD,PCOORD v3

[mesa.git] / src / gallium / docs / source / cso / rasterizer.rst

diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst
index ad1612f93e31e104826a8c5ed8b0cae8418e7d20..8338243be9f19a257702e279bb34796de8c025d8 100644 (file)
--- a/src/gallium/docs/source/cso/rasterizer.rst
+++ b/src/gallium/docs/source/cso/rasterizer.rst
@@ -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, the state tracker 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, the state tracker 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.


@@ -95,6 +129,8 @@ offset_units
     Specifies the polygon offset bias
 offset_scale
     Specifies the polygon offset scale
     Specifies the polygon offset bias
 offset_scale
     Specifies the polygon offset scale

+offset_clamp
+    Upper (if > 0) or lower (if < 0) bound on the polygon offset result

 
 
 
 
 
 


@@ -123,14 +159,30 @@ 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.
+
+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.
+
+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).
+
+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.
+
+This feature is implemented in the :ref:`Draw` module but may also be
+implemented natively by GPUs or implemented with a geometry shader.

 
 

-Specifies if a texture unit has its texture coordinates replaced or not. This
-is a packed bitfield containing the enable for all texcoords -- if all bits
-are zero, point sprites are effectively disabled. If any bit is set, then
-point_smooth and point_quad_rasterization are ignored; point smoothing is
-disabled and points are always rasterized as quads. If enabled, the four
-vertices of the resulting quad will be assigned texture coordinates,
-according to sprite_coord_mode.

 
 sprite_coord_mode
 ^^^^^^^^^^^^^^^^^
 
 sprite_coord_mode
 ^^^^^^^^^^^^^^^^^


@@ -141,20 +193,24 @@ have coordinates (0,0,0,1). For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left
 vertex will have coordinates (0,0,0,1).
 This state is used by :ref:`Draw` to generate texcoords.
 
 vertex will have coordinates (0,0,0,1).
 This state is used by :ref:`Draw` to generate texcoords.
 

-.. note::
-
-    When geometry shaders are available, a special geometry shader could be
-    used instead of this functionality, to convert incoming points into quads
-    with the proper texture coordinates.

 
 point_quad_rasterization
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 point_quad_rasterization
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

-Determines if points should be rasterized as quads or points. Certain APIs,
-like Direct3D, always use quad rasterization for points, regardless of
-whether point sprites are enabled or not. If this state is enabled, point
-smoothing and antialiasing are disabled. If it is disabled, point sprite
-coordinates are not generated.
+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.
+
+Additionally Direct3D will always use quad rasterization rules for
+points, regardless of whether point sprites are enabled or not.
+
+If this state is enabled, point smoothing and antialiasing are
+disabled. If it is disabled, point sprite coordinates are not
+generated.

 
 .. note::
 
 
 .. note::
 


@@ -186,3 +242,17 @@ 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.
 
     Whether the rasterizer should use (0.5, 0.5) pixel centers. When not set,
     the rasterizer will use (0, 0) for pixel centers.
 

+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.