From c3b6adccc91b295772a934ba4115c7f3cced4dfe Mon Sep 17 00:00:00 2001 From: Brian Paul Date: Fri, 5 Mar 2010 09:53:37 -0700 Subject: [PATCH] gallium/docs: updated/improve sampler state documentation --- src/gallium/docs/source/cso/sampler.rst | 98 +++++++++++++++++++------ 1 file changed, 77 insertions(+), 21 deletions(-) diff --git a/src/gallium/docs/source/cso/sampler.rst b/src/gallium/docs/source/cso/sampler.rst index 77979fc44d1..44698d12501 100644 --- a/src/gallium/docs/source/cso/sampler.rst +++ b/src/gallium/docs/source/cso/sampler.rst @@ -13,38 +13,94 @@ Members ------- wrap_s - How to wrap the S coordinate. One of PIPE_TEX_WRAP. + How to wrap the S coordinate. One of PIPE_TEX_WRAP_*. wrap_t - How to wrap the T coordinate. One of PIPE_TEX_WRAP. + How to wrap the T coordinate. One of PIPE_TEX_WRAP_*. wrap_r - How to wrap the R coordinate. One of PIPE_TEX_WRAP. + 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 filter to use when minifying texels. One of PIPE_TEX_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_FILTER. -mag_img_filter - The filter to use when magnifying texels. One of PIPE_TEX_FILTER. + 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, texture output is computed - according to compare_func, using r coord and the texture value as operands. + 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 - How the comparison is computed. One of PIPE_FUNC. + The inequality operator used when compare_mode=1. One of PIPE_FUNC_x. normalized_coords - Whether the texture coordinates are normalized. If normalized, they will - always be in [0, 1]. If not, they will be in the range of each dimension - of the loaded texture. + 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). lod_bias - The bias to apply to the level of detail. + 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. + 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. + Maximum level of detail, used to clamp LOD after bias. border_color - RGBA color used for out-of-bounds coordinates. + RGBA color used for texel coordinates that are outside the [0,width-1], + [0, height-1] or [0, depth-1] ranges. max_anisotropy - Maximum filtering to apply anisotropically to textures. Setting this to - 0 disables 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. + 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. -- 2.30.2