Skip to content

Commit 7a6fdfe

Browse files
committed
Document why Basis columns are a, b, and c
Why Basis doesn't follow Godot's column name convention came up in Discord, and the reasoning was fairly buried in code reviews and commits in other projects, so I'm sharing the knowledge with API users. The explanation here is lifted directly from godot-rust/gdnative@16aa18e
1 parent 4c8ea83 commit 7a6fdfe

File tree

1 file changed

+9
-3
lines changed

1 file changed

+9
-3
lines changed

godot-core/src/builtin/basis.rs

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ use std::ops::{Mul, MulAssign};
2323
///
2424
/// The basis vectors are the columns of the matrix, whereas the [`rows`](Self::rows) field represents
2525
/// the row vectors.
26+
///
27+
/// Note that the names of the column vectors here are `a`, `b`, and `c`, which differs from Godot's convention of `x`, `y`, and `z`. This is
28+
/// because columns are the basis vectors of the transform, while rows represent the X/Y/Z coordinates of each vector. Although basis vectors are
29+
/// the _transformed_ unit vectors of X/Y/Z axes, they have no direct relation to those axes in the _transformed_ coordinate system. Thus, an
30+
/// independent notion of a, b, c does not suggest such a relation. Furthermore, there are sometimes expressions such as `x.x`, `x.y`, `y.x`
31+
/// etc. They are typically hard to read and error-prone to write. Having `a.x`, `a.y`, `b.x` makes things more understandable.
2632
#[derive(Copy, Clone, PartialEq, Debug)]
2733
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
2834
#[repr(C)]
@@ -457,7 +463,7 @@ impl Basis {
457463

458464
/// Returns the first column of the matrix,
459465
///
460-
/// _Godot equivalent: `Basis.x`_
466+
/// _Godot equivalent: `Basis.x`_, see [`Basis`] for why it's changed
461467
#[doc(alias = "x")]
462468
#[must_use]
463469
pub fn col_a(&self) -> Vector3 {
@@ -473,7 +479,7 @@ impl Basis {
473479

474480
/// Returns the second column of the matrix,
475481
///
476-
/// _Godot equivalent: `Basis.y`_
482+
/// _Godot equivalent: `Basis.y`_, see [`Basis`] for why it's changed
477483
#[doc(alias = "y")]
478484
#[must_use]
479485
pub fn col_b(&self) -> Vector3 {
@@ -489,7 +495,7 @@ impl Basis {
489495

490496
/// Returns the third column of the matrix,
491497
///
492-
/// _Godot equivalent: `Basis.z`_
498+
/// _Godot equivalent: `Basis.z`_, see [`Basis`] for why it's changed
493499
#[doc(alias = "z")]
494500
#[must_use]
495501
pub fn col_c(&self) -> Vector3 {

0 commit comments

Comments
 (0)