Struct Transform 

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

表示 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

impl Transform

pub const IDENTITY: Transform

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

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

创建一个新的变换实例

参数

• 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
);

pub fn from_translation(translation: Vec3) -> Transform

从位置创建变换

示例

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));

pub fn from_rotation(rotation: Quat) -> Transform

从旋转创建变换

示例

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);

pub fn from_scale(scale: Vec3) -> Transform

从缩放创建变换

示例

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));

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

从 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);

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

从 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);

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

设置位置（链式调用）

示例

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

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

设置旋转（链式调用）

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

设置缩放（链式调用）

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

创建朝向目标的变换

参数

• 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                    // 上方向
);

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));

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));

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));

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));

pub fn from_matrix(matrix: Mat4) -> Transform

从变换矩阵创建变换

注意

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

pub fn inverse(&self) -> Result<Transform, AnvilKitError>

获取变换的逆变换

错误

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

示例

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));

pub fn is_finite(&self) -> bool

检查变换是否有效（不包含 NaN 或无穷大）

Trait Implementations

impl Clone for Transform

fn clone(&self) -> Transform

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Component for Transform

where Transform: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy_ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

fn register_component_hooks(_hooks: &mut ComponentHooks)

Called when registering this component, allowing mutable access to its ComponentHooks.

impl Debug for Transform

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Transform

fn default() -> Transform

Returns the “default value” for a type.

impl From<Transform> for GlobalTransform

fn from(transform: Transform) -> GlobalTransform

Converts to this type from the input type.

impl PartialEq for Transform

fn eq(&self, other: &Transform) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Transform

impl StructuralPartialEq for Transform