Vector documentation

ScriptCore/Math/Attributes/VectorAttribute.cs

@@ -1,17 +1,33 @@
 using System;
-using System.Collections.Generic;
-using System.Text;
 
 namespace GlitchyEngine.Math.Attributes;
 
+/// <summary>
+/// Generates fields for the components of a vector as well as basic methods like constructors, type casts and equality checks.
+/// </summary>
 [AttributeUsage(AttributeTargets.Struct)]
 public class VectorAttribute : Attribute
 {
+    /// <summary>
+    /// The Type of the vectors components.
+    /// </summary>
     public Type Type { get; set; }
+    /// <summary>
+    /// Number of components in the vectors (valid values are in the range of 2 to 4).
+    /// </summary>
     public int ComponentCount { get; set; }
     
+    /// <summary>
+    /// The base name of the vector.
+    /// </summary>
     public string TypeBase { get; set; }
 
+    /// <summary>
+    /// Creates a new instance of the <see cref="VectorAttribute"/> class.
+    /// </summary>
+    /// <param name="type"><inheritdoc cref="Type"/></param>
+    /// <param name="componentCount"><inheritdoc cref="ComponentCount"/></param>
+    /// <param name="typeBase"><inheritdoc cref="TypeBase"/></param>
     public VectorAttribute(Type type, int componentCount, string typeBase)
     {
         Type = type;
@@ -20,20 +36,45 @@ public class VectorAttribute : Attribute
     }
 }
 
+/// <summary>
+/// Generates comparison operators (>, <, >= and <=) for the vectors type.
+/// </summary>
 [AttributeUsage(AttributeTargets.Struct)]
 public class ComparableVectorAttribute : Attribute { }
+
+/// <summary>
+/// Generates component wise math operators (+, -, *, / and %) for the vectors type.
+/// </summary>
 [AttributeUsage(AttributeTargets.Struct)]
 public class VectorMathAttribute : Attribute { }
+
+/// <summary>
+/// Generates component wise logic operators (&, ^ and |) for the vectors type.
+/// </summary>
 [AttributeUsage(AttributeTargets.Struct)]
 public class VectorLogicAttribute : Attribute { }
 
+/// <summary>
+/// Generates a cast cast from the vector type to the specified target type.
+/// </summary>
 [AttributeUsage(AttributeTargets.Struct, AllowMultiple = true)]
 public class VectorCastAttribute : Attribute
 {
+    /// <summary>
+    /// The type of the target vector type.
+    /// </summary>
     public Type TargetType { get; set; }
 
+    /// <summary>
+    /// If <see cref="true"/> the cast will be explicit; if <see cref="false"/> it will an implicit cast.
+    /// </summary>
     public bool IsExplicit { get; set; }
 
+    /// <summary>
+    /// Creates a new instance of the <see cref="VectorCastAttribute"/> class.
+    /// </summary>
+    /// <param name="targetType"><inheritdoc cref="TargetType"/></param>
+    /// <param name="isExplicit"><inheritdoc cref="IsExplicit"/></param>
     public VectorCastAttribute(Type targetType, bool isExplicit)
     {
         TargetType = targetType;

ScriptCore/Math/BoolVectors.cs

@@ -4,6 +4,9 @@ using GlitchyEngine.Math.Attributes;
 
 namespace GlitchyEngine.Math;
 
+/// <summary>
+/// Represents a vector with two boolean values.
+/// </summary>
 [Vector(typeof(bool), 2, "bool")]
 [VectorLogic]
 public partial struct bool2
@@ -14,6 +17,9 @@ public partial struct bool2
     }
 }
 
+/// <summary>
+/// Represents a vector with three boolean values.
+/// </summary>
 [Vector(typeof(bool), 3, "bool")]
 [VectorLogic]
 public partial struct bool3
@@ -24,6 +30,9 @@ public partial struct bool3
     }
 }
 
+/// <summary>
+/// Represents a vector with four boolean values.
+/// </summary>
 [Vector(typeof(bool), 4, "bool")]
 [VectorLogic]
 public partial struct bool4

ScriptCore/Math/ColorRGBA.cs

