Important information regarding Mesh UV channels

The naming of UV sets in the official documentation is inconsistant, missleading, incorrect and incomplete. I would propose the following changes. Based on the information provided by Unity employees in the thread http://forum.unity3d.com/threads/quick-setup-for-starting-enlighten.309609/#post-2400531.

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.

2) Unrwapping.GenerateSecondaryUV set does this generate a UV1 channel? I think it must because I can create baked lightmaps on procedural meshes after I call this. Please mention this.

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.

The inspector for the standard shader uses:



Please name the UV sets correctly as UV3 and UV4. If a developer interprets the names in the inspector literally then they will waste many hours of development time.

 

Good Suggestion... unless a typo... don't use "uv" only for first set...extend the indexing also to that set and use "uv0"

 

Hi Duck,

Thanks for the fast response and for looking into this. I have a correction to make in your table.

Mesh.uv3 is NOT used for Realtime GI data. It goes like this:

uv Diffuse, Metal/Spec etc...
uv1 (not readable, or writable) Used for Baked GI
uv2 Used for realtime GI
uv3 Whatever you want (can optionally be used for detail maps)
uv4 Whatever you want (can optimally be used for detail maps)

Mesh.uv1 is used internally by the GI system. It used to be read/writable in Unity 4 but has been hidden in Unity 5. This is a huge source of confusion for developers. It is important that you document that it exists so that users can understand when looking at the charts in the lighting window that they can be looking at either the UV1 chart or the UV2 chart. This doc explains it very well: https://goo.gl/bHsCyq

This thread also has a lot of good information. http://forum.unity3d.com/threads/quick-setup-for-starting-enlighten.309609/#post-2400531.

 

THIS IS NOT CORRECT!!!! PLEASE!! PLEASE!! PLEASE!! CORRECT THIS!!

I CANNOT EMPHASIZE THIS ENOUGH!!!!!

THIS IS TERRIBLE MISINFORMATION! A DEVELOPER WHO BELIEVES THIS IS ABOUT TO EMBARK ON A LONG, MISERABLE, UNPLEASANT, FRUSTRATING CODE JOURNEY.

PLEASE, PLEASE, PLEASE READ THIS DOCUMENT WRITTEN BY UNITY DEVELOPERS WORKING ON GI WHICH EXPLAINS THAT mesh.uv1 IS STILL BEING USED BUT IS NOT READABLE OR WRITABLE. https://goo.gl/bHsCyq

 

Please! Please! I beg you contact Unity Developers:
KEngelstoft and
Jesper Mortensen

They work on the GI and will explain that the uv1 DOES exist. But it is not accessible through the Unity API. But it is exposed to the end user here.



You are being fooled by the same terrible documentation missinformation. The "Baked Intensity" and "Baked Direction" is NOT mesh.uv3. It is mesh.uv1 (not readable or writeable through the API).

 

I just want to say that this has been very entertaining... and informative. I too have struggled with the naming convention on the C# Mesh side and on the shader side.

Would it be too disruptive now to rename the Mesh class properties to uv0, uv1, uv2, and uv3? While it would probably break a lot of scripts, it would go a long way to avoid this whole misunderstanding. Maybe your script upgrader could rename everyones Mesh.uvX to Mesh.uvX-1?

While we're talking Mesh/UV documentation/confusion, I'd like to add a recent discovery of mine. While the new GUI system now accepts Meshes, any information in Mesh.uv3 and Mesh.uv4 is stripped out. While GUI's probably don't need the extra UV's for GI stuff, I am trying to get some extra data to a Vertex Shader Program and was disappointed to find the uv channels empty in the shader.

Thanks @duck and @superpig for your help and attention.

 

Hi Duck,

I must say I am confused and do hope you are right. I am very puzzled however. If I am using a mix of baked and realtime lightmapping and I import a mesh and check the "Generate Lightmap UVs". Nothing is generated on the mesh.uv3 channel.

Debug.Log(myMesh.uv3.Length)

Prints "0". If I print this at runtime it still returns zero. However my object is realtime lightmapped so what UV channel is it using?

Also, if I add a third set of UVs to my object and add a detail map to my object telling it to use uv3 for the detail map, then the object still works with realtime lightmapping. So how can the GI system be using uv3 for realtime lightmapping?

 

