1.. _sampler:
2
3Sampler
4=======
5
6Texture units have many options for selecting texels from loaded textures;
7this state controls an individual texture unit's texel-sampling settings.
8
9Texture coordinates are always treated as four-dimensional, and referred to
10with the traditional (S, T, R, Q) notation.
11
12Members
13-------
14
15wrap_s
16    How to wrap the S coordinate. One of PIPE_TEX_WRAP_*.
17wrap_t
18    How to wrap the T coordinate. One of PIPE_TEX_WRAP_*.
19wrap_r
20    How to wrap the R coordinate. One of PIPE_TEX_WRAP_*.
21
22The 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
31  texture wrap mode.  Historically, this mode hasn't acted consistantly across
32  all graphics hardware.  It sometimes acts like CLAMP_TO_EDGE or
33  CLAMP_TO_BORDER.  The behaviour may also vary depending on linear vs.
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
47min_img_filter
48    The image filter to use when minifying texels. One of PIPE_TEX_FILTER_*.
49mag_img_filter
50    The image filter to use when magnifying texels. One of PIPE_TEX_FILTER_*.
51
52The 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
60min_mip_filter
61    The filter to use when minifying mipmapped textures. One of
62    PIPE_TEX_MIPFILTER_*.
63
64The 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
75compare_mode
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.
80    If set to PIPE_TEX_COMPARE_NONE, no comparison calculation is performed.
81compare_func
82    The inequality operator used when compare_mode=1.  One of PIPE_FUNC_x.
83normalized_coords
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).
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.
91lod_bias
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.
96min_lod
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.
99max_lod
100    Maximum level of detail, used to clamp LOD after bias.
101border_color
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
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).
107max_anisotropy
108    Maximum anistropy ratio to use when sampling from textures.  For example,
109    if max_anistropy=4, a region of up to 1 by 4 texels will be sampled.
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.
113seamless_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
116    look.
117