Merge branch 'main' of https://github.com/irisshaders/docspage

Author: jbritain

README.md

@@ -102,10 +102,3 @@ PR's May take a while to be added, as they need to be fully verified, and someon
 
 ## Translations (i18n)
 Translations are not yet supported, but once the english version is complete we will begin building out the languages.
-
-## Contributors
-- [Iris Docs](https://github.com/IrisShaders/ShaderDoc/tree/master) - Most of the early documentation
-- WhyFencePost / WhyFenceCode - The page and a lot of the data transfer
-- NinjaMike - Many uniforms including Iris exclusive uniforms, constants, shaders.properties, programs
-- jbritain - Some uniforms, other miscellaneous things
-- kloppi417 - editor

src/content/docs/current/Reference/Attributes/at_tangent.mdx

@@ -12,16 +12,24 @@ sidebar:
 
 ---
 
-The tangent vector in model space. The `xyz` components store the tangent, and the `w` component stores the handedness of normal/tangent. The handedness should be used to invert the bitangent in cases where a texture is mirrored and the cross product of the normal and tangent vectors would produce an inverted bitangent vector. For example:
-```glsl
-vec3 normal = normalMatrix * vaNormal;
-vec3 tangent = normalMatrix * at_tangent.xyz;
+The `xyz` components store an approximation of the current tangent vector in model space, and the sign of the `w` component the handedness of the normal/tangent.
+
+:::note
+`at_tangent.xyz` is not guaranteed to be normalized, and `at_tangent.w` is only guaranteed to be in the range `[-1.0, 1.0]` and not zero.
+:::
 
-vec3 bitangent = cross(tangent, normal) * at_tangent.w;
+The handedness should be used to invert the bitangent in cases where a texture is mirrored and the cross product of the normal and tangent vectors would produce an inverted bitangent vector. For example, in [view space](/current/how-to/coordinate_spaces/):
+```glsl
+vec3 normal = normalMatrix * normalize(vaNormal);
+vec3 tangent = normalMatrix * normalize(at_tangent.xyz);
+```
+```glsl
+vec3 normal = gl_NormalMatrix * normalize(gl_Normal);
+vec3 tangent = gl_NormalMatrix * normalize(at_tangent.xyz);
 ```
 ```glsl
-vec3 normal = gl_NormalMatrix * gl_Normal;
-vec3 tangent = gl_NormalMatrix * at_tangent.xyz;
+const float inf = uintBitsToFloat(0x7f800000u);
+float handedness = clamp(at_tangent.w * inf, -1.0, 1.0); // -1.0 when at_tangent.w is negative, and 1.0 when it's positive
 
-vec3 bitangent = cross(tangent, normal) * at_tangent.w;
+vec3 bitangent = cross(tangent, normal) * handedness;
 ```

src/content/docs/current/Reference/Attributes/mc_Entity.mdx

@@ -12,14 +12,16 @@ sidebar:
 
 ---
 
-The `x` component stores the block ID which was assigned to the current block in [`block.properties`](/current/reference/miscellaneous/block_properties/). If an ID for the current block is not defined, a value of `-1` is sent.
+The `x` component stores the block ID which was assigned to the current block in [`block.properties`](/current/reference/miscellaneous/block_properties/). If an ID for the current block is not defined, a value of `-1.0` is sent.
 
-:::tip
-Iris 1.3 and later (as well as OptiFine) uses a signed short for `mc_Entity`, meaning they can store IDs from `-32768` to `32767`. Older Iris versions do not support negative values, and will send the maximum unsigned value,`65535`, for any blocks with unassigned IDs.
+:::note
+OptiFine uses a signed short (16-bit two's complement integer) for `mc_Entity.x`, meaning it can store IDs in the range `[-32768, 32767]`. This matches behavior in Iris [1.3, 1.8), while earlier Iris versions used a 16-bit unsigned integer with a range of `[0, 65535]` and its maximum value for blocks with unassigned IDs, instead of `-1.0`. **Iris versions 1.8 and later use a 31-bit unsigned integer, offset by `-1`. This means that `mc_Entity.x` can store IDs in the range `[-1, 2147483646]`, not accounting for IEEE-754 precision limitations.**
+
+Though the vertex attribute data for `mc_Entity.x` is stored as an integer in Iris 1.8+, it is always cast to a `float` before reading. This comes with significant precision issues at high values, `>= 1.0` at values `>= 16777217.0`.
 :::
 
-When [`block.properties`](/current/reference/miscellaneous/block_properties/) is not present in the shader pack files, block IDs are assigned according to their pre 1.13 numerical values, as described in the [Minecraft Wiki](https://minecraft.wiki/w/Java_Edition_data_values/Pre-flattening/#Block_IDs). This is intended for legacy purposes, and should not be used for new shader packs.
+When [`block.properties`](/current/reference/miscellaneous/block_properties/) isn't present in the shader pack files, block IDs are assigned according to their pre-Minecraft 1.13 numerical values, as described in the [Minecraft Wiki](https://minecraft.wiki/w/Java_Edition_data_values/Pre-flattening/#Block_IDs). This is intended for legacy purposes, and should not be used for new shader packs.
 
-The `y` component stores the "render type", which is `1` for fluids (water, lava, etc) and `-1` for all other blocks.
+The `y` component stores the "render type", which is `1.0` for fluids (water, lava, etc.) and `-1.0` for all other blocks.
 
-This attribute is only available for terrain. For other types of geometry, see [`entityid`](/current/reference/uniforms/id/#entityid) and [`blockentityid`](/current/reference/uniforms/id/#blockentityid).
+This attribute is only available for terrain. For other types of geometry, see [`entityid`](/current/reference/uniforms/id/#entityid) and [`blockentityid`](/current/reference/uniforms/id/#blockentityid).

src/content/docs/current/Reference/Attributes/vaNormal.mdx

@@ -21,10 +21,14 @@ This attribute only works with the `core` profile in Minecraft 1.17 and newer. I
 
 The vertex normal vector attribute, equivalent to `gl_Normal` from the `compatibility` profile.
 
-The normal vector from `vaNormal` is in model space (which varies for different geometry). It can be converted to view space using [`normalMatrix`](/current/reference/uniforms/matrices/#normalmatrix) (or `gl_NormalMatrix` in the compatibility profile).
+:::note
+The vector is not guaranteed to be normalized.
+:::
+
+The normal vector from `vaNormal` is approximate, and in model space (which varies for different geometry). It can be converted to view space using [`normalMatrix`](/current/reference/uniforms/matrices/#normalmatrix) (or `gl_NormalMatrix` in the compatibility profile).
 ```glsl
-vec3 normal = normalMatrix * vaNormal;
+vec3 normal = normalMatrix * normalize(vaNormal);
 ```
 ```glsl
-vec3 normal = gl_NormalMatrix * gl_Normal;
+vec3 normal = gl_NormalMatrix * normalize(gl_Normal);
 ```

src/content/docs/current/Reference/Buffers/colortex.mdx

@@ -26,7 +26,7 @@ Additionally, you can read and write to the first 6 colortex buffer in OptiFine
 These buffers default to the display resolution, although this can be configured with the [`size.buffer`](/current/reference/shadersproperties/rendering/#sizebuffer) define in shaders.properties. However, changing the buffer size will prevent any [`gbuffer`](/current/reference/programs/gbuffers/) program from writing to the texture.
 
 #### Format / precision
-These buffers all default to `RGBA` format (which is `RGBA8` on most systems), but this can be configured as described in the [Texture Formats](/current/reference/buffers/image_format/) section.
+These buffers all default to `RGBA` format (which is `RGBA8` on most systems), but this can be configured as described in the [Image Format](/current/reference/buffers/image_format/) section.
 
 #### Clearing
 
@@ -55,5 +55,5 @@ The first 8 colortex buffers have legacy aliases, although their names are often
 | colortex7     | gaux4       |
 
 :::note
-If `gdepth` is defined anywhere in the shader and the texture format for `colortex1`/`gdepth` is `RGBA` (or not specifically set by the shader), Iris will upgrade the format to `RGBA32F`. This represents legacy behavior, where `gdepth` was used to store depth values.
+If `gdepth` is defined anywhere in the shader and the image format for `colortex1`/`gdepth` is `RGBA` (or not specifically set by the shader), Iris will upgrade the format to `RGBA32F`. This represents legacy behavior, where `gdepth` was used to store depth values.
 :::

src/content/docs/current/Reference/Buffers/custom_images.mdx

@@ -26,9 +26,9 @@ To declare a custom image, use the following in shaders.properties:
 Replace:
 - `<imageName>` with the variable name of the image
 - `<samplerName>` with the variable name of the sampler
-- `<format>` with the [pixel format](/current/reference/buffers/image_format/) of the image (see "Pixel Formats" section)
-- `<internalFormat>` with the [texture format](/current/reference/buffers/image_format/) of the image (see "Texture Format" section)
-- `<pixelType>` with the [pixel type](/current/reference/buffers/image_format/) of the image (see "Pixel Types" section)
+- `<format>` with the [pixel format](/current/reference/buffers/image_format/) of the image
+- `<internalFormat>` with the [image format](/current/reference/buffers/image_format/) of the image
+- `<pixelType>` with the [pixel type](/current/reference/buffers/image_format/) of the image
 - `<shouldClearOnNewFrame>` with `true` to clear the image after each frame, or `false` to retain data between frames
 - `<isRelative>` with `true` to make the image dimensions relative to the screen dimensions, or `false` to make the dimensions absolute
 - `<relativeX/absoluteX>` with the relative (floating point) or absolute (integer) size in the x dimension

src/content/docs/current/Reference/Buffers/custom_textures.mdx

@@ -29,18 +29,18 @@ Atlas textures (such as the block atlas) can be loaded by passing their file pat
 Additionally, the lightmap dynamic texture can be loaded using either `minecraft:dynamic/lightmap_1` or `minecraft:dynamic/light_map_1`. This texture is equivalent to the `lightmap` sampler used in [gbuffers](/current/reference/programs/gbuffers/). For example `texture.prepare.colortex2 = minecraft:dynamic/lightmap_1` loads the lightmap into `colortex2`.
 
 #### Raw textures
-Raw textures can be loaded from the shader files, similarly to image files. However raw textures are uncompressed binary files, where the bytes represent the values in the texture directly. Raw files can also encode 3D textures, and the texture format can be directly controlled (images are always loaded as RGBA8). To use a raw texture, add the following parameters to the custom texture directive:
+Raw textures can be loaded from the shader files, similarly to image files. However raw textures are uncompressed binary files, where the bytes represent the values in the texture directly. Raw files can also encode 3D textures, and the image format can be directly controlled (PNG images are always loaded as RGBA8). To use a raw texture, add the following parameters to the custom texture directive:
 
 ```properties  title="shaders.properties" ins="<type> <internalFormat> <dimensions> <pixelFormat> <pixelType>"
 texture.<stage>.<bufferName> = <path> <type> <internalFormat> <dimensions> <pixelFormat> <pixelType>
 ```
 
 Replace:
 - `<type>` with one of the following: `TEXTURE_1D`, `TEXTURE_2D`, `TEXTURE_3D`, or `TEXTURE_RECTANGLE`.
-- `<internalFormat>` with the [texture format](/current/reference/buffers/image_format/).
+- `<internalFormat>` with the [image format](/current/reference/buffers/image_format/).
 - `<dimensions>` with the fixed size dimensions of the texture (the number of components depends on the type).
-- `<pixelFormat>` with the pixel format described in the "Pixel Formats" section of the [texture format section](/current/reference/buffers/image_format/).
-- `<pixelType>` with the pixel type described in the "Pixel Types" section of the [texture format section](/current/reference/buffers/image_format/).
+- `<pixelFormat>` with the [pixel format](/current/reference/buffers/image_format/).
+- `<pixelType>` with the [pixel type](/current/reference/buffers/image_format/).
 
 
 ### PBR textures

src/content/docs/current/Reference/Buffers/image_format.mdx

@@ -37,7 +37,7 @@ Unsigned normalized buffers support values from 0.0 to 1.0 (inclusive).
 | `R16`        | 1×16       | `RED`        | `UNSIGNED_SHORT`              | ✔️     |                                                                                                                      |
 | `R8`         | 1×8        | `RED`        | `UNSIGNED_BYTE`               | ✔️     |                                                                                                                      |
 | `RGBA2`*     | 4×2        | `RGBA`       |                               | ❌     |                                                                                                                      |
-| `R3_G3_B2`   | 3/3/2      | `RED`        | `UNSIGNED_BYTE_2_3_3_REV`     | ❌     |                                                                                                                      |
+| `R3_G3_B2`   | 3/3/2      | `RGB`        | `UNSIGNED_BYTE_2_3_3_REV`     | ❌     |                                                                                                                      |
 
 <sup>*Requires Iris 1.8+</sup>
 

src/content/docs/current/Reference/Buffers/shadowcolor.mdx

@@ -22,7 +22,7 @@ Additionally, you can read and write to `shadowcolor0` and `shadowcolor1` using
 These buffers default to the shadow pass resolution, which can be controlled with the [`shadowMapResolution`](/current/reference/constants/shadowmapresolution/) constant.
 
 #### Format / precision
-These buffers default `RGBA` format (which defaults to `RGBA8` on most systems), but this can be configured as described in the [Texture Formats](/current/reference/buffers/image_format/) section.
+These buffers default `RGBA` format (which defaults to `RGBA8` on most systems), but this can be configured as described in the [Image Format](/current/reference/buffers/image_format/) section.
 
 #### Clearing
 By default these buffers clear their values after each frame to solid white (`vec4(1.0, 1.0, 1.0, 1.0)`). This behavior can be configured with the [`shadowcolorNClear`](/current/reference/constants/buffer_clear/) directive, and the clear color can be configured with the [`shadowcolorNClearColor`](/current/reference/constants/buffer_clear_color/) directive.

src/content/docs/current/Reference/Constants/buffer_format.mdx

@@ -12,6 +12,6 @@ sidebar:
 
 ---
 
-This directive allows a shader pack to specify the format and precision of a [colortex](/current/reference/buffers/colortex/) or [shadowcolor](/current/reference/buffers/shadowcolor/) color attachment. Replace `<bufferName>` with the name of the color attachment (i.e. `colortex2`, `shadowcolor0`, etc) and `format` with the format as described in the [Texture Formats](/current/reference/buffers/image_format/) section.
+This directive allows a shader pack to specify the format and precision of a [colortex](/current/reference/buffers/colortex/) or [shadowcolor](/current/reference/buffers/shadowcolor/) color attachment. Replace `<bufferName>` with the name of the color attachment (i.e. `colortex2`, `shadowcolor0`, etc) and `format` with the [image format](/current/reference/buffers/image_format/).
 
 This directive only needs to be defined once in the shader pack, can can be defined in (mostly) any shader file. Because the format names are not defined as part of glsl, the directive must either be put in a block comment, or the format name must be otherwise manually defined to any value to avoid compilation errors. Do not put the directive in a single line comment, or have any other text in the line of the directive, as this may cause it to not be detected properly.