[API Proposal]: Quaternion.Zero is missing

[michael-hawker]

Background and motivation

Vector2, Vector3, and Vector4 when created with new() are all zeroed out and have corresponding .Zero static properties. Quaternion on the otherhand only has the Identity static property and doesn't have the corresponding Zero one to represent its base state when created with new().

API Proposal

namespace System.Numerics
{
     public class Quaternion
     {
        /// <summary>Gets a newly initialized quaternion.</summary>
        /// <value>A quaternion whose values are <c>(0, 0, 0, 0)</c>.</value>
        public static Quaternion Zero
        {
            get => new();
        }
     }
}

API Usage

// New Quaternion
var q = Quaternion.Zero;
q.X = 0.5;

// Checking
if (q == Quaternion.Zero)
{
  // Was uninitialized
}

Risks

No breaking changes, adds value to matching base struct types in the System.Numerics package for base initialization state.

[ghost]

Tagging subscribers to this area: @dotnet/area-system-numerics
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Vector2, Vector3, and Vector4 when created with new() are all zeroed out and have corresponding .Zero static properties. Quaternion on the otherhand only has the Identity static property and doesn't have the corresponding Zero one to represent its base state when created with new().

API Proposal

namespace System.Numerics
{
     public class Quaternion
     {
        /// <summary>Gets a newly initialized quaternion.</summary>
        /// <value>A quaternion whose values are <c>(0, 0, 0, 0)</c>.</value>
        public static Quaternion Zero
        {
            get => new();
        }
     }
}

API Usage

// New Quaternion
var q = Quaternion.Zero;
q.X = 0.5;

// Checking
if (q == Quaternion.Zero)
{
  // Was uninitialized
}

Risks

No breaking changes, adds value to matching base struct types in the System.Numerics package for base initialization state.

Author:	michael-hawker
Assignees:	-
Labels:	api-suggestion, area-System.Numerics, untriaged
Milestone:	-

[GrabYourPitchforks]

Quaternion also has an IsIdentity property. If this API is approved, would IsZero come along for the ride for symmetry?

[michael-hawker]

Quaternion also has an IsIdentity property. If this API is approved, would IsZero come along for the ride for symmetry?

That's a great question, would it make sense to have IsZero and IsOne type function on Vector2, Vector3, and Vector4 too for symmetry with the Quaternion function too?

[hrrrrustic]

@GrabYourPitchforks @tannergooding Is there any reason why Quaternion fields are mutable?

runtime/src/libraries/System.Private.CoreLib/src/System/Numerics/Quaternion.cs

Lines 14 to 27 in 57bfe47

	public struct Quaternion : IEquatable<Quaternion>
	{
	private const float SlerpEpsilon = 1e-6f;
	/// <summary>The X value of the vector component of the quaternion.</summary>
	public float X;
	/// <summary>The Y value of the vector component of the quaternion.</summary>
	public float Y;
	/// <summary>The Z value of the vector component of the quaternion.</summary>
	public float Z;
	/// <summary>The rotation component of the quaternion.</summary>

There are no public usages with mutations, so it's easy to make whole struct readonly, just need to rewrite code like that

runtime/src/libraries/System.Private.CoreLib/src/System/Numerics/Quaternion.cs

Lines 76 to 81 in 57bfe47

	Quaternion ans;
	ans.X = value1.X + value2.X;
	ans.Y = value1.Y + value2.Y;
	ans.Z = value1.Z + value2.Z;
	ans.W = value1.W + value2.W;

[GrabYourPitchforks]

@hrrrrustic I suspect it's mostly that there wasn't a whole lot of consistency when these types were first introduced all those years ago. Maybe partly that the original designers believed that updating individual values would be a common operation and that apps didn't want to incur the cost of updating the entire struct? (Keep in mind - this was originally designed for a much older JIT / platform.)

[hrrrrustic]

Well, I'd like to propose to make the whole struct readonly at least for consistency with other numbers/numerics-like types
But I'll wait for @tannergooding answer, maybe he has some strong arguments against that

[svick]

@hrrrrustic That would be a breaking change, so I don't see that happening.

[tannergooding]

Yep, its a breaking change since the fields are public and so we cannot make the fix.

Ideally these would be readonly, but since they can't be all the methods should (and I believe already have been updated to be) readonly instead.

[tannergooding]

I think exposing Zero makes sense here. I'm not convinced IsZero is worthwhile to expose, developers can simply use value == Quaternion.Zero, which will be more efficient.

[bartonjs]

Video

Looks good as proposed.

namespace System.Numerics
{
     partial struct Quaternion
     {
        /// <summary>Gets a newly initialized quaternion.</summary>
        /// <value>A quaternion whose values are <c>(0, 0, 0, 0)</c>.</value>
        public static Quaternion Zero
        {
            get => new();
        }
     }
}

[tannergooding]

Marked this as up-for-grabs, but note that properly implementing this may require JIT side work to ensure the codegen is optimal like for the Vector4 scenario.