Document OrthographicProjection
#6177
Conversation
alice-i-cecile
added
C-Docs
|
Ping @bzm3r for review, since this was your PR that got adopted :) |
|
@xgbwei thanks for adopting this PR! I was procrastinating on it quite hard. Overall, it's good, but I think you cut out too much in some places. Also: it's okay for docs to be wordier, for the sake of clarity, rather than less wordy at the expense of possible lack of clarity. |
| @@ -161,17 +161,49 @@ pub enum ScalingMode { | |||
| FixedHorizontal(f32), | |||
| } | |||
|
|
|||
| /// Project a 3D space onto a 2D surface using parallel lines, i.e., objects have the same | |||
| /// apparent size regardless of depth. The volume contained in the projection is called the view frustum. | |||
There was a problem hiding this comment.
We should say that the volume is a rectangular prism, so that the top, bottom, left, right, near, and far make sense to the reader in this context.
There was a problem hiding this comment.
I did consider this, but "parallel lines" is more accurate to the technical definition of orthographic projection.
Maybe something along the lines of "Since the viewport is rectangular, The view frustum is in the shape of a rectangular prism" at the end of the paragraph would work?
| pub window_origin: WindowOrigin, | ||
| pub scaling_mode: ScalingMode, | ||
| /// Scales the cross sectional area of the view frustum. | ||
| /// Scales the width and height of the view frustum. |
There was a problem hiding this comment.
This should be a bit more specific as the cross sectional area is a function of width and height, not the other way around.
| /// | ||
| /// Objects further than this will not be rendered. | ||
| pub far: f32, | ||
| /// Specifies where `(0, 0)` is located. |
There was a problem hiding this comment.
I've checked the implementation for scaling and this is incorrect. See the newly added docs for WindowOrigin.
Maybe window_origin should be renamed to scaling_origin?
There was a problem hiding this comment.
Yes, I'm on board with that. We should consider renaming the type too.
| /// | ||
| /// If the window is smaller than the view frustum, some objects within the view frustum will not appear on the screen. |
There was a problem hiding this comment.
Is there any way for the width/height of the view frustum to be different than the width/height of the window? The only case I can think of is if scaling_mode is None, but then contents in the view frustum will just be stretched to fill the window.
There was a problem hiding this comment.
@xgbwei Will the contents just be stretched to fit the window? I thought some things will just lie outside the window if the view frustrum is larger than the window, for example (and thus those objects will not be visible)?
There was a problem hiding this comment.
Is there any way for the width/height of the view frustum to be different than the width/height of the window? The only case I can think of is if
scaling_modeisNone, but then contents in the view frustum will just be stretched to fill the window.
The viewport field on the camera allows you to specify custom viewport dimensions, for things like multiple views. In my tiled camera crate I use it to force the game view to a multiple of some target resolution to avoid pixel artifacts when rendering low resolution images.
| @@ -138,7 +138,15 @@ impl Default for PerspectiveProjection { | |||
| #[derive(Debug, Clone, Reflect, FromReflect, Serialize, Deserialize)] | |||
| #[reflect(Serialize, Deserialize)] | |||
| pub enum WindowOrigin { | |||
| /// Scale the view frustum from the center. | |||
There was a problem hiding this comment.
Wow, thank you for looking into this! This is so much clearer.
Can you clarify the following?
/// When resizing the window, object in the center of the screen remain in the center, while opposite
/// faces of the view frustum expand/shrink equally.
I understand, that in contrast to BottomLeft, which keeps the bottom and left faces fixed, this will change all the faces equally to perform the scaling operation. But I am not sure I understand the significance of "objects in the center of the screen remain in the center".
What happens to objects at the center of the screen when using BottomLeft?
|
Moved to #6201 |
Objective
OrthographicProjection#5818OrthographicProjection. #5824Solution
OrthographicProjectionand its fields.