@@ -57,9 +57,13 @@ public struct ColorRGBA
     public static explicit operator float4(ColorRGBA color) => new float4(color.R, color.G, color.B, color.A);
     public static explicit operator ColorRGBA(float4 vector) => new ColorRGBA(vector.X, vector.Y, vector.Z, vector.W);
     
-    // Converts a Color from sRGB color space to Linear color space.
+    /// <summary>
+    /// Converts a Color from sRGB color space to Linear color space.
+    /// </summary>
     public static ColorRGBA SRgbToLinear(ColorRGBA sRGB) => new ColorRGBA(pow(sRGB.R, SrgbToLin), pow(sRGB.G, SrgbToLin), pow(sRGB.B, SrgbToLin), sRGB.A);
 
-    // Converts a Color from linear color space to sRGB color space.
+    /// <summary>
+    /// Converts a Color from linear color space to sRGB color space.
+    /// </summary>
     public static ColorRGBA LinearToSRGB(ColorRGBA linear) => new ColorRGBA(pow(linear.R, LinToSRGB), pow(linear.G, LinToSRGB), pow(linear.B, LinToSRGB), linear.A);
 }

ScriptCore/Math/DoubleVectors.cs

@@ -4,6 +4,9 @@ using GlitchyEngine.Math.Attributes;
 
 namespace GlitchyEngine.Math;
 
+/// <summary>
+/// Represents a vector with two double-precision floating-point values.
+/// </summary>
 [Vector(typeof(double), 2, "double")]
 [VectorMath]
 [ComparableVector]
@@ -12,6 +15,9 @@ public partial struct double2
 {
 }
 
+/// <summary>
+/// Represents a vector with three double-precision floating-point values.
+/// </summary>
 [Vector(typeof(double), 3, "double")]
 [VectorMath]
 [ComparableVector]
@@ -20,6 +26,9 @@ public partial struct double3
 {
 }
 
+/// <summary>
+/// Represents a vector with four double-precision floating-point values.
+/// </summary>
 [Vector(typeof(double), 4, "double")]
 [VectorMath]
 [ComparableVector]

ScriptCore/Math/FloatVectors.cs

@@ -8,6 +8,9 @@ using GlitchyEngine.Math.Attributes;
 
 namespace GlitchyEngine.Math;
 
+/// <summary>
+/// Represents a vector with two single-precision floating-point values.
+/// </summary>
 [Vector(typeof(float), 2, "float")]
 [ComparableVector]
 [VectorMath]
@@ -16,15 +19,30 @@ namespace GlitchyEngine.Math;
 [VectorCast(typeof(half2), true)]
 public partial struct float2
 {
+    /// <summary>
+    /// A vector whose elements are all equal to zero.
+    /// </summary>
     public static readonly float2 Zero = new(0.0f, 0.0f);
+    /// <summary>
+    /// The vector (1, 0).
+    /// </summary>
     public static readonly float2 UnitX = new(1.0f, 0.0f);
+    /// <summary>
+    /// The vector (0, 1).
+    /// </summary>
     public static readonly float2 UnitY = new(0.0f, 1.0f);
+    /// <summary>
+    /// A vector whose elements are all equal to one.
+    /// </summary>
     public static readonly float2 One = new(0.0f, 0.0f);
 
     public static explicit operator Vector2(float2 self) => new(self.X, self.Y);
     public static explicit operator float2(Vector2 self) => new(self.X, self.Y);
 }
 
+/// <summary>
+/// Represents a vector with three single-precision floating-point values.
+/// </summary>
 [Vector(typeof(float), 3, "float")]
 [ComparableVector]
 [VectorMath]
