Ok, the problem here is that the docs appear to be inconsistent, but the real problem is that the C# Mesh class API and the Shader Code API are inconsistent with each other when referring to the UV sets. For this reason, in contrast to your advice, I would say the only unambiguous way to refer to a UV set is to use the ordinal form, "first", "second", etc. So, "uv1" isn't hidden or secret, or not readable/writable. It's just that the mesh property names are uv, uv2, uv3 & uv4, and so are not "zero indexed", whereas in the shader code API, the variables go from UV0 to UV3 and are zero indexed. So, there are 4 UV channels supported, and you can access them all.
Hopefully this table should make it clear:
(seems table bbcode isn't supported, so this is an image!)
So what happened to mesh.uv1 ?
In older versions of unity, the Mesh class used to only have 2 UV channels. These were referred to as mesh.uv and mesh.uv1. However, Unity introduced support for 2 more UV channels (now 4 in total), and changed the naming on the mesh class so the names were now .uv .uv2 .uv3 & .uv4.
The old mesh property mesh.uv1 is now obsolete, and used to point to the 2nd UV layer. Old code that contains this property will be converted by the API auto updater to mesh.uv2.
1) In the Mesh page page http://docs.unity3d.com/ScriptReference/Mesh.html.
- Mention that UV2 is used for realtime lightmapping but NOT baked lightmapping so don't try to use it for anything else if using any GI.
- Mention that UV1 exists but it is not readable nor writable and that it is used for baked lightmapping. This is very important information. The API says that this channel is depricated which suggests it is not used anymore and does not exist. It does exist and is used for baked lightmaps. Without this information a developer could literally spend weeks trying to work with UV2 and baked lightmaps and have not idea why nothing is working.
- The docs say that UV2 is the "second" UV set. This is not correct. It is the "third" UV set. The existing language suggests that there is no UV1 which leads developers to a false assumption and weeks of lost development time. Please NEVER refer to to uvs as "first", "second", "third" etc.. Please ALWAYS use uv, uv1, uv2, uv3, uv4.
3) Renderer page please mention that Renderer.lightmapScaleOffset uses the UV1 channel. I have been wondering for months what mysterious set of lightmap UVs these correspond to. Also mention that Renderer.realtimeLightmapScaleOffset uses the UV2 channel.
3) In the manual please mention that Unity uses different UV sets for realtime GI and baked GI. Please include the information in this document https://goo.gl/bHsCyq in the manual. There is not enough detail about GI in the regular manual. This is the best information on GI in unity I have seen so far and would have saved me weeks of development time.
