From 678eec7530b05908715a0bacfaaf20dbe332ccc9 Mon Sep 17 00:00:00 2001 From: TechnoPorg Date: Mon, 10 Oct 2022 20:11:48 -0600 Subject: [PATCH] Fully document the Projection class. Projection is a 4x4 matrix that applies a projective transformation. --- doc/classes/Projection.xml | 62 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/doc/classes/Projection.xml b/doc/classes/Projection.xml index 5690ea5e95b..602833bca5a 100644 --- a/doc/classes/Projection.xml +++ b/doc/classes/Projection.xml @@ -1,8 +1,12 @@ + 3D projection (4x4 matrix). + A 4x4 matrix used for 3D projective transformations. It can represent transformations such as translation, rotation, scaling, shearing, and perspective division. It consists of four [Vector4] columns. + For purely linear transformations (translation, rotation, and scale), it is recommended to use [Transform3D], as it is more performant and has a lower memory footprint. + Used internally as [Camera3D]'s projection matrix. @@ -10,18 +14,21 @@ + Constructs a default-initialized [Projection] set to [constant IDENTITY]. + Constructs a [Projection] as a copy of the given [Projection]. + Constructs a Projection as a copy of the given [Transform3D]. @@ -40,12 +47,14 @@ + Creates a new [Projection] that projects positions from a depth range of [code]-1[/code] to [code]1[/code] to one that ranges from [code]0[/code] to [code]1[/code], and flips the projected positions vertically, according to [param flip_y]. + Creates a new [Projection] that scales a given projection to fit around a given [AABB] in projection space. @@ -59,6 +68,8 @@ + Creates a new [Projection] for projecting positions onto a head-mounted display with the given X:Y aspect ratio, distance between eyes, display width, distance to lens, oversampling factor, and depth clipping planes. + [param eye] creates the projection for the left eye when set to 1, or the right eye when set to 2. @@ -70,6 +81,7 @@ + Creates a new [Projection] that projects positions in a frustum with the given clipping planes. @@ -81,12 +93,15 @@ + Creates a new [Projection] that projects positions in a frustum with the given size, X:Y aspect ratio, offset, and clipping planes. + [param flip_fov] determines whether the projection's field of view is flipped over its diagonal. + Creates a new [Projection] that projects positions into the given [Rect2]. @@ -98,6 +113,7 @@ + Creates a new [Projection] that projects positions using an orthogonal projection with the given clipping planes. @@ -108,6 +124,8 @@ + Creates a new [Projection] that projects positions using an orthogonal projection with the given size, X:Y aspect ratio, and clipping planes. + [param flip_fov] determines whether the projection's field of view is flipped over its diagonal. @@ -118,6 +136,8 @@ + Creates a new [Projection] that projects positions using a perspective projection with the given Y-axis field of view (in degrees), X:Y aspect ratio, and clipping planes. + [param flip_fov] determines whether the projection's field of view is flipped over its diagonal. @@ -131,31 +151,40 @@ + Creates a new [Projection] that projects positions using a perspective projection with the given Y-axis field of view (in degrees), X:Y aspect ratio, and clipping distances. The projection is adjusted for a head-mounted display with the given distance between eyes and distance to a point that can be focused on. + [param eye] creates the projection for the left eye when set to 1, or the right eye when set to 2. + [param flip_fov] determines whether the projection's field of view is flipped over its diagonal. + Returns a scalar value that is the signed factor by which areas are scaled by this matrix. If the sign is negative, the matrix flips the orientation of the area. + The determinant can be used to calculate the invertibility of a matrix or solve linear systems of equations involving the matrix, among other applications. + Returns a copy of this [Projection] with the signs of the values of the Y column flipped. + Returns the X:Y aspect ratio of this [Projection]'s viewport. + Returns the dimensions of the far clipping plane of the projection, divided by two. + Returns the horizontal field of view of the projection (in degrees). @@ -163,89 +192,114 @@ + Returns the vertical field of view of the projection (in degrees) associated with the given horizontal field of view (in degrees) and aspect ratio. + Returns the factor by which the visible level of detail is scaled by this [Projection]. + Returns the number of pixels with the given pixel width displayed per meter, after this [Projection] is applied. + Returns the clipping plane of this [Projection] whose index is given by [param plane]. + [param plane] should be equal to one of [constant PLANE_NEAR], [constant PLANE_FAR], [constant PLANE_LEFT], [constant PLANE_TOP], [constant PLANE_RIGHT], or [constant PLANE_BOTTOM]. + Returns the dimensions of the viewport plane that this [Projection] projects positions onto, divided by two. + Returns the distance for this [Projection] beyond which positions are clipped. + Returns the distance for this [Projection] before which positions are clipped. + Returns a [Projection] that performs the inverse of this [Projection]'s projective transformation. + Returns [code]true[/code] if this [Projection] performs an orthogonal projection. + Returns a [Projection] with the X and Y values from the given [Vector2] added to the first and second values of the final column respectively. + Returns a [Projection] with the near clipping distance adjusted to be [param new_znear]. + [b]Note:[/b] The original [Projection] must be a perspective projection. + The projection matrix's W vector (column 3). Equivalent to array index [code]3[/code]. + The projection matrix's X vector (column 0). Equivalent to array index [code]0[/code]. + The projection matrix's Y vector (column 1). Equivalent to array index [code]1[/code]. + The projection matrix's Z vector (column 2). Equivalent to array index [code]2[/code]. + The index value of the projection's near clipping plane. + The index value of the projection's far clipping plane. + The index value of the projection's left clipping plane. + The index value of the projection's top clipping plane. + The index value of the projection's right clipping plane. + The index value of the projection bottom clipping plane. + A [Projection] with no transformation defined. When applied to other data structures, no transformation is performed. + A [Projection] with all values initialized to 0. When applied to other data structures, they will be zeroed. @@ -253,30 +307,38 @@ + Returns [code]true[/code] if the projections are not equal. + [b]Note:[/b] Due to floating-point precision errors, this may return [code]true[/code], even if the projections are virtually equal. An [code]is_equal_approx[/code] method may be added in a future version of Godot. + Returns a [Projection] that applies the combined transformations of this [Projection] and [param right]. + Projects (multiplies) the given [Vector4] by this [Projection] matrix. + Returns [code]true[/code] if the projections are equal. + [b]Note:[/b] Due to floating-point precision errors, this may return [code]false[/code], even if the projections are virtually equal. An [code]is_equal_approx[/code] method may be added in a future version of Godot. + Returns the column of the [Projection] with the given index. + Indices are in the following order: x, y, z, w.