From: Carlos Sanchez <1175054+carlossanlop@users.noreply.github.com> Date: Fri, 12 Feb 2021 05:30:27 +0000 (-0800) Subject: Backport docs for System.Numerics.Vectors (#47725) X-Git-Tag: submit/tizen/20210909.063632~3281 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=adf616bed26460b6bd22164b60c5f83149c8c2e7;p=platform%2Fupstream%2Fdotnet%2Fruntime.git Backport docs for System.Numerics.Vectors (#47725) * Unavoidable refresh by Visual Studio of the csproj file. * Backport Matrix3x2 * Backport Matrix4x4 * Backport Plane * Backport Quaternion * Backport Vector * Backport Vector2 * Backport Vector3 * Backport Vector4 * Manually fix Plane < and > * Manually fix Vector wrong param names * Manually fix Vector2 < and > * Manually fix Vector3 < and > * Manually fix Vector4 < and > * Add GenerateDocumentationFile to csproj * Revert csproj GenerateDocumentationFile change * Revert file fully * Fix typo "Multiples" => "Multiplies" * Use instead of T * Matrix3x2 adjust remarks. * Quaternion address remarks. * Plane adjust remarks. * Vector4 adjust remarks. * Matrix4x4 adjust remarks. * Vector2 adjust remarks. * Vector3 adjust remarks. * Address tannergooding and gewarren suggestions. * Matrix4x4 tries to invert. * Bring back GenerateDocumentationFile in csproj * Revert sln change Co-authored-by: carlossanlop --- diff --git a/src/libraries/System.Numerics.Vectors/System.Numerics.Vectors.sln b/src/libraries/System.Numerics.Vectors/System.Numerics.Vectors.sln index f1f46e3..656a719 100644 --- a/src/libraries/System.Numerics.Vectors/System.Numerics.Vectors.sln +++ b/src/libraries/System.Numerics.Vectors/System.Numerics.Vectors.sln @@ -210,4 +210,4 @@ Global GlobalSection(ExtensibilityGlobals) = postSolution SolutionGuid = {F9EDC1DC-52BE-4C40-90D2-41EE6FB7FA5C} EndGlobalSection -EndGlobal +EndGlobal \ No newline at end of file diff --git a/src/libraries/System.Numerics.Vectors/src/System.Numerics.Vectors.csproj b/src/libraries/System.Numerics.Vectors/src/System.Numerics.Vectors.csproj index dd3dc29..3061589 100644 --- a/src/libraries/System.Numerics.Vectors/src/System.Numerics.Vectors.csproj +++ b/src/libraries/System.Numerics.Vectors/src/System.Numerics.Vectors.csproj @@ -3,8 +3,9 @@ true $(NetCoreAppCurrent) enable + true - \ No newline at end of file + diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix3x2.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix3x2.cs index 1735aab..bddf63d 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix3x2.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix3x2.cs @@ -7,7 +7,10 @@ using System.Runtime.CompilerServices; namespace System.Numerics { - /// A structure encapsulating a 3x2 matrix. + /// Represents a 3x2 matrix. + /// [Intrinsic] public struct Matrix3x2 : IEquatable { @@ -19,25 +22,31 @@ namespace System.Numerics 0f, 0f ); - /// The first element of the first row + /// The first element of the first row. public float M11; - /// The second element of the first row + /// The second element of the first row. public float M12; - /// The first element of the second row + /// The first element of the second row. public float M21; - /// The second element of the second row + /// The second element of the second row. public float M22; - /// The first element of the third row + /// The first element of the third row. public float M31; - /// The second element of the third row + /// The second element of the third row. public float M32; - /// Constructs a Matrix3x2 from the given components. + /// Creates a 3x2 matrix from the specified components. + /// The value to assign to the first element in the first row. + /// The value to assign to the second element in the first row. + /// The value to assign to the first element in the second row. + /// The value to assign to the second element in the second row. + /// The value to assign to the first element in the third row. + /// The value to assign to the second element in the third row. public Matrix3x2(float m11, float m12, float m21, float m22, float m31, float m32) @@ -52,19 +61,22 @@ namespace System.Numerics M32 = m32; } - /// Returns the multiplicative identity matrix. + /// Gets the multiplicative identity matrix. + /// The multiplicative identify matrix. public static Matrix3x2 Identity { get => _identity; } - /// Returns whether the matrix is the identity matrix. + /// Gets a value that indicates whether the current matrix is the identity matrix. + /// if the current matrix is the identity matrix; otherwise, . public readonly bool IsIdentity { get => this == Identity; } /// Gets or sets the translation component of this matrix. + /// The translation component of the current instance. public Vector2 Translation { readonly get => new Vector2(M31, M32); @@ -76,10 +88,11 @@ namespace System.Numerics } } - /// Adds each matrix element in value1 with its corresponding element in value2. - /// The first source matrix. - /// The second source matrix. - /// The matrix containing the summed values. + /// Adds each element in one matrix with its corresponding element in a second matrix. + /// The first matrix. + /// The second matrix. + /// The matrix that contains the summed values. + /// The method defines the operation of the addition operator for objects. public static Matrix3x2 operator +(Matrix3x2 value1, Matrix3x2 value2) { Matrix3x2 m; @@ -96,10 +109,11 @@ namespace System.Numerics return m; } - /// Returns a boolean indicating whether the given matrices are equal. - /// The first source matrix. - /// The second source matrix. - /// True if the matrices are equal; False otherwise. + /// Returns a value that indicates whether the specified matrices are equal. + /// The first matrix to compare. + /// The second matrix to compare. + /// if and are equal; otherwise, . + /// Two matrices are equal if all their corresponding elements are equal. public static bool operator ==(Matrix3x2 value1, Matrix3x2 value2) { // Check diagonal element first for early out. @@ -111,19 +125,20 @@ namespace System.Numerics && value1.M32 == value2.M32); } - /// Returns a boolean indicating whether the given matrices are not equal. - /// The first source matrix. - /// The second source matrix. - /// True if the matrices are not equal; False if they are equal. + /// Returns a value that indicates whether the specified matrices are not equal. + /// The first matrix to compare. + /// The second matrix to compare. + /// if and are not equal; otherwise, . public static bool operator !=(Matrix3x2 value1, Matrix3x2 value2) { return !(value1 == value2); } - /// Multiplies two matrices together and returns the resulting matrix. - /// The first source matrix. - /// The second source matrix. + /// Multiplies two matrices together to compute the product. + /// The first matrix. + /// The second matrix. /// The product matrix. + /// The method defines the operation of the multiplication operator for objects. public static Matrix3x2 operator *(Matrix3x2 value1, Matrix3x2 value2) { Matrix3x2 m; @@ -143,10 +158,11 @@ namespace System.Numerics return m; } - /// Scales all elements in a matrix by the given scalar factor. - /// The source matrix. + /// Multiplies a matrix by a float to compute the product. + /// The matrix to scale. /// The scaling value to use. - /// The resulting matrix. + /// The scaled matrix. + /// The method defines the operation of the multiplication operator for objects. public static Matrix3x2 operator *(Matrix3x2 value1, float value2) { Matrix3x2 m; @@ -163,10 +179,11 @@ namespace System.Numerics return m; } - /// Subtracts each matrix element in value2 from its corresponding element in value1. - /// The first source matrix. - /// The second source matrix. - /// The matrix containing the resulting values. + /// Subtracts each element in a second matrix from its corresponding element in a first matrix. + /// The first matrix. + /// The second matrix. + /// The matrix containing the values that result from subtracting each element in from its corresponding element in . + /// The method defines the operation of the subtraction operator for objects. public static Matrix3x2 operator -(Matrix3x2 value1, Matrix3x2 value2) { Matrix3x2 m; @@ -183,9 +200,10 @@ namespace System.Numerics return m; } - /// Negates the given matrix by multiplying all values by -1. - /// The source matrix. + /// Negates the specified matrix by multiplying all its values by -1. + /// The matrix to negate. /// The negated matrix. + /// public static Matrix3x2 operator -(Matrix3x2 value) { Matrix3x2 m; @@ -202,10 +220,10 @@ namespace System.Numerics return m; } - /// Adds each matrix element in value1 with its corresponding element in value2. - /// The first source matrix. - /// The second source matrix. - /// The matrix containing the summed values. + /// Adds each element in one matrix with its corresponding element in a second matrix. + /// The first matrix. + /// The second matrix. + /// The matrix that contains the summed values of and . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix3x2 Add(Matrix3x2 value1, Matrix3x2 value2) { @@ -214,7 +232,7 @@ namespace System.Numerics /// Creates a rotation matrix using the given rotation in radians. /// The amount of rotation, in radians. - /// A rotation matrix. + /// The rotation matrix. public static Matrix3x2 CreateRotation(float radians) { radians = MathF.IEEERemainder(radians, MathF.PI * 2); @@ -265,10 +283,10 @@ namespace System.Numerics return result; } - /// Creates a rotation matrix using the given rotation in radians and a center point. + /// Creates a rotation matrix using the specified rotation in radians and a center point. /// The amount of rotation, in radians. /// The center point. - /// A rotation matrix. + /// The rotation matrix. public static Matrix3x2 CreateRotation(float radians, Vector2 centerPoint) { Matrix3x2 result; @@ -324,9 +342,9 @@ namespace System.Numerics return result; } - /// Creates a scale matrix from the given vector scale. + /// Creates a scaling matrix from the specified vector scale. /// The scale to use. - /// A scaling matrix. + /// The scaling matrix. public static Matrix3x2 CreateScale(Vector2 scales) { Matrix3x2 result = Identity; @@ -337,10 +355,10 @@ namespace System.Numerics return result; } - /// Creates a scale matrix from the given X and Y components. - /// Value to scale by on the X-axis. - /// Value to scale by on the Y-axis. - /// A scaling matrix. + /// Creates a scaling matrix from the specified X and Y components. + /// The value to scale by on the X axis. + /// The value to scale by on the Y axis. + /// The scaling matrix. public static Matrix3x2 CreateScale(float xScale, float yScale) { Matrix3x2 result = Identity; @@ -351,11 +369,11 @@ namespace System.Numerics return result; } - /// Creates a scale matrix that is offset by a given center point. - /// Value to scale by on the X-axis. - /// Value to scale by on the Y-axis. + /// Creates a scaling matrix that is offset by a given center point. + /// The value to scale by on the X axis. + /// The value to scale by on the Y axis. /// The center point. - /// A scaling matrix. + /// The scaling matrix. public static Matrix3x2 CreateScale(float xScale, float yScale, Vector2 centerPoint) { Matrix3x2 result = Identity; @@ -371,10 +389,10 @@ namespace System.Numerics return result; } - /// Creates a scale matrix from the given vector scale with an offset from the given center point. + /// Creates a scaling matrix from the specified vector scale with an offset from the specified center point. /// The scale to use. /// The center offset. - /// A scaling matrix. + /// The scaling matrix. public static Matrix3x2 CreateScale(Vector2 scales, Vector2 centerPoint) { Matrix3x2 result = Identity; @@ -390,9 +408,9 @@ namespace System.Numerics return result; } - /// Creates a scale matrix that scales uniformly with the given scale. + /// Creates a scaling matrix that scales uniformly with the given scale. /// The uniform scale to use. - /// A scaling matrix. + /// The scaling matrix. public static Matrix3x2 CreateScale(float scale) { Matrix3x2 result = Identity; @@ -403,10 +421,10 @@ namespace System.Numerics return result; } - /// Creates a scale matrix that scales uniformly with the given scale with an offset from the given center. + /// Creates a scaling matrix that scales uniformly with the specified scale with an offset from the specified center. /// The uniform scale to use. /// The center offset. - /// A scaling matrix. + /// The scaling matrix. public static Matrix3x2 CreateScale(float scale, Vector2 centerPoint) { Matrix3x2 result = Identity; @@ -422,10 +440,10 @@ namespace System.Numerics return result; } - /// Creates a skew matrix from the given angles in radians. + /// Creates a skew matrix from the specified angles in radians. /// The X angle, in radians. /// The Y angle, in radians. - /// A skew matrix. + /// The skew matrix. public static Matrix3x2 CreateSkew(float radiansX, float radiansY) { Matrix3x2 result = Identity; @@ -439,11 +457,11 @@ namespace System.Numerics return result; } - /// Creates a skew matrix from the given angles in radians and a center point. + /// Creates a skew matrix from the specified angles in radians and a center point. /// The X angle, in radians. /// The Y angle, in radians. /// The center point. - /// A skew matrix. + /// The skew matrix. public static Matrix3x2 CreateSkew(float radiansX, float radiansY, Vector2 centerPoint) { Matrix3x2 result = Identity; @@ -463,9 +481,9 @@ namespace System.Numerics return result; } - /// Creates a translation matrix from the given vector. + /// Creates a translation matrix from the specified 2-dimensional vector. /// The translation position. - /// A translation matrix. + /// The translation matrix. public static Matrix3x2 CreateTranslation(Vector2 position) { Matrix3x2 result = Identity; @@ -476,10 +494,10 @@ namespace System.Numerics return result; } - /// Creates a translation matrix from the given X and Y components. + /// Creates a translation matrix from the specified X and Y components. /// The X position. /// The Y position. - /// A translation matrix. + /// The translation matrix. public static Matrix3x2 CreateTranslation(float xPosition, float yPosition) { Matrix3x2 result = Identity; @@ -490,10 +508,10 @@ namespace System.Numerics return result; } - /// Attempts to invert the given matrix. If the operation succeeds, the inverted matrix is stored in the result parameter. - /// The source matrix. - /// The output matrix. - /// True if the operation succeeded, False otherwise. + /// Tries to invert the specified matrix. The return value indicates whether the operation succeeded. + /// The matrix to invert. + /// When this method returns, contains the inverted matrix if the operation succeeded. + /// if was converted successfully; otherwise, . public static bool Invert(Matrix3x2 matrix, out Matrix3x2 result) { float det = (matrix.M11 * matrix.M22) - (matrix.M21 * matrix.M12); @@ -518,10 +536,10 @@ namespace System.Numerics return true; } - /// Linearly interpolates from matrix1 to matrix2, based on the third parameter. - /// The first source matrix. - /// The second source matrix. - /// The relative weighting of matrix2. + /// Performs a linear interpolation from one matrix to a second matrix based on a value that specifies the weighting of the second matrix. + /// The first matrix. + /// The second matrix. + /// The relative weighting of . /// The interpolated matrix. public static Matrix3x2 Lerp(Matrix3x2 matrix1, Matrix3x2 matrix2, float amount) { @@ -542,9 +560,9 @@ namespace System.Numerics return result; } - /// Multiplies two matrices together and returns the resulting matrix. - /// The first source matrix. - /// The second source matrix. + /// Multiplies two matrices together to compute the product. + /// The first matrix. + /// The second matrix. /// The product matrix. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix3x2 Multiply(Matrix3x2 value1, Matrix3x2 value2) @@ -552,18 +570,18 @@ namespace System.Numerics return value1 * value2; } - /// Scales all elements in a matrix by the given scalar factor. - /// The source matrix. + /// Multiplies a matrix by a float to compute the product. + /// The matrix to scale. /// The scaling value to use. - /// The resulting matrix. + /// The scaled matrix. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix3x2 Multiply(Matrix3x2 value1, float value2) { return value1 * value2; } - /// Negates the given matrix by multiplying all values by -1. - /// The source matrix. + /// Negates the specified matrix by multiplying all its values by -1. + /// The matrix to negate. /// The negated matrix. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix3x2 Negate(Matrix3x2 value) @@ -571,36 +589,38 @@ namespace System.Numerics return -value; } - /// Subtracts each matrix element in value2 from its corresponding element in value1. - /// The first source matrix. - /// The second source matrix. - /// The matrix containing the resulting values. + /// Subtracts each element in a second matrix from its corresponding element in a first matrix. + /// The first matrix. + /// The second matrix. + /// The matrix containing the values that result from subtracting each element in from its corresponding element in . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix3x2 Subtract(Matrix3x2 value1, Matrix3x2 value2) { return value1 - value2; } - /// Returns a boolean indicating whether the given Object is equal to this matrix instance. - /// The Object to compare against. - /// True if the Object is equal to this matrix; False otherwise. + /// Returns a value that indicates whether this instance and a specified object are equal. + /// The object to compare with the current instance. + /// if the current instance and are equal; otherwise, . If is , the method returns . + /// The current instance and are equal if is a object and the corresponding elements of each matrix are equal. [MethodImpl(MethodImplOptions.AggressiveInlining)] public override readonly bool Equals([NotNullWhen(true)] object? obj) { return (obj is Matrix3x2 other) && Equals(other); } - /// Returns a boolean indicating whether the matrix is equal to the other given matrix. - /// The other matrix to test equality against. - /// True if this matrix is equal to other; False otherwise. + /// Returns a value that indicates whether this instance and another 3x2 matrix are equal. + /// The other matrix. + /// if the two matrices are equal; otherwise, . + /// Two matrices are equal if all their corresponding elements are equal. public readonly bool Equals(Matrix3x2 other) { return this == other; } - /// Calculates the determinant for this matrix. - /// The determinant is calculated by expanding the matrix with a third column whose values are (0,0,1). + /// Calculates the determinant for this matrix. /// The determinant. + /// The determinant is calculated by expanding the matrix with a third column whose values are (0,0,1). public readonly float GetDeterminant() { // There isn't actually any such thing as a determinant for a non-square matrix, @@ -629,8 +649,9 @@ namespace System.Numerics return HashCode.Combine(M11, M12, M21, M22, M31, M32); } - /// Returns a String representing this matrix instance. - /// The string representation. + /// Returns a string that represents this matrix. + /// The string representation of this matrix. + /// The numeric values in the returned string are formatted by using the conventions of the current culture. For example, for the en-US culture, the returned string might appear as { {M11:1.1 M12:1.2} {M21:2.1 M22:2.2} {M31:3.1 M32:3.2} }. public override readonly string ToString() { return string.Format(CultureInfo.CurrentCulture, "{{ {{M11:{0} M12:{1}}} {{M21:{2} M22:{3}}} {{M31:{4} M32:{5}}} }}", diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix4x4.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix4x4.cs index 8ede459..413695a 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix4x4.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix4x4.cs @@ -11,7 +11,10 @@ using System.Runtime.Intrinsics.X86; namespace System.Numerics { - /// A structure encapsulating a 4x4 matrix. + /// Represents a 4x4 matrix. + /// [Intrinsic] public struct Matrix4x4 : IEquatable { @@ -27,55 +30,71 @@ namespace System.Numerics 0f, 0f, 0f, 1f ); - /// Value at row 1, column 1 of the matrix. + /// The first element of the first row. public float M11; - /// Value at row 1, column 2 of the matrix. + /// The second element of the first row. public float M12; - /// Value at row 1, column 3 of the matrix. + /// The third element of the first row. public float M13; - /// Value at row 1, column 4 of the matrix. + /// The fourth element of the first row. public float M14; - /// Value at row 2, column 1 of the matrix. + /// The first element of the second row. public float M21; - /// Value at row 2, column 2 of the matrix. + /// The second element of the second row. public float M22; - /// Value at row 2, column 3 of the matrix. + /// The third element of the second row. public float M23; - /// Value at row 2, column 4 of the matrix. + /// The fourth element of the second row. public float M24; - /// Value at row 3, column 1 of the matrix. + /// The first element of the third row. public float M31; - /// Value at row 3, column 2 of the matrix. + /// The second element of the third row. public float M32; - /// Value at row 3, column 3 of the matrix. + /// The third element of the third row. public float M33; - /// Value at row 3, column 4 of the matrix. + /// The fourth element of the third row. public float M34; - /// Value at row 4, column 1 of the matrix. + /// The first element of the fourth row. public float M41; - /// Value at row 4, column 2 of the matrix. + /// The second element of the fourth row. public float M42; - /// Value at row 4, column 3 of the matrix. + /// The third element of the fourth row. public float M43; - /// Value at row 4, column 4 of the matrix. + /// The fourth element of the fourth row. public float M44; - /// Constructs a Matrix4x4 from the given components. + /// Creates a 4x4 matrix from the specified components. + /// The value to assign to the first element in the first row. + /// The value to assign to the second element in the first row. + /// The value to assign to the third element in the first row. + /// The value to assign to the fourth element in the first row. + /// The value to assign to the first element in the second row. + /// The value to assign to the second element in the second row. + /// The value to assign to the third element in the second row. + /// The value to assign to the third element in the second row. + /// The value to assign to the first element in the third row. + /// The value to assign to the second element in the third row. + /// The value to assign to the third element in the third row. + /// The value to assign to the fourth element in the third row. + /// The value to assign to the first element in the fourth row. + /// The value to assign to the second element in the fourth row. + /// The value to assign to the third element in the fourth row. + /// The value to assign to the fourth element in the fourth row. public Matrix4x4(float m11, float m12, float m13, float m14, float m21, float m22, float m23, float m24, float m31, float m32, float m33, float m34, @@ -102,8 +121,9 @@ namespace System.Numerics M44 = m44; } - /// Constructs a Matrix4x4 from the given Matrix3x2. - /// The source Matrix3x2. + /// Creates a object from a specified object. + /// A 3x2 matrix. + /// This constructor creates a 4x4 matrix whose , , , , , , , and components are zero, and whose and components are one. public Matrix4x4(Matrix3x2 value) { M11 = value.M11; @@ -127,13 +147,15 @@ namespace System.Numerics M44 = 1f; } - /// Returns the multiplicative identity matrix. + /// Gets the multiplicative identity matrix. + /// Gets the multiplicative identity matrix. public static Matrix4x4 Identity { get => _identity; } - /// Returns whether the matrix is the identity matrix. + /// Indicates whether the current matrix is the identity matrix. + /// if the current matrix is the identity matrix; otherwise, . public readonly bool IsIdentity { get @@ -147,6 +169,7 @@ namespace System.Numerics } /// Gets or sets the translation component of this matrix. + /// The translation component of the current instance. public Vector3 Translation { readonly get => new Vector3(M41, M42, M43); @@ -159,10 +182,11 @@ namespace System.Numerics } } - /// Adds two matrices together. - /// The first source matrix. - /// The second source matrix. - /// The resulting matrix. + /// Adds each element in one matrix with its corresponding element in a second matrix. + /// The first matrix. + /// The second matrix. + /// The matrix that contains the summed values. + /// The method defines the operation of the addition operator for objects. public static unsafe Matrix4x4 operator +(Matrix4x4 value1, Matrix4x4 value2) { if (AdvSimd.IsSupported) @@ -204,10 +228,11 @@ namespace System.Numerics return m; } - /// Returns a boolean indicating whether the given two matrices are equal. + /// Returns a value that indicates whether the specified matrices are equal. /// The first matrix to compare. - /// The second matrix to compare. - /// True if the given matrices are equal; False otherwise. + /// The second matrix to care + /// if and are equal; otherwise, . + /// Two matrices are equal if all their corresponding elements are equal. public static unsafe bool operator ==(Matrix4x4 value1, Matrix4x4 value2) { if (AdvSimd.Arm64.IsSupported) @@ -231,10 +256,10 @@ namespace System.Numerics value1.M34 == value2.M34 && value1.M41 == value2.M41 && value1.M42 == value2.M42 && value1.M43 == value2.M43); } - /// Returns a boolean indicating whether the given two matrices are not equal. + /// Returns a value that indicates whether the specified matrices are not equal. /// The first matrix to compare. /// The second matrix to compare. - /// True if the given matrices are not equal; False if they are equal. + /// if and are not equal; otherwise, . public static unsafe bool operator !=(Matrix4x4 value1, Matrix4x4 value2) { if (AdvSimd.Arm64.IsSupported) @@ -259,10 +284,11 @@ namespace System.Numerics value1.M41 != value2.M41 || value1.M42 != value2.M42 || value1.M43 != value2.M43 || value1.M44 != value2.M44); } - /// Multiplies a matrix by another matrix. - /// The first source matrix. - /// The second source matrix. - /// The result of the multiplication. + /// Multiplies two matrices together to compute the product. + /// The first matrix. + /// The second matrix. + /// The product matrix. + /// The method defines the operation of the multiplication operator for objects. public static unsafe Matrix4x4 operator *(Matrix4x4 value1, Matrix4x4 value2) { if (AdvSimd.Arm64.IsSupported) @@ -375,10 +401,11 @@ namespace System.Numerics return m; } - /// Multiplies a matrix by a scalar value. - /// The source matrix. - /// The scaling factor. + /// Multiplies a matrix by a float to compute the product. + /// The matrix to scale. + /// The scaling value to use. /// The scaled matrix. + /// The method defines the operation of the multiplication operator for objects. public static unsafe Matrix4x4 operator *(Matrix4x4 value1, float value2) { if (AdvSimd.IsSupported) @@ -421,10 +448,11 @@ namespace System.Numerics return m; } - /// Subtracts the second matrix from the first. - /// The first source matrix. - /// The second source matrix. - /// The result of the subtraction. + /// Subtracts each element in a second matrix from its corresponding element in a first matrix. + /// The first matrix. + /// The second matrix. + /// The matrix containing the values that result from subtracting each element in from its corresponding element in . + /// The method defines the operation of the subtraction operator for objects. public static unsafe Matrix4x4 operator -(Matrix4x4 value1, Matrix4x4 value2) { if (AdvSimd.IsSupported) @@ -466,8 +494,8 @@ namespace System.Numerics return m; } - /// Returns a new matrix with the negated elements of the given matrix. - /// The source matrix. + /// Negates the specified matrix by multiplying all its values by -1. + /// The matrix to negate. /// The negated matrix. public static unsafe Matrix4x4 operator -(Matrix4x4 value) { @@ -511,10 +539,10 @@ namespace System.Numerics return m; } - /// Adds two matrices together. - /// The first source matrix. - /// The second source matrix. - /// The resulting matrix. + /// Adds each element in one matrix with its corresponding element in a second matrix. + /// The first matrix. + /// The second matrix. + /// The matrix that contains the summed values of and . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix4x4 Add(Matrix4x4 value1, Matrix4x4 value2) { @@ -522,11 +550,11 @@ namespace System.Numerics } /// Creates a spherical billboard that rotates around a specified object position. - /// Position of the object the billboard will rotate around. - /// Position of the camera. + /// The position of the object that the billboard will rotate around. + /// The position of the camera. /// The up vector of the camera. /// The forward vector of the camera. - /// The created billboard matrix + /// The created billboard. public static Matrix4x4 CreateBillboard(Vector3 objectPosition, Vector3 cameraPosition, Vector3 cameraUpVector, Vector3 cameraForwardVector) { Vector3 zaxis = objectPosition - cameraPosition; @@ -570,12 +598,12 @@ namespace System.Numerics } /// Creates a cylindrical billboard that rotates around a specified axis. - /// Position of the object the billboard will rotate around. - /// Position of the camera. - /// Axis to rotate the billboard around. - /// Forward vector of the camera. - /// Forward vector of the object. - /// The created billboard matrix. + /// The position of the object that the billboard will rotate around. + /// The position of the camera. + /// The axis to rotate the billboard around. + /// The forward vector of the camera. + /// The forward vector of the object. + /// The billboard matrix. public static Matrix4x4 CreateConstrainedBillboard(Vector3 objectPosition, Vector3 cameraPosition, Vector3 rotateAxis, Vector3 cameraForwardVector, Vector3 objectForwardVector) { // Treat the case when object and camera positions are too close. @@ -646,7 +674,7 @@ namespace System.Numerics /// Creates a matrix that rotates around an arbitrary vector. /// The axis to rotate around. - /// The angle to rotate around the given axis, in radians. + /// The angle to rotate around , in radians. /// The rotation matrix. public static Matrix4x4 CreateFromAxisAngle(Vector3 axis, float angle) { @@ -697,7 +725,7 @@ namespace System.Numerics return result; } - /// Creates a rotation matrix from the given Quaternion rotation value. + /// Creates a rotation matrix from the specified Quaternion rotation value. /// The source Quaternion. /// The rotation matrix. public static Matrix4x4 CreateFromQuaternion(Quaternion quaternion) @@ -731,9 +759,9 @@ namespace System.Numerics } /// Creates a rotation matrix from the specified yaw, pitch, and roll. - /// Angle of rotation, in radians, around the Y-axis. - /// Angle of rotation, in radians, around the X-axis. - /// Angle of rotation, in radians, around the Z-axis. + /// The angle of rotation, in radians, around the Y axis. + /// The angle of rotation, in radians, around the X axis. + /// The angle of rotation, in radians, around the Z axis. /// The rotation matrix. public static Matrix4x4 CreateFromYawPitchRoll(float yaw, float pitch, float roll) { @@ -774,10 +802,10 @@ namespace System.Numerics } /// Creates an orthographic perspective matrix from the given view volume dimensions. - /// Width of the view volume. - /// Height of the view volume. - /// Minimum Z-value of the view volume. - /// Maximum Z-value of the view volume. + /// The width of the view volume. + /// The height of the view volume. + /// The minimum Z-value of the view volume. + /// The maximum Z-value of the view volume. /// The orthographic projection matrix. public static Matrix4x4 CreateOrthographic(float width, float height, float zNearPlane, float zFarPlane) { @@ -791,13 +819,13 @@ namespace System.Numerics return result; } - /// Builds a customized, orthographic projection matrix. - /// Minimum X-value of the view volume. - /// Maximum X-value of the view volume. - /// Minimum Y-value of the view volume. - /// Maximum Y-value of the view volume. - /// Minimum Z-value of the view volume. - /// Maximum Z-value of the view volume. + /// Creates a customized orthographic projection matrix. + /// The minimum X-value of the view volume. + /// The maximum X-value of the view volume. + /// The minimum Y-value of the view volume. + /// The maximum Y-value of the view volume. + /// The minimum Z-value of the view volume. + /// The maximum Z-value of the view volume. /// The orthographic projection matrix. public static Matrix4x4 CreateOrthographicOffCenter(float left, float right, float bottom, float top, float zNearPlane, float zFarPlane) { @@ -817,11 +845,16 @@ namespace System.Numerics } /// Creates a perspective projection matrix from the given view volume dimensions. - /// Width of the view volume at the near view plane. - /// Height of the view volume at the near view plane. - /// Distance to the near view plane. - /// Distance to the far view plane. + /// The width of the view volume at the near view plane. + /// The height of the view volume at the near view plane. + /// The distance to the near view plane. + /// The distance to the far view plane. /// The perspective projection matrix. + /// is less than or equal to zero. + /// -or- + /// is less than or equal to zero. + /// -or- + /// is greater than or equal to . public static Matrix4x4 CreatePerspective(float width, float height, float nearPlaneDistance, float farPlaneDistance) { if (nearPlaneDistance <= 0.0f) @@ -853,11 +886,19 @@ namespace System.Numerics } /// Creates a perspective projection matrix based on a field of view, aspect ratio, and near and far view plane distances. - /// Field of view in the y direction, in radians. - /// Aspect ratio, defined as view space width divided by height. - /// Distance to the near view plane. - /// Distance to the far view plane. + /// The field of view in the y direction, in radians. + /// The aspect ratio, defined as view space width divided by height. + /// The distance to the near view plane. + /// The distance to the far view plane. /// The perspective projection matrix. + /// is less than or equal to zero. + /// -or- + /// is greater than or equal to . + /// is less than or equal to zero. + /// -or- + /// is less than or equal to zero. + /// -or- + /// is greater than or equal to . public static Matrix4x4 CreatePerspectiveFieldOfView(float fieldOfView, float aspectRatio, float nearPlaneDistance, float farPlaneDistance) { if (fieldOfView <= 0.0f || fieldOfView >= MathF.PI) @@ -894,14 +935,19 @@ namespace System.Numerics return result; } - /// Creates a customized, perspective projection matrix. - /// Minimum x-value of the view volume at the near view plane. - /// Maximum x-value of the view volume at the near view plane. - /// Minimum y-value of the view volume at the near view plane. - /// Maximum y-value of the view volume at the near view plane. - /// Distance to the near view plane. - /// Distance to of the far view plane. + /// Creates a customized perspective projection matrix. + /// The minimum x-value of the view volume at the near view plane. + /// The maximum x-value of the view volume at the near view plane. + /// The minimum y-value of the view volume at the near view plane. + /// The maximum y-value of the view volume at the near view plane. + /// The distance to the near view plane. + /// The distance to the far view plane. /// The perspective projection matrix. + /// is less than or equal to zero. + /// -or- + /// is less than or equal to zero. + /// -or- + /// is greater than or equal to . public static Matrix4x4 CreatePerspectiveOffCenter(float left, float right, float bottom, float top, float nearPlaneDistance, float farPlaneDistance) { if (nearPlaneDistance <= 0.0f) @@ -933,8 +979,8 @@ namespace System.Numerics return result; } - /// Creates a Matrix that reflects the coordinate system about a specified Plane. - /// The Plane about which to create a reflection. + /// Creates a matrix that reflects the coordinate system about a specified plane. + /// The plane about which to create a reflection. /// A new matrix expressing the reflection. public static Matrix4x4 CreateReflection(Plane value) { @@ -969,8 +1015,8 @@ namespace System.Numerics return result; } - /// Creates a matrix for rotating points around the X-axis. - /// The amount, in radians, by which to rotate around the X-axis. + /// Creates a matrix for rotating points around the X axis. + /// The amount, in radians, by which to rotate around the X axis. /// The rotation matrix. public static Matrix4x4 CreateRotationX(float radians) { @@ -992,8 +1038,8 @@ namespace System.Numerics return result; } - /// Creates a matrix for rotating points around the X-axis, from a center point. - /// The amount, in radians, by which to rotate around the X-axis. + /// Creates a matrix for rotating points around the X axis from a center point. + /// The amount, in radians, by which to rotate around the X axis. /// The center point. /// The rotation matrix. public static Matrix4x4 CreateRotationX(float radians, Vector3 centerPoint) @@ -1021,7 +1067,7 @@ namespace System.Numerics return result; } - /// Creates a matrix for rotating points around the Y-axis. + /// Creates a matrix for rotating points around the Y axis. /// The amount, in radians, by which to rotate around the Y-axis. /// The rotation matrix. public static Matrix4x4 CreateRotationY(float radians) @@ -1043,7 +1089,7 @@ namespace System.Numerics return result; } - /// Creates a matrix for rotating points around the Y-axis, from a center point. + /// The amount, in radians, by which to rotate around the Y axis from a center point. /// The amount, in radians, by which to rotate around the Y-axis. /// The center point. /// The rotation matrix. @@ -1071,7 +1117,7 @@ namespace System.Numerics return result; } - /// Creates a matrix for rotating points around the Z-axis. + /// Creates a matrix for rotating points around the Z axis. /// The amount, in radians, by which to rotate around the Z-axis. /// The rotation matrix. public static Matrix4x4 CreateRotationZ(float radians) @@ -1093,7 +1139,7 @@ namespace System.Numerics return result; } - /// Creates a matrix for rotating points around the Z-axis, from a center point. + /// Creates a matrix for rotating points around the Z axis from a center point. /// The amount, in radians, by which to rotate around the Z-axis. /// The center point. /// The rotation matrix. @@ -1121,10 +1167,10 @@ namespace System.Numerics return result; } - /// Creates a scaling matrix. - /// Value to scale by on the X-axis. - /// Value to scale by on the Y-axis. - /// Value to scale by on the Z-axis. + /// Creates a scaling matrix from the specified X, Y, and Z components. + /// The value to scale by on the X axis. + /// The value to scale by on the Y axis. + /// The value to scale by on the Z axis. /// The scaling matrix. public static Matrix4x4 CreateScale(float xScale, float yScale, float zScale) { @@ -1135,10 +1181,10 @@ namespace System.Numerics return result; } - /// Creates a scaling matrix with a center point. - /// Value to scale by on the X-axis. - /// Value to scale by on the Y-axis. - /// Value to scale by on the Z-axis. + /// Creates a scaling matrix that is offset by a given center point. + /// The value to scale by on the X axis. + /// The value to scale by on the Y axis. + /// The value to scale by on the Z axis. /// The center point. /// The scaling matrix. public static Matrix4x4 CreateScale(float xScale, float yScale, float zScale, Vector3 centerPoint) @@ -1158,8 +1204,8 @@ namespace System.Numerics return result; } - /// Creates a scaling matrix. - /// The vector containing the amount to scale by on each axis. + /// Creates a scaling matrix from the specified vector scale. + /// The scale to use. /// The scaling matrix. public static Matrix4x4 CreateScale(Vector3 scales) { @@ -1171,7 +1217,7 @@ namespace System.Numerics } /// Creates a scaling matrix with a center point. - /// The vector containing the amount to scale by on each axis. + /// The vector that contains the amount to scale on each axis. /// The center point. /// The scaling matrix. public static Matrix4x4 CreateScale(Vector3 scales, Vector3 centerPoint) @@ -1191,7 +1237,7 @@ namespace System.Numerics return result; } - /// Creates a uniform scaling matrix that scales equally on each axis. + /// Creates a uniform scaling matrix that scale equally on each axis. /// The uniform scaling factor. /// The scaling matrix. public static Matrix4x4 CreateScale(float scale) @@ -1228,10 +1274,10 @@ namespace System.Numerics return result; } - /// Creates a Matrix that flattens geometry into a specified Plane as if casting a shadow from a specified light source. + /// Creates a matrix that flattens geometry into a specified plane as if casting a shadow from a specified light source. /// The direction from which the light that will cast the shadow is coming. - /// The Plane onto which the new matrix should flatten geometry so as to cast a shadow. - /// A new Matrix that can be used to flatten geometry onto the specified plane from the specified direction. + /// The plane onto which the new matrix should flatten geometry so as to cast a shadow. + /// A new matrix that can be used to flatten geometry onto the specified plane from the specified direction. public static Matrix4x4 CreateShadow(Vector3 lightDirection, Plane plane) { Plane p = Plane.Normalize(plane); @@ -1264,7 +1310,7 @@ namespace System.Numerics return result; } - /// Creates a translation matrix. + /// Creates a translation matrix from the specified 3-dimensional vector. /// The amount to translate in each axis. /// The translation matrix. public static Matrix4x4 CreateTranslation(Vector3 position) @@ -1276,10 +1322,10 @@ namespace System.Numerics return result; } - /// Creates a translation matrix. - /// The amount to translate on the X-axis. - /// The amount to translate on the Y-axis. - /// The amount to translate on the Z-axis. + /// Creates a translation matrix from the specified X, Y, and Z components. + /// The amount to translate on the X axis. + /// The amount to translate on the Y axis. + /// The amount to translate on the Z axis. /// The translation matrix. public static Matrix4x4 CreateTranslation(float xPosition, float yPosition, float zPosition) { @@ -1291,10 +1337,11 @@ namespace System.Numerics } /// Creates a world matrix with the specified parameters. - /// The position of the object; used in translation operations. - /// Forward direction of the object. - /// Upward direction of the object; usually [0, 1, 0]. + /// The position of the object. + /// The forward direction of the object. + /// The upward direction of the object. Its value is usually [0, 1, 0]. /// The world matrix. + /// is used in translation operations. public static Matrix4x4 CreateWorld(Vector3 position, Vector3 forward, Vector3 up) { Vector3 zaxis = Vector3.Normalize(-forward); @@ -1322,11 +1369,10 @@ namespace System.Numerics return result; } - /// Attempts to calculate the inverse of the given matrix. If successful, result will contain the inverted matrix. - /// The source matrix to invert. - /// If successful, contains the inverted matrix. - /// True if the source matrix could be inverted; False otherwise. - /// + /// Tries to invert the specified matrix. The return value indicates whether the operation succeeded. + /// The matrix to invert. + /// When this method returns, contains the inverted matrix if the operation succeeded. + /// if was converted successfully; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static unsafe bool Invert(Matrix4x4 matrix, out Matrix4x4 result) { @@ -1669,19 +1715,19 @@ namespace System.Numerics } } - /// Multiplies a matrix by another matrix. - /// The first source matrix. - /// The second source matrix. - /// The result of the multiplication. + /// Multiplies two matrices together to compute the product. + /// The first matrix. + /// The second matrix. + /// The product matrix. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix4x4 Multiply(Matrix4x4 value1, Matrix4x4 value2) { return value1 * value2; } - /// Multiplies a matrix by a scalar value. - /// The source matrix. - /// The scaling factor. + /// Multiplies a matrix by a float to compute the product. + /// The matrix to scale. + /// The scaling value to use. /// The scaled matrix. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix4x4 Multiply(Matrix4x4 value1, float value2) @@ -1689,8 +1735,8 @@ namespace System.Numerics return value1 * value2; } - /// Returns a new matrix with the negated elements of the given matrix. - /// The source matrix. + /// Negates the specified matrix by multiplying all its values by -1. + /// The matrix to negate. /// The negated matrix. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix4x4 Negate(Matrix4x4 value) @@ -1698,10 +1744,10 @@ namespace System.Numerics return -value; } - /// Subtracts the second matrix from the first. - /// The first source matrix. - /// The second source matrix. - /// The result of the subtraction. + /// Subtracts each element in a second matrix from its corresponding element in a first matrix. + /// The first matrix. + /// The second matrix. + /// The matrix containing the values that result from subtracting each element in from its corresponding element in . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Matrix4x4 Subtract(Matrix4x4 value1, Matrix4x4 value2) { @@ -1726,13 +1772,12 @@ namespace System.Numerics } } - /// Attempts to extract the scale, translation, and rotation components from the given scale/rotation/translation matrix. - /// If successful, the out parameters will contained the extracted values. + /// Attempts to extract the scale, translation, and rotation components from the given scale, rotation, or translation matrix. The return value indicates whether the operation succeeded. /// The source matrix. - /// The scaling component of the transformation matrix. - /// The rotation component of the transformation matrix. - /// The translation component of the transformation matrix - /// True if the source matrix was successfully decomposed; False otherwise. + /// When this method returns, contains the scaling component of the transformation matrix if the operation succeeded. + /// When this method returns, contains the rotation component of the transformation matrix if the operation succeeded. + /// When the method returns, contains the translation component of the transformation matrix if the operation succeeded. + /// if was decomposed successfully; otherwise, . public static bool Decompose(Matrix4x4 matrix, out Vector3 scale, out Quaternion rotation, out Vector3 translation) { bool result = true; @@ -1924,10 +1969,10 @@ namespace System.Numerics return result; } - /// Linearly interpolates between the corresponding values of two matrices. - /// The first source matrix. - /// The second source matrix. - /// The relative weight of the second source matrix. + /// Performs a linear interpolation from one matrix to a second matrix based on a value that specifies the weighting of the second matrix. + /// The first matrix. + /// The second matrix. + /// The relative weighting of . /// The interpolated matrix. public static unsafe Matrix4x4 Lerp(Matrix4x4 matrix1, Matrix4x4 matrix2, float amount) { @@ -1979,9 +2024,9 @@ namespace System.Numerics return result; } - /// Transforms the given matrix by applying the given Quaternion rotation. - /// The source matrix to transform. - /// The rotation to apply. + /// Transforms the specified matrix by applying the specified Quaternion rotation. + /// The matrix to transform. + /// The rotation t apply. /// The transformed matrix. public static Matrix4x4 Transform(Matrix4x4 value, Quaternion rotation) { @@ -2042,7 +2087,7 @@ namespace System.Numerics } /// Transposes the rows and columns of a matrix. - /// The source matrix. + /// The matrix to transpose. /// The transposed matrix. public static unsafe Matrix4x4 Transpose(Matrix4x4 matrix) { @@ -2112,25 +2157,26 @@ namespace System.Numerics return result; } - /// Returns a boolean indicating whether the given Object is equal to this matrix instance. - /// The Object to compare against. - /// True if the Object is equal to this matrix; False otherwise. + /// Returns a value that indicates whether this instance and a specified object are equal. + /// The object to compare with the current instance. + /// if the current instance and are equal; otherwise, . If is , the method returns . + /// The current instance and are equal if is a object and the corresponding elements of each matrix are equal. [MethodImpl(MethodImplOptions.AggressiveInlining)] public override readonly bool Equals([NotNullWhen(true)] object? obj) { return (obj is Matrix4x4 other) && Equals(other); } - /// Returns a boolean indicating whether this matrix instance is equal to the other given matrix. - /// The matrix to compare this instance to. - /// True if the matrices are equal; False otherwise. + /// Returns a value that indicates whether this instance and another 4x4 matrix are equal. + /// The other matrix. + /// if the two matrices are equal; otherwise, . public readonly bool Equals(Matrix4x4 other) { return this == other; } - /// Calculates the determinant of the matrix. - /// The determinant of the matrix. + /// Calculates the determinant of the current 4x4 matrix. + /// The determinant. public readonly float GetDeterminant() { // | a b c d | | f g h | | e g h | | e f h | | e f g | @@ -2207,8 +2253,9 @@ namespace System.Numerics return hash.ToHashCode(); } - /// Returns a String representing this matrix instance. - /// The string representation. + /// Returns a string that represents this matrix. + /// The string representation of this matrix. + /// The numeric values in the returned string are formatted by using the conventions of the current culture. For example, for the en-US culture, the returned string might appear as { {M11:1.1 M12:1.2 M13:1.3 M14:1.4} {M21:2.1 M22:2.2 M23:2.3 M24:2.4} {M31:3.1 M32:3.2 M33:3.3 M34:3.4} {M41:4.1 M42:4.2 M43:4.3 M44:4.4} }. public override readonly string ToString() { return string.Format(CultureInfo.CurrentCulture, "{{ {{M11:{0} M12:{1} M13:{2} M14:{3}}} {{M21:{4} M22:{5} M23:{6} M24:{7}}} {{M31:{8} M32:{9} M33:{10} M34:{11}}} {{M41:{12} M42:{13} M43:{14} M44:{15}}} }}", diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/Plane.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/Plane.cs index 984be6d..fa792ee 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Numerics/Plane.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/Plane.cs @@ -7,52 +7,54 @@ using System.Runtime.CompilerServices; namespace System.Numerics { - /// A structure encapsulating a 3D Plane + /// Represents a plane in three-dimensional space. + /// [Intrinsic] public struct Plane : IEquatable { private const float NormalizeEpsilon = 1.192092896e-07f; // smallest such that 1.0+NormalizeEpsilon != 1.0 - /// The normal vector of the Plane. + /// The normal vector of the plane. public Vector3 Normal; - /// The distance of the Plane along its normal from the origin. + /// The distance of the plane along its normal from the origin. public float D; - /// Constructs a Plane from the X, Y, and Z components of its normal, and its distance from the origin on that normal. - /// The X-component of the normal. - /// The Y-component of the normal. - /// The Z-component of the normal. - /// The distance of the Plane along its normal from the origin. + /// Creates a object from the X, Y, and Z components of its normal, and its distance from the origin on that normal. + /// The X component of the normal. + /// The Y component of the normal. + /// The Z component of the normal. + /// The distance of the plane along its normal from the origin. public Plane(float x, float y, float z, float d) { Normal = new Vector3(x, y, z); D = d; } - /// Constructs a Plane from the given normal and distance along the normal from the origin. - /// The Plane's normal vector. - /// The Plane's distance from the origin along its normal vector. + /// Creates a object from a specified normal and the distance along the normal from the origin. + /// The plane's normal vector. + /// The plane's distance from the origin along its normal vector. public Plane(Vector3 normal, float d) { Normal = normal; D = d; } - /// Constructs a Plane from the given Vector4. - /// A vector whose first 3 elements describe the normal vector, - /// and whose W component defines the distance along that normal from the origin. + /// Creates a object from a specified four-dimensional vector. + /// A vector whose first three elements describe the normal vector, and whose defines the distance along that normal from the origin. public Plane(Vector4 value) { Normal = new Vector3(value.X, value.Y, value.Z); D = value.W; } - /// Creates a Plane that contains the three given points. - /// The first point defining the Plane. - /// The second point defining the Plane. - /// The third point defining the Plane. - /// The Plane containing the three points. + /// Creates a object that contains three specified points. + /// The first point defining the plane. + /// The second point defining the plane. + /// The third point defining the plane. + /// The plane containing the three points. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Plane CreateFromVertices(Vector3 point1, Vector3 point2, Vector3 point3) { @@ -100,9 +102,9 @@ namespace System.Numerics } } - /// Calculates the dot product of a Plane and Vector4. - /// The Plane. - /// The Vector4. + /// Calculates the dot product of a plane and a 4-dimensional vector. + /// The plane. + /// The four-dimensional vector. /// The dot product. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static float Dot(Plane plane, Vector4 value) @@ -113,10 +115,10 @@ namespace System.Numerics plane.D * value.W; } - /// Returns the dot product of a specified Vector3 and the normal vector of this Plane plus the distance (D) value of the Plane. + /// Returns the dot product of a specified three-dimensional vector and the normal vector of this plane plus the distance () value of the plane. /// The plane. - /// The Vector3. - /// The resulting value. + /// The 3-dimensional vector. + /// The dot product. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static float DotCoordinate(Plane plane, Vector3 value) { @@ -133,10 +135,10 @@ namespace System.Numerics } } - /// Returns the dot product of a specified Vector3 and the Normal vector of this Plane. + /// Returns the dot product of a specified three-dimensional vector and the vector of this plane. /// The plane. - /// The Vector3. - /// The resulting dot product. + /// The three-dimensional vector. + /// The dot product. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static float DotNormal(Plane plane, Vector3 value) { @@ -152,9 +154,9 @@ namespace System.Numerics } } - /// Creates a new Plane whose normal vector is the source Plane's normal vector normalized. - /// The source Plane. - /// The normalized Plane. + /// Creates a new object whose normal vector is the source plane's normal vector normalized. + /// The source plane. + /// The normalized plane. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Plane Normalize(Plane value) { @@ -190,11 +192,11 @@ namespace System.Numerics } } - /// Transforms a normalized Plane by a Matrix. - /// The normalized Plane to transform. - /// This Plane must already be normalized, so that its Normal vector is of unit length, before this method is called. - /// The transformation matrix to apply to the Plane. - /// The transformed Plane. + /// Transforms a normalized plane by a 4x4 matrix. + /// The normalized plane to transform. + /// The transformation matrix to apply to . + /// The transformed plane. + /// must already be normalized so that its vector is of unit length before this method is called. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Plane Transform(Plane plane, Matrix4x4 matrix) { @@ -209,11 +211,11 @@ namespace System.Numerics x * m.M41 + y * m.M42 + z * m.M43 + w * m.M44); } - /// Transforms a normalized Plane by a Quaternion rotation. - /// The normalized Plane to transform. - /// This Plane must already be normalized, so that its Normal vector is of unit length, before this method is called. - /// The Quaternion rotation to apply to the Plane. - /// A new Plane that results from applying the rotation. + /// Transforms a normalized plane by a Quaternion rotation. + /// The normalized plane to transform. + /// The Quaternion rotation to apply to the plane. + /// A new plane that results from applying the Quaternion rotation. + /// must already be normalized so that its vector is of unit length before this method is called. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Plane Transform(Plane plane, Quaternion rotation) { @@ -253,10 +255,12 @@ namespace System.Numerics plane.D); } - /// Returns a boolean indicating whether the two given Planes are equal. - /// The first Plane to compare. - /// The second Plane to compare. - /// True if the Planes are equal; False otherwise. + /// Returns a value that indicates whether two planes are equal. + /// The first plane to compare. + /// The second plane to compare. + /// if and are equal; otherwise, . + /// Two objects are equal if their and fields are equal. + /// The method defines the operation of the equality operator for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool operator ==(Plane value1, Plane value2) { @@ -266,28 +270,31 @@ namespace System.Numerics value1.D == value2.D); } - /// Returns a boolean indicating whether the two given Planes are not equal. - /// The first Plane to compare. - /// The second Plane to compare. - /// True if the Planes are not equal; False if they are equal. + /// Returns a value that indicates whether two planes are not equal. + /// The first plane to compare. + /// The second plane to compare. + /// if and are not equal; otherwise, . + /// The method defines the operation of the inequality operator for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool operator !=(Plane value1, Plane value2) { return !(value1 == value2); } - /// Returns a boolean indicating whether the given Object is equal to this Plane instance. - /// The Object to compare against. - /// True if the Object is equal to this Plane; False otherwise. + /// Returns a value that indicates whether this instance and a specified object are equal. + /// The object to compare with the current instance. + /// if the current instance and are equal; otherwise, . If is , the method returns . + /// The current instance and are equal if is a object and their and fields are equal. [MethodImpl(MethodImplOptions.AggressiveInlining)] public override readonly bool Equals([NotNullWhen(true)] object? obj) { return (obj is Plane other) && Equals(other); } - /// Returns a boolean indicating whether the given Plane is equal to this Plane instance. - /// The Plane to compare this instance to. - /// True if the other Plane is equal to this instance; False otherwise. + /// Returns a value that indicates whether this instance and another plane object are equal. + /// The other plane. + /// if the two planes are equal; otherwise, . + /// Two objects are equal if their and fields are equal. [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly bool Equals(Plane other) { @@ -311,8 +318,9 @@ namespace System.Numerics return Normal.GetHashCode() + D.GetHashCode(); } - /// Returns a String representing this Plane instance. - /// The string representation. + /// Returns the string representation of this plane object. + /// A string that represents this object. + /// The string representation of a object use the formatting conventions of the current culture to format the numeric values in the returned string. For example, a object whose string representation is formatted by using the conventions of the en-US culture might appear as {Normal:<1.1, 2.2, 3.3> D:4.4}. public override readonly string ToString() { CultureInfo ci = CultureInfo.CurrentCulture; diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/Quaternion.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/Quaternion.cs index 042ef0d..8a8d431 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Numerics/Quaternion.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/Quaternion.cs @@ -8,28 +8,30 @@ using System.Runtime.CompilerServices; namespace System.Numerics { /// Represents a vector that is used to encode three-dimensional physical rotations. + /// The structure is used to efficiently rotate an object about the (x,y,z) vector by the angle theta, where: + /// w = cos(theta/2) [Intrinsic] public struct Quaternion : IEquatable { private const float SlerpEpsilon = 1e-6f; - /// Specifies the X-value of the vector component of the Quaternion. + /// The X value of the vector component of the quaternion. public float X; - /// Specifies the Y-value of the vector component of the Quaternion. + /// The Y value of the vector component of the quaternion. public float Y; - /// Specifies the Z-value of the vector component of the Quaternion. + /// The Z value of the vector component of the quaternion. public float Z; - /// Specifies the rotation component of the Quaternion. + /// The rotation component of the quaternion. public float W; - /// Constructs a Quaternion from the given components. - /// The X component of the Quaternion. - /// The Y component of the Quaternion. - /// The Z component of the Quaternion. - /// The W component of the Quaternion. + /// Constructs a quaternion from the specified components. + /// The value to assign to the X component of the quaternion. + /// The value to assign to the Y component of the quaternion. + /// The value to assign to the Z component of the quaternion. + /// The value to assign to the W component of the quaternion. public Quaternion(float x, float y, float z, float w) { X = x; @@ -38,9 +40,9 @@ namespace System.Numerics W = w; } - /// Constructs a Quaternion from the given vector and rotation parts. - /// The vector part of the Quaternion. - /// The rotation part of the Quaternion. + /// Creates a quaternion from the specified vector and rotation parts. + /// The vector part of the quaternion. + /// The rotation part of the quaternion. public Quaternion(Vector3 vectorPart, float scalarPart) { X = vectorPart.X; @@ -49,22 +51,26 @@ namespace System.Numerics W = scalarPart; } - /// Returns a Quaternion representing no rotation. + /// Gets a quaternion that represents no rotation. + /// A quaternion whose values are (0, 0, 0, 1). public static Quaternion Identity { get => new Quaternion(0, 0, 0, 1); } - /// Returns whether the Quaternion is the identity Quaternion. + /// Gets a value that indicates whether the current instance is the identity quaternion. + /// if the current instance is the identity quaternion; otherwise, . + /// public readonly bool IsIdentity { get => this == Identity; } - /// Adds two Quaternions element-by-element. - /// The first source Quaternion. - /// The second source Quaternion. - /// The result of adding the Quaternions. + /// Adds each element in one quaternion with its corresponding element in a second quaternion. + /// The first quaternion. + /// The second quaternion. + /// The quaternion that contains the summed values of and . + /// The method defines the operation of the addition operator for objects. public static Quaternion operator +(Quaternion value1, Quaternion value2) { Quaternion ans; @@ -77,10 +83,11 @@ namespace System.Numerics return ans; } - /// Divides a Quaternion by another Quaternion. - /// The source Quaternion. + /// Divides one quaternion by a second quaternion. + /// The dividend. /// The divisor. - /// The result of the division. + /// The quaternion that results from dividing by . + /// The method defines the division operation for objects. public static Quaternion operator /(Quaternion value1, Quaternion value2) { Quaternion ans; @@ -119,10 +126,12 @@ namespace System.Numerics return ans; } - /// Returns a boolean indicating whether the two given Quaternions are equal. - /// The first Quaternion to compare. - /// The second Quaternion to compare. - /// True if the Quaternions are equal; False otherwise. + /// Returns a value that indicates whether two quaternions are equal. + /// The first quaternion to compare. + /// The second quaternion to compare. + /// if the two quaternions are equal; otherwise, . + /// Two quaternions are equal if each of their corresponding components is equal. + /// The method defines the operation of the equality operator for objects. public static bool operator ==(Quaternion value1, Quaternion value2) { return (value1.X == value2.X) @@ -131,19 +140,20 @@ namespace System.Numerics && (value1.W == value2.W); } - /// Returns a boolean indicating whether the two given Quaternions are not equal. - /// The first Quaternion to compare. - /// The second Quaternion to compare. - /// True if the Quaternions are not equal; False if they are equal. + /// Returns a value that indicates whether two quaternions are not equal. + /// The first quaternion to compare. + /// The second quaternion to compare. + /// if and are not equal; otherwise, . public static bool operator !=(Quaternion value1, Quaternion value2) { return !(value1 == value2); } - /// Multiplies two Quaternions together. - /// The Quaternion on the left side of the multiplication. - /// The Quaternion on the right side of the multiplication. - /// The result of the multiplication. + /// Returns the quaternion that results from multiplying two quaternions together. + /// The first quaternion. + /// The second quaternion. + /// The product quaternion. + /// The method defines the operation of the multiplication operator for objects. public static Quaternion operator *(Quaternion value1, Quaternion value2) { Quaternion ans; @@ -173,10 +183,11 @@ namespace System.Numerics return ans; } - /// Multiplies a Quaternion by a scalar value. - /// The source Quaternion. + /// Returns the quaternion that results from scaling all the components of a specified quaternion by a scalar factor. + /// The source quaternion. /// The scalar value. - /// The result of the multiplication. + /// The scaled quaternion. + /// The method defines the operation of the multiplication operator for objects. public static Quaternion operator *(Quaternion value1, float value2) { Quaternion ans; @@ -189,10 +200,11 @@ namespace System.Numerics return ans; } - /// Subtracts one Quaternion from another. - /// The first source Quaternion. - /// The second Quaternion, to be subtracted from the first. - /// The result of the subtraction. + /// Subtracts each element in a second quaternion from its corresponding element in a first quaternion. + /// The first quaternion. + /// The second quaternion. + /// The quaternion containing the values that result from subtracting each element in from its corresponding element in . + /// The method defines the operation of the subtraction operator for objects. public static Quaternion operator -(Quaternion value1, Quaternion value2) { Quaternion ans; @@ -205,9 +217,10 @@ namespace System.Numerics return ans; } - /// Flips the sign of each component of the quaternion. - /// The source Quaternion. - /// The negated Quaternion. + /// Reverses the sign of each component of the quaternion. + /// The quaternion to negate. + /// The negated quaternion. + /// The method defines the operation of the unary negation operator for objects. public static Quaternion operator -(Quaternion value) { Quaternion ans; @@ -220,20 +233,20 @@ namespace System.Numerics return ans; } - /// Adds two Quaternions element-by-element. - /// The first source Quaternion. - /// The second source Quaternion. - /// The result of adding the Quaternions. + /// Adds each element in one quaternion with its corresponding element in a second quaternion. + /// The first quaternion. + /// The second quaternion. + /// The quaternion that contains the summed values of and . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Quaternion Add(Quaternion value1, Quaternion value2) { return value1 + value2; } - /// Concatenates two Quaternions; the result represents the value1 rotation followed by the value2 rotation. - /// The first Quaternion rotation in the series. - /// The second Quaternion rotation in the series. - /// A new Quaternion representing the concatenation of the value1 rotation followed by the value2 rotation. + /// Concatenates two quaternions. + /// The first quaternion rotation in the series. + /// The second quaternion rotation in the series. + /// A new quaternion representing the concatenation of the rotation followed by the rotation. public static Quaternion Concatenate(Quaternion value1, Quaternion value2) { Quaternion ans; @@ -265,9 +278,9 @@ namespace System.Numerics return ans; } - /// Creates the conjugate of a specified Quaternion. - /// The Quaternion of which to return the conjugate. - /// A new Quaternion that is the conjugate of the specified one. + /// Returns the conjugate of a specified quaternion. + /// The quaternion. + /// A new quaternion that is the conjugate of . public static Quaternion Conjugate(Quaternion value) { Quaternion ans; @@ -280,11 +293,11 @@ namespace System.Numerics return ans; } - /// Creates a Quaternion from a normalized vector axis and an angle to rotate about the vector. - /// The unit vector to rotate around. - /// This vector must be normalized before calling this function or the resulting Quaternion will be incorrect. + /// Creates a quaternion from a unit vector and an angle to rotate around the vector. + /// The unit vector to rotate around. /// The angle, in radians, to rotate around the vector. - /// The created Quaternion. + /// The newly created quaternion. + /// vector must be normalized before calling this method or the resulting will be incorrect. public static Quaternion CreateFromAxisAngle(Vector3 axis, float angle) { Quaternion ans; @@ -301,9 +314,9 @@ namespace System.Numerics return ans; } - /// Creates a Quaternion from the given rotation matrix. + /// Creates a quaternion from the specified rotation matrix. /// The rotation matrix. - /// The created Quaternion. + /// The newly created quaternion. public static Quaternion CreateFromRotationMatrix(Matrix4x4 matrix) { float trace = matrix.M11 + matrix.M22 + matrix.M33; @@ -353,11 +366,11 @@ namespace System.Numerics return q; } - /// Creates a new Quaternion from the given yaw, pitch, and roll, in radians. - /// The yaw angle, in radians, around the Y-axis. - /// The pitch angle, in radians, around the X-axis. - /// The roll angle, in radians, around the Z-axis. - /// + /// Creates a new quaternion from the given yaw, pitch, and roll. + /// The yaw angle, in radians, around the Y axis. + /// The pitch angle, in radians, around the X axis. + /// The roll angle, in radians, around the Z axis. + /// The resulting quaternion. public static Quaternion CreateFromYawPitchRoll(float yaw, float pitch, float roll) { // Roll first, about axis the object is facing, then @@ -386,20 +399,20 @@ namespace System.Numerics return result; } - /// Divides a Quaternion by another Quaternion. - /// The source Quaternion. + /// Divides one quaternion by a second quaternion. + /// The dividend. /// The divisor. - /// The result of the division. + /// The quaternion that results from dividing by . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Quaternion Divide(Quaternion value1, Quaternion value2) { return value1 / value2; } - /// Calculates the dot product of two Quaternions. - /// The first source Quaternion. - /// The second source Quaternion. - /// The dot product of the Quaternions. + /// Calculates the dot product of two quaternions. + /// The first quaternion. + /// The second quaternion. + /// The dot product. public static float Dot(Quaternion quaternion1, Quaternion quaternion2) { return quaternion1.X * quaternion2.X + @@ -408,9 +421,9 @@ namespace System.Numerics quaternion1.W * quaternion2.W; } - /// Returns the inverse of a Quaternion. - /// The source Quaternion. - /// The inverted Quaternion. + /// Returns the inverse of a quaternion. + /// The quaternion. + /// The inverted quaternion. public static Quaternion Inverse(Quaternion value) { // -1 ( a -v ) @@ -430,11 +443,11 @@ namespace System.Numerics return ans; } - /// Linearly interpolates between two quaternions. - /// The first source Quaternion. - /// The second source Quaternion. - /// The relative weight of the second source Quaternion in the interpolation. - /// The interpolated Quaternion. + /// Performs a linear interpolation between two quaternions based on a value that specifies the weighting of the second quaternion. + /// The first quaternion. + /// The second quaternion. + /// The relative weight of in the interpolation. + /// The interpolated quaternion. public static Quaternion Lerp(Quaternion quaternion1, Quaternion quaternion2, float amount) { float t = amount; @@ -472,38 +485,38 @@ namespace System.Numerics return r; } - /// Multiplies two Quaternions together. - /// The Quaternion on the left side of the multiplication. - /// The Quaternion on the right side of the multiplication. - /// The result of the multiplication. + /// Returns the quaternion that results from multiplying two quaternions together. + /// The first quaternion. + /// The second quaternion. + /// The product quaternion. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Quaternion Multiply(Quaternion value1, Quaternion value2) { return value1 * value2; } - /// Multiplies a Quaternion by a scalar value. - /// The source Quaternion. + /// Returns the quaternion that results from scaling all the components of a specified quaternion by a scalar factor. + /// The source quaternion. /// The scalar value. - /// The result of the multiplication. + /// The scaled quaternion. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Quaternion Multiply(Quaternion value1, float value2) { return value1 * value2; } - /// Flips the sign of each component of the quaternion. - /// The source Quaternion. - /// The negated Quaternion. + /// Reverses the sign of each component of the quaternion. + /// The quaternion to negate. + /// The negated quaternion. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Quaternion Negate(Quaternion value) { return -value; } - /// Divides each component of the Quaternion by the length of the Quaternion. - /// The source Quaternion. - /// The normalized Quaternion. + /// Divides each component of a specified by its length. + /// The quaternion to normalize. + /// The normalized quaternion. public static Quaternion Normalize(Quaternion value) { Quaternion ans; @@ -521,10 +534,10 @@ namespace System.Numerics } /// Interpolates between two quaternions, using spherical linear interpolation. - /// The first source Quaternion. - /// The second source Quaternion. - /// The relative weight of the second source Quaternion in the interpolation. - /// The interpolated Quaternion. + /// The first quaternion. + /// The second quaternion. + /// The relative weight of the second quaternion in the interpolation. + /// The interpolated quaternion. public static Quaternion Slerp(Quaternion quaternion1, Quaternion quaternion2, float amount) { float t = amount; @@ -569,27 +582,29 @@ namespace System.Numerics return ans; } - /// Subtracts one Quaternion from another. - /// The first source Quaternion. - /// The second Quaternion, to be subtracted from the first. - /// The result of the subtraction. + /// Subtracts each element in a second quaternion from its corresponding element in a first quaternion. + /// The first quaternion. + /// The second quaternion. + /// The quaternion containing the values that result from subtracting each element in from its corresponding element in . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Quaternion Subtract(Quaternion value1, Quaternion value2) { return value1 - value2; } - /// Returns a boolean indicating whether the given Object is equal to this Quaternion instance. - /// The Object to compare against. - /// True if the Object is equal to this Quaternion; False otherwise. + /// Returns a value that indicates whether this instance and a specified object are equal. + /// The object to compare with the current instance. + /// if the current instance and are equal; otherwise, . If is , the method returns . + /// The current instance and are equal if is a object and the corresponding components of each matrix are equal. public override readonly bool Equals([NotNullWhen(true)] object? obj) { return (obj is Quaternion other) && Equals(other); } - /// Returns a boolean indicating whether the given Quaternion is equal to this Quaternion instance. - /// The Quaternion to compare this instance to. - /// True if the other Quaternion is equal to this instance; False otherwise. + /// Returns a value that indicates whether this instance and another quaternion are equal. + /// The other quaternion. + /// if the two quaternions are equal; otherwise, . + /// Two quaternions are equal if each of their corresponding components is equal. public readonly bool Equals(Quaternion other) { return this == other; @@ -602,23 +617,24 @@ namespace System.Numerics return unchecked(X.GetHashCode() + Y.GetHashCode() + Z.GetHashCode() + W.GetHashCode()); } - /// Calculates the length of the Quaternion. - /// The computed length of the Quaternion. + /// Calculates the length of the quaternion. + /// The computed length of the quaternion. public readonly float Length() { float lengthSquared = LengthSquared(); return MathF.Sqrt(lengthSquared); } - /// Calculates the length squared of the Quaternion. This operation is cheaper than Length(). - /// The length squared of the Quaternion. + /// Calculates the squared length of the quaternion. + /// The length squared of the quaternion. public readonly float LengthSquared() { return X * X + Y * Y + Z * Z + W * W; } - /// Returns a String representing this Quaternion instance. - /// The string representation. + /// Returns a string that represents this quaternion. + /// The string representation of this quaternion. + /// The numeric values in the returned string are formatted by using the conventions of the current culture. For example, for the en-US culture, the returned string might appear as {X:1.1 Y:2.2 Z:3.3 W:4.4}. public override readonly string ToString() { return string.Format(CultureInfo.CurrentCulture, "{{X:{0} Y:{1} Z:{2} W:{3}}}", X, Y, Z, W); diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector.cs index 4943bf5..cc2d5ab 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector.cs @@ -7,15 +7,11 @@ using Internal.Runtime.CompilerServices; namespace System.Numerics { - /// - /// Contains various methods useful for creating, manipulating, combining, and converting generic vectors with one another. - /// + /// Provides a collection of static convenience methods for creating, manipulating, combining, and converting generic vectors. [Intrinsic] public static partial class Vector { - /// - /// Creates a new vector with elements selected between the two given source vectors, and based on a mask vector. - /// + /// Creates a new single-precision vector with elements selected between two specified single-precision source vectors based on an integral mask vector. /// The integral mask vector used to drive selection. /// The first source vector. /// The second source vector. @@ -27,9 +23,7 @@ namespace System.Numerics return (Vector)Vector.ConditionalSelect((Vector)condition, left, right); } - /// - /// Creates a new vector with elements selected between the two given source vectors, and based on a mask vector. - /// + /// Creates a new double-precision vector with elements selected between two specified double-precision source vectors based on an integral mask vector. /// The integral mask vector used to drive selection. /// The first source vector. /// The second source vector. @@ -41,12 +35,11 @@ namespace System.Numerics return (Vector)Vector.ConditionalSelect((Vector)condition, left, right); } - /// - /// Creates a new vector with elements selected between the two given source vectors, and based on a mask vector. - /// - /// The mask vector used to drive selection. + /// Creates a new vector of a specified type with elements selected between two specified source vectors of the same type based on an integral mask vector. + /// The integral mask vector used to drive selection. /// The first source vector. /// The second source vector. + /// The vector type. can be any primitive numeric type. /// The new vector with elements selected based on the mask. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -55,12 +48,11 @@ namespace System.Numerics return Vector.ConditionalSelect(condition, left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left and right were equal. - /// + /// Returns a new vector of a specified type whose elements signal whether the elements in two specified vectors of the same type are equal. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Equals(Vector left, Vector right) where T : struct @@ -68,12 +60,10 @@ namespace System.Numerics return Vector.Equals(left, right); } - /// - /// Returns an integral vector whose elements signal whether elements in the left and right floating point vectors were equal. - /// + /// Returns a new integral vector whose elements signal whether the elements in two specified single-precision vectors are equal. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Equals(Vector left, Vector right) @@ -81,12 +71,10 @@ namespace System.Numerics return (Vector)Vector.Equals(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left and right were equal. - /// + /// Returns a new integral vector whose elements signal whether the elements in two specified integral vectors are equal. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Equals(Vector left, Vector right) @@ -94,12 +82,10 @@ namespace System.Numerics return Vector.Equals(left, right); } - /// - /// Returns an integral vector whose elements signal whether elements in the left and right floating point vectors were equal. - /// + /// Returns a new integral vector whose elements signal whether the elements in two specified double-precision vectors are equal. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Equals(Vector left, Vector right) @@ -107,12 +93,10 @@ namespace System.Numerics return (Vector)Vector.Equals(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left and right were equal. - /// + /// Returns a new vector whose elements signal whether the elements in two specified long integer vectors are equal. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting long integer vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Equals(Vector left, Vector right) @@ -120,37 +104,33 @@ namespace System.Numerics return Vector.Equals(left, right); } - /// - /// Returns a boolean indicating whether each pair of elements in the given vectors are equal. - /// + /// Returns a value that indicates whether each pair of elements in the given vectors is equal. /// The first vector to compare. - /// The first vector to compare. - /// True if all elements are equal; False otherwise. + /// The second vector to compare. + /// The vector type. can be any primitive numeric type. + /// if all elements in and are equal; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool EqualsAll(Vector left, Vector right) where T : struct { return left == right; } - /// - /// Returns a boolean indicating whether any single pair of elements in the given vectors are equal. - /// + /// Returns a value that indicates whether any single pair of elements in the given vectors is equal. /// The first vector to compare. /// The second vector to compare. - /// True if any element pairs are equal; False if no element pairs are equal. + /// The vector type. can be any primitive numeric type. + /// if any element pair in and is equal; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool EqualsAny(Vector left, Vector right) where T : struct { return !Vector.Equals(left, right).Equals(Vector.Zero); } - /// - /// Returns a new vector whose elements signal whether the elements in left were less than their - /// corresponding elements in right. - /// + /// Returns a new vector of a specified type whose elements signal whether the elements in one vector are less than their corresponding elements in the second vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThan(Vector left, Vector right) where T : struct @@ -158,13 +138,10 @@ namespace System.Numerics return Vector.LessThan(left, right); } - /// - /// Returns an integral vector whose elements signal whether the elements in left were less than their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one single-precision vector are less than their corresponding elements in a second single-precision vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant integral vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThan(Vector left, Vector right) @@ -172,13 +149,10 @@ namespace System.Numerics return (Vector)Vector.LessThan(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left were less than their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one integral vector are less than their corresponding elements in a second integral vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThan(Vector left, Vector right) @@ -186,13 +160,10 @@ namespace System.Numerics return Vector.LessThan(left, right); } - /// - /// Returns an integral vector whose elements signal whether the elements in left were less than their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one double-precision floating-point vector are less than their corresponding elements in a second double-precision floating-point vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant integral vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThan(Vector left, Vector right) @@ -200,13 +171,10 @@ namespace System.Numerics return (Vector)Vector.LessThan(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left were less than their - /// corresponding elements in right. - /// + /// Returns a new long integer vector whose elements signal whether the elements in one long integer vector are less than their corresponding elements in a second long integer vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting long integer vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThan(Vector left, Vector right) @@ -214,12 +182,11 @@ namespace System.Numerics return Vector.LessThan(left, right); } - /// - /// Returns a boolean indicating whether all of the elements in left are less than their corresponding elements in right. - /// + /// Returns a value that indicates whether all of the elements in the first vector are less than their corresponding elements in the second vector. /// The first vector to compare. /// The second vector to compare. - /// True if all elements in left are less than their corresponding elements in right; False otherwise. + /// The vector type. can be any primitive numeric type. + /// if all of the elements in are less than the corresponding elements in ; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool LessThanAll(Vector left, Vector right) where T : struct { @@ -227,12 +194,11 @@ namespace System.Numerics return cond.Equals(Vector.AllBitsSet); } - /// - /// Returns a boolean indicating whether any element in left is less than its corresponding element in right. - /// + /// Returns a value that indicates whether any element in the first vector is less than the corresponding element in the second vector. /// The first vector to compare. /// The second vector to compare. - /// True if any elements in left are less than their corresponding elements in right; False otherwise. + /// The vector type. can be any primitive numeric type. + /// if any element in is less than the corresponding element in ; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool LessThanAny(Vector left, Vector right) where T : struct { @@ -240,13 +206,11 @@ namespace System.Numerics return !cond.Equals(Vector.Zero); } - /// - /// Returns a new vector whose elements signal whether the elements in left were less than or equal to their - /// corresponding elements in right. - /// + /// Returns a new vector whose elements signal whether the elements in one vector are less than or equal to their corresponding elements in the second vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThanOrEqual(Vector left, Vector right) where T : struct @@ -254,13 +218,10 @@ namespace System.Numerics return Vector.LessThanOrEqual(left, right); } - /// - /// Returns an integral vector whose elements signal whether the elements in left were less than or equal to their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one single-precision floating-point vector are less than or equal to their corresponding elements in a second single-precision floating-point vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant integral vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThanOrEqual(Vector left, Vector right) @@ -268,13 +229,10 @@ namespace System.Numerics return (Vector)Vector.LessThanOrEqual(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left were less than or equal to their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one integral vector are less than or equal to their corresponding elements in a second integral vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThanOrEqual(Vector left, Vector right) @@ -282,13 +240,10 @@ namespace System.Numerics return Vector.LessThanOrEqual(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left were less than or equal to their - /// corresponding elements in right. - /// + /// Returns a new long integer vector whose elements signal whether the elements in one long integer vector are less or equal to their corresponding elements in a second long integer vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting long integer vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThanOrEqual(Vector left, Vector right) @@ -296,13 +251,10 @@ namespace System.Numerics return Vector.LessThanOrEqual(left, right); } - /// - /// Returns an integral vector whose elements signal whether the elements in left were less than or equal to their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one double-precision floating-point vector are less than or equal to their corresponding elements in a second double-precision floating-point vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant integral vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector LessThanOrEqual(Vector left, Vector right) @@ -310,12 +262,11 @@ namespace System.Numerics return (Vector)Vector.LessThanOrEqual(left, right); } - /// - /// Returns a boolean indicating whether all elements in left are less than or equal to their corresponding elements in right. - /// + /// Returns a value that indicates whether all elements in the first vector are less than or equal to their corresponding elements in the second vector. /// The first vector to compare. /// The second vector to compare. - /// True if all elements in left are less than or equal to their corresponding elements in right; False otherwise. + /// The vector type. can be any primitive numeric type. + /// if all of the elements in are less than or equal to the corresponding elements in ; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool LessThanOrEqualAll(Vector left, Vector right) where T : struct { @@ -323,12 +274,11 @@ namespace System.Numerics return cond.Equals(Vector.AllBitsSet); } - /// - /// Returns a boolean indicating whether any element in left is less than or equal to its corresponding element in right. - /// + /// Returns a value that indicates whether any element in the first vector is less than or equal to the corresponding element in the second vector. /// The first vector to compare. /// The second vector to compare. - /// True if any elements in left are less than their corresponding elements in right; False otherwise. + /// The vector type. can be any primitive numeric type. + /// if any element in is less than or equal to the corresponding element in ; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool LessThanOrEqualAny(Vector left, Vector right) where T : struct { @@ -336,13 +286,11 @@ namespace System.Numerics return !cond.Equals(Vector.Zero); } - /// - /// Returns a new vector whose elements signal whether the elements in left were greater than their - /// corresponding elements in right. - /// + /// Returns a new vector whose elements signal whether the elements in one vector of a specified type are greater than their corresponding elements in the second vector of the same time. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThan(Vector left, Vector right) where T : struct @@ -350,13 +298,10 @@ namespace System.Numerics return Vector.GreaterThan(left, right); } - /// - /// Returns an integral vector whose elements signal whether the elements in left were greater than their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one single-precision floating-point vector are greater than their corresponding elements in a second single-precision floating-point vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant integral vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThan(Vector left, Vector right) @@ -364,13 +309,10 @@ namespace System.Numerics return (Vector)Vector.GreaterThan(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left were greater than their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one integral vector are greater than their corresponding elements in a second integral vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThan(Vector left, Vector right) @@ -378,13 +320,10 @@ namespace System.Numerics return Vector.GreaterThan(left, right); } - /// - /// Returns an integral vector whose elements signal whether the elements in left were greater than their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one double-precision floating-point vector are greater than their corresponding elements in a second double-precision floating-point vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant integral vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThan(Vector left, Vector right) @@ -392,13 +331,10 @@ namespace System.Numerics return (Vector)Vector.GreaterThan(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left were greater than their - /// corresponding elements in right. - /// + /// Returns a new long integer vector whose elements signal whether the elements in one long integer vector are greater than their corresponding elements in a second long integer vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting long integer vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThan(Vector left, Vector right) @@ -406,13 +342,11 @@ namespace System.Numerics return Vector.GreaterThan(left, right); } - /// - /// Returns a boolean indicating whether all elements in left are greater than the corresponding elements in right. - /// elements in right. - /// + /// Returns a value that indicates whether all elements in the first vector are greater than the corresponding elements in the second vector. /// The first vector to compare. /// The second vector to compare. - /// True if all elements in left are greater than their corresponding elements in right; False otherwise. + /// The vector type. can be any primitive numeric type. + /// if all elements in are greater than the corresponding elements in ; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool GreaterThanAll(Vector left, Vector right) where T : struct { @@ -420,12 +354,11 @@ namespace System.Numerics return cond.Equals(Vector.AllBitsSet); } - /// - /// Returns a boolean indicating whether any element in left is greater than its corresponding element in right. - /// + /// Returns a value that indicates whether any element in the first vector is greater than the corresponding element in the second vector. /// The first vector to compare. /// The second vector to compare. - /// True if any elements in left are greater than their corresponding elements in right; False otherwise. + /// The vector type. can be any primitive numeric type. + /// if any element in is greater than the corresponding element in ; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool GreaterThanAny(Vector left, Vector right) where T : struct { @@ -433,13 +366,11 @@ namespace System.Numerics return !cond.Equals(Vector.Zero); } - /// - /// Returns a new vector whose elements signal whether the elements in left were greater than or equal to their - /// corresponding elements in right. - /// + /// Returns a new vector whose elements signal whether the elements in one vector of a specified type are greater than or equal to their corresponding elements in the second vector of the same type. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThanOrEqual(Vector left, Vector right) where T : struct @@ -447,13 +378,10 @@ namespace System.Numerics return Vector.GreaterThanOrEqual(left, right); } - /// - /// Returns an integral vector whose elements signal whether the elements in left were greater than or equal to their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one vector are greater than or equal to their corresponding elements in the single-precision floating-point second vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant integral vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThanOrEqual(Vector left, Vector right) @@ -461,13 +389,10 @@ namespace System.Numerics return (Vector)Vector.GreaterThanOrEqual(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left were greater than or equal to their - /// corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one integral vector are greater than or equal to their corresponding elements in the second integral vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThanOrEqual(Vector left, Vector right) @@ -475,13 +400,10 @@ namespace System.Numerics return Vector.GreaterThanOrEqual(left, right); } - /// - /// Returns a new vector whose elements signal whether the elements in left were greater than or equal to their - /// corresponding elements in right. - /// + /// Returns a new long integer vector whose elements signal whether the elements in one long integer vector are greater than or equal to their corresponding elements in the second long integer vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant vector. + /// The resulting long integer vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThanOrEqual(Vector left, Vector right) @@ -489,13 +411,10 @@ namespace System.Numerics return Vector.GreaterThanOrEqual(left, right); } - /// - /// Returns an integral vector whose elements signal whether the elements in left were greater than or equal to - /// their corresponding elements in right. - /// + /// Returns a new integral vector whose elements signal whether the elements in one vector are greater than or equal to their corresponding elements in the second double-precision floating-point vector. /// The first vector to compare. /// The second vector to compare. - /// The resultant integral vector. + /// The resulting integral vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector GreaterThanOrEqual(Vector left, Vector right) @@ -503,13 +422,11 @@ namespace System.Numerics return (Vector)Vector.GreaterThanOrEqual(left, right); } - /// - /// Returns a boolean indicating whether all of the elements in left are greater than or equal to - /// their corresponding elements in right. - /// + /// Returns a value that indicates whether all elements in the first vector are greater than or equal to all the corresponding elements in the second vector. /// The first vector to compare. /// The second vector to compare. - /// True if all elements in left are greater than or equal to their corresponding elements in right; False otherwise. + /// The vector type. can be any primitive numeric type. + /// if all elements in are greater than or equal to the corresponding elements in ; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool GreaterThanOrEqualAll(Vector left, Vector right) where T : struct { @@ -517,12 +434,11 @@ namespace System.Numerics return cond.Equals(Vector.AllBitsSet); } - /// - /// Returns a boolean indicating whether any element in left is greater than or equal to its corresponding element in right. - /// + /// Returns a value that indicates whether any element in the first vector is greater than or equal to the corresponding element in the second vector. /// The first vector to compare. /// The second vector to compare. - /// True if any elements in left are greater than or equal to their corresponding elements in right; False otherwise. + /// The vector type. can be any primitive numeric type. + /// if any element in is greater than or equal to the corresponding element in ; otherwise, . [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool GreaterThanOrEqualAny(Vector left, Vector right) where T : struct { @@ -530,27 +446,18 @@ namespace System.Numerics return !cond.Equals(Vector.Zero); } - // Every operation must either be a JIT intrinsic or implemented over a JIT intrinsic - // as a thin wrapper - // Operations implemented over a JIT intrinsic should be inlined - // Methods that do not have a type parameter are recognized as intrinsics - /// - /// Returns whether or not vector operations are subject to hardware acceleration through JIT intrinsic support. - /// + /// Gets a value that indicates whether vector operations are subject to hardware acceleration through JIT intrinsic support. + /// if vector operations are subject to hardware acceleration; otherwise, . + /// Vector operations are subject to hardware acceleration on systems that support Single Instruction, Multiple Data (SIMD) instructions and the RyiJIT just-in-time compiler is used to compile managed code. public static bool IsHardwareAccelerated { [Intrinsic] get => false; } - // Vector - // Basic Math - // All Math operations for Vector are aggressively inlined here - - /// - /// Returns a new vector whose elements are the absolute values of the given vector's elements. - /// + /// Returns a new vector whose elements are the absolute values of the given vector's elements. /// The source vector. + /// The vector type. can be any primitive numeric type. /// The absolute value vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -559,11 +466,10 @@ namespace System.Numerics return Vector.Abs(value); } - /// - /// Returns a new vector whose elements are the minimum of each pair of elements in the two given vectors. - /// - /// The first source vector. - /// The second source vector. + /// Returns a new vector whose elements are the minimum of each pair of elements in the two given vectors. + /// The first vector to compare. + /// The second vector to compare. + /// The vector type. can be any primitive numeric type. /// The minimum vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -572,11 +478,10 @@ namespace System.Numerics return Vector.Min(left, right); } - /// - /// Returns a new vector whose elements are the maximum of each pair of elements in the two given vectors. - /// - /// The first source vector. - /// The second source vector. + /// Returns a new vector whose elements are the maximum of each pair of elements in the two given vectors. + /// The first vector to compare. + /// The second vector to compare. + /// The vector type. can be any primitive numeric type. /// The maximum vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -585,13 +490,10 @@ namespace System.Numerics return Vector.Max(left, right); } - // Specialized vector operations - - /// - /// Returns the dot product of two vectors. - /// - /// The first source vector. - /// The second source vector. + /// Returns the dot product of two vectors. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. /// The dot product. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -600,10 +502,9 @@ namespace System.Numerics return Vector.Dot(left, right); } - /// - /// Returns a new vector whose elements are the square roots of the given vector's elements. - /// + /// Returns a new vector whose elements are the square roots of a specified vector's elements. /// The source vector. + /// The vector type. can be any primitive numeric type. /// The square root vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -612,15 +513,11 @@ namespace System.Numerics return Vector.SquareRoot(value); } - /// - /// Returns a new vector whose elements are the smallest integral values that are greater than or equal to the given vector's elements. - /// + /// Returns a new vector whose elements are the smallest integral values that are greater than or equal to the given vector's elements. /// The source vector. - /// - /// The vector whose elements are the smallest integral values that are greater than or equal to the given vector's elements. - /// If a value is equal to , or , that value is returned. - /// Note that this method returns a instead of an integral type. - /// + /// The vector whose elements are the smallest integral values that are greater than or equal to the given vector's elements. + /// If a value is equal to , , or , that value is returned. + /// Note that this method returns a instead of an integral type. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Ceiling(Vector value) @@ -628,15 +525,11 @@ namespace System.Numerics return Vector.Ceiling(value); } - /// - /// Returns a new vector whose elements are the smallest integral values that are greater than or equal to the given vector's elements. - /// + /// Returns a new vector whose elements are the smallest integral values that are greater than or equal to the given vector's elements. /// The source vector. - /// - /// The vector whose elements are the smallest integral values that are greater than or equal to the given vector's elements. - /// If a value is equal to , or , that value is returned. - /// Note that this method returns a instead of an integral type. - /// + /// The vector whose elements are the smallest integral values that are greater than or equal to the given vector's elements. + /// If a value is equal to , , or , that value is returned. + /// Note that this method returns a instead of an integral type. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Ceiling(Vector value) @@ -644,15 +537,11 @@ namespace System.Numerics return Vector.Ceiling(value); } - /// - /// Returns a new vector whose elements are the largest integral values that are less than or equal to the given vector's elements. - /// + /// Returns a new vector whose elements are the largest integral values that are less than or equal to the given vector's elements. /// The source vector. - /// - /// The vector whose elements are the largest integral values that are less than or equal to the given vector's elements. - /// If a value is equal to , or , that value is returned. - /// Note that this method returns a instead of an integral type. - /// + /// The vector whose elements are the largest integral values that are less than or equal to the given vector's elements. + /// If a value is equal to , , or , that value is returned. + /// Note that this method returns a instead of an integral type. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Floor(Vector value) @@ -660,15 +549,11 @@ namespace System.Numerics return Vector.Floor(value); } - /// - /// Returns a new vector whose elements are the largest integral values that are less than or equal to the given vector's elements. - /// + /// Returns a new vector whose elements are the largest integral values that are less than or equal to the given vector's elements. /// The source vector. - /// - /// The vector whose elements are the largest integral values that are less than or equal to the given vector's elements. - /// If a value is equal to , or , that value is returned. - /// Note that this method returns a instead of an integral type. - /// + /// The vector whose elements are the largest integral values that are less than or equal to the given vector's elements. + /// If a value is equal to , , or , that value is returned. + /// Note that this method returns a instead of an integral type. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Floor(Vector value) @@ -676,11 +561,10 @@ namespace System.Numerics return Vector.Floor(value); } - /// - /// Creates a new vector whose values are the sum of each pair of elements from the two given vectors. - /// - /// The first source vector. - /// The second source vector. + /// Returns a new vector whose values are the sum of each pair of elements from two given vectors. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. /// The summed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Add(Vector left, Vector right) where T : struct @@ -688,11 +572,10 @@ namespace System.Numerics return left + right; } - /// - /// Creates a new vector whose values are the difference between each pairs of elements in the given vectors. - /// - /// The first source vector. - /// The second source vector. + /// Returns a new vector whose values are the difference between the elements in the second vector and their corresponding elements in the first vector. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. /// The difference vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Subtract(Vector left, Vector right) where T : struct @@ -700,23 +583,21 @@ namespace System.Numerics return left - right; } - /// - /// Creates a new vector whose values are the product of each pair of elements from the two given vectors. - /// - /// The first source vector. - /// The second source vector. - /// The summed vector. + /// Returns a new vector whose values are the product of each pair of elements in two specified vectors. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. + /// The element-wise product vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Multiply(Vector left, Vector right) where T : struct { return left * right; } - /// - /// Returns a new vector whose values are the values of the given vector each multiplied by a scalar value. - /// - /// The source vector. - /// The scalar factor. + /// Returns a new vector whose values are the values of a specified vector each multiplied by a scalar value. + /// The vector. + /// The scalar value. + /// The vector type. can be any primitive numeric type. /// The scaled vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Multiply(Vector left, T right) where T : struct @@ -724,11 +605,10 @@ namespace System.Numerics return left * right; } - /// - /// Returns a new vector whose values are the values of the given vector each multiplied by a scalar value. - /// - /// The scalar factor. - /// The source vector. + /// Returns a new vector whose values are a scalar value multiplied by each of the values of a specified vector. + /// The scalar value. + /// The vector. + /// The vector type. can be any primitive numeric type. /// The scaled vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Multiply(T left, Vector right) where T : struct @@ -736,12 +616,10 @@ namespace System.Numerics return left * right; } - /// - /// Returns a new vector whose values are the result of dividing the first vector's elements - /// by the corresponding elements in the second vector. - /// - /// The first source vector. - /// The second source vector. + /// Returns a new vector whose values are the result of dividing the first vector's elements by the corresponding elements in the second vector. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. /// The divided vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Divide(Vector left, Vector right) where T : struct @@ -749,10 +627,9 @@ namespace System.Numerics return left / right; } - /// - /// Returns a new vector whose elements are the given vector's elements negated. - /// + /// Returns a new vector whose elements are the negation of the corresponding element in the specified vector. /// The source vector. + /// The vector type. can be any primitive numeric type. /// The negated vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Negate(Vector value) where T : struct @@ -760,59 +637,54 @@ namespace System.Numerics return -value; } - /// - /// Returns a new vector by performing a bitwise-and operation on each of the elements in the given vectors. - /// - /// The first source vector. - /// The second source vector. - /// The resultant vector. + /// Returns a new vector by performing a bitwise operation on each pair of elements in two vectors. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector BitwiseAnd(Vector left, Vector right) where T : struct { return left & right; } - /// - /// Returns a new vector by performing a bitwise-or operation on each of the elements in the given vectors. - /// - /// The first source vector. - /// The second source vector. - /// The resultant vector. + /// Returns a new vector by performing a bitwise operation on each pair of elements in two vectors. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector BitwiseOr(Vector left, Vector right) where T : struct { return left | right; } - /// - /// Returns a new vector whose elements are obtained by taking the one's complement of the given vector's elements. - /// + /// Returns a new vector whose elements are obtained by taking the one's complement of a specified vector's elements. /// The source vector. - /// The one's complement vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector OnesComplement(Vector value) where T : struct { return ~value; } - /// - /// Returns a new vector by performing a bitwise-exclusive-or operation on each of the elements in the given vectors. - /// - /// The first source vector. - /// The second source vector. - /// The resultant vector. + /// Returns a new vector by performing a bitwise exclusive Or () operation on each pair of elements in two vectors. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector Xor(Vector left, Vector right) where T : struct { return left ^ right; } - /// - /// Returns a new vector by performing a bitwise-and-not operation on each of the elements in the given vectors. - /// - /// The first source vector. - /// The second source vector. - /// The resultant vector. + /// Returns a new vector by performing a bitwise And Not operation on each pair of corresponding elements in two vectors. + /// The first vector. + /// The second vector. + /// The vector type. can be any primitive numeric type. + /// The resulting vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector AndNot(Vector left, Vector right) where T : struct @@ -820,10 +692,9 @@ namespace System.Numerics return left & ~right; } - /// - /// Reinterprets the bits of the given vector into those of a vector of unsigned bytes. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a vector of unsigned bytes. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector AsVectorByte(Vector value) where T : struct @@ -831,10 +702,9 @@ namespace System.Numerics return (Vector)value; } - /// - /// Reinterprets the bits of the given vector into those of a vector of signed bytes. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a vector of signed bytes. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [CLSCompliant(false)] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -843,10 +713,9 @@ namespace System.Numerics return (Vector)value; } - /// - /// Reinterprets the bits of the given vector into those of a vector of 16-bit integers. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a vector of unsigned 16-bit integers. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [CLSCompliant(false)] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -855,10 +724,9 @@ namespace System.Numerics return (Vector)value; } - /// - /// Reinterprets the bits of the given vector into those of a vector of signed 16-bit integers. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a vector of 16-bit integers. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector AsVectorInt16(Vector value) where T : struct @@ -866,10 +734,9 @@ namespace System.Numerics return (Vector)value; } - /// - /// Reinterprets the bits of the given vector into those of a vector of unsigned 32-bit integers. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a vector of unsigned integers. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [CLSCompliant(false)] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -878,10 +745,9 @@ namespace System.Numerics return (Vector)value; } - /// - /// Reinterprets the bits of the given vector into those of a vector of signed 32-bit integers. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a vector of integers. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector AsVectorInt32(Vector value) where T : struct @@ -889,10 +755,9 @@ namespace System.Numerics return (Vector)value; } - /// - /// Reinterprets the bits of the given vector into those of a vector of unsigned 64-bit integers. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a vector of unsigned long integers. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [CLSCompliant(false)] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -901,11 +766,9 @@ namespace System.Numerics return (Vector)value; } - - /// - /// Reinterprets the bits of the given vector into those of a vector of signed 64-bit integers. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a vector of long integers. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector AsVectorInt64(Vector value) where T : struct @@ -913,10 +776,9 @@ namespace System.Numerics return (Vector)value; } - /// - /// Reinterprets the bits of the given vector into those of a vector of 32-bit floating point numbers. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a single-precision floating-point vector. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector AsVectorSingle(Vector value) where T : struct @@ -924,10 +786,9 @@ namespace System.Numerics return (Vector)value; } - /// - /// Reinterprets the bits of the given vector into those of a vector of 64-bit floating point numbers. - /// - /// The source vector + /// Reinterprets the bits of a specified vector into those of a double-precision floating-point vector. + /// The source vector. + /// The vector type. can be any primitive numeric type. /// The reinterpreted vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector AsVectorDouble(Vector value) where T : struct @@ -935,12 +796,10 @@ namespace System.Numerics return (Vector)value; } - /// - /// Widens a Vector{Byte} into two Vector{UInt16}'s. + /// Widens a Vector<Byte> into two Vector<UInt16> instances. /// The source vector whose elements are widened into the outputs. /// The first output vector, whose elements will contain the widened elements from lower indices in the source vector. /// The second output vector, whose elements will contain the widened elements from higher indices in the source vector. - /// [CLSCompliant(false)] [Intrinsic] public static unsafe void Widen(Vector source, out Vector low, out Vector high) @@ -961,12 +820,10 @@ namespace System.Numerics high = *(Vector*)highPtr; } - /// - /// Widens a Vector{UInt16} into two Vector{UInt32}'s. + /// Widens a Vector<UInt16> into two Vector<UInt32> instances. /// The source vector whose elements are widened into the outputs. /// The first output vector, whose elements will contain the widened elements from lower indices in the source vector. /// The second output vector, whose elements will contain the widened elements from higher indices in the source vector. - /// [CLSCompliant(false)] [Intrinsic] public static unsafe void Widen(Vector source, out Vector low, out Vector high) @@ -987,12 +844,10 @@ namespace System.Numerics high = *(Vector*)highPtr; } - /// - /// Widens a Vector{UInt32} into two Vector{UInt64}'s. + /// Widens a Vector<UInt32> into two Vector<UInt64> instances. /// The source vector whose elements are widened into the outputs. /// The first output vector, whose elements will contain the widened elements from lower indices in the source vector. /// The second output vector, whose elements will contain the widened elements from higher indices in the source vector. - /// [CLSCompliant(false)] [Intrinsic] public static unsafe void Widen(Vector source, out Vector low, out Vector high) @@ -1013,12 +868,10 @@ namespace System.Numerics high = *(Vector*)highPtr; } - /// - /// Widens a Vector{SByte} into two Vector{Int16}'s. + /// Widens a Vector<SByte> into two Vector<Int16> instances. /// The source vector whose elements are widened into the outputs. /// The first output vector, whose elements will contain the widened elements from lower indices in the source vector. /// The second output vector, whose elements will contain the widened elements from higher indices in the source vector. - /// [CLSCompliant(false)] [Intrinsic] public static unsafe void Widen(Vector source, out Vector low, out Vector high) @@ -1039,12 +892,10 @@ namespace System.Numerics high = *(Vector*)highPtr; } - /// - /// Widens a Vector{Int16} into two Vector{Int32}'s. + /// Widens a Vector<Int16> into two Vector<Int32> instances. /// The source vector whose elements are widened into the outputs. /// The first output vector, whose elements will contain the widened elements from lower indices in the source vector. /// The second output vector, whose elements will contain the widened elements from higher indices in the source vector. - /// [Intrinsic] public static unsafe void Widen(Vector source, out Vector low, out Vector high) { @@ -1064,12 +915,10 @@ namespace System.Numerics high = *(Vector*)highPtr; } - /// - /// Widens a Vector{Int32} into two Vector{Int64}'s. + /// Widens a Vector<Int32> into two Vector<Int64> instances. /// The source vector whose elements are widened into the outputs. /// The first output vector, whose elements will contain the widened elements from lower indices in the source vector. /// The second output vector, whose elements will contain the widened elements from higher indices in the source vector. - /// [Intrinsic] public static unsafe void Widen(Vector source, out Vector low, out Vector high) { @@ -1089,12 +938,10 @@ namespace System.Numerics high = *(Vector*)highPtr; } - /// - /// Widens a Vector{Single} into two Vector{Double}'s. + /// Widens a Vector<Single> into two Vector<Double> instances. /// The source vector whose elements are widened into the outputs. /// The first output vector, whose elements will contain the widened elements from lower indices in the source vector. /// The second output vector, whose elements will contain the widened elements from higher indices in the source vector. - /// [Intrinsic] public static unsafe void Widen(Vector source, out Vector low, out Vector high) { @@ -1114,12 +961,10 @@ namespace System.Numerics high = *(Vector*)highPtr; } - /// - /// Narrows two Vector{UInt16}'s into one Vector{Byte}. + /// Narrows two Vector<UInt16> instances into one Vector<Byte>. /// The first source vector, whose elements become the lower-index elements of the return value. /// The second source vector, whose elements become the higher-index elements of the return value. - /// A Vector{Byte} containing elements narrowed from the source vectors. - /// + /// A Vector<Byte> containing elements narrowed from the source vectors. [CLSCompliant(false)] [Intrinsic] public static unsafe Vector Narrow(Vector low, Vector high) @@ -1138,12 +983,10 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Narrows two Vector{UInt32}'s into one Vector{UInt16}. + /// Narrows two Vector<UInt32> instances into one Vector<UInt16>. /// The first source vector, whose elements become the lower-index elements of the return value. /// The second source vector, whose elements become the higher-index elements of the return value. - /// A Vector{UInt16} containing elements narrowed from the source vectors. - /// + /// A Vector<UInt16> containing elements narrowed from the source vectors. [CLSCompliant(false)] [Intrinsic] public static unsafe Vector Narrow(Vector low, Vector high) @@ -1162,12 +1005,10 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Narrows two Vector{UInt64}'s into one Vector{UInt32}. + /// Narrows two Vector<UInt64> instances into one Vector<UInt32>. /// The first source vector, whose elements become the lower-index elements of the return value. /// The second source vector, whose elements become the higher-index elements of the return value. - /// A Vector{UInt32} containing elements narrowed from the source vectors. - /// + /// A Vector<UInt32> containing elements narrowed from the source vectors. [CLSCompliant(false)] [Intrinsic] public static unsafe Vector Narrow(Vector low, Vector high) @@ -1186,12 +1027,10 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Narrows two Vector{Int16}'s into one Vector{SByte}. + /// Narrows two Vector<Int16> instances into one Vector<SByte>. /// The first source vector, whose elements become the lower-index elements of the return value. /// The second source vector, whose elements become the higher-index elements of the return value. - /// A Vector{SByte} containing elements narrowed from the source vectors. - /// + /// A Vector<SByte> containing elements narrowed from the source vectors. [CLSCompliant(false)] [Intrinsic] public static unsafe Vector Narrow(Vector low, Vector high) @@ -1210,12 +1049,10 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Narrows two Vector{Int32}'s into one Vector{Int16}. + /// Narrows two Vector<Int32> instances into one Vector<Int16>. /// The first source vector, whose elements become the lower-index elements of the return value. /// The second source vector, whose elements become the higher-index elements of the return value. - /// A Vector{Int16} containing elements narrowed from the source vectors. - /// + /// A Vector<Int16> containing elements narrowed from the source vectors. [Intrinsic] public static unsafe Vector Narrow(Vector low, Vector high) { @@ -1233,12 +1070,10 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Narrows two Vector{Int64}'s into one Vector{Int32}. + /// Narrows two Vector<Int64> instances into one Vector<Int32>. /// The first source vector, whose elements become the lower-index elements of the return value. /// The second source vector, whose elements become the higher-index elements of the return value. - /// A Vector{Int32} containing elements narrowed from the source vectors. - /// + /// A Vector<Int32> containing elements narrowed from the source vectors. [Intrinsic] public static unsafe Vector Narrow(Vector low, Vector high) { @@ -1256,12 +1091,10 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Narrows two Vector{Double}'s into one Vector{Single}. + /// Narrows two Vector<Double> instances into one Vector<Single>. /// The first source vector, whose elements become the lower-index elements of the return value. /// The second source vector, whose elements become the higher-index elements of the return value. - /// A Vector{Single} containing elements narrowed from the source vectors. - /// + /// A Vector<Single> containing elements narrowed from the source vectors. [Intrinsic] public static unsafe Vector Narrow(Vector low, Vector high) { @@ -1279,9 +1112,7 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Converts a Vector{Int32} to a Vector{Single}. - /// + /// Converts a Vector<Int32> to a Vector<Single>. /// The source vector. /// The converted vector. [Intrinsic] @@ -1297,9 +1128,7 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Converts a Vector{UInt32} to a Vector{Single}. - /// + /// Converts a Vector<UInt32> to a Vector<Single>. /// The source vector. /// The converted vector. [CLSCompliant(false)] @@ -1316,9 +1145,7 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Converts a Vector{Int64} to a Vector{Double}. - /// + /// Converts a Vector<Int64> to a Vector<Double>. /// The source vector. /// The converted vector. [Intrinsic] @@ -1334,9 +1161,7 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Converts a Vector{UInt64} to a Vector{Double}. - /// + /// Converts a Vector<UInt64> to a Vector<Double>. /// The source vector. /// The converted vector. [CLSCompliant(false)] @@ -1353,9 +1178,7 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Converts a Vector{Single} to a Vector{Int32}. - /// + /// Converts a Vector<Single> to a Vector<Int32>. /// The source vector. /// The converted vector. [Intrinsic] @@ -1371,9 +1194,7 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Converts a Vector{Single} to a Vector{UInt32}. - /// + /// Converts a Vector<Single> to a Vector<UInt32>. /// The source vector. /// The converted vector. [CLSCompliant(false)] @@ -1390,9 +1211,7 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Converts a Vector{Double} to a Vector{Int64}. - /// + /// Converts a Vector<Double> to a Vector<Int64>. /// The source vector. /// The converted vector. [Intrinsic] @@ -1408,9 +1227,7 @@ namespace System.Numerics return *(Vector*)retPtr; } - /// - /// Converts a Vector{Double} to a Vector{UInt64}. - /// + /// Converts a Vector<Double> to a Vector<UInt64>. /// The source vector. /// The converted vector. [CLSCompliant(false)] diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector2.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector2.cs index e1e5bce..b20b73a 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector2.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector2.cs @@ -8,7 +8,11 @@ using System.Text; namespace System.Numerics { - /// A structure encapsulating two single precision floating point values and provides hardware accelerated methods. + /// Represents a vector with two single-precision floating-point values. + /// structure provides support for hardware acceleration. + /// [!INCLUDE[vectors-are-rows-paragraph](~/includes/system-numerics-vectors-are-rows.md)] + /// ]]> [Intrinsic] public partial struct Vector2 : IEquatable, IFormattable { @@ -18,16 +22,16 @@ namespace System.Numerics /// The Y component of the vector. public float Y; - /// Constructs a vector whose elements are all the single specified value. - /// The element to fill the vector with. + /// Creates a new object whose two elements have the same value. + /// The value to assign to both elements. [Intrinsic] public Vector2(float value) : this(value, value) { } - /// Constructs a vector with the given individual elements. - /// The X component. - /// The Y component. + /// Creates a vector whose elements have the specified values. + /// The value to assign to the field. + /// The value to assign to the field. [Intrinsic] public Vector2(float x, float y) { @@ -35,36 +39,41 @@ namespace System.Numerics Y = y; } - /// Returns the vector (0,0). + /// Returns a vector whose 2 elements are equal to zero. + /// A vector whose two elements are equal to zero (that is, it returns the vector (0,0). public static Vector2 Zero { [Intrinsic] get => default; } - /// Returns the vector (1,1). + /// Gets a vector whose 2 elements are equal to one. + /// A vector whose two elements are equal to one (that is, it returns the vector (1,1). public static Vector2 One { [Intrinsic] get => new Vector2(1.0f); } - /// Returns the vector (1,0). + /// Gets the vector (1,0). + /// The vector (1,0). public static Vector2 UnitX { get => new Vector2(1.0f, 0.0f); } - /// Returns the vector (0,1). + /// Gets the vector (0,1). + /// The vector (0,1). public static Vector2 UnitY { get => new Vector2(0.0f, 1.0f); } /// Adds two vectors together. - /// The first source vector. - /// The second source vector. + /// The first vector to add. + /// The second vector to add. /// The summed vector. + /// The method defines the addition operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 operator +(Vector2 left, Vector2 right) @@ -76,9 +85,10 @@ namespace System.Numerics } /// Divides the first vector by the second. - /// The first source vector. - /// The second source vector. - /// The vector resulting from the division. + /// The first vector. + /// The second vector. + /// The vector that results from dividing by . + /// The method defines the division operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 operator /(Vector2 left, Vector2 right) @@ -89,20 +99,22 @@ namespace System.Numerics ); } - /// Divides the vector by the given scalar. - /// The source vector. + /// Divides the specified vector by a specified scalar value. + /// The vector. /// The scalar value. /// The result of the division. + /// The method defines the division operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 operator /(Vector2 value1, float value2) { return value1 / new Vector2(value2); } - /// Returns a boolean indicating whether the two given vectors are equal. + /// Returns a value that indicates whether each pair of elements in two specified vectors is equal. /// The first vector to compare. /// The second vector to compare. - /// True if the vectors are equal; False otherwise. + /// if and are equal; otherwise, . + /// Two objects are equal if each value in is equal to the corresponding value in . [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool operator ==(Vector2 left, Vector2 right) @@ -111,10 +123,10 @@ namespace System.Numerics && (left.Y == right.Y); } - /// Returns a boolean indicating whether the two given vectors are not equal. + /// Returns a value that indicates whether two specified vectors are not equal. /// The first vector to compare. /// The second vector to compare. - /// True if the vectors are not equal; False if they are equal. + /// if and are not equal; otherwise, . [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool operator !=(Vector2 left, Vector2 right) @@ -122,10 +134,11 @@ namespace System.Numerics return !(left == right); } - /// Multiplies two vectors together. - /// The first source vector. - /// The second source vector. - /// The product vector. + /// Returns a new vector whose values are the product of each pair of elements in two specified vectors. + /// The first vector. + /// The second vector. + /// The element-wise product vector. + /// The method defines the multiplication operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 operator *(Vector2 left, Vector2 right) @@ -136,20 +149,22 @@ namespace System.Numerics ); } - /// Multiplies a vector by the given scalar. - /// The source vector. + /// Multiplies the specified vector by the specified scalar value. + /// The vector. /// The scalar value. /// The scaled vector. + /// The method defines the multiplication operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 operator *(Vector2 left, float right) { return left * new Vector2(right); } - /// Multiplies a vector by the given scalar. - /// The scalar value. - /// The source vector. + /// Multiplies the scalar value by the specified vector. + /// The vector. + /// The scalar value. /// The scaled vector. + /// The method defines the multiplication operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 operator *(float left, Vector2 right) { @@ -157,9 +172,10 @@ namespace System.Numerics } /// Subtracts the second vector from the first. - /// The first source vector. - /// The second source vector. - /// The difference vector. + /// The first vector. + /// The second vector. + /// The vector that results from subtracting from . + /// The method defines the subtraction operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 operator -(Vector2 left, Vector2 right) @@ -170,17 +186,18 @@ namespace System.Numerics ); } - /// Negates a given vector. - /// The source vector. + /// Negates the specified vector. + /// The vector to negate. /// The negated vector. + /// The method defines the unary negation operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 operator -(Vector2 value) { return Zero - value; } - /// Returns a vector whose elements are the absolute values of each of the source vector's elements. - /// The source vector. + /// Returns a vector whose elements are the absolute values of each of the specified vector's elements. + /// A vector. /// The absolute value vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -193,8 +210,8 @@ namespace System.Numerics } /// Adds two vectors together. - /// The first source vector. - /// The second source vector. + /// The first vector to add. + /// The second vector to add. /// The summed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Add(Vector2 left, Vector2 right) @@ -202,10 +219,11 @@ namespace System.Numerics return left + right; } - /// Restricts a vector between a min and max value. - /// The source vector. + /// Restricts a vector between a minimum and a maximum value. + /// The vector to restrict. /// The minimum value. /// The maximum value. + /// The restricted vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Clamp(Vector2 value1, Vector2 min, Vector2 max) { @@ -213,7 +231,7 @@ namespace System.Numerics return Min(Max(value1, min), max); } - /// Returns the Euclidean distance between the two given points. + /// Computes the Euclidean distance between the two given points. /// The first point. /// The second point. /// The distance. @@ -224,7 +242,7 @@ namespace System.Numerics return MathF.Sqrt(distanceSquared); } - /// Returns the Euclidean distance squared between the two given points. + /// Returns the Euclidean distance squared between two specified points. /// The first point. /// The second point. /// The distance squared. @@ -236,8 +254,8 @@ namespace System.Numerics } /// Divides the first vector by the second. - /// The first source vector. - /// The second source vector. + /// The first vector. + /// The second vector. /// The vector resulting from the division. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Divide(Vector2 left, Vector2 right) @@ -245,10 +263,10 @@ namespace System.Numerics return left / right; } - /// Divides the vector by the given scalar. - /// The source vector. + /// Divides the specified vector by a specified scalar value. + /// The vector. /// The scalar value. - /// The result of the division. + /// The vector that results from the division. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Divide(Vector2 left, float divisor) { @@ -267,21 +285,24 @@ namespace System.Numerics + (value1.Y * value2.Y); } - /// Linearly interpolates between two vectors based on the given weighting. - /// The first source vector. - /// The second source vector. - /// Value between 0 and 1 indicating the weight of the second source vector. + /// Performs a linear interpolation between two vectors based on the given weighting. + /// The first vector. + /// The second vector. + /// A value between 0 and 1 that indicates the weight of . /// The interpolated vector. + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Lerp(Vector2 value1, Vector2 value2, float amount) { return (value1 * (1.0f - amount)) + (value2 * amount); } - /// Returns a vector whose elements are the maximum of each of the pairs of elements in the two source vectors - /// The first source vector - /// The second source vector - /// The maximized vector + /// Returns a vector whose elements are the maximum of each of the pairs of elements in two specified vectors. + /// The first vector. + /// The second vector. + /// The maximized vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Max(Vector2 value1, Vector2 value2) @@ -292,9 +313,9 @@ namespace System.Numerics ); } - /// Returns a vector whose elements are the minimum of each of the pairs of elements in the two source vectors. - /// The first source vector. - /// The second source vector. + /// Returns a vector whose elements are the minimum of each of the pairs of elements in two specified vectors. + /// The first vector. + /// The second vector. /// The minimized vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -306,18 +327,18 @@ namespace System.Numerics ); } - /// Multiplies two vectors together. - /// The first source vector. - /// The second source vector. - /// The product vector. + /// Returns a new vector whose values are the product of each pair of elements in two specified vectors. + /// The first vector. + /// The second vector. + /// The element-wise product vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Multiply(Vector2 left, Vector2 right) { return left * right; } - /// Multiplies a vector by the given scalar. - /// The source vector. + /// Multiplies a vector by a specified scalar. + /// The vector to multiply. /// The scalar value. /// The scaled vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -326,9 +347,9 @@ namespace System.Numerics return left * right; } - /// Multiplies a vector by the given scalar. - /// The scalar value. - /// The source vector. + /// Multiplies a scalar value by a specified vector. + /// The scaled value. + /// The vector. /// The scaled vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Multiply(float left, Vector2 right) @@ -336,8 +357,8 @@ namespace System.Numerics return left * right; } - /// Negates a given vector. - /// The source vector. + /// Negates a specified vector. + /// The vector to negate. /// The negated vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Negate(Vector2 value) @@ -345,7 +366,7 @@ namespace System.Numerics return -value; } - /// Returns a vector with the same direction as the given vector, but with a length of 1. + /// Returns a vector with the same direction as the specified vector, but with a length of one. /// The vector to normalize. /// The normalized vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -365,8 +386,8 @@ namespace System.Numerics return vector - (2 * dot * normal); } - /// Returns a vector whose elements are the square root of each of the source vector's elements. - /// The source vector. + /// Returns a vector whose elements are the square root of each of a specified vector's elements. + /// A vector. /// The square root vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -379,8 +400,8 @@ namespace System.Numerics } /// Subtracts the second vector from the first. - /// The first source vector. - /// The second source vector. + /// The first vector. + /// The second vector. /// The difference vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 Subtract(Vector2 left, Vector2 right) @@ -388,8 +409,8 @@ namespace System.Numerics return left - right; } - /// Transforms a vector by the given matrix. - /// The source vector. + /// Transforms a vector by a specified 3x2 matrix. + /// The vector to transform. /// The transformation matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -401,8 +422,8 @@ namespace System.Numerics ); } - /// Transforms a vector by the given matrix. - /// The source vector. + /// Transforms a vector by a specified 4x4 matrix. + /// The vector to transform. /// The transformation matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -414,8 +435,8 @@ namespace System.Numerics ); } - /// Transforms a vector by the given Quaternion rotation value. - /// The source vector to be rotated. + /// Transforms a vector by the specified Quaternion rotation value. + /// The vector to rotate. /// The rotation to apply. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -437,9 +458,9 @@ namespace System.Numerics ); } - /// Transforms a vector normal by the given matrix. + /// Transforms a vector normal by the given 3x2 matrix. /// The source vector. - /// The transformation matrix. + /// The matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 TransformNormal(Vector2 normal, Matrix3x2 matrix) @@ -450,9 +471,9 @@ namespace System.Numerics ); } - /// Transforms a vector normal by the given matrix. + /// Transforms a vector normal by the given 4x4 matrix. /// The source vector. - /// The transformation matrix. + /// The matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector2 TransformNormal(Vector2 normal, Matrix4x4 matrix) @@ -463,8 +484,12 @@ namespace System.Numerics ); } - /// Copies the contents of the vector into the given array. + /// Copies the elements of the vector to a specified array. /// The destination array. + /// must have at least two elements. The method copies the vector's elements starting at index 0. + /// is . + /// The number of elements in the current instance is greater than in the array. + /// is multidimensional. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly void CopyTo(float[] array) @@ -472,11 +497,16 @@ namespace System.Numerics CopyTo(array, 0); } - /// Copies the contents of the vector into the given array, starting from the given index. - /// If array is null. - /// If array is multidimensional. - /// If index is greater than end of the array or index is less than zero. - /// If number of elements in source vector is greater than those available in destination array or if there are not enough elements to copy. + /// Copies the elements of the vector to a specified array starting at a specified index position. + /// The destination array. + /// The index at which to copy the first element of the vector. + /// must have a sufficient number of elements to accommodate the two vector elements. In other words, elements and + 1 must already exist in . + /// is . + /// The number of elements in the current instance is greater than in the array. + /// is less than zero. + /// -or- + /// is greater than or equal to the array length. + /// is multidimensional. [Intrinsic] public readonly void CopyTo(float[] array, int index) { @@ -500,18 +530,20 @@ namespace System.Numerics array[index + 1] = Y; } - /// Returns a boolean indicating whether the given Object is equal to this Vector2 instance. - /// The Object to compare against. - /// True if the Object is equal to this Vector2; False otherwise. + /// Returns a value that indicates whether this instance and a specified object are equal. + /// The object to compare with the current instance. + /// if the current instance and are equal; otherwise, . If is , the method returns . + /// The current instance and are equal if is a object and their and elements are equal. [MethodImpl(MethodImplOptions.AggressiveInlining)] public override readonly bool Equals([NotNullWhen(true)] object? obj) { return (obj is Vector2 other) && Equals(other); } - /// Returns a boolean indicating whether the given Vector2 is equal to this Vector2 instance. - /// The Vector2 to compare this instance to. - /// True if the other Vector2 is equal to this instance; False otherwise. + /// Returns a value that indicates whether this instance and another vector are equal. + /// The other vector. + /// if the two vectors are equal; otherwise, . + /// Two vectors are equal if their and elements are equal. [Intrinsic] public readonly bool Equals(Vector2 other) { @@ -527,6 +559,7 @@ namespace System.Numerics /// Returns the length of the vector. /// The vector's length. + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly float Length() { @@ -534,33 +567,42 @@ namespace System.Numerics return MathF.Sqrt(lengthSquared); } - /// Returns the length of the vector squared. This operation is cheaper than Length(). + /// Returns the length of the vector squared. /// The vector's length squared. + /// This operation offers better performance than a call to the method. + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly float LengthSquared() { return Dot(this, this); } - /// Returns a String representing this Vector2 instance. - /// The string representation. + /// Returns the string representation of the current instance using default formatting. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current thread culture. The "<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. public override readonly string ToString() { return ToString("G", CultureInfo.CurrentCulture); } - /// Returns a String representing this Vector2 instance, using the specified format to format individual elements. - /// The format of individual elements. - /// The string representation. + /// Returns the string representation of the current instance using the specified format string to format individual elements. + /// A standard or custom numeric format string that defines the format of individual elements. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using and the current culture's formatting conventions. The "<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + /// Standard Numeric Format Strings + /// Custom Numeric Format Strings public readonly string ToString(string? format) { return ToString(format, CultureInfo.CurrentCulture); } - /// Returns a String representing this Vector2 instance, using the specified format to format individual elements and the given IFormatProvider. - /// The format of individual elements. - /// The format provider to use when formatting elements. - /// The string representation. + /// Returns the string representation of the current instance using the specified format string to format individual elements and the specified format provider to define culture-specific formatting. + /// A standard or custom numeric format string that defines the format of individual elements. + /// A format provider that supplies culture-specific formatting information. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using and . The "<" and ">" characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + /// Custom Numeric Format Strings + /// Standard Numeric Format Strings public readonly string ToString(string? format, IFormatProvider? formatProvider) { StringBuilder sb = new StringBuilder(); diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector3.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector3.cs index 8d76f77..bb34093 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector3.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector3.cs @@ -8,9 +8,11 @@ using System.Text; namespace System.Numerics { - /// - /// A structure encapsulating three single precision floating point values and provides hardware accelerated methods. - /// + /// Represents a vector with three single-precision floating-point values. + /// structure provides support for hardware acceleration. + /// [!INCLUDE[vectors-are-rows-paragraph](~/includes/system-numerics-vectors-are-rows.md)] + /// ]]> [Intrinsic] public partial struct Vector3 : IEquatable, IFormattable { @@ -23,25 +25,25 @@ namespace System.Numerics /// The Z component of the vector. public float Z; - /// Constructs a vector whose elements are all the single specified value. - /// The element to fill the vector with. + /// Creates a new object whose three elements have the same value. + /// The value to assign to all three elements. [Intrinsic] public Vector3(float value) : this(value, value, value) { } - /// Constructs a Vector3 from the given Vector2 and a third value. - /// The Vector to extract X and Y components from. - /// The Z component. + /// Creates a new object from the specified object and the specified value. + /// The vector with two elements. + /// The additional value to assign to the field. [Intrinsic] public Vector3(Vector2 value, float z) : this(value.X, value.Y, z) { } - /// Constructs a vector with the given individual elements. - /// The X component. - /// The Y component. - /// The Z component. + /// Creates a vector whose elements have the specified values. + /// The value to assign to the field. + /// The value to assign to the field. + /// The value to assign to the field. [Intrinsic] public Vector3(float x, float y, float z) { @@ -50,42 +52,48 @@ namespace System.Numerics Z = z; } - /// Returns the vector (0,0,0). + /// Gets a vector whose 3 elements are equal to zero. + /// A vector whose three elements are equal to zero (that is, it returns the vector (0,0,0). public static Vector3 Zero { [Intrinsic] get => default; } - /// Returns the vector (1,1,1). + /// Gets a vector whose 3 elements are equal to one. + /// A vector whose three elements are equal to one (that is, it returns the vector (1,1,1). public static Vector3 One { [Intrinsic] get => new Vector3(1.0f); } - /// Returns the vector (1,0,0). + /// Gets the vector (1,0,0). + /// The vector (1,0,0). public static Vector3 UnitX { get => new Vector3(1.0f, 0.0f, 0.0f); } - /// Returns the vector (0,1,0). + /// Gets the vector (0,1,0). + /// The vector (0,1,0). public static Vector3 UnitY { get => new Vector3(0.0f, 1.0f, 0.0f); } - /// Returns the vector (0,0,1). + /// Gets the vector (0,0,1). + /// The vector (0,0,1). public static Vector3 UnitZ { get => new Vector3(0.0f, 0.0f, 1.0f); } /// Adds two vectors together. - /// The first source vector. - /// The second source vector. + /// The first vector to add. + /// The second vector to add. /// The summed vector. + /// The method defines the addition operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 operator +(Vector3 left, Vector3 right) @@ -98,9 +106,10 @@ namespace System.Numerics } /// Divides the first vector by the second. - /// The first source vector. - /// The second source vector. - /// The vector resulting from the division. + /// The first vector. + /// The second vector. + /// The vector that results from dividing by . + /// The method defines the division operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 operator /(Vector3 left, Vector3 right) @@ -112,20 +121,22 @@ namespace System.Numerics ); } - /// Divides the vector by the given scalar. - /// The source vector. + /// Divides the specified vector by a specified scalar value. + /// The vector. /// The scalar value. /// The result of the division. + /// The method defines the division operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 operator /(Vector3 value1, float value2) { return value1 / new Vector3(value2); } - /// Returns a boolean indicating whether the two given vectors are equal. + /// Returns a value that indicates whether each pair of elements in two specified vectors is equal. /// The first vector to compare. /// The second vector to compare. - /// True if the vectors are equal; False otherwise. + /// if and are equal; otherwise, . + /// Two objects are equal if each element in is equal to the corresponding element in . [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool operator ==(Vector3 left, Vector3 right) @@ -135,10 +146,10 @@ namespace System.Numerics && (left.Z == right.Z); } - /// Returns a boolean indicating whether the two given vectors are not equal. + /// Returns a value that indicates whether two specified vectors are not equal. /// The first vector to compare. /// The second vector to compare. - /// True if the vectors are not equal; False if they are equal. + /// if and are not equal; otherwise, . [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool operator !=(Vector3 left, Vector3 right) @@ -146,10 +157,11 @@ namespace System.Numerics return !(left == right); } - /// Multiplies two vectors together. - /// The first source vector. - /// The second source vector. - /// The product vector. + /// Returns a new vector whose values are the product of each pair of elements in two specified vectors. + /// The first vector. + /// The second vector. + /// The element-wise product vector. + /// The method defines the multiplication operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 operator *(Vector3 left, Vector3 right) @@ -161,20 +173,22 @@ namespace System.Numerics ); } - /// Multiplies a vector by the given scalar. - /// The source vector. + /// Multiplies the specified vector by the specified scalar value. + /// The vector. /// The scalar value. /// The scaled vector. + /// The method defines the multiplication operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 operator *(Vector3 left, float right) { return left * new Vector3(right); } - /// Multiplies a vector by the given scalar. - /// The scalar value. - /// The source vector. + /// Multiplies the scalar value by the specified vector. + /// The vector. + /// The scalar value. /// The scaled vector. + /// The method defines the multiplication operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 operator *(float left, Vector3 right) { @@ -182,9 +196,10 @@ namespace System.Numerics } /// Subtracts the second vector from the first. - /// The first source vector. - /// The second source vector. - /// The difference vector. + /// The first vector. + /// The second vector. + /// The vector that results from subtracting from . + /// The method defines the subtraction operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 operator -(Vector3 left, Vector3 right) @@ -196,17 +211,18 @@ namespace System.Numerics ); } - /// Negates a given vector. - /// The source vector. + /// Negates the specified vector. + /// The vector to negate. /// The negated vector. + /// The method defines the unary negation operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 operator -(Vector3 value) { return Zero - value; } - /// Returns a vector whose elements are the absolute values of each of the source vector's elements. - /// The source vector. + /// Returns a vector whose elements are the absolute values of each of the specified vector's elements. + /// A vector. /// The absolute value vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -220,8 +236,8 @@ namespace System.Numerics } /// Adds two vectors together. - /// The first source vector. - /// The second source vector. + /// The first vector to add. + /// The second vector to add. /// The summed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 Add(Vector3 left, Vector3 right) @@ -229,8 +245,8 @@ namespace System.Numerics return left + right; } - /// Restricts a vector between a min and max value. - /// The source vector. + /// Restricts a vector between a minimum and a maximum value. + /// The vector to restrict. /// The minimum value. /// The maximum value. /// The restricted vector. @@ -255,7 +271,7 @@ namespace System.Numerics ); } - /// Returns the Euclidean distance between the two given points. + /// Computes the Euclidean distance between the two given points. /// The first point. /// The second point. /// The distance. @@ -266,7 +282,7 @@ namespace System.Numerics return MathF.Sqrt(distanceSquared); } - /// Returns the Euclidean distance squared between the two given points. + /// Returns the Euclidean distance squared between two specified points. /// The first point. /// The second point. /// The distance squared. @@ -278,8 +294,8 @@ namespace System.Numerics } /// Divides the first vector by the second. - /// The first source vector. - /// The second source vector. + /// The first vector. + /// The second vector. /// The vector resulting from the division. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 Divide(Vector3 left, Vector3 right) @@ -287,10 +303,10 @@ namespace System.Numerics return left / right; } - /// Divides the vector by the given scalar. - /// The source vector. + /// Divides the specified vector by a specified scalar value. + /// The vector. /// The scalar value. - /// The result of the division. + /// The vector that results from the division. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 Divide(Vector3 left, float divisor) { @@ -310,10 +326,10 @@ namespace System.Numerics + (vector1.Z * vector2.Z); } - /// Linearly interpolates between two vectors based on the given weighting. - /// The first source vector. - /// The second source vector. - /// Value between 0 and 1 indicating the weight of the second source vector. + /// Performs a linear interpolation between two vectors based on the given weighting. + /// The first vector. + /// The second vector. + /// A value between 0 and 1 that indicates the weight of . /// The interpolated vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 Lerp(Vector3 value1, Vector3 value2, float amount) @@ -321,9 +337,9 @@ namespace System.Numerics return (value1 * (1f - amount)) + (value2 * amount); } - /// Returns a vector whose elements are the maximum of each of the pairs of elements in the two source vectors. - /// The first source vector. - /// The second source vector. + /// Returns a vector whose elements are the maximum of each of the pairs of elements in two specified vectors. + /// The first vector. + /// The second vector. /// The maximized vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -336,9 +352,9 @@ namespace System.Numerics ); } - /// Returns a vector whose elements are the minimum of each of the pairs of elements in the two source vectors. - /// The first source vector. - /// The second source vector. + /// Returns a vector whose elements are the minimum of each of the pairs of elements in two specified vectors. + /// The first vector. + /// The second vector. /// The minimized vector. [Intrinsic] public static Vector3 Min(Vector3 value1, Vector3 value2) @@ -350,18 +366,18 @@ namespace System.Numerics ); } - /// Multiplies two vectors together. - /// The first source vector. - /// The second source vector. - /// The product vector. + /// Returns a new vector whose values are the product of each pair of elements in two specified vectors. + /// The first vector. + /// The second vector. + /// The element-wise product vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 Multiply(Vector3 left, Vector3 right) { return left * right; } - /// Multiplies a vector by the given scalar. - /// The source vector. + /// Multiplies a vector by a specified scalar. + /// The vector to multiply. /// The scalar value. /// The scaled vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -370,9 +386,9 @@ namespace System.Numerics return left * right; } - /// Multiplies a vector by the given scalar. - /// The scalar value. - /// The source vector. + /// Multiplies a scalar value by a specified vector. + /// The scaled value. + /// The vector. /// The scaled vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 Multiply(float left, Vector3 right) @@ -380,8 +396,8 @@ namespace System.Numerics return left * right; } - /// Negates a given vector. - /// The source vector. + /// Negates a specified vector. + /// The vector to negate. /// The negated vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 Negate(Vector3 value) @@ -389,7 +405,7 @@ namespace System.Numerics return -value; } - /// Returns a vector with the same direction as the given vector, but with a length of 1. + /// Returns a vector with the same direction as the specified vector, but with a length of one. /// The vector to normalize. /// The normalized vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -409,8 +425,8 @@ namespace System.Numerics return vector - (2 * dot * normal); } - /// Returns a vector whose elements are the square root of each of the source vector's elements. - /// The source vector. + /// Returns a vector whose elements are the square root of each of a specified vector's elements. + /// A vector. /// The square root vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -424,8 +440,8 @@ namespace System.Numerics } /// Subtracts the second vector from the first. - /// The first source vector. - /// The second source vector. + /// The first vector. + /// The second vector. /// The difference vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 Subtract(Vector3 left, Vector3 right) @@ -433,8 +449,8 @@ namespace System.Numerics return left - right; } - /// Transforms a vector by the given matrix. - /// The source vector. + /// Transforms a vector by a specified 4x4 matrix. + /// The vector to transform. /// The transformation matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -447,8 +463,8 @@ namespace System.Numerics ); } - /// Transforms a vector by the given Quaternion rotation value. - /// The source vector to be rotated. + /// Transforms a vector by the specified Quaternion rotation value. + /// The vector to rotate. /// The rotation to apply. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -475,9 +491,9 @@ namespace System.Numerics ); } - /// Transforms a vector normal by the given matrix. + /// Transforms a vector normal by the given 4x4 matrix. /// The source vector. - /// The transformation matrix. + /// The matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector3 TransformNormal(Vector3 normal, Matrix4x4 matrix) @@ -489,7 +505,12 @@ namespace System.Numerics ); } - /// Copies the contents of the vector into the given array. + /// Copies the elements of the vector to a specified array. + /// The destination array. + /// must have at least three elements. The method copies the vector's elements starting at index 0. + /// is . + /// The number of elements in the current instance is greater than in the array. + /// is multidimensional. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly void CopyTo(float[] array) @@ -497,11 +518,16 @@ namespace System.Numerics CopyTo(array, 0); } - /// Copies the contents of the vector into the given array, starting from index. - /// If array is null. - /// If array is multidimensional. - /// If index is greater than end of the array or index is less than zero. - /// If number of elements in source vector is greater than those available in destination array. + /// Copies the elements of the vector to a specified array starting at a specified index position. + /// The destination array. + /// The index at which to copy the first element of the vector. + /// must have a sufficient number of elements to accommodate the three vector elements. In other words, elements , + 1, and + 2 must already exist in . + /// is . + /// The number of elements in the current instance is greater than in the array. + /// is less than zero. + /// -or- + /// is greater than or equal to the array length. + /// is multidimensional. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly void CopyTo(float[] array, int index) @@ -527,18 +553,20 @@ namespace System.Numerics array[index + 2] = Z; } - /// Returns a boolean indicating whether the given Object is equal to this Vector3 instance. - /// The Object to compare against. - /// True if the Object is equal to this Vector3; False otherwise. + /// Returns a value that indicates whether this instance and a specified object are equal. + /// The object to compare with the current instance. + /// if the current instance and are equal; otherwise, . If is , the method returns . + /// The current instance and are equal if is a object and their corresponding elements are equal. [MethodImpl(MethodImplOptions.AggressiveInlining)] public override readonly bool Equals([NotNullWhen(true)] object? obj) { return (obj is Vector3 other) && Equals(other); } - /// Returns a boolean indicating whether the given Vector3 is equal to this Vector3 instance. - /// The Vector3 to compare this instance to. - /// True if the other Vector3 is equal to this instance; False otherwise. + /// Returns a value that indicates whether this instance and another vector are equal. + /// The other vector. + /// if the two vectors are equal; otherwise, . + /// Two vectors are equal if their , , and elements are equal. [Intrinsic] public readonly bool Equals(Vector3 other) { @@ -552,8 +580,9 @@ namespace System.Numerics return HashCode.Combine(X, Y, Z); } - /// Returns the length of the vector. + /// Returns the length of this vector object. /// The vector's length. + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly float Length() { @@ -561,33 +590,42 @@ namespace System.Numerics return MathF.Sqrt(lengthSquared); } - /// Returns the length of the vector squared. This operation is cheaper than Length(). + /// Returns the length of the vector squared. /// The vector's length squared. + /// This operation offers better performance than a call to the method. + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly float LengthSquared() { return Dot(this, this); } - /// Returns a String representing this Vector3 instance. - /// The string representation. + /// Returns the string representation of the current instance using default formatting. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current thread culture. The "<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. public override readonly string ToString() { return ToString("G", CultureInfo.CurrentCulture); } - /// Returns a String representing this Vector3 instance, using the specified format to format individual elements. - /// The format of individual elements. - /// The string representation. + /// Returns the string representation of the current instance using the specified format string to format individual elements. + /// A standard or custom numeric format string that defines the format of individual elements. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using and the current culture's formatting conventions. The "<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + /// Standard Numeric Format Strings + /// Custom Numeric Format Strings public readonly string ToString(string? format) { return ToString(format, CultureInfo.CurrentCulture); } - /// Returns a String representing this Vector3 instance, using the specified format to format individual elements and the given IFormatProvider. - /// The format of individual elements. - /// The format provider to use when formatting elements. - /// The string representation. + /// Returns the string representation of the current instance using the specified format string to format individual elements and the specified format provider to define culture-specific formatting. + /// A standard or custom numeric format string that defines the format of individual elements. + /// A format provider that supplies culture-specific formatting information. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using and . The "<" and ">" characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + /// Standard Numeric Format Strings + /// Custom Numeric Format Strings public readonly string ToString(string? format, IFormatProvider? formatProvider) { StringBuilder sb = new StringBuilder(); diff --git a/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector4.cs b/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector4.cs index 595a2bc..c376d53 100644 --- a/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector4.cs +++ b/src/libraries/System.Private.CoreLib/src/System/Numerics/Vector4.cs @@ -8,7 +8,11 @@ using System.Text; namespace System.Numerics { - /// A structure encapsulating four single precision floating point values and provides hardware accelerated methods. + /// Represents a vector with four single-precision floating-point values. + /// structure provides support for hardware acceleration. + /// [!INCLUDE[vectors-are-rows-paragraph](~/includes/system-numerics-vectors-are-rows.md)] + /// ]]> [Intrinsic] public partial struct Vector4 : IEquatable, IFormattable { @@ -24,15 +28,15 @@ namespace System.Numerics /// The W component of the vector. public float W; - /// Constructs a vector whose elements are all the single specified value. - /// The element to fill the vector with. + /// Creates a new object whose four elements have the same value. + /// The value to assign to all four elements. [Intrinsic] public Vector4(float value) : this(value, value, value, value) { } - /// Constructs a Vector4 from the given Vector2 and a Z and W component. - /// The vector to use as the X and Y components. + /// Creates a new object from the specified object and a Z and a W component. + /// The vector to use for the X and Y components. /// The Z component. /// The W component. [Intrinsic] @@ -40,19 +44,19 @@ namespace System.Numerics { } - /// Constructs a Vector4 from the given Vector3 and a W component. - /// The vector to use as the X, Y, and Z components. + /// Constructs a new object from the specified object and a W component. + /// The vector to use for the X, Y, and Z components. /// The W component. [Intrinsic] public Vector4(Vector3 value, float w) : this(value.X, value.Y, value.Z, w) { } - /// Constructs a vector with the given individual elements. - /// W component. - /// X component. - /// Y component. - /// Z component. + /// Creates a vector whose elements have the specified values. + /// The value to assign to the field. + /// The value to assign to the field. + /// The value to assign to the field. + /// The value to assign to the field. [Intrinsic] public Vector4(float x, float y, float z, float w) { @@ -62,48 +66,56 @@ namespace System.Numerics W = w; } - /// Returns the vector (0,0,0,0). + /// Gets a vector whose 4 elements are equal to zero. + /// A vector whose four elements are equal to zero (that is, it returns the vector (0,0,0,0). public static Vector4 Zero { [Intrinsic] get => default; } - /// Returns the vector (1,1,1,1). + /// Gets a vector whose 4 elements are equal to one. + /// Returns . + /// A vector whose four elements are equal to one (that is, it returns the vector (1,1,1,1). public static Vector4 One { [Intrinsic] get => new Vector4(1.0f); } - /// Returns the vector (1,0,0,0). + /// Gets the vector (1,0,0,0). + /// The vector (1,0,0,0). public static Vector4 UnitX { get => new Vector4(1.0f, 0.0f, 0.0f, 0.0f); } - /// Returns the vector (0,1,0,0). + /// Gets the vector (0,1,0,0). + /// The vector (0,1,0,0). public static Vector4 UnitY { get => new Vector4(0.0f, 1.0f, 0.0f, 0.0f); } - /// Returns the vector (0,0,1,0). + /// Gets the vector (0,0,1,0). + /// The vector (0,0,1,0). public static Vector4 UnitZ { get => new Vector4(0.0f, 0.0f, 1.0f, 0.0f); } - /// Returns the vector (0,0,0,1). + /// Gets the vector (0,0,0,1). + /// The vector (0,0,0,1). public static Vector4 UnitW { get => new Vector4(0.0f, 0.0f, 0.0f, 1.0f); } /// Adds two vectors together. - /// The first source vector. - /// The second source vector. + /// The first vector to add. + /// The second vector to add. /// The summed vector. + /// The method defines the addition operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 operator +(Vector4 left, Vector4 right) @@ -117,9 +129,10 @@ namespace System.Numerics } /// Divides the first vector by the second. - /// The first source vector. - /// The second source vector. - /// The vector resulting from the division. + /// The first vector. + /// The second vector. + /// The vector that results from dividing by . + /// The method defines the division operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 operator /(Vector4 left, Vector4 right) @@ -132,20 +145,22 @@ namespace System.Numerics ); } - /// Divides the vector by the given scalar. - /// The source vector. + /// Divides the specified vector by a specified scalar value. + /// The vector. /// The scalar value. /// The result of the division. + /// The method defines the division operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 operator /(Vector4 value1, float value2) { return value1 / new Vector4(value2); } - /// Returns a boolean indicating whether the two given vectors are equal. + /// Returns a value that indicates whether each pair of elements in two specified vectors is equal. /// The first vector to compare. /// The second vector to compare. - /// True if the vectors are equal; False otherwise. + /// if and are equal; otherwise, . + /// Two objects are equal if each element in is equal to the corresponding element in . [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool operator ==(Vector4 left, Vector4 right) @@ -156,10 +171,10 @@ namespace System.Numerics && (left.W == right.W); } - /// Returns a boolean indicating whether the two given vectors are not equal. + /// Returns a value that indicates whether two specified vectors are not equal. /// The first vector to compare. /// The second vector to compare. - /// True if the vectors are not equal; False if they are equal. + /// if and are not equal; otherwise, . [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static bool operator !=(Vector4 left, Vector4 right) @@ -167,10 +182,11 @@ namespace System.Numerics return !(left == right); } - /// Multiplies two vectors together. - /// The first source vector. - /// The second source vector. - /// The product vector. + /// Returns a new vector whose values are the product of each pair of elements in two specified vectors. + /// The first vector. + /// The second vector. + /// The element-wise product vector. + /// The method defines the multiplication operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 operator *(Vector4 left, Vector4 right) @@ -183,20 +199,22 @@ namespace System.Numerics ); } - /// Multiplies a vector by the given scalar. - /// The source vector. + /// Multiplies the specified vector by the specified scalar value. + /// The vector. /// The scalar value. /// The scaled vector. + /// The method defines the multiplication operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 operator *(Vector4 left, float right) { return left * new Vector4(right); } - /// Multiplies a vector by the given scalar. - /// The scalar value. - /// The source vector. + /// Multiplies the scalar value by the specified vector. + /// The vector. + /// The scalar value. /// The scaled vector. + /// The method defines the multiplication operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 operator *(float left, Vector4 right) { @@ -204,9 +222,10 @@ namespace System.Numerics } /// Subtracts the second vector from the first. - /// The first source vector. - /// The second source vector. - /// The difference vector. + /// The first vector. + /// The second vector. + /// The vector that results from subtracting from . + /// The method defines the subtraction operation for objects. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 operator -(Vector4 left, Vector4 right) @@ -219,17 +238,18 @@ namespace System.Numerics ); } - /// Negates a given vector. - /// The source vector. + /// Negates the specified vector. + /// The vector to negate. /// The negated vector. + /// The method defines the unary negation operation for objects. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 operator -(Vector4 value) { return Zero - value; } - /// Returns a vector whose elements are the absolute values of each of the source vector's elements. - /// The source vector. + /// Returns a vector whose elements are the absolute values of each of the specified vector's elements. + /// A vector. /// The absolute value vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -244,8 +264,8 @@ namespace System.Numerics } /// Adds two vectors together. - /// The first source vector. - /// The second source vector. + /// The first vector to add. + /// The second vector to add. /// The summed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 Add(Vector4 left, Vector4 right) @@ -253,8 +273,8 @@ namespace System.Numerics return left + right; } - /// Restricts a vector between a min and max value. - /// The source vector. + /// Restricts a vector between a minimum and a maximum value. + /// The vector to restrict. /// The minimum value. /// The maximum value. /// The restricted vector. @@ -265,7 +285,7 @@ namespace System.Numerics return Min(Max(value1, min), max); } - /// Returns the Euclidean distance between the two given points. + /// Computes the Euclidean distance between the two given points. /// The first point. /// The second point. /// The distance. @@ -276,7 +296,7 @@ namespace System.Numerics return MathF.Sqrt(distanceSquared); } - /// Returns the Euclidean distance squared between the two given points. + /// Returns the Euclidean distance squared between two specified points. /// The first point. /// The second point. /// The distance squared. @@ -288,8 +308,8 @@ namespace System.Numerics } /// Divides the first vector by the second. - /// The first source vector. - /// The second source vector. + /// The first vector. + /// The second vector. /// The vector resulting from the division. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 Divide(Vector4 left, Vector4 right) @@ -297,10 +317,10 @@ namespace System.Numerics return left / right; } - /// Divides the vector by the given scalar. - /// The source vector. + /// Divides the specified vector by a specified scalar value. + /// The vector. /// The scalar value. - /// The result of the division. + /// The vector that results from the division. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 Divide(Vector4 left, float divisor) { @@ -321,20 +341,23 @@ namespace System.Numerics + (vector1.W * vector2.W); } - /// Linearly interpolates between two vectors based on the given weighting. - /// The first source vector. - /// The second source vector. - /// Value between 0 and 1 indicating the weight of the second source vector. + /// Performs a linear interpolation between two vectors based on the given weighting. + /// The first vector. + /// The second vector. + /// A value between 0 and 1 that indicates the weight of . /// The interpolated vector. + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 Lerp(Vector4 value1, Vector4 value2, float amount) { return (value1 * (1.0f - amount)) + (value2 * amount); } - /// Returns a vector whose elements are the maximum of each of the pairs of elements in the two source vectors. - /// The first source vector. - /// The second source vector. + /// Returns a vector whose elements are the maximum of each of the pairs of elements in two specified vectors. + /// The first vector. + /// The second vector. /// The maximized vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -348,9 +371,9 @@ namespace System.Numerics ); } - /// Returns a vector whose elements are the minimum of each of the pairs of elements in the two source vectors. - /// The first source vector. - /// The second source vector. + /// Returns a vector whose elements are the minimum of each of the pairs of elements in two specified vectors. + /// The first vector. + /// The second vector. /// The minimized vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -364,18 +387,18 @@ namespace System.Numerics ); } - /// Multiplies two vectors together. - /// The first source vector. - /// The second source vector. - /// The product vector. + /// Returns a new vector whose values are the product of each pair of elements in two specified vectors. + /// The first vector. + /// The second vector. + /// The element-wise product vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 Multiply(Vector4 left, Vector4 right) { return left * right; } - /// Multiplies a vector by the given scalar. - /// The source vector. + /// Multiplies a vector by a specified scalar. + /// The vector to multiply. /// The scalar value. /// The scaled vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -384,9 +407,9 @@ namespace System.Numerics return left * right; } - /// Multiplies a vector by the given scalar. - /// The scalar value. - /// The source vector. + /// Multiplies a scalar value by a specified vector. + /// The scaled value. + /// The vector. /// The scaled vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 Multiply(float left, Vector4 right) @@ -394,8 +417,8 @@ namespace System.Numerics return left * right; } - /// Negates a given vector. - /// The source vector. + /// Negates a specified vector. + /// The vector to negate. /// The negated vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 Negate(Vector4 value) @@ -403,7 +426,7 @@ namespace System.Numerics return -value; } - /// Returns a vector with the same direction as the given vector, but with a length of 1. + /// Returns a vector with the same direction as the specified vector, but with a length of one. /// The vector to normalize. /// The normalized vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -412,8 +435,8 @@ namespace System.Numerics return vector / vector.Length(); } - /// Returns a vector whose elements are the square root of each of the source vector's elements. - /// The source vector. + /// Returns a vector whose elements are the square root of each of a specified vector's elements. + /// A vector. /// The square root vector. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -428,8 +451,8 @@ namespace System.Numerics } /// Subtracts the second vector from the first. - /// The first source vector. - /// The second source vector. + /// The first vector. + /// The second vector. /// The difference vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] public static Vector4 Subtract(Vector4 left, Vector4 right) @@ -437,8 +460,8 @@ namespace System.Numerics return left - right; } - /// Transforms a vector by the given matrix. - /// The source vector. + /// Transforms a two-dimensional vector by a specified 4x4 matrix. + /// The vector to transform. /// The transformation matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -452,8 +475,8 @@ namespace System.Numerics ); } - /// Transforms a vector by the given Quaternion rotation value. - /// The source vector to be rotated. + /// Transforms a two-dimensional vector by the specified Quaternion rotation value. + /// The vector to rotate. /// The rotation to apply. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -481,8 +504,8 @@ namespace System.Numerics ); } - /// Transforms a vector by the given matrix. - /// The source vector. + /// Transforms a three-dimensional vector by a specified 4x4 matrix. + /// The vector to transform. /// The transformation matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -496,8 +519,8 @@ namespace System.Numerics ); } - /// Transforms a vector by the given Quaternion rotation value. - /// The source vector to be rotated. + /// Transforms a three-dimensional vector by the specified Quaternion rotation value. + /// The vector to rotate. /// The rotation to apply. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -525,8 +548,8 @@ namespace System.Numerics ); } - /// Transforms a vector by the given matrix. - /// The source vector. + /// Transforms a four-dimensional vector by a specified 4x4 matrix. + /// The vector to transform. /// The transformation matrix. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -540,8 +563,8 @@ namespace System.Numerics ); } - /// Transforms a vector by the given Quaternion rotation value. - /// The source vector to be rotated. + /// Transforms a four-dimensional vector by the specified Quaternion rotation value. + /// The vector to rotate. /// The rotation to apply. /// The transformed vector. [MethodImpl(MethodImplOptions.AggressiveInlining)] @@ -568,7 +591,12 @@ namespace System.Numerics value.W); } - /// Copies the contents of the vector into the given array. + /// Copies the elements of the vector to a specified array. + /// The destination array. + /// must have at least four elements. The method copies the vector's elements starting at index 0. + /// is . + /// The number of elements in the current instance is greater than in the array. + /// is multidimensional. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly void CopyTo(float[] array) @@ -576,11 +604,16 @@ namespace System.Numerics CopyTo(array, 0); } - /// Copies the contents of the vector into the given array, starting from index. - /// If array is null. - /// If array is multidimensional. - /// If index is greater than end of the array or index is less than zero. - /// If number of elements in source vector is greater than those available in destination array. + /// Copies the elements of the vector to a specified array starting at a specified index position. + /// The destination array. + /// The index at which to copy the first element of the vector. + /// must have a sufficient number of elements to accommodate the four vector elements. In other words, elements through + 3 must already exist in . + /// is . + /// The number of elements in the current instance is greater than in the array. + /// is less than zero. + /// -or- + /// is greater than or equal to the array length. + /// is multidimensional. [Intrinsic] [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly void CopyTo(float[] array, int index) @@ -607,18 +640,20 @@ namespace System.Numerics array[index + 3] = W; } - /// Returns a boolean indicating whether the given Vector4 is equal to this Vector4 instance. - /// The Vector4 to compare this instance to. - /// True if the other Vector4 is equal to this instance; False otherwise. + /// Returns a value that indicates whether this instance and another vector are equal. + /// The other vector. + /// if the two vectors are equal; otherwise, . + /// Two vectors are equal if their , , , and elements are equal. [Intrinsic] public readonly bool Equals(Vector4 other) { return this == other; } - /// Returns a boolean indicating whether the given Object is equal to this Vector4 instance. - /// The Object to compare against. - /// True if the Object is equal to this Vector4; False otherwise. + /// Returns a value that indicates whether this instance and a specified object are equal. + /// The object to compare with the current instance. + /// if the current instance and are equal; otherwise, . If is , the method returns . + /// The current instance and are equal if is a object and their corresponding elements are equal. [MethodImpl(MethodImplOptions.AggressiveInlining)] public override readonly bool Equals([NotNullWhen(true)] object? obj) { @@ -632,8 +667,9 @@ namespace System.Numerics return HashCode.Combine(X, Y, Z, W); } - /// Returns the length of the vector. This operation is cheaper than Length(). + /// Returns the length of this vector object. /// The vector's length. + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly float Length() { @@ -643,32 +679,40 @@ namespace System.Numerics /// Returns the length of the vector squared. /// The vector's length squared. + /// This operation offers better performance than a call to the method. + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public readonly float LengthSquared() { return Dot(this, this); } - /// Returns a String representing this Vector4 instance. - /// The string representation. + /// Returns the string representation of the current instance using default formatting. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using the "G" (general) format string and the formatting conventions of the current thread culture. The "<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. public override readonly string ToString() { return ToString("G", CultureInfo.CurrentCulture); } - /// Returns a String representing this Vector4 instance, using the specified format to format individual elements. - /// The format of individual elements. - /// The string representation. + /// Returns the string representation of the current instance using the specified format string to format individual elements. + /// A standard or custom numeric format string that defines the format of individual elements. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using and the current culture's formatting conventions. The "<" and ">" characters are used to begin and end the string, and the current culture's property followed by a space is used to separate each element. + /// Standard Numeric Format Strings + /// Custom Numeric Format Strings public readonly string ToString(string? format) { return ToString(format, CultureInfo.CurrentCulture); } - /// Returns a String representing this Vector4 instance, using the specified format to format individual elements - /// and the given IFormatProvider. - /// The format of individual elements. - /// The format provider to use when formatting elements. - /// The string representation. + /// Returns the string representation of the current instance using the specified format string to format individual elements and the specified format provider to define culture-specific formatting. + /// A standard or custom numeric format string that defines the format of individual elements. + /// A format provider that supplies culture-specific formatting information. + /// The string representation of the current instance. + /// This method returns a string in which each element of the vector is formatted using and . The "<" and ">" characters are used to begin and end the string, and the format provider's property followed by a space is used to separate each element. + /// Standard Numeric Format Strings + /// Custom Numeric Format Strings public readonly string ToString(string? format, IFormatProvider? formatProvider) { StringBuilder sb = new StringBuilder();