Official Unity.Mathematics available on github

While i really like the parity with HLSL and similar, especially when it comes to method names, i have to admit the lowercasing of stuff is kinda problematic. While i personally like the look of it, there are a bunch of cases where i want to have a function parameter like min, max, length or distance but it clashes with the lowercase functions when importing via using static Unity.Mathematics.math. this requires me to add the math.min or math.max, kinda killing the benefit of "using static". While the copy paste from HLSL is really nice, randomly getting error messages because i have a variable called min, max, length or distance is infuriating. Keep the variables lowercase though, being able to add a number to a primitive type to make it a vector of that type is convenient as hell. float2, int3, bool4 are all awesome, seriously. also yay for the all() and any() functions. so much of my code becomes simpler using those. =3

 

Maybe I'm just unfamiliar with other applications of "dot" being used in this way, but shouldn't math.dot(v1, v2) be a dot product? I was reading through the stress testing tech demo and couldn't figure out why they would use math.dot(sameVariable, sameVariable) until I realized what math.dot was actually doing and that's what they were using to get square magnitude.

 

Yes, math.dot() is a dot product. And yes, the dot product of a vector with itself gives its magnitude squared...

 

We have a severe case of bikeshedding here
https://en.wikipedia.org/wiki/Law_of_triviality

 

Conventions are not bike shedding. It's an important part of the API. And we should discuss it now when we can change something and there are no any projects based on that lib.

 

I've become mostly fine with the style as-is, not 100% but these are the points I can see after thinking about it for a bit:

• They've explained their reasoning for it, you may not like it and I may need more convincing, but at least they did that. Many companies I've worked with either didn't have standards, didn't enforce standards, or never told me why they used the standards they do.
• It is self-consistent, the entire math library is like this. Nothing else is like this.
• It is constrained, that is, the style doesn't bleed into anything but math libraries or functions using the low-level math libs.
• Best practices guidelines should make it clear this is for "math-only" functionality and should be limited to ONLY that if developing your own math functions.
• Many C,C++/shader and other low-level math libs use these conventions or simlar ones. If they're trying to on-board/convince more AAA developers and studios to use Unity, this is likely to be more readily recognizable as "hey an optimized math library!" than something that uses pure-C# convention and therefore more oop-like. There are actual .NET math libraries that use actual reference types to store actual Vectors and it boggles my mind as a game programmer why anyone would ever do that when structs exist.
  • Most of the guys they hired to deal with the Burst compiler, jobs, and ECS are AAA veterans. This is likely one of the major factors for the style.
• It's clearly distinct from the .NET System.Math and .NET System.Numerics libs and less likely to name clash the same functions. Most othere math libs in C# use the MS guidelines, so this lowers the chance of clashing with 3rd-party / other .NET math libs in general even further.
• On the bikeshedding: There's likely factors outside the scope of public announcements regarding C# => HLSL and/or burst-compiled intrinsics.
  • If the intent is to have this convert easily to standard math libs for HLSL / platform-specifics, and they switch styles, they may have to add another layer of indirect mapping by changing it to be more in line with expectations / normal code.
  • Keeping it this way may reduce the amount of special case work they have to do. It may not be as simple as "just call ToLowercase() on it and call it a day". Or it could be. We don't have enough information I feel.
• And my final selfish reasoning for keeping it as-is: I'm already using it in my project and I don't want to rewrite a bunch of code .

 

Ah, so it was my experience with Vector3.Dot() throwing me off. I'd only ever used it with normalized vectors and didn't understand the math underneath. Thanks!

 

Will it be possible to modularly replace the mathematics library with our own in the future, without altering any other packages?

 

I see. The goal would be custom naming conventions. I thought maybe I could just make my own library instead of insisting on your guys to change the naming of this package.

 

Sigh... If the naming is really such a big deal for you just make a new class and do something like this for every method

Code (CSharp):

