From e88a8191948642f5764e1de6d1b904aaec1a6202 Mon Sep 17 00:00:00 2001
From: Micky <micheledevita2@gmail.com>
Date: Sun, 31 Dec 2023 12:00:50 +0100
Subject: [PATCH] Add more examples to Basis' Documentation

---
 doc/classes/Basis.xml | 65 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/doc/classes/Basis.xml b/doc/classes/Basis.xml
index f98c207a6e0..be1ebd3a03d 100644
--- a/doc/classes/Basis.xml
+++ b/doc/classes/Basis.xml
@@ -71,6 +71,12 @@
 			<param index="1" name="order" type="int" default="2" />
 			<description>
 				Constructs a pure rotation Basis matrix from Euler angles in the specified Euler rotation order. By default, use YXZ order (most common). See the [enum EulerOrder] enum for possible values.
+				[codeblock]
+				# Creates a Basis whose z axis points down.
+				var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0))
+
+				print(my_basis.z) # Prints (0, -1, 0).
+				[/codeblock]
 			</description>
 		</method>
 		<method name="from_scale" qualifiers="static">
@@ -78,6 +84,13 @@
 			<param index="0" name="scale" type="Vector3" />
 			<description>
 				Constructs a pure scale basis matrix with no rotation or shearing. The scale values are set as the diagonal of the matrix, and the other parts of the matrix are zero.
+				[codeblock]
+				var my_basis = Basis.from_scale(Vector3(2, 4, 8))
+
+				print(my_basis.x) # Prints (2, 0, 0).
+				print(my_basis.y) # Prints (0, 4, 0).
+				print(my_basis.z) # Prints (0, 0, 8).
+				[/codeblock]
 			</description>
 		</method>
 		<method name="get_euler" qualifiers="const">
@@ -98,6 +111,18 @@
 			<return type="Vector3" />
 			<description>
 				Assuming that the matrix is the combination of a rotation and scaling, return the absolute value of scaling factors along each axis.
+				[codeblock]
+				var my_basis = Basis(
+				    Vector3(2, 0, 0),
+				    Vector3(0, 4, 0),
+				    Vector3(0, 0, 8)
+				)
+				# Rotating the Basis in any way preserves its scale.
+				my_basis = my_basis.rotated(Vector3.UP, TAU / 2)
+				my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4)
+
+				print(my_basis.get_scale()) # Prints (2, 4, 8).
+				[/codeblock]
 			</description>
 		</method>
 		<method name="inverse" qualifiers="const">
@@ -140,6 +165,14 @@
 			<return type="Basis" />
 			<description>
 				Returns the orthonormalized version of the matrix (useful to call from time to time to avoid rounding error for orthogonal matrices). This performs a Gram-Schmidt orthonormalization on the basis of the matrix.
+				[codeblock]
+				# Rotate this Node3D every frame.
+				func _process(delta):
+				    basis = basis.rotated(Vector3.UP, TAU * delta)
+				    basis = basis.rotated(Vector3.RIGHT, TAU * delta)
+
+				    basis = basis.orthonormalized()
+				[/codeblock]
 			</description>
 		</method>
 		<method name="rotated" qualifiers="const">
@@ -148,6 +181,14 @@
 			<param index="1" name="angle" type="float" />
 			<description>
 				Introduce an additional rotation around the given axis by [param angle] (in radians). The axis must be a normalized vector.
+				[codeblock]
+				var my_basis = Basis.IDENTITY
+				var angle = TAU / 2
+
+				my_basis = my_basis.rotated(Vector3.UP, angle)    # Rotate around the up axis (yaw)
+				my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Rotate around the right axis (pitch)
+				my_basis = my_basis.rotated(Vector3.BACK, angle)  # Rotate around the back axis (roll)
+				[/codeblock]
 			</description>
 		</method>
 		<method name="scaled" qualifiers="const">
@@ -155,6 +196,18 @@
 			<param index="0" name="scale" type="Vector3" />
 			<description>
 				Introduce an additional scaling specified by the given 3D scaling factor.
+				[codeblock]
+				var my_basis = Basis(
+				    Vector3(1, 1, 1),
+				    Vector3(2, 2, 2),
+				    Vector3(3, 3, 3)
+				)
+				my_basis = my_basis.scaled(Vector3(0, 2, -2))
+
+				print(my_basis.x) # Prints (0, 2, -2).
+				print(my_basis.y) # Prints (0, 4, -4).
+				print(my_basis.z) # Prints (0, 6, -6).
+				[/codeblock]
 			</description>
 		</method>
 		<method name="slerp" qualifiers="const">
@@ -190,6 +243,18 @@
 			<return type="Basis" />
 			<description>
 				Returns the transposed version of the matrix.
+				[codeblock]
+				var my_basis = Basis(
+				    Vector3(1, 2, 3),
+				    Vector3(4, 5, 6),
+				    Vector3(7, 8, 9)
+				)
+				my_basis = my_basis.transposed()
+
+				print(my_basis.x) # Prints (1, 4, 7).
+				print(my_basis.y) # Prints (2, 5, 8).
+				print(my_basis.z) # Prints (3, 6, 9).
+				[/codeblock]
 			</description>
 		</method>
 	</methods>