@@ -33,23 +51,59 @@ public partial struct float2
 [VectorCast(typeof(half3), true)]
 public partial struct float3
 {
+    /// <summary>
+    /// A vector whose elements are all equal to zero.
+    /// </summary>
     public static readonly float3 Zero = new(0.0f, 0.0f, 0.0f);
+    /// <summary>
+    /// The vector (1, 0, 0).
+    /// </summary>
     public static readonly float3 UnitX = new(1.0f, 0.0f, 0.0f);
+    /// <summary>
+    /// The vector (0, 1, 0).
+    /// </summary>
     public static readonly float3 UnitY = new(0.0f, 1.0f, 0.0f);
+    /// <summary>
+    /// The vector (0, 0, 1).
+    /// </summary>
     public static readonly float3 UnitZ = new(0.0f, 0.0f, 1.0f);
+    /// <summary>
+    /// A vector whose elements are all equal to one.
+    /// </summary>
     public static readonly float3 One = new(0.0f, 0.0f, 0.0f);
 
+    /// <summary>
+    /// The vector (0, 0, 1).
+    /// </summary>
     public static readonly float3 Forward = new(0.0f, 0.0f, 1.0f);
+    /// <summary>
+    /// The vector (0, 0, -1).
+    /// </summary>
     public static readonly float3 Backward = new(0.0f, 0.0f, -1.0f);
+    /// <summary>
+    /// The vector (-1, 0, 0).
+    /// </summary>
     public static readonly float3 Left = new(-1.0f, 0.0f, 0.0f);
+    /// <summary>
+    /// The vector (1, 0, 0).
+    /// </summary>
     public static readonly float3 Right = new(1.0f, 0.0f, 0.0f);
+    /// <summary>
+    /// The vector (0, 1, 0).
+    /// </summary>
     public static readonly float3 Up = new(0.0f, 1.0f, 0.0f);
+    /// <summary>
+    /// The vector (0, -1, 0).
+    /// </summary>
     public static readonly float3 Down = new(0.0f, -1.0f, 0.0f);
     
     public static explicit operator Vector3(float3 self) => new(self.X, self.Y, self.Z);
     public static explicit operator float3(Vector3 self) => new(self.X, self.Y, self.Z);
 }
 
+/// <summary>
+/// Represents a vector with four single-precision floating-point values.
+/// </summary>
 [Vector(typeof(float), 4, "float")]
 [ComparableVector]
 [VectorMath]
