Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
Transform2D
Матрица 2×3, представляющая двумерное преобразование.
Описание
The Transform2D built-in Variant type is a 2×3 matrix representing a transformation in 2D space. It contains three Vector2 values: x, y, and origin. Together, they can represent translation, rotation, scale, and skew.
The x and y axes form a 2×2 matrix, known as the transform's basis. The length of each axis (Vector2.length()) influences the transform's scale, while the direction of all axes influence the rotation. Usually, both axes are perpendicular to one another. However, when you rotate one axis individually, the transform becomes skewed. Applying a skewed transform to a 2D sprite will make the sprite appear distorted.
For a general introduction, see the Matrices and transforms tutorial.
Note: Unlike Transform3D, there is no 2D equivalent to the Basis type. All mentions of "basis" refer to the x and y components of Transform2D.
Note: In a boolean context, a Transform2D will evaluate to false if it's equal to IDENTITY. Otherwise, a Transform2D will always evaluate to true.
Примечание
Существуют заметные различия при использовании данного API с C#. Подробнее см. API различия C# и GDScript.
Обучающие материалы
Свойства
|
||
|
||
|
Конструкторы
Transform2D(from: Transform2D) |
|
Transform2D(rotation: float, position: Vector2) |
|
Transform2D(rotation: float, scale: Vector2, skew: float, position: Vector2) |
|
Transform2D(x_axis: Vector2, y_axis: Vector2, origin: Vector2) |
Методы
affine_inverse() const |
|
basis_xform(v: Vector2) const |
|
basis_xform_inv(v: Vector2) const |
|
determinant() const |
|
get_origin() const |
|
get_rotation() const |
|
get_scale() const |
|
get_skew() const |
|
interpolate_with(xform: Transform2D, weight: float) const |
|
inverse() const |
|
is_conformal() const |
|
is_equal_approx(xform: Transform2D) const |
|
is_finite() const |
|
looking_at(target: Vector2 = Vector2(0, 0)) const |
|
orthonormalized() const |
|
rotated_local(angle: float) const |
|
scaled_local(scale: Vector2) const |
|
translated(offset: Vector2) const |
|
translated_local(offset: Vector2) const |
Операторы
operator !=(right: Transform2D) |
|
operator *(right: PackedVector2Array) |
|
operator *(right: Rect2) |
|
operator *(right: Transform2D) |
|
operator *(right: Vector2) |
|
operator *(right: float) |
|
operator *(right: int) |
|
operator /(right: float) |
|
operator /(right: int) |
|
operator ==(right: Transform2D) |
|
operator [](index: int) |
Константы
IDENTITY = Transform2D(1, 0, 0, 1, 0, 0) 🔗
Тождество Transform2D. Это преобразование без перемещения, без вращения и масштабом Vector2.ONE. Это также означает, что:
x указывает вправо (Vector2.RIGHT);
y указывает вниз (Vector2.DOWN).
var transform = Transform2D.IDENTITY
print("| X | Y | Origin")
print("| %.f | %.f | %.f" % [transform.x.x, transform.y.x, transform.origin.x])
print("| %.f | %.f | %.f" % [transform.x.y, transform.y.y, transform.origin.y])
# Prints:
# | X | Y | Origin
# | 1 | 0 | 0
# | 0 | 1 | 0
Если Vector2, Rect2, PackedVector2Array или другой Transform2D преобразуется (умножается) этой константой, то преобразование не происходит.
Примечание: В GDScript эта константа эквивалентна созданию Transform2D без каких-либо аргументов. Ее можно использовать для того, чтобы сделать ваш код более понятным и для согласованности с C#.
FLIP_X = Transform2D(-1, 0, 0, 1, 0, 0) 🔗
Когда любое преобразование умножается на FLIP_X, оно инвертирует все компоненты оси x (столбец X).
Когда FLIP_X умножается на любое преобразование, оно инвертирует компонент Vector2.x всех осей (строка X).
FLIP_Y = Transform2D(1, 0, 0, -1, 0, 0) 🔗
Когда любое преобразование умножается на FLIP_Y, оно инвертирует все компоненты оси y (столбец Y).
Когда FLIP_Y умножается на любое преобразование, оно инвертирует компонент Vector2.y всех осей (строка Y).
Описания свойств
Vector2 origin = Vector2(0, 0) 🔗
Смещение перевода этого преобразования и столбец 2 матрицы. В двумерном пространстве это можно рассматривать как позицию.
Ось X базиса преобразования и столбец 0 матрицы. В сочетании с y это представляет поворот, масштаб и наклон преобразования.
В тождественном преобразовании этот вектор указывает вправо (Vector2.RIGHT).
Ось Y базиса преобразования и столбец 1 матрицы. В сочетании с x это представляет поворот, масштаб и наклон преобразования.
В тождественном преобразовании этот вектор указывает вниз (Vector2.DOWN).
Описания конструктора
Transform2D Transform2D() 🔗
Создает Transform2D, идентичный IDENTITY.
Примечание: В C# это создает Transform2D, все компоненты которого установлены в Vector2.ZERO.
Transform2D Transform2D(from: Transform2D)
Создает Transform2D как копию заданного Transform2D.
Transform2D Transform2D(rotation: float, position: Vector2)
Создает Transform2D по заданному углу (в радианах) и положению.
Transform2D Transform2D(rotation: float, scale: Vector2, skew: float, position: Vector2)
Создает Transform2D по заданному углу (в радианах), масштабу, наклону (в радианах) и положению.
Transform2D Transform2D(x_axis: Vector2, y_axis: Vector2, origin: Vector2)
Создает Transform2D из 3 значений Vector2, представляющих x, y и origin (три столбца матрицы).
Описания метода
Transform2D affine_inverse() const 🔗
Возвращает инвертированную версию этого преобразования. В отличие от inverse(), этот метод работает практически с любым базисом, включая неравномерные, но медленнее.
Примечание: Чтобы этот метод возвращал правильно, базис преобразования должен иметь определитель, который не равен в точности 0.0 (см. determinant()).
Vector2 basis_xform(v: Vector2) const 🔗
Возвращает копию вектора v, преобразованного (умноженного) на матрицу базиса преобразования. В отличие от оператора умножения (*), этот метод игнорирует origin.
Vector2 basis_xform_inv(v: Vector2) const 🔗
Возвращает копию вектора v, преобразованного (умноженного) на матрицу базиса обратного преобразования (см. inverse()). Этот метод игнорирует origin.
Примечание: Этот метод предполагает, что базис этого преобразования является ортонормальным (см. orthonormalized()). Если базис не является ортонормальным, вместо него следует использовать transform.affine_inverse().basis_xform(vector) (см. affine_inverse()).
Возвращает определитель матрицы этого базиса преобразования. Для продвинутой математики это число может использоваться для определения нескольких атрибутов:
Если определитель равен точно
0.0, базис необратим (см. inverse()).Если определитель — отрицательное число, базис представляет собой отрицательный масштаб.
Примечание: Если масштаб базиса одинаков для каждой оси, его определитель всегда равен этому масштабу в степени 2.
Возвращает перевод этого преобразования. Эквивалентно origin.
Возвращает поворот этого преобразования (в радианах). Это эквивалентно углу x (см. Vector2.angle()).
Возвращает длину x и y как Vector2. Если основа этого преобразования не перекошена, это значение является коэффициентом масштабирования. Оно не зависит от вращения.
var my_transform = Transform2D(
Vector2(2, 0),
Vector2(0, 4),
Vector2(0, 0)
)
# Поворот Transform2D любым способом сохраняет его масштаб.
my_transform = my_transform.rotated(TAU / 2)
print(my_transform.get_scale()) # Prints (2.0, 4.0)
var myTransform = new Transform2D(
Vector3(2.0f, 0.0f),
Vector3(0.0f, 4.0f),
Vector3(0.0f, 0.0f)
);
// Поворот Transform2D любым способом сохраняет его масштаб.
myTransform = myTransform.Rotated(Mathf.Tau / 2.0f);
GD.Print(myTransform.GetScale()); // Prints (2, 4)
Примечание: Если значение, возвращаемое determinant(), отрицательное, масштаб также будет отрицательным.
Возвращает наклон данного преобразования (в радианах).
Transform2D interpolate_with(xform: Transform2D, weight: float) const 🔗
Возвращает результат линейной интерполяции между этим преобразованием и xform по заданному weight.
weight должен быть между 0.0 и 1.0 (включительно). Значения вне этого диапазона разрешены и могут использоваться для выполнения экстраполяции.
Transform2D inverse() const 🔗
Возвращает инвертированную версию этого преобразования.
Примечание: Чтобы этот метод возвращал правильно, базис преобразования должен быть ортонормальным (см. orthonormalized()). Это означает, что базис должен представлять только поворот. Если это не так, используйте вместо этого affine_inverse().
Возвращает true, если базис этого преобразования конформный. Конформный базис является как ортогональным (оси перпендикулярны друг другу), так и равномерным (оси имеют одинаковую длину). Этот метод может быть особенно полезен при физических расчетах.
bool is_equal_approx(xform: Transform2D) const 🔗
Возвращает true, если это преобразование и xform приблизительно равны, путем запуска @GlobalScope.is_equal_approx() для каждого компонента.
Возвращает true, если это преобразование конечно, вызывая @GlobalScope.is_finite() для каждого компонента.
Transform2D looking_at(target: Vector2 = Vector2(0, 0)) const 🔗
Возвращает копию преобразования, повернутую таким образом, что повернутая ось X указывает на позицию target в глобальном пространстве.
Transform2D orthonormalized() const 🔗
Возвращает копию этого преобразования с ортонормированным базисом. Ортонормированный базис является как ортогональным (оси перпендикулярны друг другу), так и нормализованным (оси имеют длину 1.0), что также означает, что он может представлять только поворот.
Transform2D rotated(angle: float) const 🔗
Возвращает копию этого преобразования, повернутую на заданный angle (в радианах).
Если angle положительно, преобразование поворачивается по часовой стрелке.
Этот метод является оптимизированной версией умножения заданного преобразования X на соответствующее преобразование поворота R слева, т. е. R * X.
Это можно рассматривать как преобразование относительно глобального/родительского кадра.
Transform2D rotated_local(angle: float) const 🔗
Возвращает копию преобразования, повернутую на заданный angle (в радианах).
Этот метод является оптимизированной версией умножения заданного преобразования X на соответствующее преобразование поворота R справа, т. е. X * R.
Это можно рассматривать как преобразование относительно локального кадра.
Transform2D scaled(scale: Vector2) const 🔗
Возвращает копию преобразования, масштабированную заданным коэффициентом scale.
Этот метод является оптимизированной версией умножения заданного преобразования X на соответствующее масштабирующее преобразование S слева, т. е. S * X.
Это можно рассматривать как преобразование относительно глобального/родительского кадра.
Transform2D scaled_local(scale: Vector2) const 🔗
Возвращает копию преобразования, масштабированную заданным коэффициентом scale.
Этот метод является оптимизированной версией умножения заданного преобразования X на соответствующее масштабирующее преобразование S справа, т. е. X * S.
Это можно рассматривать как преобразование относительно локального кадра.
Transform2D translated(offset: Vector2) const 🔗
Возвращает копию преобразования, переведенную на заданное offset.
Этот метод является оптимизированной версией умножения заданного преобразования X на соответствующее преобразование перевода T слева, т. е. T * X.
Это можно рассматривать как преобразование относительно глобального/родительского фрейма.
Transform2D translated_local(offset: Vector2) const 🔗
Возвращает копию преобразования, переведенную на заданное offset.
Этот метод является оптимизированной версией умножения заданного преобразования X на соответствующее преобразование перевода T справа, т. е. X * T.
Это можно рассматривать как преобразование относительно локального фрейма.
Описания оператора
bool operator !=(right: Transform2D) 🔗
Возвращает true, если компоненты обоих преобразований не равны.
Примечание: Из-за ошибок точности с плавающей точкой рассмотрите возможность использования is_equal_approx() вместо этого, что более надежно.
PackedVector2Array operator *(right: PackedVector2Array) 🔗
Преобразует (умножает) каждый элемент Vector2 заданного PackedVector2Array на эту матрицу преобразования.
На больших массивах эта операция выполняется намного быстрее, чем преобразование каждого Vector2 по отдельности.
Rect2 operator *(right: Rect2) 🔗
Преобразует (умножает) Rect2 на эту матрицу преобразования.
Transform2D operator *(right: Transform2D) 🔗
Преобразует (умножает) это преобразование на преобразование right.
Это операция, выполняемая между родительским и дочерним узлами CanvasItem.
Примечание: Если вам нужно изменить только один атрибут этого преобразования, рассмотрите возможность использования одного из следующих методов:
Для перевода см. translate() или translate_local().
Для поворота см. rotated() или rotated_local().
Для масштабирования см. scaled() или scaled_local().
Vector2 operator *(right: Vector2) 🔗
Преобразует (умножает) Vector2 на эту матрицу преобразования.
Transform2D operator *(right: float) 🔗
Умножает все компоненты Transform2D на заданный float, включая origin. Это равномерно влияет на масштаб преобразования.
Transform2D operator *(right: int) 🔗
Умножает все компоненты Transform2D на заданное int, включая origin. Это равномерно влияет на масштаб преобразования.
Transform2D operator /(right: float) 🔗
Делит все компоненты Transform2D на заданный float, включая origin. Это равномерно влияет на масштаб преобразования.
Transform2D operator /(right: int) 🔗
Делит все компоненты Transform2D на заданное int, включая origin. Это равномерно влияет на масштаб преобразования.
bool operator ==(right: Transform2D) 🔗
Возвращает true, если компоненты обоих преобразований в точности равны.
Примечание: Из-за ошибок точности с плавающей точкой рассмотрите возможность использования is_equal_approx() вместо этого, что более надежно.
Vector2 operator [](index: int) 🔗
Доступ к каждой оси (столбцу) этого преобразования по их индексу. Индекс 0 совпадает с x, индекс 1 совпадает с y, а индекс 2 совпадает с origin.