Skip to content

Commit

Permalink
Backport docs for System.Numerics.Vectors (#47725)
Browse files Browse the repository at this point in the history 
* 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 <typeparamref name="T" /> instead of <c>T</c>

* 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 <carlossanlop@users.noreply.github.com>
  • Loading branch information
@carlossanlop
carlossanlop and carlossanlop authored Feb 12, 2021
1 parent 9db2d1d commit adf616b
Show file tree
Hide file tree
Showing 10 changed files with 1,217 additions and 1,183 deletions.
2 changes: 1 addition & 1 deletion src/libraries/System.Numerics.Vectors/System.Numerics.Vectors.sln
View file
Original file line number Diff line number Diff line change
Expand Up @@ -210,4 +210,4 @@ Global
GlobalSection(ExtensibilityGlobals) = postSolution
SolutionGuid = {F9EDC1DC-52BE-4C40-90D2-41EE6FB7FA5C}
EndGlobalSection
EndGlobal
EndGlobal
3 changes: 2 additions & 1 deletion src/libraries/System.Numerics.Vectors/src/System.Numerics.Vectors.csproj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@
<IsPartialFacadeAssembly>true</IsPartialFacadeAssembly>
<TargetFrameworks>$(NetCoreAppCurrent)</TargetFrameworks>
<Nullable>enable</Nullable>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="$(CoreLibProject)" />
</ItemGroup>
</Project>
</Project>
211 changes: 116 additions & 95 deletions src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix3x2.cs
View file

Large diffs are not rendered by default.

373 changes: 210 additions & 163 deletions src/libraries/System.Private.CoreLib/src/System/Numerics/Matrix4x4.cs
View file

Large diffs are not rendered by default.

122 changes: 65 additions & 57 deletions src/libraries/System.Private.CoreLib/src/System/Numerics/Plane.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,52 +7,54 @@

namespace System.Numerics
{
/// <summary>A structure encapsulating a 3D Plane</summary>
/// <summary>Represents a plane in three-dimensional space.</summary>
/// <remarks><format type="text/markdown"><![CDATA[
/// [!INCLUDE[vectors-are-rows-paragraph](~/includes/system-numerics-vectors-are-rows.md)]
/// ]]></format></remarks>
[Intrinsic]
public struct Plane : IEquatable<Plane>
{
private const float NormalizeEpsilon = 1.192092896e-07f; // smallest such that 1.0+NormalizeEpsilon != 1.0

/// <summary>The normal vector of the Plane.</summary>
/// <summary>The normal vector of the plane.</summary>
public Vector3 Normal;

/// <summary>The distance of the Plane along its normal from the origin.</summary>
/// <summary>The distance of the plane along its normal from the origin.</summary>
public float D;

/// <summary>Constructs a Plane from the X, Y, and Z components of its normal, and its distance from the origin on that normal.</summary>
/// <param name="x">The X-component of the normal.</param>
/// <param name="y">The Y-component of the normal.</param>
/// <param name="z">The Z-component of the normal.</param>
/// <param name="d">The distance of the Plane along its normal from the origin.</param>
/// <summary>Creates a <see cref="System.Numerics.Plane" /> object from the X, Y, and Z components of its normal, and its distance from the origin on that normal.</summary>
/// <param name="x">The X component of the normal.</param>
/// <param name="y">The Y component of the normal.</param>
/// <param name="z">The Z component of the normal.</param>
/// <param name="d">The distance of the plane along its normal from the origin.</param>
public Plane(float x, float y, float z, float d)
{
Normal = new Vector3(x, y, z);
D = d;
}

/// <summary>Constructs a Plane from the given normal and distance along the normal from the origin.</summary>
/// <param name="normal">The Plane's normal vector.</param>
/// <param name="d">The Plane's distance from the origin along its normal vector.</param>
/// <summary>Creates a <see cref="System.Numerics.Plane" /> object from a specified normal and the distance along the normal from the origin.</summary>
/// <param name="normal">The plane's normal vector.</param>
/// <param name="d">The plane's distance from the origin along its normal vector.</param>
public Plane(Vector3 normal, float d)
{
Normal = normal;
D = d;
}

/// <summary>Constructs a Plane from the given Vector4.</summary>
/// <param name="value">A vector whose first 3 elements describe the normal vector,
/// and whose W component defines the distance along that normal from the origin.</param>
/// <summary>Creates a <see cref="System.Numerics.Plane" /> object from a specified four-dimensional vector.</summary>
/// <param name="value">A vector whose first three elements describe the normal vector, and whose <see cref="System.Numerics.Vector4.W" /> defines the distance along that normal from the origin.</param>
public Plane(Vector4 value)
{
Normal = new Vector3(value.X, value.Y, value.Z);
D = value.W;
}

/// <summary>Creates a Plane that contains the three given points.</summary>
/// <param name="point1">The first point defining the Plane.</param>
/// <param name="point2">The second point defining the Plane.</param>
/// <param name="point3">The third point defining the Plane.</param>
/// <returns>The Plane containing the three points.</returns>
/// <summary>Creates a <see cref="System.Numerics.Plane" /> object that contains three specified points.</summary>
/// <param name="point1">The first point defining the plane.</param>
/// <param name="point2">The second point defining the plane.</param>
/// <param name="point3">The third point defining the plane.</param>
/// <returns>The plane containing the three points.</returns>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Plane CreateFromVertices(Vector3 point1, Vector3 point2, Vector3 point3)
{
Expand Down Expand Up @@ -100,9 +102,9 @@ public static Plane CreateFromVertices(Vector3 point1, Vector3 point2, Vector3 p
}
}

/// <summary>Calculates the dot product of a Plane and Vector4.</summary>
/// <param name="plane">The Plane.</param>
/// <param name="value">The Vector4.</param>
/// <summary>Calculates the dot product of a plane and a 4-dimensional vector.</summary>
/// <param name="plane">The plane.</param>
/// <param name="value">The four-dimensional vector.</param>
/// <returns>The dot product.</returns>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static float Dot(Plane plane, Vector4 value)
Expand All @@ -113,10 +115,10 @@ public static float Dot(Plane plane, Vector4 value)
plane.D * value.W;
}

/// <summary>Returns the dot product of a specified Vector3 and the normal vector of this Plane plus the distance (D) value of the Plane.</summary>
/// <summary>Returns the dot product of a specified three-dimensional vector and the normal vector of this plane plus the distance (<see cref="System.Numerics.Plane.D" />) value of the plane.</summary>
/// <param name="plane">The plane.</param>
/// <param name="value">The Vector3.</param>
/// <returns>The resulting value.</returns>
/// <param name="value">The 3-dimensional vector.</param>
/// <returns>The dot product.</returns>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static float DotCoordinate(Plane plane, Vector3 value)
{
Expand All @@ -133,10 +135,10 @@ public static float DotCoordinate(Plane plane, Vector3 value)
}
}

/// <summary>Returns the dot product of a specified Vector3 and the Normal vector of this Plane.</summary>
/// <summary>Returns the dot product of a specified three-dimensional vector and the <see cref="System.Numerics.Plane.Normal" /> vector of this plane.</summary>
/// <param name="plane">The plane.</param>
/// <param name="value">The Vector3.</param>
/// <returns>The resulting dot product.</returns>
/// <param name="value">The three-dimensional vector.</param>
/// <returns>The dot product.</returns>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static float DotNormal(Plane plane, Vector3 value)
{
Expand All @@ -152,9 +154,9 @@ public static float DotNormal(Plane plane, Vector3 value)
}
}

