godotengine / godotengine/godot-docs
SurfaceTool set_tangent documentation should explain why the tangent is a Plane
- Dominant language
- reStructuredText
- Stars
- 5.7k
- Forks
- 3.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Description
**Your Godot version:** 4.2-stable
**Issue description:**
The way I understand vertex normals, tangents and binormals:
- The normal points away from the surface.
- The tangent is in the plane of the surface, orthogonal to the normal.
- The binormal is orthogonal to both of these. It's inferred automatically by the engine.
This is the normal situation (no pun intended) barring any trickery like bent normals, of course.
In `ArrayMesh`, the normal is specified as a `PackedVector3Array` as normal (no pun intended). The tangent, though, is given as a `PackedFloatArray` containing 4-tuples: x, y, z of the tangent vector, plus a fourth element which is +1 or -1 depending on which direction the binormal should be pointing. This is [documented properly](https://docs.godotengine.org/en/stable/classes/class_mesh.html#class-mesh-constant-array-tangent).
In `SurfaceTool` on the other hand, the `set_tangent` function takes a `Plane` instead of a vector. So I naively assumed that the plane would be the _tangent plane_, finding it weird that I wasn't able to specify the actual direction of the tangent vector within that plane.
Looking at [the source](https://github.com/godotengine/godot/blob/a311a4b162364d032b03ddf2a0e603ba40615ad7/scene/resources/surface_tool.cpp#L237-L238) makes it clear that that's not what's going on at all. The `Plane` struct is being abused here to mean "`Vector3` plus another `float`", and I should pass the actual tangent vector as the normal of the plane. The `d` component of the `Plane` should be +1 or -1; the semantics are exactly the same as with `ArrayMesh`.
However, the documentation for `set_tangent` just says "Specifies a tangent to use".
**URL to the documentation page (if already existing):**
https://docs.godotengine.org/en/stable/classes/class_surfacetool.html#class-surfacetool-method-set-tangent
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.