Merge pull request #352 from IrisShaders/texture-atlases

add texture atlases

Author: jbritain

src/content/docs/current/How To/pbr_standards.mdx

@@ -9,13 +9,11 @@ Texture packs can optionally provide extra data to Iris through the use of norma
 
 ## Access
 
-Normal map textures have the same name as the texture they should be attached to, with the `_n` suffix. For example, for a block of cobblestone, the texture is called `cobblestone.png`, and the normal map for cobblestone would be `cobblestone_n.png`. Likewise, specular maps have the suffix `_s`, meaning for cobblestone it would be `cobblestone_s.png`.
+Normal and specular map textures are provided by the resource pack. Normal maps have the same name as the texture they should be attached to, with the `_n` suffix. For example, for a block of cobblestone, the texture is called `cobblestone.png`, and the normal map for cobblestone would be `cobblestone_n.png`. Likewise, specular maps have the suffix `_s`, meaning for cobblestone it would be `cobblestone_s.png`.
 
 These textures are provided in the form of two additional texture atlases.
-- `uniform sampler2D normals`
-- `uniform sampler2D specular`
-
-These texture atlases should be sampled in the same way that `gtexture` is sampled.
+- [`uniform sampler2D normals`](current/reference/buffers/atlases/#uniform-sampler2d-normals)
+- [`uniform sampler2D specular`](current/reference/buffers/atlases/#uniform-sampler2d-specular)
 
 ## Formats
 There are two standard formats used for encoding PBR data in the normal and specular maps - oldPBR (also known as seusPBR) and labPBR.
@@ -40,22 +38,22 @@ A texture pack can optionally declare that it is LabPBR compliant (and the versi
 
 
 If labPBR is declared at all, the following preprocessor define will be declared
-```
-// texture.properties
+```properties
+# texture.properties
 format=lab-pbr
 ```
-```
+```glsl
 // this will be defined
 MC_TEXTURE_FORMAT_LAB_PBR
 ```
 
 Additionally, if a version is specified, a further define will be declared. **For example, with version 1.3:**
-```
-// texture.properties
+```properties
+# texture.properties
 format=lab-pbr/1.3
 ```
-```
-// this will be defined
+```glsl
+// these will be defined
 MC_TEXTURE_FORMAT_LAB_PBR
 MC_TEXTURE_FORMAT_LAB_PBR_1_3
 ```

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

@@ -0,0 +1,57 @@
+---
+title: Texture Atlases
+description: Buffers containing textures used to render geometry.
+sidebar:
+  label: Texture Atlases
+  order: 1
+---
+
+The coordinates used to sample the texture atlases in a gbuffers pass are obtained in the vertex shader using the following code:
+
+```glsl title="Compatibility Profile"
+coord = (gl_TextureMatrix[0] * gl_MultiTexCoord0).xy;
+```
+```glsl title="Core Profile"
+coord = (textureMatrix * vec4(vaUV0, 0.0, 1.0)).xy;
+```
+
+For more information, see [`vaUV0`](http://localhost:4321/current/reference/attributes/vauv0/).
+
+Texture atlases are *not bound* in non-gbuffers passes. To access them in other passes, [custom textures](/current/reference/buffers/custom_textures/#texture-types) can be used.
+
+### `uniform sampler2D gtexture`
+`gtexture` is the main texture atlas, used to obtain the albedo color of any geometry rendered in a gbuffers pass. It is usually multiplied by the result of [`gl_Color`](/current/reference/attributes/overview/)/[`vaColor`](/current/reference/attributes/vacolor/) (passed through from the vertex shader) to obtain the final color value. 
+
+:::caution[Warning]
+Some shaderpacks may use other aliases such as `tex`, as samplers using texture names that do not exist will simply bind to the atlas. *This is undefined behavior and should not be relied upon.*
+
+`texture` is a valid alias in `#version 120`, however in any newer version of GLSL this is a reserved keyword and should not be used.
+:::
+
+### `uniform sampler2D normals`
+`normals` is the normal map atlas. If the resource pack does not have a texture suffixed with `_n` for the current geometry, or there is no resource pack loaded, then the value returned will be as follows.
+
+| Component | Value (0-255) |
+|-----------|---------------|
+| `r`       | 127           |
+| `g`       | 127           |
+| `b`       | 255           |
+| `a`       | 255           |
+
+*Note that the values returned when sampling the texture are in the 0-1 range, whereas they are displayed here in the 0-255 range.*
+
+For information on how to use these values, see [PBR Standards](/current/how-to/pbr_standards/).
+
+### `uniform sampler2D specular`
+`specular` is the specular map atlas. If the resource pack does not have a texture suffixed with `_s` for the current geometry, or there is no resource pack loaded, then the value returned will be as follows.
+
+| Component | Value (0-255) |
+|-----------|---------------|
+| `r`       | 0             |
+| `g`       | 0             |
+| `b`       | 0             |
+| `a`       | 0             |
+
+*Note that the values returned when sampling the texture are in the 0-1 range, whereas they are displayed here in the 0-255 range.*
+
+For information on how to use these values, see [PBR Standards](/current/how-to/pbr_standards/).