Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Basis

用于表示 3D 旋转和缩放的 3×3 矩阵。

描述

用于表示 3D 旋转和缩放的 3×3 矩阵。通常用作 Transform3D 的正交基。

包含 3 个向量字段 X、Y 和 Z 作为其列,它们通常被解释为变换的局部基向量。对于这种用途,它由缩放和旋转矩阵组成,顺序为 (M = R.S)。

基也可以作为 3D 向量的数组访问。这些向量通常彼此正交,但(由于缩放)不一定是归一化的。

有关一般介绍,请参阅 矩阵与变换 教程。

备注

通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异

教程

属性

Vector3

x

Vector3(1, 0, 0)

Vector3

y

Vector3(0, 1, 0)

Vector3

z

Vector3(0, 0, 1)

构造函数

Basis

Basis ( )

Basis

Basis ( Basis from )

Basis

Basis ( Vector3 axis, float angle )

Basis

Basis ( Quaternion from )

Basis

Basis ( Vector3 x_axis, Vector3 y_axis, Vector3 z_axis )

方法

float

determinant ( ) const

Basis

from_euler ( Vector3 euler, int order=2 ) static

Basis

from_scale ( Vector3 scale ) static

Vector3

get_euler ( int order=2 ) const

Quaternion

get_rotation_quaternion ( ) const

Vector3

get_scale ( ) const

Basis

inverse ( ) const

bool

is_conformal ( ) const

bool

is_equal_approx ( Basis b ) const

bool

is_finite ( ) const

Basis

looking_at ( Vector3 target, Vector3 up=Vector3(0, 1, 0), bool use_model_front=false ) static

Basis

orthonormalized ( ) const

Basis

rotated ( Vector3 axis, float angle ) const

Basis

scaled ( Vector3 scale ) const

Basis

slerp ( Basis to, float weight ) const

float

tdotx ( Vector3 with ) const

float

tdoty ( Vector3 with ) const

float

tdotz ( Vector3 with ) const

Basis

transposed ( ) const

操作符

bool

operator != ( Basis right )

Basis

operator * ( Basis right )

Vector3

operator * ( Vector3 right )

Basis

operator * ( float right )

Basis

operator * ( int right )

bool

operator == ( Basis right )

Vector3

operator [] ( int index )


常量

IDENTITY = Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)

恒等基,未应用旋转或缩放。

这与不带任何参数调用 Basis 来创建是一样的。这个常量可以用来让你的代码更清晰,并与 C# 保持一致。

FLIP_X = Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1)

在变换中使用时,会沿 X 轴翻转某物的基。

FLIP_Y = Basis(1, 0, 0, 0, -1, 0, 0, 0, 1)

在变换中使用时,会沿 Y 轴翻转某物的基。

FLIP_Z = Basis(1, 0, 0, 0, 1, 0, 0, 0, -1)

在变换中使用时,会沿 Z 轴翻转某物的基。


属性说明

Vector3 x = Vector3(1, 0, 0)

基矩阵的 X 向量(第 0 列)。相当于数组索引 0


Vector3 y = Vector3(0, 1, 0)

基矩阵的 Y 向量(第 1 列)。相当于数组索引 1


Vector3 z = Vector3(0, 0, 1)

基矩阵的 Z 向量(第 2 列)。相当于数组索引 2


构造函数说明

Basis Basis ( )

构造默认初始化为 IDENTITYBasis


Basis Basis ( Basis from )

构造给定 Basis 的副本。


Basis Basis ( Vector3 axis, float angle )

构造纯旋转的基矩阵,围绕给定的轴 axis 旋转 angle(单位为弧度)。该轴必须是归一化向量。


Basis Basis ( Quaternion from )

根据给定的四元数构造纯旋转的基矩阵。


Basis Basis ( Vector3 x_axis, Vector3 y_axis, Vector3 z_axis )

从 3 个轴向量(矩阵列)构造一个基矩阵。


方法说明

float determinant ( ) const

返回基矩阵的行列式。如果基是均匀缩放的,它的行列式是缩放的平方。

负的行列式意味着基的缩放是负的。负的行列式意味着基不可逆,通常被认为无效。


Basis from_euler ( Vector3 euler, int order=2 ) static

按照指定的欧拉旋转顺序,从欧拉角中构造一个纯旋转的 Basis 矩阵。默认情况下,使用 YXZ 顺序(最常用)。参见枚举 EulerOrder 的可能值。


