Document some notable unfixable Iris limitations, especially when usi…

…ng mods / resource packs

- Closes #677: ComputerCraft: Restitched Monitors display black panel
- Closes #585: wrong blocks waving with multiconnect on 1.8-1.12.2 servers
- Closes #507: Incompatible with Colored Lights by Gegy
- Closes #807: [Immersive portals] Mirrors not working above water when shaders are enabled
- Closes #1237: Shaders not working together with MC-164001 painting transparency fix
- Closes #1042: [MC 1.17] Iris overrides vanilla shaders, causing texture bugs for displayed (custom) armour

README.md

@@ -11,8 +11,9 @@
 
 ## FAQ
 
-Find answers to frequently asked questions on our [FAQ page](docs/faq.md).\
-A list of known-supported shaderpacks can be found [here](docs/supportedshaders.md)
+- Find answers to frequently asked questions on our [FAQ page](docs/faq.md).
+- A list of known-supported shaderpacks is available [here](docs/supportedshaders.md).
+- A list of unfixable limitations in Iris is available [here](docs/limitations.md).
 
 
 ## Why did you make Iris?

docs/development/compatibility/core-shaders.md

@@ -0,0 +1,38 @@
+# On the incompatibility with core shaders & custom shaders added by mods
+
+Or, "why don't my custom shaders work when a shader pack is active?"
+
+Executive Summary: Custom shaders added by mods or resource packs are ignored by Iris when an Iris shader pack is loaded. Mods and resource packs using custom shader behavior / vertex formats are extremely difficult to accomodate within Iris.
+
+This issue thread also has useful information: https://github.com/IrisShaders/Iris/issues/1042
+
+This document is *not* intended to inform the reader on how to make their custom shaders compatible with Iris shader packs. Rather, it's intended to provide an explanation for why the incompatibility exists. It's not because we don't care about compatibility - it's because this is a hard problem and there is no general solution to it.
+
+
+## Primer: What's a shader?
+
+The word "shader" has many meanings in Minecraft. You might think that it refers to something that adds fancy graphics effects like bloom or reflections, or allows servers to add things like custom armor.
+
+In actuality, a shader is just a program that runs on a graphics processor, whether that is a dedicated graphics card or an integrated graphics chip in a laptop. As with any program, a shader takes some data as input, and produces data as output. Conventionally, most shaders take vertex data, matrices, and textures as input, and produce pixels as output. Obviously, this is a simplification, but it gets the point across for this document.
+
+## Shaders in Iris Shader Packs
+
+Though Iris provides many features for shader packs, including support for shadow mapping, setting up certain inputs such as textures, uniforms, and extra vertex data, and ways to configure how the outputs of each shader program feed into other programs, most importantly it offers ways for shader packs to specify their own shader programs to be used for rendering content in Minecraft.
+
+Critically, these custom shader programs allow shader packs to implement many custom effects for various types of in-world content, including applying dynamic shadows, changing lighting colors, and writing data to G-Buffers for deferred rendering. As these shader programs produce certain expected output colors, if a shader pack provides a certain shader program (such as a `gbuffers_terrain` program), it expects that program to run on all terrain and output colors to a certain framebuffer (or set of framebuffers).
+
+
+## Tying things back to Minecraft
+
+What happens when both a resource pack provides a custom shader program for a given piece of content & a shader pack provides a custom core shader program for that same content? There's a problem: both shader programs are provided as complete shader programs that take vertices and other inputs, and produce color outputs.
+
+Given two arbitrary shader programs, there's no general sensible algorithm to "merge" them into a program that combines the behavior of both shader programs. Even writing out that previous sentence in a way that makes sense is difficult, because such a concept doesn't exist in computer science.
+
+
+## Conclusion
+
+By providing a high degree of control over Minecraft's rendering, Iris allows shader packs to accomplish advanced graphical effects. However, this comes at the natural expense of compatibility with other mods or resource packs that attempt to modify rendering through their own shaders.
+
+Though it is possible to fix many compatibility issues between shader packs and mods through improving the implementation of shader mods like Iris, some sources of compatibility issues fundamentally cannot be fixed. Custom shader programs are one example.
+
+As a result, it is strongly advised that mods that wish to maintain compatibility with Iris shader packs avoid using their own shader programs if at all possible. If mods do use shaders for some rendering, for the purposes of compatibility with mods like Canvas and Iris, it is recommended to create fallback rendering pathways that do not use custom shaders.