/// <summary>Creates a new Plane whose normal vector is the source Plane's normal vector normalized.</summary>
/// <param name="value">The source Plane.</param>
/// <returns>The normalized Plane.</returns>
/// <summary>Creates a new <see cref="System.Numerics.Plane" /> object whose normal vector is the source plane's normal vector normalized.</summary>
/// <param name="value">The source plane.</param>
/// <returns>The normalized plane.</returns>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Plane Normalize(Plane value)
{
Expand Down Expand Up @@ -190,11 +192,11 @@ public static Plane Normalize(Plane value)
}
}

/// <summary>Transforms a normalized Plane by a Matrix.</summary>
/// <param name="plane"> 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.</param>
/// <param name="matrix">The transformation matrix to apply to the Plane.</param>
/// <returns>The transformed Plane.</returns>
/// <summary>Transforms a normalized plane by a 4x4 matrix.</summary>
/// <param name="plane">The normalized plane to transform.</param>
/// <param name="matrix">The transformation matrix to apply to <paramref name="plane" />.</param>
/// <returns>The transformed plane.</returns>
/// <remarks><paramref name="plane" /> must already be normalized so that its <see cref="System.Numerics.Plane.Normal" /> vector is of unit length before this method is called.</remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Plane Transform(Plane plane, Matrix4x4 matrix)
{
Expand All @@ -209,11 +211,11 @@ public static Plane Transform(Plane plane, Matrix4x4 matrix)
x * m.M41 + y * m.M42 + z * m.M43 + w * m.M44);
}

/// <summary> Transforms a normalized Plane by a Quaternion rotation.</summary>
/// <param name="plane"> 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.</param>
/// <param name="rotation">The Quaternion rotation to apply to the Plane.</param>
/// <returns>A new Plane that results from applying the rotation.</returns>
/// <summary>Transforms a normalized plane by a Quaternion rotation.</summary>
/// <param name="plane">The normalized plane to transform.</param>
/// <param name="rotation">The Quaternion rotation to apply to the plane.</param>
/// <returns>A new plane that results from applying the Quaternion rotation.</returns>
/// <remarks><paramref name="plane" /> must already be normalized so that its <see cref="System.Numerics.Plane.Normal" /> vector is of unit length before this method is called.</remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static Plane Transform(Plane plane, Quaternion rotation)
{
Expand Down Expand Up @@ -253,10 +255,12 @@ public static Plane Transform(Plane plane, Quaternion rotation)
plane.D);
}

