Documenting `OrthographicProjection`. #5824

bzm3r · 2022-08-28T19:23:14Z

Objective

Documentation for OrthographicProjection is something that is often asked for implicitly in the #help channel on Discord. More explicitly, we now have #5818 , which this PR aims to fix.

Solution

Provided explanation for what left/right/top/bottom are, and in what units they are given. Also provided explanations for concepts like "field of view", "scale" and "window".

Co-authored-by: Robert Swain <robert.swain@gmail.com>

…w being merged. Co-authored-by: Robert Swain <robert.swain@gmail.com>

…ce memory" Co-authored-by: Robert Swain <robert.swain@gmail.com>

Co-authored-by: Robert Swain <robert.swain@gmail.com>

…documentation for StorageBuffer.

…mic storage buffer docs

Co-authored-by: Robert Swain <robert.swain@gmail.com>

…t of links to other data storage options at end of docstring fro each particular data storage option

…ckticks

bzm3r · 2022-08-28T19:24:31Z

@superdump ping as you've requested, for rendering related docs 😄

tim-blackbird · 2022-08-28T19:38:05Z

crates/bevy_render/src/camera/projection.rs

@@ -131,14 +131,16 @@ impl Default for PerspectiveProjection {
 #[derive(Debug, Clone, Reflect, FromReflect, Serialize, Deserialize)]
 #[reflect(Serialize, Deserialize)]
 pub enum WindowOrigin {
+    /// `(0, 0, 0)` is at the center of the screen.


Suggested change

/// `(0, 0, 0)` is at the center of the screen.

/// `(0, 0)` is at the center of the screen.

This affects only 2 dimensions.

MrGVSV · 2022-08-29T06:39:13Z

crates/bevy_render/src/camera/projection.rs

+    /// The value by which `left`, `right`, `bottom`, and `top` are multiplied (scaled). The smaller the `scale`, the smaller the
+    /// field of view, and thus, the *greater* the magnification of objects in the field of view. The larger the `scale`, the
+    /// larger the field of view, and thus the *smaller* the magnification of objects in the field of view.


Maybe this is too specific, but it would be nice to note somewhere that this is what people will typically want to manipulate to achieve a "camera zoom" effect.

Maybe we can put a doc alias here

sarkahn · 2022-08-29T14:42:29Z

crates/bevy_render/src/camera/projection.rs

+/// than the field of view, then some objects will naturally not appear on the screen. The relationship between the field of view
+/// and the window is governed by [`window_origin`].


That last sentence feels a bit off to me - aside from it being a bit vague, I think the purpose of window_origin should be explained within the struct or a related function, not in the general overview.

sarkahn · 2022-08-29T14:44:23Z

crates/bevy_render/src/camera/projection.rs

    pub near: f32,
+    /// The location of the face (in the z-direction) farthest from the camera, in world units.


Suggested change

/// The location of the face (in the z-direction) farthest from the camera, in world units.

/// The distance of the clipping plane (in the z-direction) farthest from the camera, in world units.

Isn't "furthest" more common than "farthest"?

sarkahn · 2022-08-29T14:44:56Z

crates/bevy_render/src/camera/projection.rs

    pub top: f32,
+    /// The location of the face (in the z-direction) nearest to the camera, in world units.


Suggested change

/// The location of the face (in the z-direction) nearest to the camera, in world units.

/// The distance of the clipping plane (in the z-direction) nearest to the camera, in world units.

Nilirad

Left some basic writing guidelines. Make sure you're only talking about the projection itself. Anything concerning the camera should go in its relative item.

I also advice semantic line breaks: they're getting popular lately in the repo.

Note: CI fails because rustdoc can't find links to objects like [`window_origin`]. You should transform those into [`window_origin`](Self::window_origin) to make them work.

Nilirad · 2022-08-29T14:39:11Z

crates/bevy_render/src/camera/projection.rs

@@ -154,17 +156,49 @@ pub enum ScalingMode {
    FixedHorizontal(f32),
 }

+/// A camera using `OrthographicProjection` displays the world within a rectangular prism (the "viewport", the "frustum", or


The description should be phrased in the terms of the type itself, not of the camera.

It could be something like: “Projects a 3D space onto a 2D surface using a rectangular prism.”, but I don't know if it is 100% correct since rendering is not my strong point.

The point is that the description of an item should not go outside its scope. You should also isolate the first sentence into its own paragraph.

Also "viewport" and "frustum" are two different things, but are used as synonyms here.

Nilirad · 2022-08-29T14:55:52Z

crates/bevy_render/src/camera/projection.rs

@@ -154,17 +156,49 @@ pub enum ScalingMode {
    FixedHorizontal(f32),
 }

+/// A camera using `OrthographicProjection` displays the world within a rectangular prism (the "viewport", the "frustum", or
+/// "field of view"). Objects that do not lie in this prism are culled ("frustum culling"): in other words, they are not displayed.


Triangles that fall outside the frustum are naturally not displayed, since they can't be projected. Frustum culling is just an algorithm that optimizes this process by not even trying to render certain things that are certainly out of sight.

Yes this is unrelated to the projection component. This should probably be deleted.

djeedai · 2022-09-01T22:34:00Z

crates/bevy_render/src/camera/projection.rs

 #[derive(Component, Debug, Clone, Reflect, FromReflect)]
 #[reflect(Component, Default)]
 pub struct OrthographicProjection {
+    /// The location of the left face of the camera's field of view, relative to the origin specified in [`window_origin`], in


"field of view" generally refers to the concept about how wide an angle the camera uses. Here we're talking about planes/faces, which is more about the frustum I think.

djeedai · 2022-09-01T22:36:36Z

crates/bevy_render/src/camera/projection.rs

    pub far: f32,
+    /// Specifies where `(0, 0, 0)` is located.


This does not really help comprehension I find. The "origin" is (0,0,0) so the comment is kind of redundant. It would be better to explain what this affects and how to configure it, maybe with an example.

xgbwei · 2022-10-06T00:22:19Z

@alice-i-cecile This PR has been inactive so I've started another and applied most changes suggested here.

alice-i-cecile · 2022-10-06T00:32:49Z

Closing in favor of #6177.

Brian Merchant and others added 27 commits May 6, 2022 13:30

Documenting BufferVec.

11727c5

Replace RenderDevice by GPU.

9ef6d24

Co-authored-by: Robert Swain <robert.swain@gmail.com>

State Pod as the direct requirement; and reflect reality of encase no…

5ffd580

…w being merged. Co-authored-by: Robert Swain <robert.swain@gmail.com>

Say "system RAM" instead of "host memory" and "VRAM" instead of "devi…

da1f666

…ce memory" Co-authored-by: Robert Swain <robert.swain@gmail.com>

remove repetition of "data"

e407b97

Co-authored-by: Robert Swain <robert.swain@gmail.com>

run cargo fmt

c50f80c

Merge branch 'main' of github.com:bevyengine/bevy

1dab056

Add documentation for UniformBuffer and DynamicUniformBuffer.

b974929

run cargo fmt

8a49be6

Merge branch 'bevyengine:main' into main

919c444

Clarifications regarding dynamic vs. non-dynamic buffers. Also added …

f77cd5a

…documentation for StorageBuffer.

Merge branch 'main' of github.com:bzm3r/bevy

ecfeac0

clarifying docs further.

908bd6a

say 'dynamic storage buffer', instead of only storage buffer, in dyna…

d275294

…mic storage buffer docs

addressing suggestions by @superdump (robswain)

d34311f

Update crates/bevy_render/src/render_resource/uniform_buffer.rs

e77771e

Co-authored-by: Robert Swain <robert.swain@gmail.com>

Update crates/bevy_render/src/render_resource/uniform_buffer.rs

8cb0f04

Co-authored-by: Robert Swain <robert.swain@gmail.com>

Update crates/bevy_render/src/render_resource/storage_buffer.rs

d4c1761

Co-authored-by: Robert Swain <robert.swain@gmail.com>

Update crates/bevy_render/src/render_resource/storage_buffer.rs

a109dad

Co-authored-by: Robert Swain <robert.swain@gmail.com>

Update crates/bevy_render/src/render_resource/storage_buffer.rs

d5bf796

Co-authored-by: Robert Swain <robert.swain@gmail.com>

Update crates/bevy_render/src/render_resource/uniform_buffer.rs

4ff1a55

Co-authored-by: Robert Swain <robert.swain@gmail.com>

strip down docs a bit, to avoid repetition, and provide a cohesive se…

fb5001a

…t of links to other data storage options at end of docstring fro each particular data storage option

allow doc_markdown clippy lint so that we can write WebGL2 without ba…

15f7033

…ckticks

Merge branch 'bevyengine:main' into main

211ca7c

Merge branch 'main' of github.com:bzm3r/bevy

6c9754f

Documenting and related concepts.

b2b87f8

cargo fmt

6881927

bzm3r marked this pull request as draft August 28, 2022 19:23

Weibye added the C-Docs An addition or correction to our documentation label Aug 28, 2022

Weibye added the A-Rendering Drawing game state to the screen label Aug 28, 2022

tim-blackbird reviewed Aug 28, 2022

View reviewed changes

MrGVSV reviewed Aug 29, 2022

View reviewed changes

sarkahn reviewed Aug 29, 2022

View reviewed changes

Nilirad reviewed Aug 29, 2022

View reviewed changes

djeedai reviewed Sep 1, 2022

View reviewed changes

xgbwei mentioned this pull request Oct 6, 2022

Document OrthographicProjection #6177

Closed

alice-i-cecile added the S-Adopt-Me The original PR author has no intent to complete this work. Pick me up! label Oct 6, 2022

alice-i-cecile closed this Oct 6, 2022

bzm3r deleted the ortho-proj-docs branch October 6, 2022 14:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documenting `OrthographicProjection`. #5824

Documenting `OrthographicProjection`. #5824

bzm3r commented Aug 28, 2022

bzm3r commented Aug 28, 2022

tim-blackbird Aug 28, 2022

MrGVSV Aug 29, 2022

Nilirad Aug 29, 2022

sarkahn Aug 29, 2022 •

edited

Loading

sarkahn Aug 29, 2022

djeedai Sep 1, 2022

sarkahn Aug 29, 2022

Nilirad left a comment

Nilirad Aug 29, 2022

djeedai Sep 1, 2022

Nilirad Aug 29, 2022

djeedai Sep 1, 2022

djeedai Sep 1, 2022

djeedai Sep 1, 2022

xgbwei commented Oct 6, 2022

alice-i-cecile commented Oct 6, 2022

	/// `(0, 0, 0)` is at the center of the screen.
	/// `(0, 0)` is at the center of the screen.

		/// than the field of view, then some objects will naturally not appear on the screen. The relationship between the field of view
		/// and the window is governed by [`window_origin`].

		pub near: f32,
		/// The location of the face (in the z-direction) farthest from the camera, in world units.

	/// The location of the face (in the z-direction) farthest from the camera, in world units.
	/// The distance of the clipping plane (in the z-direction) farthest from the camera, in world units.

		pub top: f32,
		/// The location of the face (in the z-direction) nearest to the camera, in world units.

Documenting OrthographicProjection. #5824

Documenting OrthographicProjection. #5824

Conversation

bzm3r commented Aug 28, 2022

Objective

Solution

bzm3r commented Aug 28, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sarkahn Aug 29, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Nilirad left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xgbwei commented Oct 6, 2022

alice-i-cecile commented Oct 6, 2022

Documenting `OrthographicProjection`. #5824

Documenting `OrthographicProjection`. #5824

sarkahn Aug 29, 2022 •

edited

Loading