change wording to be more passive

add explainers to the example textures

.wordlist.txt

@@ -92,6 +92,7 @@ PTX
 PyHIP
 queryable
 prefetching
+quad
 representable
 RMW
 ROCm's
@@ -108,10 +109,13 @@ SPMV
 structs
 SYCL
 syntaxes
+texel
+texels
 tradeoffs
 templated
 typedefs
 UMM
+unintuitive
 upscaled
 variadic
 WinGDB

docs/understand/texture_fetching.rst

@@ -9,16 +9,29 @@ Texture Fetching
 
 `Textures <https://rocm.docs.amd.com/projects/HIP/en/latest/doxygen/html/group___texture.html>`_ are more than just a buffer, that is interpreted as 1D, 2D or 3D array. Because of its legacy as a graphics functionality, textures are indexed with floats. This can happen two different ways, either the index will be in the range of [0..size-1] or in [0..1]. The difference is mathematically just a division, so for the explanations on this page, we'll use the [0..size-1] indices.
 
-Using float indices isn't trivial. You as a developer, have to decide what happens, when the index is a fraction. There is no rule for how to choose between filtering methods, as it is very dependent of the application.
+Using float indices isn't trivial. The two issues that come up are sampling and addressing.
+
+When a texture is indexed with a fraction, the queried value is often between two or more texels (texture elements). The sampling method defines what value to return in these cases.
+
+Sometimes the index is outside the bounds of the texture. This might seem unintuitive, but is useful in computer graphics for putting a texture on a surface multiple times, or just creating a visible sign of out of bounds indexing. Addressing mode defines what value to return when indexing a texture out of bounds.
+
+There are several different sampling and addressing modes, and no rule for how to choose between them, as it is dependent on the application. This means that it has to be decided during development which sampling and addressing method to use.
+
+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
+  :width: 150
+  :alt: Texture used as example
 
-Textures also have a mechanism to handle, what happens when indexing out of bounds. As a developer, you have to decide what happens. There is no rule for how to choose between addressing modes, as it is very dependent of the application.
 
 .. _texture_fetching_nearest:
 Nearest point sampling
 ===============================================================================
 
 In this mode the ``tex(x) = T[floor(x)]`` and similarly for 2D and 3D variants. In practice this will not 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
   :width: 300
   :alt: Texture upscaled with nearest point sampling
@@ -35,6 +48,8 @@ Linear filtering method simply does a linear interpolation between values.
 
 Where ``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``
 
+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
   :width: 300
   :alt: Texture upscaled with linear filtering
@@ -45,6 +60,8 @@ 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
   :width: 300
   :alt: Texture with yellow border color
@@ -59,6 +76,8 @@ This addressing mode is very simple. Mathematically it uses modulo of the index.
 
 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
   :width: 300
   :alt: Texture with wrap addressing
@@ -69,6 +88,8 @@ 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
   :width: 300
   :alt: Texture with mirror addressing
@@ -79,6 +100,8 @@ 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
   :width: 300
   :alt: Texture with clamp addressing