/// <summary>Returns a boolean indicating whether the two given Planes are equal.</summary>
/// <param name="value1">The first Plane to compare.</param>
/// <param name="value2">The second Plane to compare.</param>
/// <returns>True if the Planes are equal; False otherwise.</returns>
/// <summary>Returns a value that indicates whether two planes are equal.</summary>
/// <param name="value1">The first plane to compare.</param>
/// <param name="value2">The second plane to compare.</param>
/// <returns><see langword="true" /> if <paramref name="value1" /> and <paramref name="value2" /> are equal; otherwise, <see langword="false" />.</returns>
/// <remarks>Two <see cref="System.Numerics.Plane" /> objects are equal if their <see cref="System.Numerics.Plane.Normal" /> and <see cref="System.Numerics.Plane.D" /> fields are equal.
/// The <see cref="System.Numerics.Plane.op_Equality" /> method defines the operation of the equality operator for <see cref="System.Numerics.Plane" /> objects.</remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool operator ==(Plane value1, Plane value2)
{
Expand All @@ -266,28 +270,31 @@ public static Plane Transform(Plane plane, Quaternion rotation)
value1.D == value2.D);
}

/// <summary>Returns a boolean indicating whether the two given Planes are not equal.</summary>
/// <param name="value1">The first Plane to compare.</param>
/// <param name="value2">The second Plane to compare.</param>
/// <returns>True if the Planes are not equal; False if they are equal.</returns>
/// <summary>Returns a value that indicates whether two planes are not equal.</summary>
/// <param name="value1">The first plane to compare.</param>
/// <param name="value2">The second plane to compare.</param>
/// <returns><see langword="true" /> if <paramref name="value1" /> and <paramref name="value2" /> are not equal; otherwise, <see langword="false" />.</returns>
/// <remarks>The <see cref="System.Numerics.Plane.op_Inequality" /> method defines the operation of the inequality operator for <see cref="System.Numerics.Plane" /> objects.</remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool operator !=(Plane value1, Plane value2)
{
return !(value1 == value2);
}

/// <summary>Returns a boolean indicating whether the given Object is equal to this Plane instance.</summary>
/// <param name="obj">The Object to compare against.</param>
/// <returns>True if the Object is equal to this Plane; False otherwise.</returns>
/// <summary>Returns a value that indicates whether this instance and a specified object are equal.</summary>
/// <param name="obj">The object to compare with the current instance.</param>
/// <returns><see langword="true" /> if the current instance and <paramref name="obj" /> are equal; otherwise, <see langword="false" />. If <paramref name="obj" /> is <see langword="null" />, the method returns <see langword="false" />.</returns>
/// <remarks>The current instance and <paramref name="obj" /> are equal if <paramref name="obj" /> is a <see cref="System.Numerics.Plane" /> object and their <see cref="System.Numerics.Plane.Normal" /> and <see cref="System.Numerics.Plane.D" /> fields are equal.</remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public override readonly bool Equals([NotNullWhen(true)] object? obj)
{
return (obj is Plane other) && Equals(other);
}

/// <summary>Returns a boolean indicating whether the given Plane is equal to this Plane instance.</summary>
/// <param name="other">The Plane to compare this instance to.</param>
/// <returns>True if the other Plane is equal to this instance; False otherwise.</returns>
/// <summary>Returns a value that indicates whether this instance and another plane object are equal.</summary>
/// <param name="other">The other plane.</param>
/// <returns><see langword="true" /> if the two planes are equal; otherwise, <see langword="false" />.</returns>
/// <remarks>Two <see cref="System.Numerics.Plane" /> objects are equal if their <see cref="System.Numerics.Plane.Normal" /> and <see cref="System.Numerics.Plane.D" /> fields are equal.</remarks>
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public readonly bool Equals(Plane other)
{
Expand All @@ -311,8 +318,9 @@ public override readonly int GetHashCode()
return Normal.GetHashCode() + D.GetHashCode();
}

/// <summary>Returns a String representing this Plane instance.</summary>
/// <returns>The string representation.</returns>
/// <summary>Returns the string representation of this plane object.</summary>
/// <returns>A string that represents this <see cref="System.Numerics.Plane" /> object.</returns>
/// <remarks>The string representation of a <see cref="System.Numerics.Plane" /> object use the formatting conventions of the current culture to format the numeric values in the returned string. For example, a <see cref="System.Numerics.Plane" /> object whose string representation is formatted by using the conventions of the en-US culture might appear as <c>{Normal:&lt;1.1, 2.2, 3.3&gt; D:4.4}</c>.</remarks>
public override readonly string ToString()
{
CultureInfo ci = CultureInfo.CurrentCulture;
Expand Down
Loading

0 comments on commit adf616b

Please sign in to comment.