docs/gallium/cso/rasterizer.rst - platform/external/mesa3d - Git at Google

 .. _rasterizer:

 Rasterizer
 ==========

 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.

 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
    :ext:`GL_ARB_color_buffer_float`

    D3D11: seems always disabled

    Note pipe_caps.vertex_color_clamped 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
    :ext:`GL_ARB_color_buffer_float`

    D3D11: seems always disabled

    Note pipe_caps.fragment_color_clamped 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.

    The actual interpolated shading algorithm is obviously
    implementation-dependent, but will usually be Gouraud 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.

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

    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_caps.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 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 front-face vertex shader color output is marked with TGSI semantic
    COLOR[0], and back-face COLOR[1].

 front_ccw
     Indicates whether the window order of front-facing polygons is
     counter-clockwise (TRUE) or clockwise (FALSE).

 cull_mode
     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_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 behavior. If true, offset_units is a floating point offset
     which isn't scaled (D3D9). Note that GL/D3D1X behavior 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_smooth
     Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
 line_stipple_enable
     Whether line stippling is enabled.
 line_stipple_pattern
     16-bit bitfield of on/off flags, used to pattern the line stipple.
 line_stipple_factor
     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_caps.tgsi_texcoord !

    Controls automatic texture coordinate generation for rendering sprite points.

    If pipe_caps.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_caps.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 the vertex shader is expected to have a point size output.
     Undefined behavior 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.


 Other Members
 -------------

 scissor
     Whether the scissor test is enabled.

 multisample
     Whether :term:`MSAA` is enabled.

 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 earlier)::

          -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:
      - https://learn.microsoft.com/en-us/windows/win32/direct3d11/d3d10-graphics-programming-guide-rasterizer-stage-rules
      - https://learn.microsoft.com/en-us/windows/win32/direct3d9/rasterization-rules

 clip_halfz
     When true clip space in the z axis goes from [0..1] (D3D).  When false
     [-1, 1] (GL)

 depth_clip_near
     When false, the near depth clipping plane of the view volume is disabled.
 depth_clip_far
     When false, the far depth clipping plane of the view volume is disabled.
 depth_clamp
     Whether the depth value will be clamped to the interval defined by the
     near and far depth range at the per-pixel level, after polygon offset has
     been applied and before depth testing. Note that a clamp to [0,1] according
     to GL rules should always happen even if this is disabled.

 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 PIPE_CONSERVATIVE_RASTER_POST_SNAP
     or PIPE_CONSERVATIVE_RASTER_PRE_SNAP, conservative rasterization is enabled.
     When conservative rasterization is enabled, the polygon smooth, line smooth,
     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.
	.. _rasterizer:

	Rasterizer
	==========

	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.

	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
	:ext:`GL_ARB_color_buffer_float`

	D3D11: seems always disabled

	Note pipe_caps.vertex_color_clamped 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
	:ext:`GL_ARB_color_buffer_float`

	D3D11: seems always disabled

	Note pipe_caps.fragment_color_clamped 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.

	The actual interpolated shading algorithm is obviously
	implementation-dependent, but will usually be Gouraud 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.

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

	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_caps.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 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 front-face vertex shader color output is marked with TGSI semantic
	COLOR[0], and back-face COLOR[1].

	front_ccw
	Indicates whether the window order of front-facing polygons is
	counter-clockwise (TRUE) or clockwise (FALSE).

	cull_mode
	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_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 behavior. If true, offset_units is a floating point offset
	which isn't scaled (D3D9). Note that GL/D3D1X behavior 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_smooth
	Whether lines should be smoothed. Line smoothing is simply anti-aliasing.
	line_stipple_enable
	Whether line stippling is enabled.
	line_stipple_pattern
	16-bit bitfield of on/off flags, used to pattern the line stipple.
	line_stipple_factor
	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_caps.tgsi_texcoord !

	Controls automatic texture coordinate generation for rendering sprite points.

	If pipe_caps.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_caps.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 the vertex shader is expected to have a point size output.
	Undefined behavior 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.



	Other Members
	-------------

	scissor
	Whether the scissor test is enabled.

	multisample
	Whether :term:`MSAA` is enabled.

	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 earlier)::

	-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:
	- https://learn.microsoft.com/en-us/windows/win32/direct3d11/d3d10-graphics-programming-guide-rasterizer-stage-rules
	- https://learn.microsoft.com/en-us/windows/win32/direct3d9/rasterization-rules

	clip_halfz
	When true clip space in the z axis goes from [0..1] (D3D). When false
	[-1, 1] (GL)

	depth_clip_near
	When false, the near depth clipping plane of the view volume is disabled.
	depth_clip_far
	When false, the far depth clipping plane of the view volume is disabled.
	depth_clamp
	Whether the depth value will be clamped to the interval defined by the
	near and far depth range at the per-pixel level, after polygon offset has
	been applied and before depth testing. Note that a clamp to [0,1] according
	to GL rules should always happen even if this is disabled.

	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 PIPE_CONSERVATIVE_RASTER_POST_SNAP
	or PIPE_CONSERVATIVE_RASTER_PRE_SNAP, conservative rasterization is enabled.
	When conservative rasterization is enabled, the polygon smooth, line smooth,
	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.