init

docs/gallium/cso/sampler.rst

@@ -0,0 +1,116 @@
+.. _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 consistently across
+  all graphics hardware.  It sometimes acts like CLAMP_TO_EDGE or
+  CLAMP_TO_BORDER.  The behavior 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.
+unnormalized_coords
+    If set, incoming texture coordinates are used as-is to compute
+    texel addresses. When set, 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. If unset, the incoming texture
+    coordinates are assumed to be normalized to the range [0, 1],
+    and will be scaled by the texture dimensions to compute texel
+    addresses.
+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
+    Color union used for texel coordinates that are outside the [0,width-1],
+    [0, height-1] or [0, depth-1] ranges. Interpreted according to sampler
+    view format, unless the driver reports
+    pipe_caps.texture_border_color_quirk, in which case special care has to be
+    taken (see description of the cap).
+max_anisotropy
+    Maximum anisotropy ratio to use when sampling from textures.  For example,
+    if max_anisotropy=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.
+seamless_cube_map
+    If set, the bilinear filter of a cube map may take samples from adjacent
+    cube map faces when sampled near a texture border to produce a seamless
+    look.