Corbin Simpson | a524aab | 2009-12-20 19:41:50 -0800 | [diff] [blame] | 1 | .. _sampler: |
| 2 | |
Corbin Simpson | c686e17 | 2009-12-20 15:00:40 -0800 | [diff] [blame] | 3 | Sampler |
| 4 | ======= |
| 5 | |
| 6 | Texture units have many options for selecting texels from loaded textures; |
| 7 | this state controls an individual texture unit's texel-sampling settings. |
| 8 | |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 9 | Texture coordinates are always treated as four-dimensional, and referred to |
| 10 | with the traditional (S, T, R, Q) notation. |
| 11 | |
Corbin Simpson | c686e17 | 2009-12-20 15:00:40 -0800 | [diff] [blame] | 12 | Members |
| 13 | ------- |
| 14 | |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 15 | wrap_s |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 16 | How to wrap the S coordinate. One of PIPE_TEX_WRAP_*. |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 17 | wrap_t |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 18 | How to wrap the T coordinate. One of PIPE_TEX_WRAP_*. |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 19 | wrap_r |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 20 | How to wrap the R coordinate. One of PIPE_TEX_WRAP_*. |
| 21 | |
| 22 | The wrap modes are: |
| 23 | |
| 24 | * ``PIPE_TEX_WRAP_REPEAT``: Standard coord repeat/wrap-around mode. |
| 25 | * ``PIPE_TEX_WRAP_CLAMP_TO_EDGE``: Clamp coord to edge of texture, the border |
| 26 | color is never sampled. |
| 27 | * ``PIPE_TEX_WRAP_CLAMP_TO_BORDER``: Clamp coord to border of texture, the |
| 28 | border color is sampled when coords go outside the range [0,1]. |
| 29 | * ``PIPE_TEX_WRAP_CLAMP``: The coord is clamped to the range [0,1] before |
| 30 | scaling to the texture size. This corresponds to the legacy OpenGL GL_CLAMP |
Erik Faye-Lund | 6ec9a7e | 2020-09-28 17:56:22 +0200 | [diff] [blame] | 31 | texture wrap mode. Historically, this mode hasn't acted consistently across |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 32 | all graphics hardware. It sometimes acts like CLAMP_TO_EDGE or |
Erik Faye-Lund | 9890927 | 2020-09-25 14:54:56 +0200 | [diff] [blame] | 33 | CLAMP_TO_BORDER. The behavior may also vary depending on linear vs. |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 34 | nearest sampling mode. |
| 35 | * ``PIPE_TEX_WRAP_MIRROR_REPEAT``: If the integer part of the coordinate |
| 36 | is odd, the coord becomes (1 - coord). Then, normal texture REPEAT is |
| 37 | applied to the coord. |
| 38 | * ``PIPE_TEX_WRAP_MIRROR_CLAMP_TO_EDGE``: First, the absolute value of the |
| 39 | coordinate is computed. Then, regular CLAMP_TO_EDGE is applied to the coord. |
| 40 | * ``PIPE_TEX_WRAP_MIRROR_CLAMP_TO_BORDER``: First, the absolute value of the |
| 41 | coordinate is computed. Then, regular CLAMP_TO_BORDER is applied to the |
| 42 | coord. |
| 43 | * ``PIPE_TEX_WRAP_MIRROR_CLAMP``: First, the absolute value of the coord is |
| 44 | computed. Then, regular CLAMP is applied to the coord. |
| 45 | |
| 46 | |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 47 | min_img_filter |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 48 | The image filter to use when minifying texels. One of PIPE_TEX_FILTER_*. |
| 49 | mag_img_filter |
| 50 | The image filter to use when magnifying texels. One of PIPE_TEX_FILTER_*. |
| 51 | |
| 52 | The texture image filter modes are: |
| 53 | |
| 54 | * ``PIPE_TEX_FILTER_NEAREST``: One texel is fetched from the texture image |
| 55 | at the texture coordinate. |
| 56 | * ``PIPE_TEX_FILTER_LINEAR``: Two, four or eight texels (depending on the |
| 57 | texture dimensions; 1D/2D/3D) are fetched from the texture image and |
| 58 | linearly weighted and blended together. |
| 59 | |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 60 | min_mip_filter |
| 61 | The filter to use when minifying mipmapped textures. One of |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 62 | PIPE_TEX_MIPFILTER_*. |
| 63 | |
| 64 | The texture mip filter modes are: |
| 65 | |
| 66 | * ``PIPE_TEX_MIPFILTER_NEAREST``: A single mipmap level/image is selected |
| 67 | according to the texture LOD (lambda) value. |
| 68 | * ``PIPE_TEX_MIPFILTER_LINEAR``: The two mipmap levels/images above/below |
| 69 | the texture LOD value are sampled from. The results of sampling from |
| 70 | those two images are blended together with linear interpolation. |
| 71 | * ``PIPE_TEX_MIPFILTER_NONE``: Mipmap filtering is disabled. All texels |
| 72 | are taken from the level 0 image. |
| 73 | |
| 74 | |
Roland Scheidegger | c6c9d3b | 2010-01-21 20:22:24 +0100 | [diff] [blame] | 75 | compare_mode |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 76 | If set to PIPE_TEX_COMPARE_R_TO_TEXTURE, the result of texture sampling |
| 77 | is not a color but a true/false value which is the result of comparing the |
| 78 | sampled texture value (typically a Z value from a depth texture) to the |
| 79 | texture coordinate's R component. |
Roland Scheidegger | c6c9d3b | 2010-01-21 20:22:24 +0100 | [diff] [blame] | 80 | If set to PIPE_TEX_COMPARE_NONE, no comparison calculation is performed. |
| 81 | compare_func |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 82 | The inequality operator used when compare_mode=1. One of PIPE_FUNC_x. |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 83 | normalized_coords |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 84 | If set, the incoming texture coordinates (nominally in the range [0,1]) |
| 85 | will be scaled by the texture width, height, depth to compute texel |
| 86 | addresses. Otherwise, the texture coords are used as-is (they are not |
| 87 | scaled by the texture dimensions). |
Brian Paul | 76e8778 | 2010-03-05 13:30:24 -0700 | [diff] [blame] | 88 | When normalized_coords=0, only a subset of the texture wrap modes are |
| 89 | allowed: PIPE_TEX_WRAP_CLAMP, PIPE_TEX_WRAP_CLAMP_TO_EDGE and |
| 90 | PIPE_TEX_WRAP_CLAMP_TO_BORDER. |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 91 | lod_bias |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 92 | Bias factor which is added to the computed level of detail. |
| 93 | The normal level of detail is computed from the partial derivatives of |
| 94 | the texture coordinates and/or the fragment shader TEX/TXB/TXL |
| 95 | instruction. |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 96 | min_lod |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 97 | Minimum level of detail, used to clamp LOD after bias. The LOD values |
| 98 | correspond to mipmap levels where LOD=0 is the level 0 mipmap image. |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 99 | max_lod |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 100 | Maximum level of detail, used to clamp LOD after bias. |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 101 | border_color |
Dave Airlie | 9f61e43 | 2011-09-27 10:08:34 +0100 | [diff] [blame] | 102 | Color union used for texel coordinates that are outside the [0,width-1], |
| 103 | [0, height-1] or [0, depth-1] ranges. Interpreted according to sampler |
Christoph Bumiller | 729abfd | 2013-04-12 13:42:01 +0200 | [diff] [blame] | 104 | view format, unless the driver reports |
| 105 | PIPE_CAP_TEXTURE_BORDER_COLOR_QUIRK, in which case special care has to be |
| 106 | taken (see description of the cap). |
Corbin Simpson | c80f2b0 | 2009-12-20 16:40:39 -0800 | [diff] [blame] | 107 | max_anisotropy |
Erik Faye-Lund | a22cedf | 2020-09-30 15:20:15 +0200 | [diff] [blame^] | 108 | Maximum anisotropy ratio to use when sampling from textures. For example, |
| 109 | if max_anisotropy=4, a region of up to 1 by 4 texels will be sampled. |
Brian Paul | c3b6adc | 2010-03-05 09:53:37 -0700 | [diff] [blame] | 110 | Set to zero to disable anisotropic filtering. Any other setting enables |
| 111 | anisotropic filtering, however it's not unexpected some drivers only will |
| 112 | change their filtering with a setting of 2 and higher. |
Marek Olšák | a5f0a11 | 2011-05-02 02:37:46 +0200 | [diff] [blame] | 113 | seamless_cube_map |
| 114 | If set, the bilinear filter of a cube map may take samples from adjacent |
| 115 | cube map faces when sampled near a texture border to produce a seamless |
Christoph Bumiller | 729abfd | 2013-04-12 13:42:01 +0200 | [diff] [blame] | 116 | look. |