It’s very likely that the documentation should be clearer. I’ll try clarifying a bit here.
There are normal ids and normal vectors. Both normal ids and normal vectors can be automatically created or manually controlled. There is one normal vector per normal id.
Normal ids control the topology of the normals - how they’re connected with the vertices and face corners. For example, you might want a single normal per vertex (e.g. in a smooth sphere), or you might want multiple normals per vertex (e.g. the sharp corner of a cube). You might also want a single normal to be shared among multiple vertices (for example, you might want all vertices in a plane to share the same normal).
One part that could probably use additional documentation is how AddTriangle creates normal ids. When you call AddTriangle it creates 3 new face corners on the new triangle. If a vertex is newly used, it will make a new normal id. If a vertex is already part of another face, it will reuse whatever normal id is in use on that face. That’s how we get the smooth normal ids by default. I wrote up a bit more about this with diagrams here.
Automatic normal vector computation is whether, for a particular normal id, the normal vector is recomputed after mesh changes, or manually set. The automatic normal computation is pretty straightforward - it does a weighted average of the face normals of every vertex that’s using that normal id. Manually set normals are even easier - no matter what else is changed about a mesh, we just use that normal vector for that normal id.
If you make a mesh just using AddVertex and AddTriangle, you’ll get automatically created normal ids. These will be a single normal id per vertex, so you’ll get smooth normals at every vertex.
You’ll also get automatically computed normal vectors, so the normal vectors rendered will be reasonable.
Automatically computed normal vectors are dirtied on every mesh change, so if you move vertices using SetPosition, then the automatic normal vectors will be updated next time the mesh is rendered or GetNormal is called.
For many use cases, that’s fine. But you might want things to be manual in two ways - manually set normal ids or manually computed normal vectors.
Here’s a piece of example code to create a sharp quad:
local function addSharpQuad(editableMesh, vid0, vid1, vid2, vid3)
local nid = editableMesh:AddNormal() -- This creates a normal ID which is automatically computed
local fid1 = editableMesh:AddTriangle(vid0, vid1, vid2)
editableMesh:SetFaceNormals(fid1, {nid, nid, nid})
local fid2 = editableMesh:AddTriangle(vid0, vid2, vid3)
editableMesh:SetFaceNormals(fid2, {nid, nid, nid})
end
This is creating a single normal id and sharing it for all 6 face corners. Both triangles will have the same normal vector for all of their vertices, so you won’t see a crease between them. But, that normal vector is automatically computed. If you want to use your own normal vector for some reason (maybe the automatic normal vector computation isn’t giving you what you want), you could change the code to:
local nid = editableMesh:AddNormal(Vector3.new(0, 1, 0)) -- This creates a normal ID which is manually specified
You can also call SetNormal(nid, vec) to change a given normal id from automatic to manual computation, or ResetNormal(nid) to change it from manual to automatic computation.