@@ -58,11 +112,29 @@ public partial struct float3
 [VectorCast(typeof(half4), true)]
 public partial struct float4
 {
+    /// <summary>
+    /// A vector whose elements are all equal to zero.
+    /// </summary>
     public static readonly float4 Zero	= new(0f, 0f, 0f, 0f);
+    /// <summary>
+    /// The vector (1, 0, 0, 0).
+    /// </summary>
     public static readonly float4 UnitX	= new(1f, 0f, 0f, 0f);
+    /// <summary>
+    /// The vector (0, 1, 0, 0).
+    /// </summary>
     public static readonly float4 UnitY	= new(0f, 1f, 0f, 0f);
+    /// <summary>
+    /// The vector (0, 0, 1, 0).
+    /// </summary>
     public static readonly float4 UnitZ	= new(0f, 0f, 1f, 0f);
+    /// <summary>
+    /// The vector (0, 0, 0, 1).
+    /// </summary>
     public static readonly float4 UnitW	= new(0f, 0f, 0f, 1f);
+    /// <summary>
+    /// A vector whose elements are all equal to one.
+    /// </summary>
     public static readonly float4 One   = new(1f, 1f, 1f, 1f);
 
     public static explicit operator Vector4(float4 self) => new(self.X, self.Y, self.Z, self.W);

ScriptCore/Math/Half.cs

@@ -4,18 +4,19 @@ using System.Runtime.CompilerServices;
 namespace GlitchyEngine.Math;
 
 /// <summary>
-/// Represents a 16-bit floating point number. (IEEE 754 half-precision binary floating-point (binary16))
+/// Represents a 16-bit (half-precision) floating point number. (aka. IEEE 754 half-precision binary floating-point (binary16))
 /// </summary>
 /// <remarks>
-/// Even though it is possible, it's not recommended to perform calculations using this type directly, because most operators will simply cast the operands to <see cref="float"/> and cast the result back to <see cref="Half"/>.
+/// Even though it is possible, it's not recommended to perform large calculations using this type directly because most operators will simply cast the operands to <see cref="float"/> and cast the result back to <see cref="Half"/>.
+/// If you need to do larger calculations consider casting to <see cref="float"/> once and cast the result back to <see cref="Half"/> afterwards. This will not only have better performance, but will also increase the accuracy of the result.
 /// </remarks>
 public struct Half : IComparable , IComparable<Half>, IConvertible, IEquatable<Half>, IFormattable
 {
     public static readonly Half MinValue = new(-65504); // Should be 0xFBFF
     public static readonly Half MaxValue = new(65504); // Should be 0x7BFF
 
-    // The numbers for Inifnity, NaN and Zero need to be hardcoded as binaries,
-    // because the conversion intself relies on them.
+    // The numbers for Infinity, NaN and Zero need to be hardcoded as binaries,
+    // because the conversion itself relies on them.
 
     public static readonly Half PositiveInfinity = new(0x7C00);
     public static readonly Half NegativeInfinity = new(0xFC00);

ScriptCore/Math/HalfVectors.cs

@@ -3,19 +3,37 @@ using GlitchyEngine.Math.Attributes;
 
 namespace GlitchyEngine.Math;
 
+/// <summary>
+/// Represents a vector with two half-precision floating-point values.
+/// </summary>
+/// <inheritdoc cref="Half" select="remarks" />
 [Vector(typeof(Half), 2, "half")]
+[VectorMath]
+[ComparableVector]
 [VectorCast(typeof(float2), true)]
 public partial struct half2
 {
 }
 
+/// <summary>
+/// Represents a vector with three half-precision floating-point values.
+/// </summary>
+/// <inheritdoc cref="Half" select="remarks" />
 [Vector(typeof(Half), 3, "half")]
+[VectorMath]
+[ComparableVector]
 [VectorCast(typeof(float3), true)]
 public partial struct half3
 {
 }
 
+/// <summary>
+/// Represents a vector with four half-precision floating-point values.
+/// </summary>
+/// <inheritdoc cref="Half" select="remarks" />
 [Vector(typeof(Half), 4, "half")]
+[VectorMath]
+[ComparableVector]
 [VectorCast(typeof(float4), true)]
 public partial struct half4
 {

ScriptCore/Math/IntVectors.cs

@@ -4,6 +4,9 @@ using GlitchyEngine.Math.Attributes;
 
 namespace GlitchyEngine.Math;
 
+/// <summary>
+/// Represents a vector with two 32-bit signed integer values.
+/// </summary>
 [Vector(typeof(int), 2, "int")]
 [VectorMath]
 [VectorLogic]
@@ -18,6 +21,9 @@ public partial struct int2
     }
 }
 
+/// <summary>
+/// Represents a vector with three 32-bit signed integer values.
+/// </summary>
 [Vector(typeof(int), 3, "int")]
 [VectorMath]
 [VectorLogic]
@@ -32,6 +38,9 @@ public partial struct int3
     }
 }
 
+/// <summary>
+/// Represents a vector with four 32-bit signed integer values.
+/// </summary>
 [Vector(typeof(int), 4, "int")]
 [VectorMath]
 [VectorLogic]

ScriptCore/Math/UIntVectors.cs

@@ -6,6 +6,9 @@ namespace GlitchyEngine.Math;
 
 // TODO: Currently no VectorMath-Attribute because -uint results in long
 
+/// <summary>
+/// Represents a vector with two 32-bit unsigned integer values.
+/// </summary>
 [Vector(typeof(uint), 2, "uint")]
 [VectorLogic]
 [ComparableVector]
@@ -19,6 +22,9 @@ public partial struct uint2
     }
 }
 
+/// <summary>
+/// Represents a vector with three 32-bit unsigned integer values.
+/// </summary>
 [Vector(typeof(uint), 3, "uint")]
 [VectorLogic]
 [ComparableVector]
@@ -32,6 +38,9 @@ public partial struct uint3
     }
 }
 
+/// <summary>
+/// Represents a vector with four 32-bit unsigned integer values.
+/// </summary>
 [Vector(typeof(uint), 4, "uint")]
 [VectorLogic]
 [ComparableVector]