Basis from_scale ( Vector3 scale ) static

构造一个没有旋转或剪切的纯缩放基础矩阵。scale 值被设置为矩阵的对角线,矩阵的其他部分为零。


Vector3 get_euler ( int order=2 ) const

以欧拉角的形式返回基的旋转。欧拉顺序取决于 order 参数,默认使用 YXZ 惯例:分解时,先 Z、再 X、最后 Y。返回的向量包含格式为(X 角、Y 角、Z 角)的旋转角。

可考虑改用 get_rotation_quaternion 方法,将返回 Quaternion 四元数而不是欧拉角。


Quaternion get_rotation_quaternion ( ) const

以四元数的形式返回基的旋转。如果你需要欧拉角,请参阅 get_euler 方法,但通常首选四元数而不是欧拉角。


Vector3 get_scale ( ) const

假设矩阵是旋转和缩放的组合,返回沿各轴缩放系数的绝对值。


Basis inverse ( ) const

返回矩阵的逆值。


bool is_conformal ( ) const

如果该基是共形的,则返回true,这意味着它保留角度和距离比率,并且只能由旋转和均匀缩放组成。如果该基具有不均匀的缩放或剪切/倾斜,则返回 false。这可以用来验证该基是否不失真,这对于物理和其他用例很重要。


bool is_equal_approx ( Basis b ) const

如果该基和 b 近似相等,则返回 true,判断方法是在每个向量分量上调用 @GlobalScope.is_equal_approx


bool is_finite ( ) const

如果该基是有限的,则返回 true,判断方法是在每个向量分量上调用 @GlobalScope.is_finite


Basis looking_at ( Vector3 target, Vector3 up=Vector3(0, 1, 0), bool use_model_front=false ) static

创建旋转 Basis,向前的轴(-Z)指向 target 的位置。

向上的轴(+Y)在保持与向前的轴垂直的前提下,尽可能接近 up 向量。最终的 Basis 是标准正交基。 targetup 向量不能为零,不能互相平行。

如果 use_model_fronttrue,则会将 +Z 轴(资产正面)作为向前的轴(此时 +X 为左),指向 target 的位置。默认情况下会将 -Z 轴(相机前方)作为向前的轴(此时 +X 为右)。


Basis orthonormalized ( ) const

返回矩阵的正交归一化版本(对于正交矩阵来说,偶尔调用以避免四舍五入错误是有用的)。这将在矩阵的基上执行 Gram-Schmidt 正交化。


Basis rotated ( Vector3 axis, float angle ) const

围绕给定轴线引入一个额外的旋转 angle(单位为弧度)。该轴必须是一个归一化的向量。


Basis scaled ( Vector3 scale ) const

引入一个由给定的 3D 缩放因子指定的附加缩放。


Basis slerp ( Basis to, float weight ) const

假设该矩阵是一个合适的旋转矩阵,slerp 与另一个旋转矩阵进行球面直线插值。


float tdotx ( Vector3 with ) const

与矩阵 X 轴的转置点积。


float tdoty ( Vector3 with ) const

与矩阵 Y 轴的转置点积。


float tdotz ( Vector3 with ) const

与矩阵 Z 轴的转置点积。


Basis transposed ( ) const

返回矩阵的转置版本。


操作符说明

bool operator != ( Basis right )

如果 Basis 矩阵不相等,则返回 true

注意:由于浮点数精度误差,请考虑改用 is_equal_approx,会更可靠。


Basis operator * ( Basis right )

通过将这两个 basis 矩阵相乘来组合它们。这具有使用第一个 basis(父项)变换第二个 basis(子项)的效果。


Vector3 operator * ( Vector3 right )

使用给定的 Basis 矩阵变换(乘)该 Vector3


Basis operator * ( float right )

该运算符会对 Basis 的所有分量进行乘操作,达到统一缩放的效果。


Basis operator * ( int right )

该运算符会对 Basis 的所有分量进行乘操作,达到统一缩放的效果。


bool operator == ( Basis right )

如果 Basis 矩阵完全相等,则返回 true

注意:由于浮点数精度误差,请考虑改用 is_equal_approx,会更可靠。


Vector3 operator [] ( int index )

使用索引访问基的分量。b[0] 相当于 b.xb[1] 相当于 b.yb[2] 相当于 b.z