Home | History | Annotate | Download | only in cso
      1 .. _sampler:
      2 
      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 
      9 Texture coordinates are always treated as four-dimensional, and referred to
     10 with the traditional (S, T, R, Q) notation.
     11 
     12 Members
     13 -------
     14 
     15 wrap_s
     16     How to wrap the S coordinate. One of PIPE_TEX_WRAP_*.
     17 wrap_t
     18     How to wrap the T coordinate. One of PIPE_TEX_WRAP_*.
     19 wrap_r
     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
     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 
     47 min_img_filter
     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 
     60 min_mip_filter
     61     The filter to use when minifying mipmapped textures. One of
     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 
     75 compare_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.
     81 compare_func
     82     The inequality operator used when compare_mode=1.  One of PIPE_FUNC_x.
     83 normalized_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.
     91 lod_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.
     96 min_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.
     99 max_lod
    100     Maximum level of detail, used to clamp LOD after bias.
    101 border_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.
    105 max_anisotropy
    106     Maximum anistropy ratio to use when sampling from textures.  For example,
    107     if max_anistropy=4, a region of up to 1 by 4 texels will be sampled.
    108     Set to zero to disable anisotropic filtering.  Any other setting enables
    109     anisotropic filtering, however it's not unexpected some drivers only will
    110     change their filtering with a setting of 2 and higher.
    111 seamless_cube_map
    112     If set, the bilinear filter of a cube map may take samples from adjacent
    113     cube map faces when sampled near a texture border to produce a seamless
    114     look.