1. [MethodImpl(MethodImplOptions.AggressiveInlining)]
2. public static float Max(float a, float b)
3. {
4. return math.max(a,b);
5. }

Problem solved.

 

I am aware of this option.

This creates duplicate names for everything, which is worse than off-convention naming. I won't even mention the maintenance problems that come with it.

Thanks for your suggestion, regardless.

 

After some thinking, this will be something I can get used to, but still.

I think my personal issue with it currently is that I have never seen a library use this convention in C# and I think the UnityEngine.Mathematics namespace does not really help it either.

The expectation of it functioning the same as the current implementation will always be there, no matter the style. I think that is quite a weak argument.

How often do you guys expect people to be porting GLSL/HLSL code in relation to people having to port over C# code?
Because this is coming over as inconveniencing the majority of the user base just please a small subset.

 

Yeah. I'm sure that your solution (making your own math library and somehow magically replacing the current one with it) wouldn't pose any duplicity or maintenance challenges...

 

I'm honestly not seeing why this is such a big issue to people. I'm an enterprise solutions developer by day and I'll honestly say that I've seen much worse conventions in the systems I've been developing on. I'm talking about database columns with names that don't match the data that it contains, horrible coding conventions that are used with justifications that are completely invalid as well as just general ineptitude causing people to write code that is just so overly complex for the problem they're trying to solve that it defeats the purpose of even trying to build the feature.

I've seen this type of thing happen because a system couldn't just be rewritten in one go, but had to have it done incrementally and of the different ways one would distinguish the shift would be to veer away from some of the conventions. This is unfortunately the biggest thing at the moment that they're trying to focus on; move parts of the engine into a more optimizable way of doing things while still keeping support up for the old way.

With this we're still getting an API that will do what it says, is clear in what it does and we're not going to have to go and implement this ourselves - a big bloody win in my view. Saying that the expectation of it functioning like the UnityEngine.Mathematics is a weak argument is in itself a weak argument. Unity has a specific vision with regards to providing us with a math library that allows for optimization and it's likely the case that the way UnityEngine.Mathematics currently doesn't allow for this (I might be wrong on this). I think their taking lessons with regards to the math library form GLSL/HLSL and they've found a way to distinguis the new library from the old. In which case it is of UTTER importance that one can distinguish between the two in order to be aware of these changes.

If you ultimately don't like this the don't use Unity. I'm sure you're going to find something where the styling might be more consistent. I'd say you can even go out and build your own engine. I'm not in the business fo building engines though and I'm happy to use an amazingly powerful engine to sit down and actaully make some games.

 

I think you misunderstood what I said. I said that people will expect, when porting over code to the new library, that the output of functions is the same. No matter the convention being used. Changing the naming convention does not inherently specify a change in behaviour. And that's why I called it a weak argument.

In the end it doesn't matter. If it gets implemented this way, so be it. I can live with it, but discussing it should be fine.

 

I'm sure that once this becomes mainstream there will be documentation supporting this library. Currently it's still in preview and on the todo list it's explicitly stated that documentation is missing. The documentation is where this will have to be made clear that the library does NOT behave in the same way as the old library. You are correct in that a change of convention does not show this, however to people who are aware of this it will. If you open up a piece of code and see both conventions you'll immediately be able to determine which is which.

My main argument is that all this tech is in preview and most of the gripes I've seen on this forum was people expecting things to be production ready.

 

First of all, replacing the existing library with a custom one would not introduce any duplicate naming, you would simply have your own library and that's all. Maintenance would be minimal due to modularity and take place only while the development of the actual library and not the code that uses it.

Second, I am not looking to start any flame wars here and I would appreciate it if you stop with your aggressive tone. I just expressed a feature request of mine, that's all. I'm not looking for any further arguments on this topic, because I have better things to do than arguing about what is the best naming solution for a library, it is far from being productive for anyone.

 

Thanks a lot for replying! Its really great Unity is so close with the community.