Thank you so much for this information Duck each time I get some nuggets of information like this it is like finding gold! (I re-read this about six times).

Yes I was being mislead by the fact that I can read from the mesh.uv3 channel and receive a zero length array but the channel has data! This is VERY misleading and needs to be documented. What happens if I write to it at runtime?

Interesting about the detail maps I thought that this was working but now that I test it I see that the detail map does look funny.

The project that led to all of this was trying to combine meshes preserving a lightmap bake. This used to work in Unity 4. I could read all the source mesh.uv2 channels combine them and write them to a combined mesh uv2 channel. I would need to adjust the renderer.lightmapScaleOffset so that it would encapsulate the lightmapScaleAndOffset of all the source objects and adjust the UV2 values to fit the new lightmapScaleAndOffset. This works for meshes that all share the same lightmap In Unity 4. It doen'st work in Unity 5.

Does reading from the UV2 channel also report non-repacked UVs when read from? That would explain why this doesn't work.

 

I don't think I have ever rambled this much on a forum thread but there is another point beyond the difference between the shader naming and mesh naming that NEEDs to be documented.

Based on Duck's explanation there ARE two hidden non-readable, non-writable uv channels in the mesh class. The repacked baked UVs and the repacked realtime UVs exist, and are used by the GI system. Any developer who thinks they can get this data by reading it from mesh.uv2 and mesh.uv3 is in for a miserable time.

 

O.K. Just so I am clear on this, does it work like this?:

• read from C# code mesh.uv2 at runtime get your original data back
• read from 2nd channel in shader code get a repacked version of mesh.uv2
• read from C# code mesh.uv3 at runtime get your original data back
• read from 3rd channel in shader code get the repacked version of mesh.uv3

Also one more question I have from all this is when does the UV repack occur for the realtime UVs. If I create a procedural mesh at runtime, are the UVs repacked on demand? On mesh creation? Is it when the UVs are assigned to the mesh? If it happens when UVs are assigned to the mesh then the order channels are assigned must matter beacuase:

myMesh.uv3 = myUV3layout;
myMesh.uv2 = myUV2layout;
myMesh.uv = myUVLayout;

The realtime lightmap UVs will be repacked once because uv3 takes precedence over uv and uv2. However if I assign in this order:

myMesh.uv = myUV3layout;
myMesh.uv2 = myUV2layout;
myMesh.uv3 = myUVLayout;

Then the repack will be triggered three times because each time I am assigning a channel with higher precedence. Is this a correct assumption I am making?

 

Ahhh! Thanks superpig! Another gold nugget!

 

Actually, i had a hard time finding this information (Duck's table) to solve an issue I had with a custom shader utilizing UV channel 3 which got broken after realtime GI precomputation.

But still I'm a bit confused what happens to the 2nd channel and which channels are used with specific options set on an object. In the "Lighting - Object" tab we have a "Preserve UVs" checkbox which tooltip says it would preserve the "lightmap uvs when generatnig realtime GI UVs". referring to the discussion above and the confusion about the exact use of words I wonder if the tooltip refers to the "Second" channel (marked as used by baked lightmaps) or the "Third". Or does it simply take whatever is available (and prioritize the third over the second).

Back to the table and the information, it would be awesome to have that table inside the docs and not only at the mesh api (as description to the respective uv, uv2, uv3, uv4 members) and the manual for the mesh data structure (e.g. there as a hint of the uv different usages) but also somewhere in the shader manuals for providing data to own shaders and the lighting/GI manual (e.g. what uvs are used for which part of the GI solution)

Gave me quite a headache, wrapping my mind around this, as only the parts with the custom shader got broken after precomputation and I started to ponder over weird solutions with duplicate objects and alpha or cutout shaders giving me a slight feeling of working around in a quick & dirty manner.

 

Hi Tobias, did you find this document https://goo.gl/bHsCyq ? It was a big help for me understanding how this works.

 

lol

 

I am completely confused AF !

All this is explaining to me why my uv2 (out of 3DSMax is being destroyed at runtime). If uv2 is a dedicated channel set side for Baking why does the secondary map for a standard sharder only offer uv0 and uv1 (mesh uv and mesh uv2).

All this is what Phong is talking about - maybe pop up dialogs should appear warning the developer of potential conflicts and restrictions when using specific uvs.

 

Hi, I'm trying to write custom standard shader now, and find this in UnityStandardCore.cginc:

Code (CSharp):

1. VertexOutputForwardBase vertForwardBase (VertexInput v)
2. {
3.     // ...
4.     o.tex = TexCoords(v);
5.     // ...
6.     UNITY_TRANSFER_SHADOW(o, v.uv1);
7. }

The TexCoords uses v.uv1 for detail map, and UNITY_TRANSFER_SHADOW uses v.uv1 for baked lightmap, how can v.uv1 be used for different purpose?

 

Thank you for letting us know and giving us lots of suggestions; this is always helpful. We're investigating this and will make any updates as soon as we can

This is because the realtime lightmapping data isn't provided back to you via the mesh class, because each instance of that mesh has different UV values for the realtime GI data, and this GI data is applied at a later stage in the rendering pipeline.

 

Hi all

i'm pretty sorry, and might be dumb.... i've trying all day long, after reading this post, doing something proper with 2 maps ( 1 diffuse and 1 detail ) and GI.
G1 ALWAYS messes up the detailmap.
i use blender, and my model got 2 UV layers named UV0 and UV3.
I also use the standard shaders )
UV0 is the diffuse/spec/norm layer and UV3 is my detailmap ( actually a dirtmap )

