Attributes include polygon culling state, line width, line stipple,
multisample state, scissoring and flat/smooth shading.
+Linkage
-Members
+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
-------
flatshade
- If set, the provoking vertex of each polygon is used to determine the
- color of the entire polygon. If not set, fragment colors will be
- interpolated between the vertex colors.
- Note that this is separate from the fragment shader input attributes
- CONSTANT, LINEAR and PERSPECTIVE. We need the flatshade state at
+^^^^^^^^^
+
+If set, the provoking vertex of each polygon is used to determine the color
+of the entire polygon. If not set, fragment colors will be interpolated
+between the vertex colors.
+
+The actual interpolated shading algorithm is obviously
+implementation-dependent, but will usually be Gourard for most hardware.
+
+.. note::
+
+ This is separate from the fragment shader input attributes
+ CONSTANT, LINEAR and PERSPECTIVE. The flatshade state is needed at
clipping time to determine how to set the color of new vertices.
- Also note that the draw module can implement flat shading by copying
- the provoking vertex color to all the other vertices in the primitive.
+
+ :ref:`Draw` can implement flat shading by copying the provoking vertex
+ color to all the other vertices in the primitive.
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 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_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.
+
+Polygons
+--------
light_twoside
- If set, there are per-vertex back-facing colors. The draw module
- uses this state along with the front/back information to set the
- final vertex colors prior to rasterization.
+^^^^^^^^^^^^^
+
+If set, there are per-vertex back-facing colors. The hardware
+(perhaps assisted by :ref:`Draw`) should be set up to use this state
+along with the front/back information to set the final vertex colors
+prior to rasterization.
+
+The frontface vertex shader color output is marked with TGSI semantic
+COLOR[0], and backface COLOR[1].
+
+front_ccw
+ Indicates whether the window order of front-facing polygons is
+ counter-clockwise (TRUE) or clockwise (FALSE).
-front_winding
- Indicates the window order of front-facing polygons, either
- PIPE_WINDING_CW or PIPE_WINDING_CCW
cull_mode
- Indicates which polygons to cull, either PIPE_WINDING_NONE (cull no
- polygons), PIPE_WINDING_CW (cull clockwise-winding polygons),
- PIPE_WINDING_CCW (cull counter clockwise-winding polygons), or
- PIPE_WINDING_BOTH (cull all polygons).
-
-fill_cw
- Indicates how to fill clockwise polygons, either PIPE_POLYGON_MODE_FILL,
- PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT.
-fill_ccw
- Indicates how to fill counter clockwise polygons, either
- PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or PIPE_POLYGON_MODE_POINT.
+ Indicates which faces of polygons to cull, either PIPE_FACE_NONE
+ (cull no polygons), PIPE_FACE_FRONT (cull front-facing polygons),
+ PIPE_FACE_BACK (cull back-facing polygons), or
+ PIPE_FACE_FRONT_AND_BACK (cull all polygons).
+
+fill_front
+ Indicates how to fill front-facing polygons, either
+ PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
+ PIPE_POLYGON_MODE_POINT.
+fill_back
+ Indicates how to fill back-facing polygons, either
+ PIPE_POLYGON_MODE_FILL, PIPE_POLYGON_MODE_LINE or
+ PIPE_POLYGON_MODE_POINT.
poly_stipple_enable
Whether polygon stippling is enabled.
poly_smooth
Controls OpenGL-style polygon smoothing/antialiasing
-offset_cw
- If set, clockwise polygons will have polygon offset factors applied
-offset_ccw
- If set, counter clockwise polygons will have polygon offset factors applied
+
+offset_point
+ If set, point-filled polygons will have polygon offset factors applied
+offset_line
+ If set, line-filled polygons will have polygon offset factors applied
+offset_tri
+ If set, filled polygons will have polygon offset factors applied
+
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_clamp
+ Upper (if > 0) or lower (if < 0) bound on the polygon offset result
+
+
+
+Lines
+-----
line_width
The width of lines.
line_stipple_pattern
16-bit bitfield of on/off flags, used to pattern the line stipple.
line_stipple_factor
- When drawinga stippled line, each bit in the stipple pattern is
+ When drawing a stippled line, each bit in the stipple pattern is
repeated N times, where N = line_stipple_factor + 1.
line_last_pixel
Controls whether the last pixel in a line is drawn or not. OpenGL
omits the last pixel to avoid double-drawing pixels at the ends of lines
when drawing connected lines.
+
+Points
+------
+
+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 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.
+
+
+sprite_coord_mode
+^^^^^^^^^^^^^^^^^
+
+Specifies how the value for each shader output should be computed when drawing
+point sprites. For PIPE_SPRITE_COORD_LOWER_LEFT, the lower-left vertex will
+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.
+
+
+point_quad_rasterization
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Determines if points should be rasterized according to quad or point
+rasterization 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.
+
+If this state is enabled, point smoothing and antialiasing are
+disabled. If it is disabled, point sprite coordinates are not
+generated.
+
+.. note::
+
+ 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_size_per_vertex
- Whether vertices have a point size element.
+ Whether the vertex shader is expected to have a point size output.
+ Undefined behaviour is permitted if there is disagreement between
+ this flag and the actual bound shader.
point_size
The size of points, if not specified per-vertex.
-point_size_min
- The minimum size of points.
-point_size_max
- The maximum size of points.
-point_sprite
- Whether points are drawn as sprites (textured quads)
-sprite_coord_mode
- Specifies how the value for each shader output should be computed when
- drawing sprites. If PIPE_SPRITE_COORD_NONE, don't change the vertex
- shader output. Otherwise, the four vertices of the resulting quad will
- be assigned texture coordinates. For PIPE_SPRITE_COORD_LOWER_LEFT, the
- lower left vertex will have coordinate (0,0,0,1).
- For PIPE_SPRITE_COORD_UPPER_LEFT, the upper-left vertex will have
- coordinate (0,0,0,1).
- This state is needed by the 'draw' module because that's where each
- point vertex is converted into four quad vertices. There's no other
- place to emit the new vertex texture coordinates which are required for
- sprite rendering.
- Note that when geometry shaders are available, this state could be
- removed. A special geometry shader defined by the state tracker could
- converts the incoming points into quads with the proper texture coords.
+
+
+
+Other Members
+-------------
scissor
Whether the scissor test is enabled.
multisample
- Whether :ref:`MSAA` is enabled.
+ Whether :term:`MSAA` is enabled.
-bypass_vs_clip_and_viewport
- Whether the entire TCL pipeline should be bypassed. This implies that
- vertices are pre-transformed for the viewport, and will not be run
- through the vertex shader. Note that implementations may still clip away
- vertices that are not in the viewport.
+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)::
-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.
+ 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)::
-Notes
------
+ -0.5 0 0.5
+ -0.5 +-----+
+ | |
+ 0 | X |
+ | |
+ 0.5 +-----+
-flatshade
-^^^^^^^^^
+bottom_edge_rule
+ Determines what happens when a pixel sample lies precisely on a triangle
+ edge.
-The actual interpolated shading algorithm is obviously
-implementation-dependent, but will usually be Gourard for most hardware.
+ 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)::
-bypass_vs_clip_and_viewport
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 0 x
+ 0 +--------------------->
+ |
+ | +-------------+
+ | | |
+ | | |
+ | | |
+ | +=============+
+ |
+ y V
-When set, this implies that vertices are pre-transformed for the viewport, and
-will not be run through the vertex shader. Note that implementations may still
-clip away vertices that are not visible.
+ 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)::
-flatshade_first
-^^^^^^^^^^^^^^^
+ 0 x
+ 0 +--------------------->
+ |
+ | +=============+
+ | | |
+ | | |
+ | | |
+ | +-------------+
+ |
+ y V
-There are several important exceptions to the specification of this rule.
+ 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.
-* ``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_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.
+ .. 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.
projects / mesa.git / blobdiff