I understand that your GLSL porting was easier because its more similar, and having to decide the 'regular' convention will make porting 'shader' code more difficult compared to C# code.
But given your target audience, what type of code do you expect will be ported more often? I strongly feel like its our existing codebases, from the current C# component system to the new ECS. Perhaps Unity has more analytics about what a project consists of, but mine usually are 90% C# and 10% shader syntax.
Thats true for this case, but even more so if (like in slide 60) we can write C# that is run on the GPU. It doesnt make sense to adhere to GLSL standards in a framework that might replace that sort of tech.You're making that for C# developers, not for graphics programmers.

Point 2 is not something i considered and a great point. for some the fact that its another module and in another namespace is enough, but this does make it more apparent.

 

I would like to port some stuff to Unity.Mathematics but it currently lacks functions. Where can I find some background on Matrix4x4 functions, like Matrix4x4.MultiplyVector --- I am not good with Vector Math

Can I recreate this with current Unity.Mathematics functions?

 

I read suggestions that we should be using float4 where possible to simplify compiler SIMD optimisations. While 128bit wide lanes are the target at the moment there are already 256bit/512bit versions on the horizon.

Are there plans to create a numerical vector type that is mapped to the register width of the runtime platform, something similar to System.Numerics.Vector<T> structure?

Am I flawed in my thinking about the usefulness of such a type? Would your experience suggest that, generally speaking, I would be better off building logic for the fixed float4 type?

I'm interested in understanding how to design a small job that might perform a series of vector operations that takes full advantage of the lane width on a particular platform.

An example of a job I'm considering at the moment would look something like this in an ideal world:

Code (CSharp):

1. [ComputeJobOptimization]
2. private struct DequantizeJob: IJobParallelFor
3. {
4.     [ReadOnly] public NativeSlice<Vector<uint>> Value;
5.     [ReadOnly] public NativeSlice<Vector<float>> Min;
6.     [ReadOnly] public NativeSlice<Vector<float>> Max;
7.     [ReadOnly] public NativeSlice<Vector<int>> QuantizedRange;
8.     [WriteOnly] public NativeSlice<Vector<float>> Result;
9.  
10.  
11.     void IJobParallelFor.Execute(int index)
12.     {
13.         Vector<uint> value = Value[index];
14.         Vector<float> min = Min[index];
15.         Vector<float> max = Max[index];
16.         Vector<int> quantizedRange = QuantizedRange[index];
17.  
18.         Vector<float> range = max - min;
19.         Vector<float> result = value / quantizedRange;
20.         result = result * range;
21.         result = result + min;
22.  
23.         Result[index] = result;
24.     }
25. }

 

After reading all posts, I had to agree with him.

The main goal of Unity.Mathematics is to be a performant, shader-like and SIMD-aware library. I'm using it whenver I can and I prefer to always use math.min, math.sin, noise.snoise, etc. For my style of coding, it's better to don't use static import, they are all evil in my opnion.

 

I should probably let this go, and try to adapt to the new standard. There was just a new mini series released on the ECS and Job system, which is really awesome to see. Full playlist here.

Firstly they show how you'd do it right now, and after that they show a new system. Just like our use-cases, existing systems that would benefit will have to be upgraded at some point. Its even remarked how nice it is that it looks the same! Personally i think thats great, keeping the same naming allows us to easily update existing code, and keep referencing forum post as solutions, and saving a lot of renaming.

Ultimately in the 4th video he uses the ECS proper and the new math library. The code looks as such:



This uses three different coding styles interchangeably, PascalCase Value from the .NET naming conventions, Unity's camelCased style and now also completely lowercased math.forward.

From the github description:

After years of feedback and experience with the previous API, we believe that providing an API that is closer to the way graphics developers have been using math libraries should better help its adoption and the ease of its usage. HLSL / GLSL math library is a very well designed, well understood math library leading to greater consistency.​

