From 73814d1562c945455c9ab8dc7cbfd708c33ddb34 Mon Sep 17 00:00:00 2001 From: Istvan Kiss Date: Wed, 25 Sep 2024 16:31:27 +0200 Subject: [PATCH] Fix the texture fetching warnings and fix precision support broken link --- docs/index.md | 2 +- docs/understand/hardware_implementation.rst | 2 +- docs/understand/texture_fetching.rst | 103 ++++++++++++++------ 3 files changed, 77 insertions(+), 30 deletions(-) diff --git a/docs/index.md b/docs/index.md index 476564993f..81ffc9c921 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,7 +32,7 @@ On non-AMD platforms, like NVIDIA, HIP provides header files required to support * {doc}`./understand/programming_model` * {doc}`./understand/hardware_implementation` * {doc}`./understand/amd_clr` -* [Texture fetching](./understand/texture_fetching) +* {doc}`./understand/texture_fetching` ::: diff --git a/docs/understand/hardware_implementation.rst b/docs/understand/hardware_implementation.rst index 9cf97b444a..7352841926 100644 --- a/docs/understand/hardware_implementation.rst +++ b/docs/understand/hardware_implementation.rst @@ -110,7 +110,7 @@ The general structure of CUs stays mostly as it is in GCN architectures. The most prominent change is the addition of matrix ALUs, which can greatly improve the performance of algorithms involving matrix multiply-accumulate operations for -:doc:`int8, float16, bfloat16 or float32`. +:doc:`int8, float16, bfloat16 or float32`. .. figure:: ../data/understand/hardware_implementation/cdna3_cu.png :alt: Block diagram showing the structure of a CDNA3 compute unit. It includes diff --git a/docs/understand/texture_fetching.rst b/docs/understand/texture_fetching.rst index 259186b605..498e5723f3 100644 --- a/docs/understand/texture_fetching.rst +++ b/docs/understand/texture_fetching.rst @@ -1,25 +1,36 @@ .. meta:: :description: This chapter describes the texture fetching modes of the HIP ecosystem - ROCm software. + ROCm software. :keywords: AMD, ROCm, HIP, Texture, Texture Fetching ******************************************************************************* Texture fetching ******************************************************************************* -`Textures <../doxygen/html/group___texture.html>`_ are more than just a buffer interpreted as a 1D, 2D, or 3D array. +`Textures <../doxygen/html/group___texture.html>`_ 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]. +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. +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 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. +**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. +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. +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 @@ -31,11 +42,14 @@ Here is the sample texture used in this document for demonstration purposes. It 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. +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 ------------------------------------------------------------------------------- @@ -45,9 +59,12 @@ In this method, the modulo of index is calculated as: This is also applicable for 2D and 3D variants. -This doesn't interpolate between neighboring values, which results in a pixelated look. +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. +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 @@ -57,10 +74,14 @@ The following image shows a texture stretched to a 4x4 pixel quad but still inde 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. +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: @@ -68,9 +89,13 @@ In the case of texture sampling the following formulas are used: * 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`` +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. +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 @@ -82,17 +107,22 @@ This following image shows a texture stretched out to a 4x4 pixel quad, but stil 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. +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. +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. +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 @@ -101,15 +131,21 @@ The following image shows the texture on a 4x4 pixel quad, indexed in the [0 to Texture with yellow border color. -The purple lines are not part of the texture. They only denote the edge, where the addressing begins. +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. +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. +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 @@ -118,19 +154,23 @@ The following image shows the texture on a 4x4 pixel quad, indexed in the [0 to Texture with clamp addressing -The purple lines are not part of the texture. They only denote the edge, where the addressing begins. +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: +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. +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 @@ -139,21 +179,27 @@ The following image shows the texture on a 4x4 pixel quad, indexed in the [0 to Texture with wrap addressing. -The purple lines are not part of the texture. They only denote the edge, where the addressing begins. +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. +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(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. +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 @@ -162,4 +208,5 @@ The following image shows the texture on a 4x4 pixel quad, indexed in the [0 to Texture with mirror addressing -The purple lines are not part of the texture. They only denote the edge, where the addressing begins. +The purple lines are not part of the texture. They only denote the edge, where +the addressing begins.