Merge pull request #351 from kloppi417/standardization

Standardization changes

Author: jbritain

README.md

@@ -37,23 +37,45 @@ Unfinished/Unfinished docs are marked with the `Unfinished` tag in the warning s
 
 Write in your own way, and try to use existing pages or ask before adding new ones. For how to write content, follow the guides on [https://diataxis.fr/](https://diataxis.fr/).
 
-### Dictionary:
-
-- Please use full terms, no shortening. EX no `complementary -> comp`.
-- Refer to shader packs as `pack` and/ or `packs`.
-- If referring to worlds (`world0` and the like), use this syntax: Overworld(`world0`)
+### Style Guide
+
+- Use proper capitalization. Common mistakes include:
+    - `Optifine` (should be `OptiFine`)
+    - `glsl` (should be `GLSL`)
+- Use the correct text stylization:
+    - Backticks (\`) should be used for any term used exactly in code (ex: `uniform`) 
+        - For colortex buffers, only use backticks if the number is included (ex: `colortex5`)
+        - For gbuffers, just kinda vibe it, I don't have a definitive rule here
+    - Bold (\*\*) should be used for any term not used in code (ex: **attributes**)
+    - Italics (\*) may be used for emphasis
+- Use full terms, no shortening. (ex: no `complementary -> comp`.)
+- Something specific to a specific type of shader (vertex, fragment, etc) should include the file extension (ex: `gbuffers_water.fsh`)
+- Use wildcard notation (`*`) to indicate multiple files (ex: `gbuffers_*.fsh` refers to all fragment shaders in a`gbuffers` program)
+- Something valid for all shader types should omit an extension (ex: `final`)
+- Refer to shader packs as `shader pack(s)`.
+- Refer to texture/resource packs as `resource pack(s)`
+- Use `rgba` for swizzling only when explicitly related to color channels, otherwise use `xyzw`
 - Make headings as succinct as possible to help the reader quickly find the content they need
 - Use simple present tense for verbs
 
-### Guides:
-Guides walk the user through completing a task (EX creating their first shader). A guide should lead from one outcome to another, and is a multi lesson system of teaching (defined by their folder with multiple pages). They are to be written in a style similar to [tutorials on Diataxis](https://diataxis.fr/tutorials/). Guides are open ended.
+#### File Structure
+- Use `/` to denote folders (as opposed to `\`, which is used on Windows)
+- Add a closing `/` to indicate folders, omit to indicate files
+- The root directory is assumed to be the Minecraft folder. Ex:
+    - `/patched_shaders/`
+    - `/mods/1.21.4/iris-1.7.1+mc1.21.jar`
+- For a local directory, omit the starting `/`. Ex:
+    - `shaders/final.fsh`
+
+### Guides
+Guides walk the user through completing a task (e.g. creating their first shader). A guide should lead from one outcome to another, and is a multi lesson system of teaching (defined by their folder with multiple pages). They are to be written in a style similar to [tutorials on Diataxis](https://diataxis.fr/tutorials/). Guides are open ended.
 
 A guide should leave the reader feeling comfortable with the topic, and it should leave them in a way that they are able to experiment by themselves.
 
-### How To:
-A how to is a singular short article that walks a user through a small problem in their way (EX transforming shadows to screen space or tonemapping). A how to is made to walk a user through a short section of code and does not need to lead from one outcome to another. It is made to increase/create the understanding on a small section of code, and is rarely open ended. The how to should be written similar to [how to guides on Diataxis](https://diataxis.fr/how-to-guides/).
+### How To
+A how to is a singular short article that walks a user through a small problem in their way (e.g. transforming shadows to screen space or tonemapping). A how to is made to walk a user through a short section of code and does not need to lead from one outcome to another. It is made to increase/create the understanding on a small section of code, and is rarely open ended. The how to should be written similar to [how to guides on Diataxis](https://diataxis.fr/how-to-guides/).
 
-### Reference:
+### Reference
 A reference is a docs page. It give objective information on a subject, without moving towards individual use cases. These are often short pages, which are written to provide information about syntax surrounding a line or two of code. These need to be written in a succinct way so that the user can quickly find information. Best practices are located at [references in Diataxis](https://diataxis.fr/current/reference/)
 
 For uniform references please look at `alphaTestRef` for formatting. The aside found there can be used for any version specific stuff.
@@ -85,4 +107,5 @@ Translations are not yet supported, but once the english version is complete we
 - [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
+- jbritain - Some uniforms, other miscellaneous things
+- kloppi417 - editor

SECURITY.md

@@ -11,7 +11,7 @@
 
 If you've found a vulnerability, we would like to know so we can fix it before it is released publicly. Do not open a GitHub issue for a found vulnerability.
 
-Please join [The Iris Discord](https://discord.gg/jQJnav2jPu) and dm one of the docs developers. Send the details:
+Please join [The Iris Discord](https://discord.gg/jQJnav2jPu) and DM one of the docs developers. Send the details:
 
 - where the vulnerability can be observed
 - a brief description of the vulnerability

src/content/docs/aperture/migration.mdx

@@ -15,7 +15,7 @@ Aperture is a new pipeline for Iris, set to be released with Iris 2.0.
 - It uses pipeline code written by shader developers in TypeScript, allowing for fully customizable packs.
 - It has a mod API that allows for mods to apply custom vertex formats, vertex transformations, and (basic) fragment warping without interfering with shader developers.
 - It has no limits on the number of textures, buffers, or programs you can have, how complex they can be, or how they are running.
-- It has a new shadow mapping system based on cascaded shadow maps, allowing shadow maps that reach far beyond what Optifine packs can without distortion.
+- It has a new shadow mapping system based on cascaded shadow maps, allowing shadow maps that reach far beyond what OptiFine packs can without distortion.
 - Packs written on Aperture use a modern version of OpenGL that can be translated to other API's in the future.
 
 This serves as temporary documentation whilst Aperture is being developed.
@@ -47,7 +47,7 @@ Shader programs are registered in the `setupShader` function with the `registerS
 
 `ObjectShader`s take a `programUsage`, these are predefined for you, for example `TERRAIN_SOLID`.
 
-`Composite` and `Compute` shaders require a `Stage` argument passed to `registerShader` before the shader object itself. This defines when the shader runs - for example `Stage.POST_RENDER` is equivalent to a `composite` pass in the Optifine format.
+`Composite` and `Compute` shaders require a `Stage` argument passed to `registerShader` before the shader object itself. This defines when the shader runs - for example `Stage.POST_RENDER` is equivalent to a `composite` pass in the OptiFine format.
 
 To add a vertex and fragment shader to your shader object, you can call `.vertex(<PATH_TO_VERTEX>)` and `.fragment(<PATH_TO_FRAGMENT>)`.
 
@@ -70,7 +70,7 @@ Vertex shaders should define two functions:
 Set `data.clipPos` as you would `gl_Position`. Usually this can just be `iris_projectionMatrix * iris_modelViewMatrix * data.modelPos`
 
 :::note[Info]
-`iris_projectionMatrix` and `iris_modelViewMatrix` are patched to make sense for the relevant usage, in the same way `gl_ModelViewMatrix` is in Optifine.
+`iris_projectionMatrix` and `iris_modelViewMatrix` are patched to make sense for the relevant usage, in the same way `gl_ModelViewMatrix` is in OptiFine.
 :::
 
 #### `void iris_sendParameters(VertexData data)`

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

@@ -8,7 +8,9 @@ sidebar:
 
 At the start of a shader program, the vertex position is provided in the form of `gl_Vertex` (or `VAPosition`). This position is in *model space*. By the time it reaches the fragment shader, the position is in *screen space*. Between these two are a number of other coordinate spaces.
 
-**This page does not cover *clip space*, *NDC space*, or *screen space*, as these are applicable to all 3D graphics, not just Minecraft.** It is recommended that you also read the [LearnOpenGL article on coordinate systems](https://learnopengl.com/Getting-started/Coordinate-Systems) to gain a good understanding of these other spaces. The [shaderLABS Wiki](https://shaderlabs.org/wiki/Coordinate_Spaces) also has an explanation of different types of transformations, as well as an interactive visualiser of the different spaces.
+:::note
+This page does not cover **clip space**, **NDC space**, or **screen space**, as these are applicable to all 3D graphics, not just Minecraft. It is recommended that you also read the [LearnOpenGL article on coordinate systems](https://learnopengl.com/Getting-started/Coordinate-Systems) to gain a good understanding of these other spaces. The [shaderLABS Wiki](https://shaderlabs.org/wiki/Coordinate_Spaces) also has an explanation of different types of transformations, as well as an interactive visualiser of the different spaces.
+:::
 
 ## Space Conversion Cheatsheet
 This page is designed to be read in tandem with this cheatsheet, which shows every space and how to convert between them.
@@ -18,7 +20,7 @@ This page is designed to be read in tandem with this cheatsheet, which shows eve
 ## Spaces
 
 ### Model Space
-In Iris (and Optifine), *model space* is whatever coordinate space the vertex position attribute is sent in. The exact coordinate space varies based on the specific geometry, and has the potential to vary across different Minecraft versions. As a result, it is always recommended to treat *model space* like an unknown space and convert to view space with the `gl_ModelViewMatrix`/[`modelViewMatrix`](/current/reference/uniforms/matrices#modelviewmatrix). *Model space* is also sometimes known as '*local space*'.
+In Iris (and OptiFine), **model space** is whatever coordinate space the vertex position attribute is sent in. The exact coordinate space varies based on the specific geometry, and has the potential to vary across different Minecraft versions. As a result, it is always recommended to treat *model space* like an unknown space and convert to view space with the `gl_ModelViewMatrix`/[`modelViewMatrix`](/current/reference/uniforms/matrices#modelviewmatrix). **Model space** is also sometimes known as "**local space**".
 
 
 If using the core profile (and as such using [`vaPosition`](/current/reference/attributes/vaposition) instead of `gl_Vertex`), the *model space* position for terrain should be offset with [`chunkOffset`](/current/reference/uniforms/rendering#chunkoffset). The conversion sheet assumes this has already been done. Here's an example of what that should look like:
@@ -27,24 +29,24 @@ vec3 model_pos = vaPosition + chunkOffset;
 ```
 
 ### View Space
-*View space* is the vertex position relative to the camera. This is also sometimes known as '*eye space*' (not to be confused with '*eye player space*').
+*View space* is the vertex position relative to the camera. This is also sometimes known as "**eye space**" (not to be confused with "**eye player space**").
 
-The `x` and `y` components of view space line up with screenspace (negative is left/down, positive is right/up), however the `z` coordinate is "backwards" (forward is negative z).
+The `x` and `y` components of view space line up with screen space (negative is left/down, positive is right/up), however the `z` coordinate is "backwards" (forward is negative z).
 
 ### Player Space
-*Player space* is the vertex position relative to the *camera* (not the player). The difference between view and *player space* is that whilst *view space* directions change based on the camera angle, *player space* directions are constant, aligned to the axes of Minecraft's coordinates. For example, a vector `0.0, 1.0, 0.0` is along the Y axis and as such would be along Minecraft's actual Y axis (upwards).
+*Player space* is the vertex position relative to the *camera* (not the player). The difference between view and **player space** is that whilst **view space** directions change based on the camera angle, **player space** directions are constant, aligned to the axes of Minecraft's coordinates. For example, a `vec3(0.0, 1.0, 0.0)` is along the Y axis and as such would be along Minecraft's actual Y axis (upwards).
 
 To get a position which is relative to the actual player model in third person, you can use [`relativeEyePosition`](/current/reference/uniforms/camera#relativeeyeposition).
 
 #### Feet and Eye Player Space
-The names of these spaces are misleading, as '*feet player space*' is not in any way related to the player's feet. The difference between the two is that in *feet player space*, the origin remains locked to the player's head position, whereas in *eye player space*, effects like view bobbing are accounted for, meaning that the origin is locked to the camera. This is why the two can be interchanged with the addition and subtraction of [`gbufferModelViewInverse[3]`](/current/reference/uniforms/matrices#gbuffermodelviewinverse) - this fourth component of the matrix accounts for the translation from the player's head to the camera.
+The names of these spaces are misleading, as "**feet player space**" is not in any way related to the player's feet. The difference between the two is that in **feet player space**, the origin remains locked to the player's head position, whereas in **eye player space**, effects like view bobbing are accounted for, meaning that the origin is locked to the camera. This is why the two can be interchanged with the addition and subtraction of [`gbufferModelViewInverse[3]`](/current/reference/uniforms/matrices#gbuffermodelviewinverse) - this fourth component of the matrix accounts for the translation from the player's head to the camera.
 
-It is also worth noting that in third person mode, view bobbing is disabled, and as such, *eye* and *feet player space* are *usually* identical.
+It is also worth noting that in third person mode, view bobbing is disabled, and as such, eye and feet player space are *usually* identical.
 
 ### World Space
-*World space* is the vertex position in Minecraft's actual coordinate system. It is directionally equivalent to *player space*, as it is simply the result of offsetting a *feet player space* position by the camera position. This roughly lines up with the game's actual coordinate positions, however [`cameraPosition`](/current/reference/uniforms/camera#cameraposition) resets every 30000 blocks (or every 1000 blocks when teleporting). If the exact Minecraft position is required, [`cameraPositionInt`](/current/reference/uniforms/camera#camerapositionint) and [`cameraPositionFract`](/current/reference/uniforms/camera#camerapositionfract) can be used
+**World space** is the vertex position in Minecraft's actual coordinate system. It is directionally equivalent to **player space**, as it is simply the result of offsetting a *feet player space* position by the camera position. This roughly lines up with the game's actual coordinate positions, however [`cameraPosition`](/current/reference/uniforms/camera#cameraposition) resets every 30000 blocks (or every 1000 blocks when teleporting). If the exact Minecraft position is required, [`cameraPositionInt`](/current/reference/uniforms/camera#camerapositionint) and [`cameraPositionFract`](/current/reference/uniforms/camera#camerapositionfract) can be used
 
 ## Shadow Space
-'Shadow Space' can refer to a number of different coordinate spaces, all of which are used for the [shadow pass](/current/reference/programs/shadow). As such, the "shadow" versions of coordinate spaces are generally equivalent to their normal versions but from the perspective of the shadow camera (the sun/moon). The shadow spaces include *shadow view space*, *shadow clip space*, *shadow NDC space*, and *shadow screen space*.
+"Shadow Space" can refer to a number of different coordinate spaces, all of which are used for the [shadow pass](/current/reference/programs/shadow). As such, the "shadow" versions of coordinate spaces are generally equivalent to their normal versions but from the perspective of the shadow camera (the sun/moon). The shadow spaces include **shadow view space**, **shadow clip space**, **shadow NDC space**, and **shadow screen space**.
 
-In the [shadow pass](/current/reference/programs/shadow), the same base matrices are used ([`modelViewMatrix`](/current/reference/uniforms/matrices#modelviewmatrix), [`projectionMatrix`](/current/reference/uniforms/matrices#projectionmatrix), etc), or the `shadow` matrix uniforms (e.g. [`shadowModelView`](/current/reference/uniforms/matrices#shadowmodelview), [`shadowProjection`](/current/reference/uniforms/matrices#shadowprojection)) can be used from any program. When sampling the shadow map, positions can be transformed into *player space*, and from there back into *shadow screen space*.
+In the [shadow pass](/current/reference/programs/shadow), the same base matrices are used ([`modelViewMatrix`](/current/reference/uniforms/matrices#modelviewmatrix), [`projectionMatrix`](/current/reference/uniforms/matrices#projectionmatrix), etc), or the `shadow` matrix uniforms (e.g. [`shadowModelView`](/current/reference/uniforms/matrices#shadowmodelview), [`shadowProjection`](/current/reference/uniforms/matrices#shadowprojection)) can be used from any program. When sampling the shadow map, positions can be transformed into **player space**, and from there back into *shadow screen space*.

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

@@ -60,5 +60,6 @@ MC_TEXTURE_FORMAT_LAB_PBR
 MC_TEXTURE_FORMAT_LAB_PBR_1_3
 ```
 
-**Note:** At the time of writing, the only supported LabPBR version is 1.3. **Specifying other versions in a texture pack may cause errors.**
-
+:::caution[Warning]
+At the time of writing, the only supported LabPBR version is 1.3. Specifying other versions in a texture pack may cause errors.
+:::

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

@@ -8,15 +8,13 @@ sidebar:
 
 ### `in vec4 at_midBlock;`
 
-**Valid Programs**: terrain (*gbuffers_terrain*, *gbuffers_water*, *shadow*)
+**Valid Programs**: `gbuffers_terrain.vsh`, `gbuffers_water.vsh`, `shadow.vsh`
 
 ---
 
-The first three components store the world/player space offset from the vertex's position to the center of the block in 1/64th block units. For example, the center position would be calculated like this:
+The `xyz` components store the world/player space offset from the vertex's position to the center of the block in 1/64th block units. For example, the center position would be calculated like this:
 ```glsl
-vec3 centerPosition = position + at_midBlock.xyz/64.0;
+vec3 centerPosition = position + at_midBlock.xyz / 64.0;
 ```
 
-In Iris 1.7 and newer, `at_midBlock.w` stores the light level of the current block (without the influence of nearby light sources, range `0` to `15`). This can be used to tell if a block is emissive. It's recommended to use this together with [`BLOCK_EMISSION_ATTRIBUTE`](/current/reference/shadersproperties/flags).
-
-This attribute (both the mid block offset and the emission value) are only available for terrain.
+In Iris 1.7 and newer, the `w` component stores the light level of the current block (without the influence of nearby light sources, range `0` to `15`). This can be used to tell if a block is emissive. It's recommended to use this together with [`BLOCK_EMISSION_ATTRIBUTE`](/current/reference/shadersproperties/flags).

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

@@ -8,7 +8,7 @@ sidebar:
 
 ### `in vec4 at_tangent;`
 
-**Valid Programs**: all gbuffers/shadow
+**Valid Programs**: `gbuffers_*.vsh`, `shadow.vsh`
 
 ---