To make a C# API easier to use we are going to deviate from C# standards and adopt a standard only used by graphics programmers. Maybe i'm phrasing it wrong, but that doesnt sound logical at all. Not quite sure why adoption is an issue at all to be honest, there is no alternative to the old one! Additionally, is the naming really the one thing that confuses people?

I've made this point before as well, but i strongly feel like the overwhelming majority of Unity programmers are C# developers first and foremost. For the majority (myself included) it will be more difficult, for beginners it will be confusing why some things are capitalized and some arent, and for a minority (that is already considered an expert) it will be more convenient. You cant ever win and please everyone, but you can aim to please most. A graphics programmer would already feel out of place doing gameplay either way, writing in an unfamilliar language and consuming APIs with different standards. How often do users port code from HLSL to C#, and how often would you think users will port code from 'classic' to ECS?

In my opinion there is no greater consistency achieved in making a new standard and modeling a C# API like a HLSL API, unless you rename all existing API's. If this were graphics code i'd understand, but it isnt. This is gameplay code, and thus it will clash with existing .NET, Unity and our own code-style at a big loss of consistency. There will be three standards in the C# side of your codebase, and thats bad in my opinion. Guidelines can differ between languages, not so much between 'types' of code.

HLSL math libraries are indeed very well designed, its genius to take inspiration and personally I'd love to use swizzling! But you can still use proper PascalCasing, that doesnt interfere with the design at all.

One day we might even not have to write HLSL at all, and i look forward to that day. Everything in C#, where things are nice and managed. True, converting our shaders at that point to a new writing style is some work. But the alternative is that we have a HLSL-type library and no longer even use HLSL.

 

What if the reason this maths library is so close to HLSL is so in the future the Burst compiler can also target the GPU as well as CPU?

Imagine ECS Jobs code that can be ran on the CPU or GPU the potential bandwidth available for small jobs on a GPU is literally 100-200 times more than that available on the CPU e.g. Modern CPUS about 20-50 GFLOPs vs GPUS with 2,000-10,000 GFLOPS.

 

I'm trying to use import it through the package manager but the README on GitHub only says the name of the package. I'm not sure what version to use.

Code (csharp):

1. {
2.  
3.     "dependencies":
4.     {
5.  
6.         "com.unity.mathematics": "?.?.?"
7.     }
8. }
9.  

 

I do think that is the goal, that you'd write shaders and other GPU in C#. I saw that mentioned in a talk by Aras i linked earlier too.

But in my opinion it would make not a lot of sense to seek more consistency with a language you are replacing, to make it easier for a type of programmer you are sidestepping.

In that future we wouldnt write any HLS, just C#. So why deviate from the C# standard?

 

Compiler simplicity, imagine your compiling to Burst on CPU and use C# standard then you want to add GPU and now have to convert your C# to HLS to run on the GPU... If your burst maths library is already in a HLSL style that's a lot less work for you and only a little bit of getting used to the API for the developers.

Or maybe the developers working on the system have more of a shader programming background or you would like all of the shader/rendering pipeline and Job/ECS system to have a common style across Unity?

 

In the end Unity is still providing us with a tool to write performant code by default. If you don't want to use it then don't. I can't vouch for why it can't be C# standard, hell I don't even agree with all the standards. Thinking back to high school I remember my teacher telling me not to break my head about all the weird syntactical stuff. Heck someone learning might not even be adhering to the standards if they don't know it.

 

I'd like to pitch in a thing totally unrelated to naming conventions! I know shocker! It would be really nice to have array-like operators for vectors. these would return a single float and take a single vector (float2, float4, etc...) examples include max(float4 x) which returns the maximum component, super useful, min, average, sum, etc... this would allow small compact arrays for when you only need a few values. eg: i need to store the amount of hits the actor has received this frame and their respective damage values. plus these operators are super useful =3

 

