rasterizer.rst 12.7 KB
Newer Older
Corbin Simpson's avatar
Corbin Simpson committed
1
2
.. _rasterizer:

Corbin Simpson's avatar
Corbin Simpson committed
3
4
5
Rasterizer
==========

6
7
8
9
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.

10
11
12
13
14
15
16
17
18
19
20
21
22
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

23
Note the PIPE_CAP_VERTEX_COLOR_CLAMPED query indicates whether or not the
24
driver supports this control.  If it's not supported, gallium frontends may
25
26
27
have to insert extra clamping code.


28
29
30
31
32
33
34
35
36
37
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

38
Note the PIPE_CAP_FRAGMENT_COLOR_CLAMPED query indicates whether or not the
39
driver supports this control.  If it's not supported, gallium frontends may
40
41
have to insert extra clamping code.

42

43
Shading
Corbin Simpson's avatar
Corbin Simpson committed
44
45
-------

Corbin Simpson's avatar
Corbin Simpson committed
46
flatshade
47
48
49
50
51
52
53
54
55
56
57
58
59
^^^^^^^^^

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
60
    clipping time to determine how to set the color of new vertices.
61
62
63

    :ref:`Draw` can implement flat shading by copying the provoking vertex
    color to all the other vertices in the primitive.
64
65

flatshade_first
66
67
68
69
70
^^^^^^^^^^^^^^^

Whether the first vertex should be the provoking vertex, for most primitives.
If not set, the last vertex is the provoking vertex.

71
There are a few important exceptions to the specification of this rule.
72
73
74
75

* ``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.
76
77
78
* ``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.
79
80
81
82
* ``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.

83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
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 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).

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
130
131
offset_units_unscaled
    Specifies the unit of the polygon offset bias. If false, use the
Erik Faye-Lund's avatar
Erik Faye-Lund committed
132
133
    GL/D3D1X behavior. If true, offset_units is a floating point offset
    which isn't scaled (D3D9). Note that GL/D3D1X behavior has different
134
135
    formula whether the depth buffer is unorm or float, which is not
    the case for D3D9.
136
137
offset_scale
    Specifies the polygon offset scale
138
139
offset_clamp
    Upper (if > 0) or lower (if < 0) bound on the polygon offset result
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162



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.


163
164
165
166
167
Points
------

sprite_coord_enable
^^^^^^^^^^^^^^^^^^^
168
The effect of this state depends on PIPE_CAP_TGSI_TEXCOORD !
169

170
171
Controls automatic texture coordinate generation for rendering sprite points.

172
If PIPE_CAP_TGSI_TEXCOORD is false:
173
174
175
176
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.

177
178
179
If PIPE_CAP_TGSI_TEXCOORD is true:
The bitfield refers to inputs with TEXCOORD semantic instead of generic inputs.

180
181
182
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).
183
184
185
186

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
187
be considered a bug in the gallium frontend.
188

189
190
191
This feature is implemented in the :ref:`Draw` module but may also be
implemented natively by GPUs or implemented with a geometry shader.

192
193
194
195
196
197
198
199
200
201

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.

202

203
204
205
point_quad_rasterization
^^^^^^^^^^^^^^^^^^^^^^^^

206
207
208
Determines if points should be rasterized according to quad or point
rasterization rules.

209
210
211
212
213
(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.
214
215
216
217
218
219
220

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.
221
222
223
224
225
226

.. note::

   Some renderers always internally translate points into quads; this state
   still affects those renderers by overriding other rasterization state.

227
228
229
230
231
232
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.
Corbin Simpson's avatar
Corbin Simpson committed
233
234
235
236
point_smooth
    Whether points should be smoothed. Point smoothing turns rectangular
    points into circles or ovals.
point_size_per_vertex
237
    Whether the vertex shader is expected to have a point size output.
Erik Faye-Lund's avatar
Erik Faye-Lund committed
238
    Undefined behavior is permitted if there is disagreement between
239
    this flag and the actual bound shader.
240
241
242
point_size
    The size of points, if not specified per-vertex.

243
244
245
246
247


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

248
249
250
scissor
    Whether the scissor test is enabled.

Corbin Simpson's avatar
Corbin Simpson committed
251
multisample
Corbin Simpson's avatar
Corbin Simpson committed
252
    Whether :term:`MSAA` is enabled.
253

254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
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
324

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

329
330
331
332
333
334
335
336
337
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.
338
339
340
341
342
343
344
345
346
347

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.
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370

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.