does anybody have an example of how to make this work ? or mebe a tuto somewhere on the web ?

thanks in advance )

 

I find all this confusing too. Why not stick to the default naming convention of UV0, UV1, UV2, UV3?

I understand the mesh UV and shader UV are technically a different thing but in reality, they are not so... why?

Jumping from UV to UV2 is just plain weird.

I'm expecthing the Shader's uv0 to match what I can read from mesh.uv and so on. Maybe name it something else? Then you're gonna say, no its UV data we cant name it something else... see my point?

 

4 years later ... the docs for Mesh class are still seriously wrong, then? And no-one (in four years) could fix them?

"
Mesh.uv3
Switch to Manual
public Vector2[] uv3;
Description
The third texture coordinate set of the mesh, if present.
"

...according to the above description, that text is simply a lie. It will not be the 3rd tex coord set of the mesh if present - it will be the 3rd tex coord if present AND ONLY IF Realtime GI is disabled?

(personally, I stopped using Unity's GI implementation a long time ago - waaaaaay too slow in the Editor, and too little detail in the documentation)

 

Yes, same for me.
U3D team buziness run make them implement new features while leaving mandatory old unfinished things in the cellar....
I also think about navmeshes

 

Yes, old thread, but I have a question :/
Guys, how to access generated uv1 (uv for lightmaps)???

I baked the light and tried to access uv1. Some models have expectable backed uv1, some don't: /

 

As I understand it:

UV2 is usually generated lightmap UVs. Although sometimes there is renderer specific data in MeshRenderer.additionalVertexStreams.

 

But a main problem is that those channels can't be imported lets say from FBX. This is really limiting and frustrating.

 

For Importer:
-Importer will import existing UV sets, but it will skip non existing ones. This means that if an UV set doesn't contain any data, it gets skipped. Example: lets say that we have assigned UV sets in modelling software as follows: UV0, UV3, UV4, UV5. Importer will import them as UV0, UV1, UV2, UV3. It will sequentially import UV sets that have data. This leads to reordering of all data and shifting of existing model UV sets.

Why we would prefer not to reorder those channels into UV0, UV1, UV2...?
Both UV1 and UV2 are used by Unity for Lightmapping and Realtime GI. They are practically internally reserved mapping channels. If we have any data on those channels, Unity will overwrite those channels by it's own data. Right now, we can force correct order of UV sets only by filling UV sets that we actually don't plan to use. This comes at a cost of much more data to save, and more data to manage at rendering time (at performance and file size cost).

NOTE: Both Unity and FBX permit UV-set skipping (empty UV sets). We can generate any procedural mesh in Unity and assign only a UV7 for example.

I can understand that messing with default importer behavior could be a problem, but we could have a tick-box to enable one-to-one UV channel assignment.

For Exporter:
-A change to be able to export all 8 UV sets is pretty straight-forward and I can confirm that does require 4 lines of code (that are actually a same line
But here also applies what applies for importer. Any empty UV slots will lead to UV channel shifting instead of following actual UV channel ID's (by taking into consideration empty channels).

Sincerely,
Oliver