I've tried to remain neutral on the subject but I think it's probably a lot better to use Math.Thing than math.thing because it really does screw with the C# conventions we have all throughout our code base. It's not an argument to say "it makes it clear it's Unity mathematics" because we're all used to using Math. and Mathf and Mathx or whatever as a library including where.

As the use case is going to be, 9 times out of 10, someone working from or with C# code I'll have accept that I prefer Math.Thing not math.thing if only because every single library in my project does that. Except this.

And if you really were going to use C# to code a shader, then you would still expect C# syntax. It's the shader syntax that is the minority of code in a code base.

That's my vote.

 

I think the main reason to keep

math.thing

is to have a portable code to run on GPU when the API reaches there.

If you have the same syntax that runs seamlessy on CPU and GPU, the Job System would be even more porwerfull, because they could add the possibility to run it on GPU.

 

That makes no sense at all.
If your code is in C# then it wont run on the GPU anyway without some hugely complicated cross-compiler / "transpiler".
The little difference in naming would have to be handled by the transpiler anyway, just like the other 9 billion differences in syntax between C# and HLSL.

It's not like you just change a few method names and suddenly your C# code has become HLSL.

 

Here is one shader function that I got randomly on builtin_shaders of Unity:

Code (CSharp):

1. // Used in Vertex pass: Calculates diffuse lighting from lightCount lights. Specifying true to spotLight is more expensive
2. // to calculate but lights are treated as spot lights otherwise they are treated as point lights.
3. float3 ShadeVertexLightsFull (float4 vertex, float3 normal, int lightCount, bool spotLight)
4. {
5.     float3 viewpos = UnityObjectToViewPos (vertex);
6.     float3 viewN = normalize (mul ((float3x3)UNITY_MATRIX_IT_MV, normal));
7.  
8.     float3 lightColor = UNITY_LIGHTMODEL_AMBIENT.xyz;
9.     for (int i = 0; i < lightCount; i++) {
10.         float3 toLight = unity_LightPosition[i].xyz - viewpos.xyz * unity_LightPosition[i].w;
11.         float lengthSq = dot(toLight, toLight);
12.  
13.         // don't produce NaNs if some vertex position overlaps with the light
14.         lengthSq = max(lengthSq, 0.000001);
15.  
16.         toLight *= rsqrt(lengthSq);
17.  
18.         float atten = 1.0 / (1.0 + lengthSq * unity_LightAtten[i].z);
19.         if (spotLight)
20.         {
21.             float rho = max (0, dot(toLight, unity_SpotDirection[i].xyz));
22.             float spotAtt = (rho - unity_LightAtten[i].x) * unity_LightAtten[i].y;
23.             atten *= saturate(spotAtt);
24.         }
25.  
26.         float diff = max (0, dot (viewN, toLight));
27.         lightColor += unity_LightColor[i].rgb * (diff * atten);
28.     }
29.     return lightColor;
30. }

Assuming a

using static Unity.Mathematics.math

and that all those functions are already implemented on

Unity.Mathematics

, I don't see any need for a 'those hugely complicated cross-compiler / "transpiler"'.

This function could easily run on CPU with BrustCompiler and on GPU with a shader compiler.

 

Ok, and what about this?

Code (CSharp):

1. struct a2v {
2.     float4 Position : POSITION;
3.   };
4.  
5. struct v2p {
6.     float4 Position : POSITION;
7.   };
8.  
9.  

There is no c# syntax that would be valid for ": POSITION"

or

Code (CSharp):

1. void main(in a2v IN, out v2p OUT, uniform float4x4 ModelViewMatrix)
2.   {
3.     OUT.Position = mul(IN.Position, ModelViewMatrix);
4.   }

there's no "uniform" keyword in c#, and there are more examples...

 

You are getting the wrong point here. I'm not talking that you can get shader code from GPU and port it to CPU, it's the opposite way where you get the benefits. You only need to access uniforms, POSITION, COLOR0, etc on GPU, because that's the graphics part.

