Aras said that he would like to have us list what we would like to have documented, that is not currently. However, I have no interest in overwhelming him or anyone else on his team with a disorganized mess. Posting in a thread is not going to be good enough. I think we need something where, when the requested documentation happens, we can move the request out of the way into an “answered” section. What would you guys like to do? Googles Docs has been recommended to me, but I’ve never used it.
Why not use the Unify Community wiki?
Also, I think it makes sense to discuss documentation requests here and then move them to whatever tool is going to be used.
And to start a list, I think the main problem is that the documentation doesn’t explain Cg/HLSL or even GLSL. I understand that this is considered to be out-of-scope of the Unity documentation but in my humble opinion this is the main reason why the documentation is useless for more than 90% of Unity developers when it comes to programming shaders. (I’m just guessing the number.)
What kind of additional documentation would be useful to have for the less than 10% Unity developers who currently program shaders? I think that boils down to this: enough information to implement vertex and fragment shaders that support all the features that are supported by surface shaders. (Of course, you would usually use only bits and pieces of this information, but the point is that different bits and pieces are useful in different situations.)
And then there are things that are just strange, e.g. what exactly is _World2Object? (My current assumption is that _World2Object * unity_Scale.w with the bottom-right element being set to 1 is the transformation from world coordinates to object coordinates. Of course, if you only transform normalized directions, you don’t need the strange scaling with unity_Scale.w.)
Unify is unreliable; it’s down often for long stretches, unfortunately.
You’re right about the documentation not being useful for noobies, but people like you and I can answer many of their questions about the languages, or get them started. You’re also right about what we need, i.e. “enough information to implement …”, but that’s too broad. It’s apparent that it’s unrealistic to ask for good, “complete” documentation from Unity, because it just doesn’t pay off for the vast majority of users. So, if we can just keep getting focused questions answered, bit by bit, we’ll be able to make our own manual, if it comes to that. We’ve both done that kind of thing before. Are we allowed to sell a “missing manual” on the Asset Store? I would have vastly preferred to have paid a good deal of money than have had to have wasted so much of my life figuring out stuff that no one provided proper help with. Your wikibook has saved me a lot of time; I’d buy that on the Asset Store and recommend it to anyone interested, to show my support, even though I’ve used it as a free reference. Package it with some test scenes; that’d be a great buy for, I don’t know, somewhere up to $100.
http://forum.unity3d.com/threads/149595-Shaderlab-Documentation-Requests
Post concrete requests in the link above, discuss things here.
Well, OK, then let’s get started.
As I mentioned, I would like to have proper documentation of the scaling of _World2Object with unity_Scale.w. (As far as I know one has to set the bottom-right element to 1 after multiplying the matrix with unity_Scale.w; does that work always on all devices?)
How to write a single fragment shader in Cg or GLSL that works with normal maps generated by Unity both on mobile and desktop devices?
How to access the vertex lights in the ForwardBase pass? (here is how I do it, but I’m not sure this is correct: http://en.wikibooks.org/wiki/GLSL_Programming/Unity/Multiple_Lights )
What are the equations for attenuation of light source intensity with distance and for spot lights also with angle?
Some built-in shaders multiply colors with a factor of 2. One has to include this factor, when one tries to write shaders that behave similarly as built-in fallback shaders. What is this factor about?
Are these requests reasonable?
That sounds pretty good to me. I’m sure you’re willing to provide deeper clarify upon request. Let’s hear from stramit. The first post in the other thread, by mgear, doesn’t sound good to me; its scope is huge.
I don’t have a list prepared. I’m be coming back to these threads as I think of what’s undocumented. Here’s one for now, that is a piece of a puzzle Martin asked about:
How does this function end up working? I can’t get any code in #if defined(SHADER_API_MOBILE) to run, and yet, normal mapped shaders do apparently work using this.
inline fixed3 UnpackNormal(fixed4 packednormal)
{
#if defined(SHADER_API_GLES) defined(SHADER_API_MOBILE)
return packednormal.xyz * 2 - 1;
#else
fixed3 normal;
normal.xy = packednormal.wy * 2 - 1;
normal.z = sqrt(1 - normal.x*normal.x - normal.y * normal.y);
return normal;
#endif
}
Hi,
I find the expansion of shaderlab’s documentation great. For me, the most important thing would be more and more examples.
I would also love to see an expanded “tree” display of each shader that would display the mesh input (verts - tris - normals - etc) and the shaders (including the hidden ones) that form the final shader. Along with some comments. Per platform. With some explanations regarding why the specific approach is chosen. And a free pizza.
I understand that if someone wishes to learn cg - hlsl - glsl should go another route ( eg download directx sdk and have fun with c++ ). It would be nice to have some sort of learning material regarding how to learn cg - hlsl - glsl on unity. And free beer too.
Also, if you allow user feedback in the documentation ( ie user questions / answers - user shader examples ), in an integrated fashion instead of the current search in the forums - answers - wiki - irc(is Texel around?) fashion the whole thing could grow stronger, better and faster. As well as its maintenance costs. But hey, unity is a top game engine and its biggest asset is its community, right ?
No specific questions here, everything in the docs is perfectly explained (/me runs now, Martin and Jessy picked up the torches).
Cheers,
-Ippokratis
Note that I’ve recently adapted my wikibook about GLSL programming in Unity ( http://en.wikibooks.org/wiki/GLSL_Programming/Unity ) to Cg/HLSL programming in Unity ( http://en.wikibooks.org/wiki/Cg_Programming/Unity ).
However, both books could be greatly extended. In particular with some guidance on optimization and features of Unity Pro.
I cannot help with the free beer, though.
Hi,
It is a very interesting source of information Martin, much appreciated.
Is there a forum support thread where users can add feedback ?
There is no support thread here on forum.unity3d.com. However, http://en.wikibooks.org/wiki/GLSL_Programming/Unity and http://en.wikibooks.org/wiki/Cg_Programming/Unity are wikibooks, which means that there is (at least potentially) a discussion page for every page (i.e. tutorial). You are more than welcome to leave feedback on those discussion pages. It works very much like Wikipedia (it’s actually the same software), i.e. everyone can edit almost everything (even without logging in but then your IP address is published). Actually, you are also welcome to edit the tutorials if you find an error. (Of course, larger changes, e.g. changes to all tutorials, should be discussed first.)