godotengine / godotengine/godot-docs

SurfaceTool set_tangent documentation should explain why the tangent is a Plane

Open
#8,587 5 comments 1 reaction 0 assignees View on GitHub
discussion enhancement
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.