I got one graphic shader just to show that you can run C# code (more likely HPC# subset) on GPU by just using the Unity.Mathematics library.

You need to keep in mind that they are not replacing the Unity Math library by this one, they are writing a new math library to use together with Job System and ECS to get the so called performance by default. And, again, one way to get even more performance by default is writing HPC# code witch can run both on CPU and GPU depending on your logic and such.

I wonder that it would be magical if you can just tag your function as

[OpenCL]

and it runs on GPU core, or

[BrustCompile]

and it runs on CPU with SIMD instructions and all that heavy optmized instructions.

 

I really don't get this reasoning at all, I'm pretty sure most people here want to write C# code anyway. Besides, it's trivial to write a system that modifies the syntax to be compatible, that's not a real reason to force all programmers to use a convention they wouldn't use normally.

IMO it's pointless to keep guessing the reasoning behind the naming convention as we'd just need some direct answers and stop the speculation. If Unity has a good reason for this, I feel like they would have told already or alternatively it's based on some plans that they are not willing to share yet (as people tend to get upset if some plans don't work out in the end).

 

Yes I was speaking about that months ago. But the point is that is the minority use case, one that Unity can translate to easily enough vs the constant use of C#

 

They have, here, here and here. And they do make some valid points, and obviously they have more insight than we have.

But from my limited view, it seems like the cons outweigh the pros, and some goals are (in my opinion) not worth chasing. Like consistency in coding standards between different languages.

 

Ah, I probably explained my opinion better on the other thread on this matter. I'm aware of that one reason, I just don't agree with it I tried to mention this on my post where I said this library is aimed at C# programmers (and not shader programmers). To me it feels almost absurd that code portability is somehow issue here if they stick to same naming convention as rest of new Unity libs (considering that we got some of the best talent from the industry working on this). I still think they are not telling everything or alternatively the reason really is that silly as they've mentioned.

I said this on the other post: I don't really care too much as I'll adapt anyway, I just disagree with the logic on given explanations why they do it this way.

 

This is the other thread mentioned, if anyone is curious.

Obviously its a limited set of the community that replies here, but it seems like many people are not happy with the change of standard.

 

Thanks for the insight. I've personally not been able to put into well formed words why the conventions didn't bother me, but this is a very compelling argument @xoofx .

 

So, the current entities package doesn't use the latest math package?

I'm having a really stupid problem with (s)lerping quaternions, current entities package gives me Not Implemented exceptions, and when I do import the latest math from github, entities package complains about missing math functions.

When will we get a proper release with entities and math being in sync?
or alternatively, is there a place where I can get my hands on the latest entities package?

 

So what is best practice for comparing vectors? They seem to have Equals methods, plus there is math.equals. And for defaults, is the norm now just something like default(float3) vs the .zero approach in the old library?. Is it just a matter of preference or are there other reasons to use one vs the other?

 

I imagine they will go back to float3.zero when C# Jobs support readonly static values. Currently they don't so it either needs to be a getter property, which is a pretty janky hack or needs to be a constant, which only supports builtin C# types like float, int bool, etc... But that's just what i've heard, i'm not a reliable source for this.
[EDIT]
Never mind i'm actually super off on this answer, turns out they actually did the HLSL thing, there is an implicit conversion between floats and float2, float3, etc... so you can literally type 0f and it will convert to a float3 implicitly! This is way cleaner than my thought.

so it would be "myFloat3 == 0f"

 

For the record, I like the change.

It’s supposed to be the hlsl math ported to C#. It works very different than a typical C# math library, in much more meaningful ways than the capitalization.

It talks, walks, dresses and dances like the hlsl math library, but for some reason every one of you keeps insisting it needs to wear C# lipstick for... “consistency” reasons.

Bah!

 

Call the namespace Unity.HLSL and everybody is happy.

 

this is not hlsl, this is hlsl compatible c#