From d261e49e8f043668112d632ce485d6436f53108c Mon Sep 17 00:00:00 2001 From: Istvan Kiss Date: Fri, 20 Sep 2024 13:58:36 +0200 Subject: [PATCH] Added texture fetching page --- .wordlist.txt | 6 + docs/data/understand/textures/border.png | Bin 0 -> 1127 bytes docs/data/understand/textures/clamp.png | Bin 0 -> 1146 bytes docs/data/understand/textures/linear.png | Bin 0 -> 2939 bytes docs/data/understand/textures/mirror.png | Bin 0 -> 1155 bytes docs/data/understand/textures/nearest.png | Bin 0 -> 1284 bytes docs/data/understand/textures/original.png | Bin 0 -> 401 bytes docs/data/understand/textures/wrap.png | Bin 0 -> 1166 bytes docs/index.md | 1 + docs/sphinx/_toc.yml.in | 2 + docs/understand/texture_fetching.rst | 165 +++++++++++++++++++++ 11 files changed, 174 insertions(+) create mode 100644 docs/data/understand/textures/border.png create mode 100644 docs/data/understand/textures/clamp.png create mode 100644 docs/data/understand/textures/linear.png create mode 100644 docs/data/understand/textures/mirror.png create mode 100644 docs/data/understand/textures/nearest.png create mode 100644 docs/data/understand/textures/original.png create mode 100644 docs/data/understand/textures/wrap.png create mode 100644 docs/understand/texture_fetching.rst diff --git a/.wordlist.txt b/.wordlist.txt index 87d1579669..5e266ba469 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -85,6 +85,7 @@ Nsight overindex overindexing oversubscription +pixelated pragmas preconditioners prefetched @@ -93,6 +94,7 @@ PTX PyHIP queryable prefetching +quad representable RMW ROCm's @@ -109,11 +111,15 @@ SPMV structs SYCL syntaxes +texel +texels tradeoffs templated typedefs +unintuitive UMM unmap +upscaled variadic WinGDB zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz diff --git a/docs/data/understand/textures/border.png b/docs/data/understand/textures/border.png new file mode 100644 index 0000000000000000000000000000000000000000..e616610c15f2894237fb97ba93a26af994c3a7c4 GIT binary patch literal 1127 zcmeAS@N?(olHy`uVBq!ia0y~yVAKI&4mO}jWo=(6kYXuz@(kesf*OvL4j@;~)5S5Q zV$R!Z8+n-wMOYoBWBaEtmpIp&BqS;6Z5B&2O84grt6yh$?ZK3n%lGX%cl-G7pH(?g zhxB*7kz**BmcS_4#G1k(HbF7Mp>4Qxj>}|!Z|k!x*KgSW>=2U?3-<{D9R=qN4Lk>j zF{kIT)w|v1EqBWJk$s)K?s~*-cZN9+M@%>j>qy4oxyQU;m3b#`TD9~yu;gIyboFyt I=akR{0E_xXKmY&$ literal 0 HcmV?d00001 diff --git a/docs/data/understand/textures/clamp.png b/docs/data/understand/textures/clamp.png new file mode 100644 index 0000000000000000000000000000000000000000..63ed5f116fdd4897a7997c2c82a0b5bf16725669 GIT binary patch literal 1146 zcmeAS@N?(olHy`uVBq!ia0y~yVAKI&4mO}jWo=(6kYXuz@(kesf*OvL4j|Xi)5S5Q zV$R!Z8*`ZrMOYm#1@woXi+sAmORFq}m0h5E*2x*R1`&UD9*b!1_p$%FK6zgKz4c%3 zY-zFnb<>vNL2wgm3WwMP#R!MC1V+i>&artGvD>`l%+6}Ze*MQzdO8Zu8ya{HG8wUO zpAf*o>Gs}xtoS=io)4yV6eQ?lM1Ey%X-K8Odw5 yR=XU(W6Q8_7Wcq8j&OX8x(#1yB^)|E=J#&#Z44AWybD;EFnGH9xvXRtvY3H^?=T269?xHq!oa{S;OXKRQW5v|Qea^+BM-|#b`=+%BMv^N zRf>Pkb6&76)Rgh+xzE2J?90FNyZiN`V!ugWRU-Yx=N3;|qkgh#*NZumQ*1r2U3Psw zN9DEWrg?f+&w44R15SEXs-vvYFo^UYhGD?EcmDdfUq5gByC-hjez(fCV&JlMa-8QV zYcve54aaogc>eS1->-~T9^VgcJ*d3?s1Is20Gkefyg{u6&rNdw!Q4q}MwN_)3(XV5 di|Tpx0y{UamntjU18guec)I$ztaD0e0sxQxdprOD literal 0 HcmV?d00001 diff --git a/docs/data/understand/textures/mirror.png b/docs/data/understand/textures/mirror.png new file mode 100644 index 0000000000000000000000000000000000000000..d26a241183c58f9c992e9878234f3388e5f82b3d GIT binary patch literal 1155 zcmeAS@N?(olHy`uVBq!ia0y~yVAKI&4mO}jWo=(6kYXuz@(kesf*OvL4j|Xc)5S5Q zV$R!Z8*`Zr1za81EtCuGTT>LGDr$X6mF?r3nQu1nGkxE%`TDJH?_=JzCG(H>zrS85 z7jn}4itP|2vaNf|sbCAi1h5LlSFy}lr%btJlf?;u$W54?E6ZREzxre`> zp|P9y{cCNN^NGh_7=B!jiEwC3V3cfPO*s=)Jzwsk;d1s5>OWc67bSuPIm9L?!c`1U y&apRJzr7R`eZ2GsYqg*Li-Hm3acI2nVLWwRcx_JJMqm-cz~JfX=d#Wzp$PzCv{F?7 literal 0 HcmV?d00001 diff --git a/docs/data/understand/textures/nearest.png b/docs/data/understand/textures/nearest.png new file mode 100644 index 0000000000000000000000000000000000000000..edfbf8cfbe0d283d4be1c1260059e6319d9413e9 GIT binary patch literal 1284 zcmeAS@N?(olHy`uVBq!ia0y~yVAKI&4kn<;H+e}VAjMc5RtvY3H^?=T269?xHq0#q~8)5S5QBJS-)LoQ}V9+rcD|1W=AqbF_> z5`0qQ>TlayWz5G%(GU)S$)7DJEUx(+STrTy&a3a!S@)BH`+jOzo-&tLb^rNn@e_^v sHB)4s&hDQys%SI_22Cn>dha(g|E10AYl5^xfF&1$r>mdKI;Vst0E60D5&!@I literal 0 HcmV?d00001 diff --git a/docs/data/understand/textures/original.png b/docs/data/understand/textures/original.png new file mode 100644 index 0000000000000000000000000000000000000000..eaf6e7f7be7cf7f3f6de56ada985dd96375ac07f GIT binary patch literal 401 zcmeAS@N?(olHy`uVBq!ia0vp^Q$U!78A!GZ$vy{CEa{HEjtmSN`?>!lvI6-E$sR$z z3=CCj3=9n|3=F@3LJcn%7)lKo7+xhXFj&oCU=S~uvn$XBD8V1#6XNAf83^QX7I;J!GcfQS24TkI`72U@g6t)pzOL*qI9R!@+2_BLJq8pK zNKW)C1M1a*UWZj~5 zL3^T))>N;hK`TQL)Ys6h%+J-31fbHU3#%@<`%c^=9XAbVvTBKIL`h0wNvc(HQ7VvP zFfuSQ(KWEpH82e^G_W$Uurf8(HZZUV>cW(omGZXFzrOwc{MU{x zOAhb0`d(Jea6t1QlMxH|2>~4i=M4=!!<{3y`P*AwS>x^EPb%Ws_pDCV8yVgPMsS7A z_1|xK71!Tpeh^=r$SB!=oB7A>Z?kR-*X_NzUA$z+hK8P-*)M-9{%?7{?eMD^<)!CZ zSyMQ~CMZTYv?VY~HVtRa=4`_ are more than just a buffer interpreted as a 1D, 2D, or 3D array. + +As textures are associated with graphics, they are indexed using floating-point values. The index can be in the range of [0 to size-1] or [0 to 1]. + +Depending on the index, texture sampling or texture addressing is performed, which decides the return value. + +**Texture sampling**: 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 such cases. + +**Texture addressing**: Sometimes, the index is outside the bounds of the texture. This condition might look like a problem but helps to put a texture on a surface multiple times or to create a visible sign of out-of-bounds indexing, in computer graphics. The addressing mode defines what value to return when indexing a texture out of bounds. + +The different sampling and addressing modes are described in the following sections. + +Here is the sample texture used in this document for demonstration purposes. It is 2x2 texels and indexed in the [0 to 1] range. + +.. figure:: ../data/understand/textures/original.png + :width: 150 + :alt: Sample texture + :align: center + + Texture used as example + +Texture sampling +=============================================================================== + +Texture sampling handles the usage of fractional indices. It is the method that describes, which nearby values will be used, and how they are combined into the resulting value. + +The various texture sampling methods are discussed in the following sections. + +.. _texture_fetching_nearest: +Nearest point sampling +------------------------------------------------------------------------------- + +In this method, the modulo of index is calculated as: + +``tex(x) = T[floor(x)]`` + +This is also applicable for 2D and 3D variants. + +This doesn't interpolate between neighboring values, which results in a pixelated look. + +The following image shows a texture stretched to a 4x4 pixel quad but still indexed in the [0 to 1] range. The in-between values are the same as the values of the nearest texel. + +.. figure:: ../data/understand/textures/nearest.png + :width: 300 + :alt: Texture upscaled with nearest point sampling + :align: center + + Texture upscaled with nearest point sampling + +.. _texture_fetching_linear: +Linear filtering +------------------------------------------------------------------------------- + +The linear filtering method does a linear interpolation between values. Linear interpolation is used to create a linear transition between two values. The formula used is ``(1-t)P1 + tP2`` where ``P1`` and ``P2`` are the values and ``t`` is within the [0 to 1] range. + +In the case of texture sampling the following formulas are used: + +* For one dimensional textures: ``tex(x) = (1-α)T[i] + αT[i+1]`` +* For two dimensional textures: ``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: ``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, and, z are the floating-point indices. i, j, and, k are the integer indices and, α, β, 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 following image shows a texture stretched out to a 4x4 pixel quad, but still indexed in the [0 to 1] range. The in-between values are interpolated between the neighboring texels. + +.. figure:: ../data/understand/textures/linear.png + :width: 300 + :alt: Texture upscaled with linear filtering + :align: center + + Texture upscaled with linear filtering + +Texture addressing +=============================================================================== + +Texture addressing mode handles the index that is out of bounds of the texture. This mode describes which values of the texture or a preset value to use when the index is out of bounds. + +The following sections describe the various texture addressing methods. + +.. _texture_fetching_border: +Address mode border +------------------------------------------------------------------------------- + +In this method, the texture fetching returns a border value when indexing out of bounds. The border value must be set before texture fetching. + +The following image shows the texture on a 4x4 pixel quad, indexed in the [0 to 3] range. The out-of-bounds values are the border color, which is yellow. + +.. figure:: ../data/understand/textures/border.png + :width: 300 + :alt: Texture with yellow border color + :align: center + + Texture with yellow border color. + +The purple lines are not part of the texture. They only denote the edge, where the addressing begins. + +.. _texture_fetching_clamp: +Address mode clamp +------------------------------------------------------------------------------- + +This mode clamps the index between [0 to size-1]. Due to this, when indexing out-of-bounds, the values on the edge of the texture repeat. The clamp mode is the default addressing mode. + +The following image shows the texture on a 4x4 pixel quad, indexed in the [0 to 3] range. The out-of-bounds values are repeating the values at the edge of the texture. + +.. figure:: ../data/understand/textures/clamp.png + :width: 300 + :alt: Texture with clamp addressing + :align: center + + Texture with clamp addressing + +The purple lines are not part of the texture. They only denote the edge, where the addressing begins. + +.. _texture_fetching_wrap: +Address mode wrap +------------------------------------------------------------------------------- + +Wrap mode addressing is only available for normalized texture coordinates. In this addressing mode, the fractional part of the index is used: + +``tex(frac(x))`` + +This creates a repeating image effect. + +The following image shows the texture on a 4x4 pixel quad, indexed in the [0 to 3] range. The out-of-bounds values are repeating the original texture. + +.. figure:: ../data/understand/textures/wrap.png + :width: 300 + :alt: Texture with wrap addressing + :align: center + + Texture with wrap addressing. + +The purple lines are not part of the texture. They only denote the edge, where the addressing begins. + +.. _texture_fetching_mirror: +Address mode mirror +------------------------------------------------------------------------------- + +Similar to the wrap mode the mirror mode is only available for normalized texture coordinates and also creates a repeating image, but mirroring the neighboring instances. + +The formula is the following: + +``tex(frac(x))``, if ``floor(x)`` is even, + +``tex(1 - frac(x))``, if ``floor(x)`` is odd. + +The following image shows the texture on a 4x4 pixel quad, indexed in the [0 to 3] range. The out-of-bounds values are repeating the original texture, but mirrored. + +.. figure:: ../data/understand/textures/mirror.png + :width: 300 + :alt: Texture with mirror addressing + :align: center + + Texture with mirror addressing + +The purple lines are not part of the texture. They only denote the edge, where the addressing begins.