Shader documentation (or lack thereof)

The shader documentation is absolutely atrocious and this is mostly due to the fact that it hardly exists. All we have for shader documentation right now are a handful of shaderlab examples and we're basically expected to go out on our own and learn Cg, HLSL, or GLSL. Except right now, there's a bunch of Unity specific extensions like unity_Scale, which I had to look up on the forums to find the actual functionality of.

Are there any plans to give us something as comprehensive as the scripting reference, but for shaders?

 

There is a bit more than just ShaderLab examples. There is actually quite a lot of information in the ShaderLab syntax pages but it is categorised under the syntax elements themselves. This same problem of information being available but incomplete and scattered is one of the main things we are trying to address in the docs. ShaderLab is a bit different to (and bigger than) most sub-topics but the same approach to overhauling the docs will apply: we'll bring the main information out of the reference pages into overviews, procedures and examples/how-tos and then link from there to the reference pages for the precise details of the syntax, etc. I think having the shader reference pages in the roughly the same format as the script ref pages is a good thing to aim for; as mentioned elsewhere, it is a goal to get API information incorporated in with the explanatory material anyway.

Is this the sort of thing you have in mind for ShaderLab? I think even when the information is abstracted out of the reference pages, we will still need to expand and clarify it somewhat but we'll be in a much better position to see what actually needs expanding and clarifying

 

All I want is something that's:
1. Comprehensive
2. Searchable
3. Provides syntax
4. Easy to access

Right now, the documentation seems to be just the first one, and even that's only half-true

 

So, after years of headaches with writing shaders, I have come to a realization. Writing shaders is complex, but not that difficult if you know what you're trying to accomplish. However, writing shaders in Unity is extremely frustrating due to both the lack of good documentation and the limited debugging.

I feel like most of the stuff you can do between CGPROGRAM and ENDCG is pretty clear, and documention is pretty well taken care of: http://http.developer.nvidia.com/CgTutorial/cg_tutorial_appendix_e.html

It's the stuff that surrounds the CG (whether you use any CG or not) that gets really convoluted. There are so many nit-picky, Unity-specific rules to follow, and most of them go off the principle that if the user sees examples set up the right way, then they'll do it that way too. Unfortunately though, when you don't specifically say that things have to be a particular way people will often do it their own (wrong) way. One of the best examples is where to place tags and what are only referred to in the docs as "terms" (which is a problem on its own).

http://docs.unity3d.com/Manual/SL-CullAndDepth.html
Nothing on this page tells us where to put ZWrite (or the other terms). Does it go in the Pass? Does it always have to go in the Pass? Can it go in SubShader and not in the pass?

http://docs.unity3d.com/Manual/SL-Blend.html
Same here, nothing specifically says where it can or should go. Yes, it's in the documentation section under SubShader > Pass, but there are exceptions. For example, when writing Surface Shaders you don't write the Pass block, as it's done for you, so where do you put the blend mode? The Blend term also can also be overriden by Surface Shader pragmas "alpha", "decal:add", and "decal:blend", but that is not pointed out anywhere, and thus makes it really confusing to do a simple, regular additive Surface Shader.

In addition to the documentation needing to be updated on things like this, the compiler also needs to produce warnings for things that are redundant, overridden, or simply unused/ignored. Tags, for example, are listed in the docs under the SubShader section, so obviously they need to be in a SubShader block. However Pass blocks are inside SubShader blocks, so if you put your tags in a Pass, you're still technically following the rules. In fact, if you do that, Unity's shader compiler doesn't return any errors or warnings - it simply ignores the code, leaving developers to wonder why the tags aren't being used when their shader produces no errors.

Writing shaders should not be difficult or confusing because of the syntax - especially when it's Unity-specific syntax. Writing shaders should be difficult because of the math and efficiency requirements.

 

I also feel like the pure ShaderLab documentation and examples should be listed as "Legacy", as Unity no longer even supports the hardware that requires their use (from what I understand). The Shader documentation should be changed to focus on the use of Surface Shaders, as they are (for the most part) the most user-friendly approach to writing multi-platform shaders for current hardware.

The only reason ShaderLab syntax should show up in the documentation is to show what's needed to support Surface Shaders or Fragment Shaders. Anything that assumes the user will be writing their entire shader in ShaderLab should be put in its own separate Legacy section.

As for Fragment Shader documentation, it also suffers from some of the same issues - it expects you to learn ShaderLab syntax, and then "unlearn" most of it so you can replace it with vertex and fragment programs.

Basically, ShaderLab is only used at this point to give Unity access to Surface and Fragment shader code, and it should be treated as such in the documentation. Stop encouraging the use of pure ShaderLab shaders.