Struct Transform

Source

pub struct Transform {
    pub translation: Vec3,
    pub rotation: Quat,
    pub scale: Vec3,
}

Expand description

表示 3D 空间中位置、旋转和缩放的变换组件。

Transform 是 AnvilKit 中用于表示对象空间变换的基础类型。它支持 2D 和 3D 使用场景，对于 2D 对象，通常将 Z 分量设置为 0。

§内存布局

该结构体使用紧凑的内存布局，总大小为 40 字节：

translation: 12 字节 (3 × f32)
rotation: 16 字节 (4 × f32)
scale: 12 字节 (3 × f32)

§线程安全

Transform 实现了 Send 和 Sync，可以安全地在线程间传递。

Fields§

§translation: Vec3

世界空间中的位置

§rotation: Quat

四元数表示的旋转

§scale: Vec3

各轴的缩放因子

Implementations§

Source §

impl Transform

Source

pub const IDENTITY: Self

单位变换（无平移、旋转或缩放）

Source

pub fn new(translation: Vec3, rotation: Quat, scale: Vec3) -> Self

创建一个新的变换实例

§参数

translation: 位置向量
rotation: 旋转四元数
scale: 缩放向量

§示例

use anvilkit_core::math::Transform;
use glam::{Vec3, Quat};
 
let transform = Transform::new(
    Vec3::new(1.0, 2.0, 3.0),
    Quat::IDENTITY,
    Vec3::ONE
);

Source

pub fn from_translation(translation: Vec3) -> Self

从位置创建变换

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;
 
let transform = Transform::from_translation(Vec3::new(1.0, 2.0, 3.0));
assert_eq!(transform.translation, Vec3::new(1.0, 2.0, 3.0));

Source

pub fn from_rotation(rotation: Quat) -> Self

从旋转创建变换

§示例

use anvilkit_core::math::Transform;
use glam::Quat;
 
let rotation = Quat::from_rotation_y(std::f32::consts::PI / 4.0);
let transform = Transform::from_rotation(rotation);
assert_eq!(transform.rotation, rotation);

Source

pub fn from_scale(scale: Vec3) -> Self

从缩放创建变换

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;
 
let transform = Transform::from_scale(Vec3::splat(2.0));
assert_eq!(transform.scale, Vec3::splat(2.0));

Source

pub fn from_xyz(x: f32, y: f32, z: f32) -> Self

从 XYZ 坐标创建变换

§示例

use anvilkit_core::math::Transform;
 
let transform = Transform::from_xyz(1.0, 2.0, 3.0);
assert_eq!(transform.translation.x, 1.0);
assert_eq!(transform.translation.y, 2.0);
assert_eq!(transform.translation.z, 3.0);

Source

pub fn from_xy(x: f32, y: f32) -> Self

从 XY 坐标创建 2D 变换（Z = 0）

§示例

use anvilkit_core::math::Transform;
 
let transform = Transform::from_xy(1.0, 2.0);
assert_eq!(transform.translation.z, 0.0);

Source

pub fn with_translation(self, translation: Vec3) -> Self

设置位置（链式调用）

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;
 
let transform = Transform::IDENTITY
    .with_translation(Vec3::new(1.0, 2.0, 3.0));

Source

pub fn with_rotation(self, rotation: Quat) -> Self

设置旋转（链式调用）

Source

pub fn with_scale(self, scale: Vec3) -> Self

设置缩放（链式调用）

Source

pub fn looking_at(eye: Vec3, target: Vec3, up: Vec3) -> Result<Self>

创建朝向目标的变换

§参数

eye: 观察者位置
target: 目标位置
up: 上方向向量

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;
 
let transform = Transform::looking_at(
    Vec3::new(0.0, 0.0, 5.0),  // 相机位置
    Vec3::ZERO,                // 看向原点
    Vec3::Y                    // 上方向
);

Source

pub fn compute_matrix(&self) -> Mat4

将变换转换为 4x4 变换矩阵

矩阵的计算顺序为：缩放 → 旋转 → 平移

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;
 
let transform = Transform::from_xyz(1.0, 2.0, 3.0);
let matrix = transform.compute_matrix();
 
// 验证平移部分
assert_eq!(matrix.w_axis.truncate(), Vec3::new(1.0, 2.0, 3.0));

Source

pub fn transform_point(&self, point: Vec3) -> Vec3

应用变换到点

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;
 
let transform = Transform::from_xyz(1.0, 2.0, 3.0);
let point = Vec3::ZERO;
let transformed = transform.transform_point(point);
 
assert_eq!(transformed, Vec3::new(1.0, 2.0, 3.0));

Source

pub fn transform_vector(&self, vector: Vec3) -> Vec3

应用变换到向量（忽略平移）

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;
 
let transform = Transform::from_scale(Vec3::splat(2.0));
let vector = Vec3::new(1.0, 1.0, 1.0);
let transformed = transform.transform_vector(vector);
 
assert_eq!(transformed, Vec3::new(2.0, 2.0, 2.0));

Source

pub fn mul_transform(&self, other: &Transform) -> Transform

组合两个变换（self * other）

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;
 
let parent = Transform::from_xyz(1.0, 0.0, 0.0);
let child = Transform::from_xyz(0.0, 1.0, 0.0);
let combined = parent.mul_transform(&child);
 
assert_eq!(combined.translation, Vec3::new(1.0, 1.0, 0.0));

Source

pub fn from_matrix(matrix: Mat4) -> Self

从变换矩阵创建变换

§注意

如果矩阵包含非均匀缩放或剪切，可能会丢失信息。

Source

pub fn inverse(&self) -> Result<Self>

获取变换的逆变换

§错误

如果变换不可逆（例如缩放为零），返回错误。

§示例

use anvilkit_core::math::Transform;
use glam::Vec3;

let transform = Transform::from_xyz(1.0, 2.0, 3.0);
let inverse = transform.inverse().unwrap();
let identity = transform.mul_transform(&inverse);

// 结果应该接近单位变换
assert!((identity.translation.length() < 1e-5));