Skip to content

Commit 8da3988

Browse files
dfkeenandfkeenan
authored
WIP Proposal - 3.0 Additional types for Silk.NET.Maths (#1806)
* start of additional math api proposal * Create proposal with summary. * Reference decisions from 3.0 math proposal. * Add headings for types under consideration. * Add rough cut of Angle struct * add parsable interfaces to Angle * Add more angle methods. * add more angle helper methods. * Split proposal into 3 * Tweak angles * More collisions * Angle - rename T to TScalar * More angles * Add some collision shape interfaces. * Angel changes * More collision updates. * Make Angle constructor internal * Add some Frustum details * Add meeting agenda/notes sections * Add discussion notes to angle * Add Empty to IColliderShape * Make a start on color types. (Copying Stride 3D.) * propsal - angle: change: add "in" modifier to some methods. * proposal - collision: add more details for BoxExtentF and OrientedBoxF * Rename additional math type proposals to WIP
1 parent bd2f7a1 commit 8da3988

File tree

3 files changed

+3364
-0
lines changed

3 files changed

+3364
-0
lines changed

‎documentation/proposals/(WIP) Proposal - 3.0 Additional math types - Angle.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
# Summary
2+
Proposal API for additional math types to bring it up to feature parity with other popular math libraries i.e. `SlimDX`, `SharpDX`, or `Stride3D`. Leveraging modern .NET features such as `INumber<T>` and vectorization.
3+
4+
# Contributors
5+
- Daniel Keenan (dfkeenan)
6+
7+
# Current Status
8+
- [x] Proposed
9+
- [ ] Discussed with API Review Board (ARB)
10+
- [ ] Approved
11+
- [ ] Implemented
12+
13+
# Design Decisions
14+
- This proposal should compliment/augment the proposed 3.0 implementation of `Silk.Net.Maths`, matching `System.Numerics` where possible, with concessions for design oversights in that api.
15+
- This proposal assumes no knowledge of the 2.x Math library.
16+
- Text herein marked **INFORMATIVE** does not form a normative part of this proposal, and is for background only.
17+
- Within this proposal, the key words **must**, **required**, **shall**, **should**, **recommended**, **may**, **could**, and **optional** are to be interpreted as described in [RFC 2119 - Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.txt). The additional key word **optionally** is an alternate form of **optional**, for use where grammatically appropriate. These key words are highlighted in the proposal for clarity.
18+
19+
20+
21+
# Proposed API
22+
23+
## Angle
24+
25+
* `IParsable<TSelf>`, `ISpanParsable<TSelf>`, `IUtf8SpanParsable<TSelf>`
26+
* must parse angle in degrees using `IParsable<TScalar>`, `ISpanParsable<TScalar>`, `IUtf8SpanParsable<TSelf>`
27+
* optional handle `°` character
28+
29+
* `IFormattable`, `IUtf8SpanFormattable`
30+
* must produce text in degrees with default format of 2 decimal places. i.e. format string `0.##`
31+
* optional include `°` character. i.e. format string `0.##°`
32+
33+
Interface implementations not included for brevity.
34+
35+
```csharp
36+
/// <summary>
37+
/// Represents a unit independant angle using a floating-point
38+
/// internal representation.
39+
/// </summary>
40+
public readonly struct Angle<TScalar>
41+
: IEquatable<Angle<TScalar>>
42+
, IEqualityOperators<Angle<TScalar>,Angle<TScalar>, bool>
43+
, IComparable<Angle<TScalar>>
44+
, IComparisonOperators<Angle<TScalar>,Angle<TScalar>, bool>
45+
, IAdditionOperators<Angle<TScalar>,Angle<TScalar>,Angle<TScalar>>
46+
, IDivisionOperators<Angle<TScalar>, TScalar, Angle<TScalar>>
47+
, IDivisionOperators<TScalar, Angle<TScalar>, Angle<TScalar>>
48+
, IMultiplyOperators<Angle<TScalar>, TScalar, Angle<TScalar>>
49+
, IMultiplyOperators<TScalar, Angle<TScalar>, Angle<TScalar>>
50+
, IModulusOperators<Angle<TScalar>, Angle<TScalar>, Angle<TScalar>>
51+
, ISubtractionOperators<Angle<TScalar>,Angle<TScalar>,Angle<TScalar>>
52+
, IParsable<Angle<TScalar>>
53+
, ISpanParsable<Angle<TScalar>>
54+
, IUtf8SpanParsable<Angle<TScalar>>
55+
, IFormattable
56+
, IUtf8SpanFormattable
57+
where TScalar : IFloatingPointIeee754<TScalar>
58+
{
59+
internal Angle(TScalar radians) { }
60+
61+
/// <summary>Angle in degrees in the range [0, 360]. Without fractional component.</summary>
62+
public TScalar Degrees { get; }
63+
64+
/// <summary>Angle in degrees in the range [0, 360]. With fractional component.</summary>
65+
public TScalar TotalDegrees { get; }
66+
67+
/// <summary>Angle in radians in range [π, -π].</summary>
68+
public TScalar Radians { get; }
69+
70+
/// <summary>Angle in radians in range [0, 2π].</summary>
71+
public TScalar PositiveRadians { get; }
72+
73+
/// <summary>Gets or sets the minutes component of the degrees this Silk.NET.Maths.Angle<TScalar> represents.</summary>
74+
public TScalar Minutes { get; }
75+
76+
/// <summary>Gets or sets the seconds of the degrees this Silk.NET.Maths.Angle<TScalar> represents.</summary>
77+
public TScalar Seconds { get; }
78+
79+
80+
/// <summary>
81+
/// Gets a System.Boolean that determines whether this Silk.NET.Maths.Angle<TScalar>
82+
/// is a right angle (i.e. 90° or π/2).
83+
/// </summary>
84+
public bool IsRight { get; }
85+
86+
/// <summary>
87+
/// Gets a System.Boolean that determines whether this Silk.NET.Maths.Angle<TScalar>
88+
/// is a straight angle (i.e. 180° or π).
89+
/// </summary>
90+
public bool IsStraight { get; }
91+
92+
/// <summary>
93+
/// Gets a System.Boolean that determines whether this Silk.NET.Maths.Angle<TScalar>
94+
/// is a full rotation angle (i.e. 360° or 2π).
95+
/// </summary>
96+
public bool IsFullRotation { get; }
97+
98+
/// <summary>
99+
/// Gets a System.Boolean that determines whether this Silk.NET.Maths.Angle<TScalar>
100+
/// is an oblique angle (i.e. is not 90° or a multiple of 90°).
101+
/// </summary>
102+
public bool IsOblique { get; }
103+
104+
/// <summary>
105+
/// Gets a System.Boolean that determines whether this Silk.NET.Maths.Angle<TScalar>
106+
/// is an acute angle (i.e. less than 90° but greater than 0°).
107+
/// </summary>
108+
public bool IsAcute { get; }
109+
110+
/// <summary>
111+
/// Gets a System.Boolean that determines whether this Silk.NET.Maths.Angle<TScalar>
112+
/// is an obtuse angle (i.e. greater than 90° but less than 180°).
113+
/// </summary>
114+
public bool IsObtuse { get; }
115+
116+
/// <summary>
117+
/// Gets a System.Boolean that determines whether this Silk.NET.Maths.Angle<TScalar>
118+
/// is a reflex angle (i.e. greater than 180° but less than 360°).
119+
/// </summary>
120+
public bool IsReflex { get; }
121+
122+
/// <summary>
123+
/// Gets a Silk.NET.Maths.Angle<TScalar> instance that complements this angle (i.e. the two angles add to 90°).
124+
/// </summary>
125+
public Angle<TScalar> Complement { get; }
126+
127+
/// <summary>
128+
/// Gets a Silk.NET.Maths.Angle<TScalar> instance that supplements this angle (i.e. the two angles add to 180°).
129+
/// </summary>
130+
public Angle<TScalar> Supplement { get; }
131+
132+
/// <summary>Implicit cast in radians</summary>
133+
public static implicit operator TScalar(Angle<TScalar> angle) => default;
134+
}
135+
136+
```
137+
138+
139+
140+
```csharp
141+
142+
public static class Angle
143+
{
144+
public static Angle<TScalar> FromRadians<TScalar>(TScalar radians)
145+
where TScalar : IFloatingPointIeee754<TScalar>
146+
=> default;
147+
148+
public static Angle<TScalar> FromDegrees<TScalar>(TScalar degrees)
149+
where TScalar : IFloatingPointIeee754<TScalar>
150+
=> default;
151+
152+
public static Angle<TScalar> FromDegrees<TScalar>(TScalar degrees, TScalar minutes, TScalar seconds)
153+
where TScalar : IFloatingPointIeee754<TScalar>
154+
=> default;
155+
156+
public static Angle<TScalar> Min<TScalar>(Angle<TScalar> left, Angle<TScalar> right)
157+
where TScalar : IFloatingPointIeee754<TScalar>
158+
=> default;
159+
160+
public static Angle<TScalar> Max<TScalar>(Angle<TScalar> left, Angle<TScalar> right)
161+
where TScalar : IFloatingPointIeee754<TScalar>
162+
=> default;
163+
164+
public static Angle<TScalar> Add<TScalar>(Angle<TScalar> left, Angle<TScalar> right)
165+
where TScalar : IFloatingPointIeee754<TScalar>
166+
=> default;
167+
168+
public static Angle<TScalar> Subtract<TScalar>(Angle<TScalar> left, Angle<TScalar> right)
169+
where TScalar : IFloatingPointIeee754<TScalar>
170+
=> default;
171+
172+
public static Angle<TScalar> Multiply<TScalar>(Angle<TScalar> left, TScalar right)
173+
where TScalar : IFloatingPointIeee754<TScalar>
174+
=> default;
175+
176+
public static Angle<TScalar> Divide<TScalar>(Angle<TScalar> left, TScalar right)
177+
where TScalar : IFloatingPointIeee754<TScalar>
178+
=> default;
179+
180+
public static Angle<TScalar> Clamp<TScalar>(Angle<TScalar> value, Angle<TScalar> min, Angle<TScalar> max)
181+
where TScalar : IFloatingPointIeee754<TScalar>
182+
=> default;
183+
184+
public static Angle<TScalar> Atan2<TScalar>(TScalar y, TScalar x)
185+
where TScalar : IFloatingPointIeee754<TScalar>
186+
=> default;
187+
188+
public static Angle<TScalar> ArcTan<TScalar>(TScalar y, TScalar x)
189+
where TScalar : IFloatingPointIeee754<TScalar>
190+
=> default;
191+
192+
public static Angle<TScalar> ArcSin<TScalar>(TScalar sin)
193+
where TScalar : IFloatingPointIeee754<TScalar>
194+
=> default;
195+
196+
public static Angle<TScalar> ArcCos<TScalar>(TScalar cos)
197+
where TScalar : IFloatingPointIeee754<TScalar>
198+
=> default;
199+
200+
public static Angle<TScalar> Between<TScalar>(in Vector2F<TScalar> left, in Vector2F<TScalar> right)
201+
where TScalar : IFloatingPointIeee754<TScalar>
202+
=> default;
203+
204+
public static Angle<TScalar> Between<TScalar>(in Vector3F<TScalar> left, in Vector3F<TScalar> right)
205+
where TScalar : IFloatingPointIeee754<TScalar>
206+
=> default;
207+
208+
public static Angle<TScalar> ZeroAngle<TScalar>()
209+
where TScalar : IFloatingPointIeee754<TScalar>
210+
=> default;
211+
212+
public static Angle<TScalar> RightAngle<TScalar>()
213+
where TScalar : IFloatingPointIeee754<TScalar>
214+
=> default;
215+
216+
public static Angle<TScalar> StraightAngle<TScalar>()
217+
where TScalar : IFloatingPointIeee754<TScalar>
218+
=> default;
219+
220+
public static Angle<TScalar> FullRotationAngle<TScalar>()
221+
where TScalar : IFloatingPointIeee754<TScalar>
222+
=> default;
223+
}
224+
```
225+
226+
# Meeting Agenda/Notes
227+
## TDB
228+
* Degrees, minutes and seconds are not fractional. Should they be changed to an integer type (`int`)?
229+
* ```csharp
230+
public int Degrees { get; }
231+
public int Minutes { get; }
232+
public int Seconds { get; }
233+
234+
public static Angle<TScalar> FromDegrees<TScalar>(int degrees, int minutes, int seconds)
235+
where TScalar : IFloatingPointIeee754<TScalar>
236+
=> default;
237+
```

0 commit comments

Comments
 (0)