Add Transform Helper methods

[Bayslak]

Objective

• The objective of this PR reflects the idea of adding some helper methods to Transform to avoid cumbersome way of providing direction and moving an object. The issue taken in consideration is the following: Helper methods on Transform

Solution

• I decided to add a basic translate method in the Transform class translate(&mut self, direction: Vec3, speed: f32, delta_time_seconds: f32). This function simply provides a faster way of adding a translation to the Transform by providing a direction, a speed and a delta_seconds (or delta in general referring to time). This doesn't take in account the rotation of the Transform.
• I also added a second function translate_with_local_rotation(&mut self, direction: Vec3, speed: f32, delta_time_seconds: f32). This function differs from the one above because it also utilizes the rotation of the Transform to provide a way of moving the object following a specific direction and taking in account also it's rotation.

Testing

• I didn't test the new function, but I changed the example translation.rs using the newly implemented function translate to see if the result was the same.
• I also tried the second method translate_with_local_rotation by modifing the example 3d_rotation and adding a new line just after the rotation. It moved as expected, but the addition of the line felt like out of scope of the example, so I removed it.

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[IQuick143]

Overall I think the code is good, I'm not sure on the naming though.
I feel like translate should take an offset vector, and translate the Transform by that value.
This is more related to velocities and kinematics (moving objects over time).

Not sure what would be a better name.

[Bayslak]

Overall I think the code is good, I'm not sure on the naming though.
I feel like translate should take an offset vector, and translate the Transform by that value.
This is more related to velocities and kinematics (moving objects over time).

Not sure what would be a better name.

I see what you mean.

Maybe to make it more coherent might be better to only have a Vec3 as the signature of the method, calling it translation and let the user create the translation vector by multiplying it by the speed AND the delta time?

[Bayslak]

Going to change it later to only receive a Vec3

[BenjaminBrienen]

I think translate_to for a new absolute position and translate_by for an offset would be a good naming convention. It might also be worth wrapping the Vec3 in a newtype Offset and Position to prevent accidentally providing the wrong kind of value. Mojang actually just had this exact mixup earlier this month when reimplementing ender pearl teleportation!

[Bayslak]

I think translate_to for a new absolute position and translate_by for an offset would be a good naming convention. It might also be worth wrapping the Vec3 in a newtype Offset and Position to prevent accidentally providing the wrong kind of value. Mojang actually just had this exact mixup earlier this month when reimplementing ender pearl teleportation!

I see your points, but isn't just easier to read and understand a single Vec3 as a parameter? Then it's the user's job to provide the correct calculation over that Vec3 I feel 🤔

[BenjaminBrienen]

I think translate_to for a new absolute position and translate_by for an offset would be a good naming convention. It might also be worth wrapping the Vec3 in a newtype Offset and Position to prevent accidentally providing the wrong kind of value. Mojang actually just had this exact mixup earlier this month when reimplementing ender pearl teleportation!

I see your points, but isn't just easier to read and understand a single Vec3 as a parameter? Then it's the user's job to provide the correct calculation over that Vec3 I feel 🤔

It's not wrong either way. I feel like it's the same difference between having a raw boolean parameter vs an enum with 2 values. There is a clippy lint against boolean parameters because it's easy to accidentally mix up which parameter or which value you meant to use. Also, a raw true doesn't mean much to a first time reader unless they also look at the name of the parameter. However, there's also a balance to be had, of course. We don't need to newtype everything. My suggestion can be decided against. It's just a little piece of input in case everyone likes the idea. :)

[IQuick143]

RE: Point & Offset newtype.

While mathematically I 100% agree that the semantics of vectors (as offsets) vs points are very different (and the reason we use Vec3 for both could be regarded as a "hack" based on arbitrarily fixing the origin) the codebase is generally not made for this and it would be a very controversial change.
(Feel free to make an issue to discuss this, but we would likely need to convince glam to cooperate and we would make a very big breaking change.)
(Note: There's also some API design issues with affine combinations (specific subset of linear combinations) being valid operations on both Points and Vectors, while general linear combinations being well-defined only on vectors, however there is no type-based way to decide this, so you either need to allow points to behave like vectors, or force users to convert a bunch, introducing a lot of friction.)

Relevant discussion @ glam: bitshifter/glam-rs#133

[chompaa]

Doc suggestions :)

[BD103]

Looks good, thank you!

[alice-i-cecile]

Happy enough to have these, but the methods can be made const now :)

[Jondolf]

This name is way too verbose to me, I would just call this translate_local, matching the existing rotate_local. Godot also has Transform3D.translated_local

Suggested change

	pub const fn translate_with_local_rotation(&mut self, translation: Vec3) {
	pub const fn translate_local(&mut self, translation: Vec3) {

[Jondolf]

I guess the downside is that one could expect a "local translation" to also consider scale (Godot's does afaik), which translate_with_local_rotation shouldn't do.

But idk I'd rather just manually do transform.translate(transform.rotation * local_translation) than use the long name and do transform.translate_with_local_rotation(local_translation), but that's probably a me-problem 😅

[Jondolf]

I think my personal preference here would probably be having translate and translate_local, where the latter is with respect to the local frame, considering both rotation and scale. If you only want to consider rotation, then you can just do transform.translate(transform.rotation * local_translation).

[janhohenheim]

Could we also have -ed versions for parity? E.g. Transform::translated(self) -> Transform