Skip to content

Commit

Permalink
add more explanation for sampling and addressing modes
Browse files Browse the repository at this point in the history
clear up some formulas
center align images
  • Loading branch information
parbenc committed Aug 12, 2024
1 parent 39e047c commit a13eb26
Showing 1 changed file with 39 additions and 22 deletions.
61 changes: 39 additions & 22 deletions docs/understand/texture_fetching.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,63 +19,77 @@ There are several different sampling and addressing modes, the differences betwe

This image is the texture, that will be used as for the examples below. It is 2x2 texels and is indexed in the [0..1] range.

.. image:: ../data/understand/textures/original.png
.. figure:: ../data/understand/textures/original.png
:width: 150
:alt: Texture used as example
:align: center

Texture used as example
Texture used as example

Texture sampling
===============================================================================

Texture sampling handles the usage of fractional indices. It is the method that describes, which near by values will be used, and how they are combined into the resulting value.

.. _texture_fetching_nearest:
Nearest point sampling
===============================================================================
-------------------------------------------------------------------------------

In this mode the ``tex(x) = T[floor(x)]`` and similarly for 2D and 3D variants. This doesn't interpolate between neighboring values, which results in a pixelated look.
In this mode the ``tex(x) = T[floor(x+0.5)]`` and similarly for 2D and 3D variants. This doesn't interpolate between neighboring values, which results in a pixelated look.

This image is the example texture stretched out to a 4x4 pixel quad, but still indexed in the [0..1] range. The in between values are the same as the values of the nearest texel.

.. image:: ../data/understand/textures/nearest.png
.. figure:: ../data/understand/textures/nearest.png
:width: 300
:alt: Texture upscaled with nearest point sampling
:align: center

Texture upscaled with nearest point sampling
Texture upscaled with nearest point sampling

.. _texture_fetching_linear:
Linear filtering
===============================================================================
-------------------------------------------------------------------------------

The linear filtering method simply does a linear interpolation between values.

* For one dimensional textures it is ``tex(x) = (1-α)T[i] + αT[i+1]``
* For two dimensional textures it is ``tex(x,y) = (1-α)(1-β)T[i,j] + α(1-β)T[i+1,j] + (1-α)βT[i,j+1] + αβT[i+1,j+1]``
* For three dimensional textures it is ``tex(x,y,z) = (1-α)(1-β)(1-γ)T[i,j,k] + α(1-β)(1-γ)T[i+1,j,k] + (1-α)β(1-γ)T[i,j+1,k] + αβ(1-γ)T[i+1,j+1,k] + (1-α)(1-β)γT[i,j,k+1] + α(1-β)γT[i+1,j,k+1] + (1-α)βγT[i,j+1,k+1] + αβγT[i+1,j+1,k+1]``

Where ``x, y, z`` are the floating-point indices, ``i, j, k`` are the integer indices and ``α, β, γ`` values represent how far along the sampled point is on the three axes. These values are calculated by these formulas: ``i = round(x')``, ``α = frac(x')``, ``x' = x - 0.5``, ``j = round(y')``, ``β = frac(y')``, ``y' = y - 0.5``, ``k = round(z')``, ``γ = frac(z')`` and ``z' = z - 0.5``
Where ``x, y, z`` are the floating-point indices, ``i, j, k`` are the integer indices and ``α, β, γ`` values represent how far along the sampled point is on the three axes. These values are calculated by these formulas: ``i = floor(x')``, ``α = frac(x')``, ``x' = x - 0.5``, ``j = floor(y')``, ``β = frac(y')``, ``y' = y - 0.5``, ``k = floor(z')``, ``γ = frac(z')`` and ``z' = z - 0.5``

This image is the example texture stretched out to a 4x4 pixel quad, but still indexed in the [0..1] range. The in between values are interpolated between the neighboring texels.

.. image:: ../data/understand/textures/linear.png
.. figure:: ../data/understand/textures/linear.png
:width: 300
:alt: Texture upscaled with linear filtering
:align: center

Texture upscaled with linear filtering

Texture upscaled with linear filtering
Texture addressing
===============================================================================

Texture addressing mode handles, when the index is out of bounds of the texture. It describes which values of the texture (or a preset value) to use, when the index is out of bounds.

.. _texture_fetching_border:
Address mode border
===============================================================================
-------------------------------------------------------------------------------

This is probably the simplest address mode. When indexing out of bounds, the texture fetching returns a border value. This has to be set before texture fetching.

This image is the example texture on a 4x4 pixel quad indexed in the [0..3] range. The out of bounds values are the border color, which is yellow.

.. image:: ../data/understand/textures/border.png
.. figure:: ../data/understand/textures/border.png
:width: 300
:alt: Texture with yellow border color
:align: center

Texture with yellow border color
Texture with yellow border color

.. _texture_fetching_wrap:
Address mode wrap
===============================================================================
-------------------------------------------------------------------------------

This addressing mode is very simple. Mathematically it uses modulo of the index.

Expand All @@ -85,36 +99,39 @@ This creates a repeating image effect.

This image is the example texture on a 4x4 pixel quad indexed in the [0..3] range. The out of bounds values are repeating the original texture.

.. image:: ../data/understand/textures/wrap.png
.. figure:: ../data/understand/textures/wrap.png
:width: 300
:alt: Texture with wrap addressing
:align: center

Texture with wrap addressing
Texture with wrap addressing

.. _texture_fetching_mirror:
Address mode mirror
===============================================================================
-------------------------------------------------------------------------------

Similar to wrapping mirror mode also creates a repeating image, but this time neighboring instances are mirrored.

This image is the example texture on a 4x4 pixel quad indexed in the [0..3] range. The out of bounds values are repeating the original texture, but mirrored.

.. image:: ../data/understand/textures/mirror.png
.. figure:: ../data/understand/textures/mirror.png
:width: 300
:alt: Texture with mirror addressing
:align: center

Texture with mirror addressing
Texture with mirror addressing

.. _texture_fetching_clamp:
Address mode clamp
===============================================================================
-------------------------------------------------------------------------------

This mode simply clamps the index to be between [0..size-1]. This means that when indexing out of bounds, the values on the edge of the texture will repeat.

This image is the example texture on a 4x4 pixel quad indexed in the [0..3] range. The out of bounds values are repeating the values at the edge of the texture.

.. image:: ../data/understand/textures/clamp.png
.. figure:: ../data/understand/textures/clamp.png
:width: 300
:alt: Texture with clamp addressing
:align: center

Texture with clamp addressing
Texture with clamp addressing

0 comments on commit a13eb26

Please sign in to comment.