Should I mention that the rotation in perp is anticlockwise?

[makoConstruct]

I guess whether it's anticlockwise or not depends on whether the user is treating y as being up or down, and that varies, so maybe we can't say a thing like that? But for me, it would have been helpful if it'd said anticlockwise.

Should it just say explicitly "anticlockwise (iff y is up and x is right)"

[bitshifter]

As you point out, whether it is anticlockwise or not depends on the coordinate system the user is using. glam is coordinate system agnostic. If they are using X right and Y up rotation would be counter clockwise, if X right and Y down it would be clockwise. Users could be using either a left or right hand coordinate system, glam doesn't force any particular convention. For this reason glam cannot make assumptions about the perceived direction of rotation.

[bitshifter]

https://pressbooks.library.upei.ca/statics/chapter/right-hand-rule/ has a bit of an explanation about co-ordinate system and rotation handedness, glam doesn't enforce any particular convention.

[makoConstruct]

So you're going to just continue not saying which of the two possible behaviors it is?

[aloucks]

Rather than thinking about it in terms of up or down, couldn't this be described as counter-clockwise around the positive y-axis?

[bitshifter]

So you're going to just continue not saying which of the two possible behaviors it is?

@makoConstruct No, I can think of 4 possible conventions:

| +X    | +Y   | Rot |
| Right | Up   | CCW |
| Left  | Up   | CW  |
| Right | Down | CW  |
| Left  | Down | CCW |

If you have a fixed co-ordinate system then it is easy to explain rotation direction, so for pretty much anyone using glam they will have a fixed coordinate system they are using which is easy to explain. This crate however cannot make any assumptions about the coordinate system being used. It is difficult to explain rotation order in a way that generalises to all possible use cases that is succinct (there are many rotation functions, if glam is to document rotation direction it needs to be done everywhere, consistently) and easy to understand (not much point writing docs that are not clear).

Rather than thinking about it in terms of up or down, couldn't this be described as counter-clockwise around the positive y-axis?

Rotation is on the XY plane, so around the Z axis. I agree with @aloucks with regards to avoiding talking about coordinate systems (e.g. what is up or down) in the docs.

I think the easiest way to document rotation methods would to not touch on coordinate systems at all and simply provide examples.

assert_eq!(Vec2::X.perp(), Vec2::Y);
assert_eq!(Vec2::Y.perp(), -Vec2::X);

Users can translate that into whatever co-ordinate system they are using and it should make sense.

[makoConstruct]

I agree that assert_eq!(Vec2::X.perp(), Vec2::Y); is a great way to express the thing.

[bitshifter]

Cool, definitely happy to accept PRs adding simple examples for these kinds of doc improvements.

[bitshifter]

Moved this to a discussion as per https://github.com/bitshifter/glam-rs/blob/main/CONTRIBUTING.md.