docs/usage/incompatible-mods.md

@@ -0,0 +1,45 @@
+# Notably incompatible mods / mod features that cannot be fixed on the side of Iris
+
+This is a list of issues that, after careful investigation by Iris developers, have been determined to be unfixable on the side of Iris. Please don't open issues regarding them unless you have additional information.
+
+## Botania's custom shaders
+
+These shaders conflict with shaders provided by Iris shader packs. See [the core shaders compatibility document](../development/compatibility/core-shaders.md). This will need to be worked around on Botania's side by not using a custom shader, Iris cannot fix this. 
+
+See https://github.com/VazkiiMods/Botania/issues/3912
+
+
+## ComputerCraft's TBO-based monitor rendering 
+
+Similarly to Botania, ComputerCraft uses custom shader programs for high-performance monitor rendering. Unfortunately, this doesn't work with Iris shader programs.
+
+This will need to be fixed on the side of ComputerCraft once Iris has requisite code to accommodate the fix, which will be available once Iris has fixed this issue: [Screens/monitors from Lifts mod turn black with shaders enabled](https://github.com/IrisShaders/Iris/issues/686). Once this issue is closed, CC:R will be able to render using its shaders to a custom framebuffer, then that framebuffer can be rendered to the scene with Iris's shaders.
+
+The ComputerCraft: Restitched developers have implemented specific workarounds when using shader packs with OptiFine, but have not done so for Iris.
+
+See: https://github.com/cc-tweaked/cc-restitched/issues/1
+
+
+## Colored Lights by Gegy
+
+Beyond potential issues with shader packs, [Colored Lights isn't compatible with Sodium](https://github.com/Gegy/colored-lights/issues/11), and Iris requires Sodium, so Colored Lights cannot be used with Iris.
+
+See https://github.com/Gegy/colored-lights/issues/11
+
+
+## Issues when connecting to 1.8-1.12 servers using the Multiconnect mod
+
+Multiconnect completely replaces the content of Minecraft's registries with pre-flattening block IDs when connecting to pre-1.13 servers. Since Iris shader packs use block IDs to determine block effects, and do not expect pre-1.13 block IDs when running on a post-1.13 Minecraft version, this breaks shader packs.
+
+This notably results in solid grass blocks waving like grass plants, since in 1.12 `minecraft:grass` refers to solid grass blocks and in 1.13 `minecraft:grass` refers to the non-solid plant.
+
+We can't fix this on our side, Multiconnect will ideally need to be changed to not disrupt registry content to such an extent.
+
+See https://github.com/Earthcomputer/multiconnect/issues/205
+
+
+## Immersive Portals: Underwater mirrors are not visible from above water
+
+This is a fundamental limitation of how portals are rendered when shaders are enabled. They are composited on to the scene after rendering has completed, meaning that they cannot be rendered behind translucent surfaces like water.
+
+This cannot be fixed by either Immersive Portals or Iris without completely reworking how portal rendering works with shaders.

docs/usage/limitations.md

@@ -0,0 +1,10 @@
+# Limitations of Iris
+
+There's a number of issues in Iris that are fundamental limitations of Iris and the platforms it runs on. We choose not to maintain these issues on the issue tracker because they can feasibly not be fixed, or it is not worth our time to attempt to work around them or fix them. We feel that it's better to have these limtations properly documented instead of having issues on the trackers that we won't ever close.
+
+1. [Iris doesn't fully work with all drivers, notably Apple's drivers on macOS.](drivers.md)
+2. [Iris doesn't work with certain mods or features of mods, because these mods do things that Iris cannot support.](incompatible-mods.md)
+3. [Some shader packs have bugs and shortcoings that are not the fault of Iris](../ShaderpackBugs.md). Some of these are limitations in the way that the shader pack is designed.
+4. Iris cannot support resource packs using custom core shaders, including:
+    - Custom armor shaders used on many servers, such as Origin Realms
+    - The workaround resource pack for https://bugs.mojang.com/browse/MC-164001