diff options
Diffstat (limited to 'src/gallium/docs/source/cso')
| -rw-r--r-- | src/gallium/docs/source/cso/blend.rst | 55 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/dsa.rst | 61 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/rasterizer.rst | 188 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/sampler.rst | 109 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/shader.rst | 12 | ||||
| -rw-r--r-- | src/gallium/docs/source/cso/velems.rst | 24 |
6 files changed, 449 insertions, 0 deletions
diff --git a/src/gallium/docs/source/cso/blend.rst b/src/gallium/docs/source/cso/blend.rst new file mode 100644 index 0000000000..c74396284c --- /dev/null +++ b/src/gallium/docs/source/cso/blend.rst @@ -0,0 +1,55 @@ +.. _blend: + +Blend +===== + +This state controls blending of the final fragments into the target rendering +buffers. + +Blend Factors +------------- + +The blend factors largely follow the same pattern as their counterparts +in other modern and legacy drawing APIs. + +XXX blurb about dual-source blends + +Members +------- + +independent_blend_enable + If enabled, blend state is different for each render target, and + for each render target set in the respective member of the rt array. + If disabled, blend state is the same for all render targets, and only + the first member of the rt array contains valid data. +logicop_enable + Enables logic ops. Cannot be enabled at the same time as blending, and + is always the same for all render targets. +logicop_func + The logic operation to use if logic ops are enabled. One of PIPE_LOGICOP. +dither + Whether dithering is enabled. Note: Dithering is implementation-dependent. +rt + Contains the per-rendertarget blend state. + +Per-rendertarget Members +------------------------ + +blend_enable + If blending is enabled, perform a blend calculation according to blend + functions and source/destination factors. Otherwise, the incoming fragment + color gets passed unmodified (but colormask still applies). +rgb_func + The blend function to use for rgb channels. One of PIPE_BLEND. +rgb_src_factor + The blend source factor to use for rgb channels. One of PIPE_BLENDFACTOR. +rgb_dst_factor + The blend destination factor to use for rgb channels. One of PIPE_BLENDFACTOR. +alpha_func + The blend function to use for the alpha channel. One of PIPE_BLEND. +alpha_src_factor + The blend source factor to use for the alpha channel. One of PIPE_BLENDFACTOR. +alpha_dst_factor + The blend destination factor to use for alpha channel. One of PIPE_BLENDFACTOR. +colormask + Bitmask of which channels to write. Combination of PIPE_MASK bits. diff --git a/src/gallium/docs/source/cso/dsa.rst b/src/gallium/docs/source/cso/dsa.rst new file mode 100644 index 0000000000..1bbe381f9e --- /dev/null +++ b/src/gallium/docs/source/cso/dsa.rst @@ -0,0 +1,61 @@ +.. _depth,stencil,&alpha: + +Depth, Stencil, & Alpha +======================= + +These three states control the depth, stencil, and alpha tests, used to +discard fragments that have passed through the fragment shader. + +Traditionally, these three tests have been clumped together in hardware, so +they are all stored in one structure. + +During actual execution, the order of operations done on fragments is always: + +* Alpha +* Stencil +* Depth + +Depth Members +------------- + +enabled + Whether the depth test is enabled. +writemask + Whether the depth buffer receives depth writes. +func + The depth test function. One of PIPE_FUNC. + +Stencil Members +--------------- + +enabled + Whether the stencil test is enabled. For the second stencil, whether the + two-sided stencil is enabled. If two-sided stencil is disabled, the other + fields for the second array member are not valid. +func + The stencil test function. One of PIPE_FUNC. +valuemask + Stencil test value mask; this is ANDed with the value in the stencil + buffer and the reference value before doing the stencil comparison test. +writemask + Stencil test writemask; this controls which bits of the stencil buffer + are written. +fail_op + The operation to carry out if the stencil test fails. One of + PIPE_STENCIL_OP. +zfail_op + The operation to carry out if the stencil test passes but the depth test + fails. One of PIPE_STENCIL_OP. +zpass_op + The operation to carry out if the stencil test and depth test both pass. + One of PIPE_STENCIL_OP. + +Alpha Members +------------- + +enabled + Whether the alpha test is enabled. +func + The alpha test function. One of PIPE_FUNC. +ref_value + Alpha test reference value; used for certain functions. diff --git a/src/gallium/docs/source/cso/rasterizer.rst b/src/gallium/docs/source/cso/rasterizer.rst new file mode 100644 index 0000000000..ad1612f93e --- /dev/null +++ b/src/gallium/docs/source/cso/rasterizer.rst @@ -0,0 +1,188 @@ +.. _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. + +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 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. + + :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 several 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``: 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. + +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 +offset_scale + Specifies the polygon offset scale + + + +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 +^^^^^^^^^^^^^^^^^^^ + +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 +^^^^^^^^^^^^^^^^^ + +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. + +.. 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 +^^^^^^^^^^^^^^^^^^^^^^^^ + +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. + +.. note:: + + Some renderers always internally translate points into quads; this state + still affects those renderers by overriding other rasterization state. + +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 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. + + + +Other Members +------------- + +scissor + Whether the scissor test 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. + diff --git a/src/gallium/docs/source/cso/sampler.rst b/src/gallium/docs/source/cso/sampler.rst new file mode 100644 index 0000000000..9bbb784de8 --- /dev/null +++ b/src/gallium/docs/source/cso/sampler.rst @@ -0,0 +1,109 @@ +.. _sampler: + +Sampler +======= + +Texture units have many options for selecting texels from loaded textures; +this state controls an individual texture unit's texel-sampling settings. + +Texture coordinates are always treated as four-dimensional, and referred to +with the traditional (S, T, R, Q) notation. + +Members +------- + +wrap_s + How to wrap the S coordinate. One of PIPE_TEX_WRAP_*. +wrap_t + How to wrap the T coordinate. One of PIPE_TEX_WRAP_*. +wrap_r + How to wrap the R coordinate. One of PIPE_TEX_WRAP_*. + +The wrap modes are: + +* ``PIPE_TEX_WRAP_REPEAT``: Standard coord repeat/wrap-around mode. +* ``PIPE_TEX_WRAP_CLAMP_TO_EDGE``: Clamp coord to edge of texture, the border + color is never sampled. +* ``PIPE_TEX_WRAP_CLAMP_TO_BORDER``: Clamp coord to border of texture, the + border color is sampled when coords go outside the range [0,1]. +* ``PIPE_TEX_WRAP_CLAMP``: The coord is clamped to the range [0,1] before + scaling to the texture size. This corresponds to the legacy OpenGL GL_CLAMP + texture wrap mode. Historically, this mode hasn't acted consistantly across + all graphics hardware. It sometimes acts like CLAMP_TO_EDGE or + CLAMP_TO_BORDER. The behaviour may also vary depending on linear vs. + nearest sampling mode. +* ``PIPE_TEX_WRAP_MIRROR_REPEAT``: If the integer part of the coordinate + is odd, the coord becomes (1 - coord). Then, normal texture REPEAT is + applied to the coord. +* ``PIPE_TEX_WRAP_MIRROR_CLAMP_TO_EDGE``: First, the absolute value of the + coordinate is computed. Then, regular CLAMP_TO_EDGE is applied to the coord. +* ``PIPE_TEX_WRAP_MIRROR_CLAMP_TO_BORDER``: First, the absolute value of the + coordinate is computed. Then, regular CLAMP_TO_BORDER is applied to the + coord. +* ``PIPE_TEX_WRAP_MIRROR_CLAMP``: First, the absolute value of the coord is + computed. Then, regular CLAMP is applied to the coord. + + +min_img_filter + The image filter to use when minifying texels. One of PIPE_TEX_FILTER_*. +mag_img_filter + The image filter to use when magnifying texels. One of PIPE_TEX_FILTER_*. + +The texture image filter modes are: + +* ``PIPE_TEX_FILTER_NEAREST``: One texel is fetched from the texture image + at the texture coordinate. +* ``PIPE_TEX_FILTER_LINEAR``: Two, four or eight texels (depending on the + texture dimensions; 1D/2D/3D) are fetched from the texture image and + linearly weighted and blended together. + +min_mip_filter + The filter to use when minifying mipmapped textures. One of + PIPE_TEX_MIPFILTER_*. + +The texture mip filter modes are: + +* ``PIPE_TEX_MIPFILTER_NEAREST``: A single mipmap level/image is selected + according to the texture LOD (lambda) value. +* ``PIPE_TEX_MIPFILTER_LINEAR``: The two mipmap levels/images above/below + the texture LOD value are sampled from. The results of sampling from + those two images are blended together with linear interpolation. +* ``PIPE_TEX_MIPFILTER_NONE``: Mipmap filtering is disabled. All texels + are taken from the level 0 image. + + +compare_mode + If set to PIPE_TEX_COMPARE_R_TO_TEXTURE, the result of texture sampling + is not a color but a true/false value which is the result of comparing the + sampled texture value (typically a Z value from a depth texture) to the + texture coordinate's R component. + If set to PIPE_TEX_COMPARE_NONE, no comparison calculation is performed. +compare_func + The inequality operator used when compare_mode=1. One of PIPE_FUNC_x. +normalized_coords + If set, the incoming texture coordinates (nominally in the range [0,1]) + will be scaled by the texture width, height, depth to compute texel + addresses. Otherwise, the texture coords are used as-is (they are not + scaled by the texture dimensions). + When normalized_coords=0, only a subset of the texture wrap modes are + allowed: PIPE_TEX_WRAP_CLAMP, PIPE_TEX_WRAP_CLAMP_TO_EDGE and + PIPE_TEX_WRAP_CLAMP_TO_BORDER. +lod_bias + Bias factor which is added to the computed level of detail. + The normal level of detail is computed from the partial derivatives of + the texture coordinates and/or the fragment shader TEX/TXB/TXL + instruction. +min_lod + Minimum level of detail, used to clamp LOD after bias. The LOD values + correspond to mipmap levels where LOD=0 is the level 0 mipmap image. +max_lod + Maximum level of detail, used to clamp LOD after bias. +border_color + RGBA color used for texel coordinates that are outside the [0,width-1], + [0, height-1] or [0, depth-1] ranges. +max_anisotropy + Maximum anistropy ratio to use when sampling from textures. For example, + if max_anistropy=4, a region of up to 1 by 4 texels will be sampled. + Set to zero to disable anisotropic filtering. Any other setting enables + anisotropic filtering, however it's not unexpected some drivers only will + change their filtering with a setting of 2 and higher. diff --git a/src/gallium/docs/source/cso/shader.rst b/src/gallium/docs/source/cso/shader.rst new file mode 100644 index 0000000000..0ee42c8787 --- /dev/null +++ b/src/gallium/docs/source/cso/shader.rst @@ -0,0 +1,12 @@ +.. _shader: + +Shader +====== + +One of the two types of shaders supported by Gallium. + +Members +------- + +tokens + A list of tgsi_tokens. diff --git a/src/gallium/docs/source/cso/velems.rst b/src/gallium/docs/source/cso/velems.rst new file mode 100644 index 0000000000..92cde014fb --- /dev/null +++ b/src/gallium/docs/source/cso/velems.rst @@ -0,0 +1,24 @@ +.. _vertexelements: + +Vertex Elements +=============== + +This state controls format etc. of the input attributes contained +in the pipe_vertex_buffer(s). There's one pipe_vertex_element array member +for each input attribute. + +Members +------- + +src_offset + The byte offset of the attribute in the buffer given by + vertex_buffer_index for the first vertex. +instance_divisor + The instance data rate divisor, used for instancing. + 0 means this is per-vertex data, n means per-instance data used for + n consecutive instances (n > 0). +vertex_buffer_index + The vertex buffer this attribute lives in. Several attributes may + live in the same vertex buffer. +src_format + The format of the attribute data. One of the PIPE_FORMAT tokens. |