maxmustermann/godot
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add documentation to GodotSharp

Browse source 
- Adds documentation to almost every class and member in `GodotSharp`
- Fixes some old documentation to more closely follow the XML comments convention
This commit is contained in:
Raul Santos 2021-09-03 02:00:47 +02:00
parent 415529400b
commit 48c66b80ad
36 changed files with 2380 additions and 645 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

156
modules/mono/glue/GodotSharp/GodotSharp/Core/AABB.cs
View file

@ -20,7 +20,7 @@ namespace Godot
private Vector3 _size;
/// <summary>
/// Beginning corner. Typically has values lower than End.
/// Beginning corner. Typically has values lower than <see cref="End"/>.
/// </summary>
/// <value>Directly uses a private field.</value>
public Vector3 Position
@ -30,7 +30,7 @@ namespace Godot
}
/// <summary>
/// Size from Position to End. Typically all components are positive.
/// Size from <see cref="Position"/> to <see cref="End"/>. Typically all components are positive.
/// If the size is negative, you can use <see cref="Abs"/> to fix it.
/// </summary>
/// <value>Directly uses a private field.</value>
@ -44,7 +44,10 @@ namespace Godot
/// Ending corner. This is calculated as <see cref="Position"/> plus
/// <see cref="Size"/>. Setting this value will change the size.
/// </summary>
/// <value>Getting is equivalent to `value = Position + Size`, setting is equivalent to `Size = value - Position`.</value>
/// <value>
/// Getting is equivalent to <paramref name="value"/> = <see cref="Position"/> + <see cref="Size"/>,
/// setting is equivalent to <see cref="Size"/> = <paramref name="value"/> - <see cref="Position"/>
/// </value>
public Vector3 End
{
get { return _position + _size; }
@ -52,10 +55,10 @@ namespace Godot
}
/// <summary>
/// Returns an AABB with equivalent position and size, modified so that
/// Returns an <see cref="AABB"/> with equivalent position and size, modified so that
/// the most-negative corner is the origin and the size is positive.
/// </summary>
/// <returns>The modified AABB.</returns>
/// <returns>The modified <see cref="AABB"/>.</returns>
public AABB Abs()
{
Vector3 end = End;
@ -64,10 +67,12 @@ namespace Godot
}
/// <summary>
/// Returns true if this AABB completely encloses another one.
/// Returns <see langword="true"/> if this <see cref="AABB"/> completely encloses another one.
/// </summary>
/// <param name="with">The other AABB that may be enclosed.</param>
/// <returns>A bool for whether or not this AABB encloses `b`.</returns>
/// <param name="with">The other <see cref="AABB"/> that may be enclosed.</param>
/// <returns>
/// A <see langword="bool"/> for whether or not this <see cref="AABB"/> encloses <paramref name="with"/>.
/// </returns>
public bool Encloses(AABB with)
{
Vector3 srcMin = _position;
@ -84,10 +89,10 @@ namespace Godot
}
/// <summary>
/// Returns this AABB expanded to include a given point.
/// Returns this <see cref="AABB"/> expanded to include a given point.
/// </summary>
/// <param name="point">The point to include.</param>
/// <returns>The expanded AABB.</returns>
/// <returns>The expanded <see cref="AABB"/>.</returns>
public AABB Expand(Vector3 point)
{
Vector3 begin = _position;
@ -123,7 +128,7 @@ namespace Godot
}
/// <summary>
/// Returns the area of the AABB.
/// Returns the area of the <see cref="AABB"/>.
/// </summary>
/// <returns>The area.</returns>
public real_t GetArea()
@ -132,10 +137,10 @@ namespace Godot
}
/// <summary>
/// Gets the position of one of the 8 endpoints of the AABB.
/// Gets the position of one of the 8 endpoints of the <see cref="AABB"/>.
/// </summary>
/// <param name="idx">Which endpoint to get.</param>
/// <returns>An endpoint of the AABB.</returns>
/// <returns>An endpoint of the <see cref="AABB"/>.</returns>
public Vector3 GetEndpoint(int idx)
{
switch (idx)
@ -165,9 +170,9 @@ namespace Godot
}
/// <summary>
/// Returns the normalized longest axis of the AABB.
/// Returns the normalized longest axis of the <see cref="AABB"/>.
/// </summary>
/// <returns>A vector representing the normalized longest axis of the AABB.</returns>
/// <returns>A vector representing the normalized longest axis of the <see cref="AABB"/>.</returns>
public Vector3 GetLongestAxis()
{
var axis = new Vector3(1f, 0f, 0f);
@ -188,7 +193,7 @@ namespace Godot
}
/// <summary>
/// Returns the <see cref="Vector3.Axis"/> index of the longest axis of the AABB.
/// Returns the <see cref="Vector3.Axis"/> index of the longest axis of the <see cref="AABB"/>.
/// </summary>
/// <returns>A <see cref="Vector3.Axis"/> index for which axis is longest.</returns>
public Vector3.Axis GetLongestAxisIndex()
@ -211,9 +216,9 @@ namespace Godot
}
/// <summary>
/// Returns the scalar length of the longest axis of the AABB.
/// Returns the scalar length of the longest axis of the <see cref="AABB"/>.
/// </summary>
/// <returns>The scalar length of the longest axis of the AABB.</returns>
/// <returns>The scalar length of the longest axis of the <see cref="AABB"/>.</returns>
public real_t GetLongestAxisSize()
{
real_t maxSize = _size.x;
@ -228,9 +233,9 @@ namespace Godot
}
/// <summary>
/// Returns the normalized shortest axis of the AABB.
/// Returns the normalized shortest axis of the <see cref="AABB"/>.
/// </summary>
/// <returns>A vector representing the normalized shortest axis of the AABB.</returns>
/// <returns>A vector representing the normalized shortest axis of the <see cref="AABB"/>.</returns>
public Vector3 GetShortestAxis()
{
var axis = new Vector3(1f, 0f, 0f);
@ -251,7 +256,7 @@ namespace Godot
}
/// <summary>
/// Returns the <see cref="Vector3.Axis"/> index of the shortest axis of the AABB.
/// Returns the <see cref="Vector3.Axis"/> index of the shortest axis of the <see cref="AABB"/>.
/// </summary>
/// <returns>A <see cref="Vector3.Axis"/> index for which axis is shortest.</returns>
public Vector3.Axis GetShortestAxisIndex()
@ -274,9 +279,9 @@ namespace Godot
}
/// <summary>
/// Returns the scalar length of the shortest axis of the AABB.
/// Returns the scalar length of the shortest axis of the <see cref="AABB"/>.
/// </summary>
/// <returns>The scalar length of the shortest axis of the AABB.</returns>
/// <returns>The scalar length of the shortest axis of the <see cref="AABB"/>.</returns>
public real_t GetShortestAxisSize()
{
real_t maxSize = _size.x;
@ -308,10 +313,10 @@ namespace Godot
}
/// <summary>
/// Returns a copy of the AABB grown a given amount of units towards all the sides.
/// Returns a copy of the <see cref="AABB"/> grown a given amount of units towards all the sides.
/// </summary>
/// <param name="by">The amount to grow by.</param>
/// <returns>The grown AABB.</returns>
/// <returns>The grown <see cref="AABB"/>.</returns>
public AABB Grow(real_t by)
{
AABB res = this;
@ -327,28 +332,37 @@ namespace Godot
}
/// <summary>
/// Returns true if the AABB is flat or empty, or false otherwise.
/// Returns <see langword="true"/> if the <see cref="AABB"/> is flat or empty,
/// or <see langword="false"/> otherwise.
/// </summary>
/// <returns>A bool for whether or not the AABB has area.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="AABB"/> has area.
/// </returns>
public bool HasNoArea()
{
return _size.x <= 0f || _size.y <= 0f || _size.z <= 0f;
}
/// <summary>
/// Returns true if the AABB has no surface (no size), or false otherwise.
/// Returns <see langword="true"/> if the <see cref="AABB"/> has no surface (no size),
/// or <see langword="false"/> otherwise.
/// </summary>
/// <returns>A bool for whether or not the AABB has area.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="AABB"/> has area.
/// </returns>
public bool HasNoSurface()
{
return _size.x <= 0f && _size.y <= 0f && _size.z <= 0f;
}
/// <summary>
/// Returns true if the AABB contains a point, or false otherwise.
/// Returns <see langword="true"/> if the <see cref="AABB"/> contains a point,
/// or <see langword="false"/> otherwise.
/// </summary>
/// <param name="point">The point to check.</param>
/// <returns>A bool for whether or not the AABB contains `point`.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="AABB"/> contains <paramref name="point"/>.
/// </returns>
public bool HasPoint(Vector3 point)
{
if (point.x < _position.x)
@ -368,10 +382,10 @@ namespace Godot
}
/// <summary>
/// Returns the intersection of this AABB and `b`.
/// Returns the intersection of this <see cref="AABB"/> and <paramref name="with"/>.
/// </summary>
/// <param name="with">The other AABB.</param>
/// <returns>The clipped AABB.</returns>
/// <param name="with">The other <see cref="AABB"/>.</param>
/// <returns>The clipped <see cref="AABB"/>.</returns>
public AABB Intersection(AABB with)
{
Vector3 srcMin = _position;
@ -409,15 +423,18 @@ namespace Godot
}
/// <summary>
/// Returns true if the AABB overlaps with `b`
/// Returns <see langword="true"/> if the <see cref="AABB"/> overlaps with <paramref name="with"/>
/// (i.e. they have at least one point in common).
///
/// If `includeBorders` is true, they will also be considered overlapping
/// if their borders touch, even without intersection.
/// If <paramref name="includeBorders"/> is <see langword="true"/>,
/// they will also be considered overlapping if their borders touch,
/// even without intersection.
/// </summary>
/// <param name="with">The other AABB to check for intersections with.</param>
/// <param name="with">The other <see cref="AABB"/> to check for intersections with.</param>
/// <param name="includeBorders">Whether or not to consider borders.</param>
/// <returns>A bool for whether or not they are intersecting.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not they are intersecting.
/// </returns>
public bool Intersects(AABB with, bool includeBorders = false)
{
if (includeBorders)
@ -455,10 +472,12 @@ namespace Godot
}
/// <summary>
/// Returns true if the AABB is on both sides of `plane`.
/// Returns <see langword="true"/> if the <see cref="AABB"/> is on both sides of <paramref name="plane"/>.
/// </summary>
/// <param name="plane">The plane to check for intersection.</param>
/// <returns>A bool for whether or not the AABB intersects the plane.</returns>
/// <param name="plane">The <see cref="Plane"/> to check for intersection.</param>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="AABB"/> intersects the <see cref="Plane"/>.
/// </returns>
public bool IntersectsPlane(Plane plane)
{
Vector3[] points =
@ -492,11 +511,14 @@ namespace Godot
}
/// <summary>
/// Returns true if the AABB intersects the line segment between `from` and `to`.
/// Returns <see langword="true"/> if the <see cref="AABB"/> intersects
/// the line segment between <paramref name="from"/> and <paramref name="to"/>.
/// </summary>
/// <param name="from">The start of the line segment.</param>
/// <param name="to">The end of the line segment.</param>
/// <returns>A bool for whether or not the AABB intersects the line segment.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="AABB"/> intersects the line segment.
/// </returns>
public bool IntersectsSegment(Vector3 from, Vector3 to)
{
real_t min = 0f;
@ -552,10 +574,10 @@ namespace Godot
}
/// <summary>
/// Returns a larger AABB that contains this AABB and `b`.
/// Returns a larger <see cref="AABB"/> that contains this <see cref="AABB"/> and <paramref name="with"/>.
/// </summary>
/// <param name="with">The other AABB.</param>
/// <returns>The merged AABB.</returns>
/// <param name="with">The other <see cref="AABB"/>.</param>
/// <returns>The merged <see cref="AABB"/>.</returns>
public AABB Merge(AABB with)
{
Vector3 beg1 = _position;
@ -579,7 +601,7 @@ namespace Godot
}
/// <summary>
/// Constructs an AABB from a position and size.
/// Constructs an <see cref="AABB"/> from a position and size.
/// </summary>
/// <param name="position">The position.</param>
/// <param name="size">The size, typically positive.</param>
@ -590,7 +612,8 @@ namespace Godot
}
/// <summary>
/// Constructs an AABB from a position, width, height, and depth.
/// Constructs an <see cref="AABB"/> from a <paramref name="position"/>,
/// <paramref name="width"/>, <paramref name="height"/>, and <paramref name="depth"/>.
/// </summary>
/// <param name="position">The position.</param>
/// <param name="width">The width, typically positive.</param>
@ -603,7 +626,8 @@ namespace Godot
}
/// <summary>
/// Constructs an AABB from x, y, z, and size.
/// Constructs an <see cref="AABB"/> from <paramref name="x"/>,
/// <paramref name="y"/>, <paramref name="z"/>, and <paramref name="size"/>.
/// </summary>
/// <param name="x">The position's X coordinate.</param>
/// <param name="y">The position's Y coordinate.</param>
@ -616,7 +640,9 @@ namespace Godot
}
/// <summary>
/// Constructs an AABB from x, y, z, width, height, and depth.
/// Constructs an <see cref="AABB"/> from <paramref name="x"/>,
/// <paramref name="y"/>, <paramref name="z"/>, <paramref name="width"/>,
/// <paramref name="height"/>, and <paramref name="depth"/>.
/// </summary>
/// <param name="x">The position's X coordinate.</param>
/// <param name="y">The position's Y coordinate.</param>
@ -640,6 +666,11 @@ namespace Godot
return !left.Equals(right);
}
/// <summary>
/// Returns <see langword="true"/> if this AABB and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the AABB structure and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is AABB)
@ -650,32 +681,49 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this AABB and <paramref name="other"/> are equal
/// </summary>
/// <param name="other">The other AABB to compare.</param>
/// <returns>Whether or not the AABBs are equal.</returns>
public bool Equals(AABB other)
{
return _position == other._position && _size == other._size;
}
/// <summary>
/// Returns true if this AABB and `other` are approximately equal, by running
/// <see cref="Vector3.IsEqualApprox(Vector3)"/> on each component.
/// Returns <see langword="true"/> if this AABB and <paramref name="other"/> are approximately equal,
/// by running <see cref="Vector3.IsEqualApprox(Vector3)"/> on each component.
/// </summary>
/// <param name="other">The other AABB to compare.</param>
/// <returns>Whether or not the AABBs are approximately equal.</returns>
/// <returns>Whether or not the AABBs structures are approximately equal.</returns>
public bool IsEqualApprox(AABB other)
{
return _position.IsEqualApprox(other._position) && _size.IsEqualApprox(other._size);
}
/// <summary>
/// Serves as the hash function for <see cref="AABB"/>.
/// </summary>
/// <returns>A hash code for this AABB.</returns>
public override int GetHashCode()
{
return _position.GetHashCode() ^ _size.GetHashCode();
}
/// <summary>
/// Converts this <see cref="AABB"/> to a string.
/// </summary>
/// <returns>A string representation of this AABB.</returns>
public override string ToString()
{
return $"{_position}, {_size}";
}
/// <summary>
/// Converts this <see cref="AABB"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this AABB.</returns>
public string ToString(string format)
{
return $"{_position.ToString(format)}, {_size.ToString(format)}";

20
modules/mono/glue/GodotSharp/GodotSharp/Core/Array.cs
View file

@ -93,7 +93,7 @@ namespace Godot.Collections
/// <summary>
/// Duplicates this <see cref="Array"/>.
/// </summary>
/// <param name="deep">If true, performs a deep copy.</param>
/// <param name="deep">If <see langword="true"/>, performs a deep copy.</param>
/// <returns>A new Godot Array.</returns>
public Array Duplicate(bool deep = false)
{
@ -155,9 +155,9 @@ namespace Godot.Collections
bool IList.IsFixedSize => false;
/// <summary>
/// Returns the object at the given index.
/// Returns the object at the given <paramref name="index"/>.
/// </summary>
/// <value>The object at the given index.</value>
/// <value>The object at the given <paramref name="index"/>.</value>
public object this[int index]
{
get => godot_icall_Array_At(GetPtr(), index);
@ -166,7 +166,7 @@ namespace Godot.Collections
/// <summary>
/// Adds an object to the end of this <see cref="Array"/>.
/// This is the same as `append` or `push_back` in GDScript.
/// This is the same as <c>append</c> or <c>push_back</c> in GDScript.
/// </summary>
/// <param name="value">The object to add.</param>
/// <returns>The new size after adding the object.</returns>
@ -203,7 +203,7 @@ namespace Godot.Collections
public void Insert(int index, object value) => godot_icall_Array_Insert(GetPtr(), index, value);
/// <summary>
/// Removes the first occurrence of the specified value
/// Removes the first occurrence of the specified <paramref name="value"/>
/// from this <see cref="Array"/>.
/// </summary>
/// <param name="value">The value to remove.</param>
@ -425,7 +425,7 @@ namespace Godot.Collections
/// <summary>
/// Duplicates this <see cref="Array{T}"/>.
/// </summary>
/// <param name="deep">If true, performs a deep copy.</param>
/// <param name="deep">If <see langword="true"/>, performs a deep copy.</param>
/// <returns>A new Godot Array.</returns>
public Array<T> Duplicate(bool deep = false)
{
@ -464,9 +464,9 @@ namespace Godot.Collections
// IList<T>
/// <summary>
/// Returns the value at the given index.
/// Returns the value at the given <paramref name="index"/>.
/// </summary>
/// <value>The value at the given index.</value>
/// <value>The value at the given <paramref name="index"/>.</value>
public T this[int index]
{
get { return (T)Array.godot_icall_Array_At_Generic(GetPtr(), index, elemTypeEncoding, elemTypeClass); }
@ -522,7 +522,7 @@ namespace Godot.Collections
/// <summary>
/// Adds an item to the end of this <see cref="Array{T}"/>.
/// This is the same as `append` or `push_back` in GDScript.
/// This is the same as <c>append</c> or <c>push_back</c> in GDScript.
/// </summary>
/// <param name="item">The item to add.</param>
/// <returns>The new size after adding the item.</returns>
@ -583,7 +583,7 @@ namespace Godot.Collections
/// from this <see cref="Array{T}"/>.
/// </summary>
/// <param name="item">The value to remove.</param>
/// <returns>A bool indicating success or failure.</returns>
/// <returns>A <see langword="bool"/> indicating success or failure.</returns>
public bool Remove(T item)
{
return Array.godot_icall_Array_Remove(GetPtr(), item);

4
modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/DisableGodotGeneratorsAttribute.cs
View file

@ -3,7 +3,5 @@ using System;
namespace Godot
{
[AttributeUsage(AttributeTargets.Class)]
public class DisableGodotGeneratorsAttribute : Attribute
{
}
public class DisableGodotGeneratorsAttribute : Attribute { }
}

4
modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/RPCAttributes.cs
View file

@ -3,8 +3,8 @@ using System;
namespace Godot
{
[AttributeUsage(AttributeTargets.Method)]
public class RemoteAttribute : Attribute {}
public class RemoteAttribute : Attribute { }
[AttributeUsage(AttributeTargets.Method)]
public class PuppetAttribute : Attribute {}
public class PuppetAttribute : Attribute { }
}

4
modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/SignalAttribute.cs
View file

@ -3,7 +3,5 @@ using System;
namespace Godot
{
[AttributeUsage(AttributeTargets.Delegate | AttributeTargets.Event)]
public class SignalAttribute : Attribute
{
}
public class SignalAttribute : Attribute { }
}

2
modules/mono/glue/GodotSharp/GodotSharp/Core/Attributes/ToolAttribute.cs
View file

@ -3,5 +3,5 @@ using System;
namespace Godot
{
[AttributeUsage(AttributeTargets.Class)]
public class ToolAttribute : Attribute {}
public class ToolAttribute : Attribute { }
}

85
modules/mono/glue/GodotSharp/GodotSharp/Core/Basis.cs
View file

@ -31,7 +31,7 @@ namespace Godot
/// <summary>
/// The basis matrix's X vector (column 0).
/// </summary>
/// <value>Equivalent to <see cref="Column0"/> and array index `[0]`.</value>
/// <value>Equivalent to <see cref="Column0"/> and array index <c>[0]</c>.</value>
public Vector3 x
{
get => Column0;
@ -41,7 +41,7 @@ namespace Godot
/// <summary>
/// The basis matrix's Y vector (column 1).
/// </summary>
/// <value>Equivalent to <see cref="Column1"/> and array index `[1]`.</value>
/// <value>Equivalent to <see cref="Column1"/> and array index <c>[1]</c>.</value>
public Vector3 y
{
get => Column1;
@ -51,7 +51,7 @@ namespace Godot
/// <summary>
/// The basis matrix's Z vector (column 2).
/// </summary>
/// <value>Equivalent to <see cref="Column2"/> and array index `[2]`.</value>
/// <value>Equivalent to <see cref="Column2"/> and array index <c>[2]</c>.</value>
public Vector3 z
{
get => Column2;
@ -82,7 +82,7 @@ namespace Godot
/// <summary>
/// Column 0 of the basis matrix (the X vector).
/// </summary>
/// <value>Equivalent to <see cref="x"/> and array index `[0]`.</value>
/// <value>Equivalent to <see cref="x"/> and array index <c>[0]</c>.</value>
public Vector3 Column0
{
get => new Vector3(Row0.x, Row1.x, Row2.x);
@ -97,7 +97,7 @@ namespace Godot
/// <summary>
/// Column 1 of the basis matrix (the Y vector).
/// </summary>
/// <value>Equivalent to <see cref="y"/> and array index `[1]`.</value>
/// <value>Equivalent to <see cref="y"/> and array index <c>[1]</c>.</value>
public Vector3 Column1
{
get => new Vector3(Row0.y, Row1.y, Row2.y);
@ -112,7 +112,7 @@ namespace Godot
/// <summary>
/// Column 2 of the basis matrix (the Z vector).
/// </summary>
/// <value>Equivalent to <see cref="z"/> and array index `[2]`.</value>
/// <value>Equivalent to <see cref="z"/> and array index <c>[2]</c>.</value>
public Vector3 Column2
{
get => new Vector3(Row0.z, Row1.z, Row2.z);
@ -150,9 +150,10 @@ namespace Godot
}
/// <summary>
/// Access whole columns in the form of Vector3.
/// Access whole columns in the form of <see cref="Vector3"/>.
/// </summary>
/// <param name="column">Which column vector.</param>
/// <value>The basis column.</value>
public Vector3 this[int column]
{
get
@ -193,6 +194,7 @@ namespace Godot
/// </summary>
/// <param name="column">Which column, the matrix horizontal position.</param>
/// <param name="row">Which row, the matrix vertical position.</param>
/// <value>The matrix element.</value>
public real_t this[int column, int row]
{
get
@ -207,6 +209,13 @@ namespace Godot
}
}
/// <summary>
/// Returns the <see cref="Basis"/>'s rotation in the form of a
/// <see cref="Quaternion"/>. See <see cref="GetEuler"/> if you
/// need Euler angles, but keep in mind quaternions should generally
/// be preferred to Euler angles.
/// </summary>
/// <returns>The basis rotation.</returns>
public Quaternion GetRotationQuaternion()
{
Basis orthonormalizedBasis = Orthonormalized();
@ -263,10 +272,10 @@ namespace Godot
/// The returned vector contains the rotation angles in
/// the format (X angle, Y angle, Z angle).
///
/// Consider using the <see cref="Basis.Quaternion()"/> method instead, which
/// Consider using the <see cref="Quaternion()"/> method instead, which
/// returns a <see cref="Godot.Quaternion"/> quaternion instead of Euler angles.
/// </summary>
/// <returns>A Vector3 representing the basis rotation in Euler angles.</returns>
/// <returns>A <see cref="Vector3"/> representing the basis rotation in Euler angles.</returns>
public Vector3 GetEuler()
{
Basis m = Orthonormalized();
@ -304,7 +313,10 @@ namespace Godot
/// but are more efficient for some internal calculations.
/// </summary>
/// <param name="index">Which row.</param>
/// <returns>One of `Row0`, `Row1`, or `Row2`.</returns>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when the <paramref name="index"/> is not 0, 1 or 2.
/// </exception>
/// <returns>One of <c>Row0</c>, <c>Row1</c>, or <c>Row2</c>.</returns>
public Vector3 GetRow(int index)
{
switch (index)
@ -326,6 +338,9 @@ namespace Godot
/// </summary>
/// <param name="index">Which row.</param>
/// <param name="value">The vector to set the row to.</param>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when the <paramref name="index"/> is not 0, 1 or 2.
/// </exception>
public void SetRow(int index, Vector3 value)
{
switch (index)
@ -452,8 +467,8 @@ namespace Godot
}
/// <summary>
/// Introduce an additional rotation around the given `axis`
/// by `phi` (in radians). The axis must be a normalized vector.
/// Introduce an additional rotation around the given <paramref name="axis"/>
/// by <paramref name="phi"/> (in radians). The axis must be a normalized vector.
/// </summary>
/// <param name="axis">The axis to rotate around. Must be normalized.</param>
/// <param name="phi">The angle to rotate, in radians.</param>
@ -553,6 +568,7 @@ namespace Godot
/// <summary>
/// Returns a vector transformed (multiplied) by the basis matrix.
/// </summary>
/// <seealso cref="XformInv(Vector3)"/>
/// <param name="v">A vector to transform.</param>
/// <returns>The transformed vector.</returns>
public Vector3 Xform(Vector3 v)
@ -571,6 +587,7 @@ namespace Godot
/// Note: This results in a multiplication by the inverse of the
/// basis matrix only if it represents a rotation-reflection.
/// </summary>
/// <seealso cref="Xform(Vector3)"/>
/// <param name="v">A vector to inversely transform.</param>
/// <returns>The inversely transformed vector.</returns>
public Vector3 XformInv(Vector3 v)
@ -675,25 +692,25 @@ namespace Godot
/// <summary>
/// The identity basis, with no rotation or scaling applied.
/// This is used as a replacement for `Basis()` in GDScript.
/// Do not use `new Basis()` with no arguments in C#, because it sets all values to zero.
/// This is used as a replacement for <c>Basis()</c> in GDScript.
/// Do not use <c>new Basis()</c> with no arguments in C#, because it sets all values to zero.
/// </summary>
/// <value>Equivalent to `new Basis(Vector3.Right, Vector3.Up, Vector3.Back)`.</value>
/// <value>Equivalent to <c>new Basis(Vector3.Right, Vector3.Up, Vector3.Back)</c>.</value>
public static Basis Identity { get { return _identity; } }
/// <summary>
/// The basis that will flip something along the X axis when used in a transformation.
/// </summary>
/// <value>Equivalent to `new Basis(Vector3.Left, Vector3.Up, Vector3.Back)`.</value>
/// <value>Equivalent to <c>new Basis(Vector3.Left, Vector3.Up, Vector3.Back)</c>.</value>
public static Basis FlipX { get { return _flipX; } }
/// <summary>
/// The basis that will flip something along the Y axis when used in a transformation.
/// </summary>
/// <value>Equivalent to `new Basis(Vector3.Right, Vector3.Down, Vector3.Back)`.</value>
/// <value>Equivalent to <c>new Basis(Vector3.Right, Vector3.Down, Vector3.Back)</c>.</value>
public static Basis FlipY { get { return _flipY; } }
/// <summary>
/// The basis that will flip something along the Z axis when used in a transformation.
/// </summary>
/// <value>Equivalent to `new Basis(Vector3.Right, Vector3.Up, Vector3.Forward)`.</value>
/// <value>Equivalent to <c>new Basis(Vector3.Right, Vector3.Up, Vector3.Forward)</c>.</value>
public static Basis FlipZ { get { return _flipZ; } }
/// <summary>
@ -752,8 +769,8 @@ namespace Godot
}
/// <summary>
/// Constructs a pure rotation basis matrix, rotated around the given `axis`
/// by `phi` (in radians). The axis must be a normalized vector.
/// Constructs a pure rotation basis matrix, rotated around the given <paramref name="axis"/>
/// by <paramref name="phi"/> (in radians). The axis must be a normalized vector.
/// </summary>
/// <param name="axis">The axis to rotate around. Must be normalized.</param>
/// <param name="phi">The angle to rotate, in radians.</param>
@ -830,6 +847,11 @@ namespace Godot
return !left.Equals(right);
}
/// <summary>
/// Returns <see langword="true"/> if this basis and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the basis and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Basis)
@ -840,32 +862,49 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this basis and <paramref name="other"/> are equal
/// </summary>
/// <param name="other">The other basis to compare.</param>
/// <returns>Whether or not the bases are equal.</returns>
public bool Equals(Basis other)
{
return Row0.Equals(other.Row0) && Row1.Equals(other.Row1) && Row2.Equals(other.Row2);
}
/// <summary>
/// Returns true if this basis and `other` are approximately equal, by running
/// <see cref="Vector3.IsEqualApprox(Vector3)"/> on each component.
/// Returns <see langword="true"/> if this basis and <paramref name="other"/> are approximately equal,
/// by running <see cref="Vector3.IsEqualApprox(Vector3)"/> on each component.
/// </summary>
/// <param name="other">The other basis to compare.</param>
/// <returns>Whether or not the matrices are approximately equal.</returns>
/// <returns>Whether or not the bases are approximately equal.</returns>
public bool IsEqualApprox(Basis other)
{
return Row0.IsEqualApprox(other.Row0) && Row1.IsEqualApprox(other.Row1) && Row2.IsEqualApprox(other.Row2);
}
/// <summary>
/// Serves as the hash function for <see cref="Basis"/>.
/// </summary>
/// <returns>A hash code for this basis.</returns>
public override int GetHashCode()
{
return Row0.GetHashCode() ^ Row1.GetHashCode() ^ Row2.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Basis"/> to a string.
/// </summary>
/// <returns>A string representation of this basis.</returns>
public override string ToString()
{
return $"[X: {x}, Y: {y}, Z: {z}]";
}
/// <summary>
/// Converts this <see cref="Basis"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this basis.</returns>
public string ToString(string format)
{
return $"[X: {x.ToString(format)}, Y: {y.ToString(format)}, Z: {z.ToString(format)}]";

44
modules/mono/glue/GodotSharp/GodotSharp/Core/Callable.cs
View file

@ -2,18 +2,58 @@ using System;
namespace Godot
{
/// <summary>
/// Callable is a first class object which can be held in variables and passed to functions.
/// It represents a given method in an Object, and is typically used for signal callbacks.
/// </summary>
/// <example>
/// <code>
/// public void PrintArgs(object ar1, object arg2, object arg3 = null)
/// {
/// GD.PrintS(arg1, arg2, arg3);
/// }
///
/// public void Test()
/// {
/// // This Callable object will call the PrintArgs method defined above.
/// Callable callable = new Callable(this, nameof(PrintArgs));
/// callable.Call("hello", "world"); // Prints "hello world null".
/// callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs".
/// callable.Call("invalid"); // Invalid call, should have at least 2 arguments.
/// }
/// </code>
/// </example>
public struct Callable
{
private readonly Object _target;
private readonly StringName _method;
private readonly Delegate _delegate;
/// <summary>
/// Object that contains the method.
/// </summary>
public Object Target => _target;
/// <summary>
/// Name of the method that will be called.
/// </summary>
public StringName Method => _method;
/// <summary>
/// Delegate of the method that will be called.
/// </summary>
public Delegate Delegate => _delegate;
/// <summary>
/// Converts a <see cref="Delegate"/> to a <see cref="Callable"/>.
/// </summary>
/// <param name="delegate">The delegate to convert.</param>
public static implicit operator Callable(Delegate @delegate) => new Callable(@delegate);
/// <summary>
/// Constructs a new <see cref="Callable"/> for the method called <paramref name="method"/>
/// in the specified <paramref name="target"/>.
/// </summary>
/// <param name="target">Object that contains the method.</param>
/// <param name="method">Name of the method that will be called.</param>
public Callable(Object target, StringName method)
{
_target = target;
@ -21,6 +61,10 @@ namespace Godot
_delegate = null;
}
/// <summary>
/// Constructs a new <see cref="Callable"/> for the given <paramref name="delegate"/>.
/// </summary>
/// <param name="delegate">Delegate method that will be called.</param>
public Callable(Delegate @delegate)
{
_target = null;

98
modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs
View file

@ -7,11 +7,11 @@ namespace Godot
/// A color represented by red, green, blue, and alpha (RGBA) components.
/// The alpha component is often used for transparency.
/// Values are in floating-point and usually range from 0 to 1.
/// Some properties (such as CanvasItem.modulate) may accept values
/// Some properties (such as <see cref="CanvasItem.Modulate"/>) may accept values
/// greater than 1 (overbright or HDR colors).
///
/// If you want to supply values in a range of 0 to 255, you should use
/// <see cref="Color8"/> and the `r8`/`g8`/`b8`/`a8` properties.
/// <see cref="Color8"/> and the <c>r8</c>/<c>g8</c>/<c>b8</c>/<c>a8</c> properties.
/// </summary>
[Serializable]
[StructLayout(LayoutKind.Sequential)]
@ -173,7 +173,7 @@ namespace Godot
/// <summary>
/// The HSV value (brightness) of this color, on the range 0 to 1.
/// </summary>
/// <value>Getting is equivalent to using `Max()` on the RGB components. Setting uses <see cref="FromHSV"/>.</value>
/// <value>Getting is equivalent to using <see cref="Math.Max(float, float)"/> on the RGB components. Setting uses <see cref="FromHSV"/>.</value>
public float v
{
get
@ -189,7 +189,12 @@ namespace Godot
/// <summary>
/// Access color components using their index.
/// </summary>
/// <value>`[0]` is equivalent to `.r`, `[1]` is equivalent to `.g`, `[2]` is equivalent to `.b`, `[3]` is equivalent to `.a`.</value>
/// <value>
/// <c>[0]</c> is equivalent to <see cref="r"/>,
/// <c>[1]</c> is equivalent to <see cref="g"/>,
/// <c>[2]</c> is equivalent to <see cref="b"/>,
/// <c>[3]</c> is equivalent to <see cref="a"/>.
/// </value>
public float this[int index]
{
get
@ -236,7 +241,7 @@ namespace Godot
/// The second color may have a range of alpha values.
/// </summary>
/// <param name="over">The color to blend over.</param>
/// <returns>This color blended over `over`.</returns>
/// <returns>This color blended over <paramref name="over"/>.</returns>
public Color Blend(Color over)
{
Color res;
@ -258,8 +263,8 @@ namespace Godot
/// <summary>
/// Returns a new color with all components clamped between the
/// components of `min` and `max` using
/// <see cref="Mathf.Clamp(float, float, float)"/>.
/// components of <paramref name="min"/> and <paramref name="max"/>
/// using <see cref="Mathf.Clamp(float, float, float)"/>.
/// </summary>
/// <param name="min">The color with minimum allowed values.</param>
/// <param name="max">The color with maximum allowed values.</param>
@ -293,7 +298,7 @@ namespace Godot
}
/// <summary>
/// Returns the inverted color: `(1 - r, 1 - g, 1 - b, a)`.
/// Returns the inverted color: <c>(1 - r, 1 - g, 1 - b, a)</c>.
/// </summary>
/// <returns>The inverted color.</returns>
public Color Inverted()
@ -323,7 +328,7 @@ namespace Godot
/// <summary>
/// Returns the result of the linear interpolation between
/// this color and `to` by amount `weight`.
/// this color and <paramref name="to"/> by amount <paramref name="weight"/>.
/// </summary>
/// <param name="to">The destination color for interpolation.</param>
/// <param name="weight">A value on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
@ -341,7 +346,7 @@ namespace Godot
/// <summary>
/// Returns the result of the linear interpolation between
/// this color and `to` by color amount `weight`.
/// this color and <paramref name="to"/> by color amount <paramref name="weight"/>.
/// </summary>
/// <param name="to">The destination color for interpolation.</param>
/// <param name="weight">A color with components on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
@ -362,7 +367,7 @@ namespace Godot
/// format (each byte represents a color channel).
/// ABGR is the reversed version of the default format.
/// </summary>
/// <returns>A uint representing this color in ABGR32 format.</returns>
/// <returns>A <see langword="uint"/> representing this color in ABGR32 format.</returns>
public uint ToAbgr32()
{
uint c = (byte)Math.Round(a * 255);
@ -381,7 +386,7 @@ namespace Godot
/// format (each word represents a color channel).
/// ABGR is the reversed version of the default format.
/// </summary>
/// <returns>A ulong representing this color in ABGR64 format.</returns>
/// <returns>A <see langword="ulong"/> representing this color in ABGR64 format.</returns>
public ulong ToAbgr64()
{
ulong c = (ushort)Math.Round(a * 65535);
@ -400,7 +405,7 @@ namespace Godot
/// format (each byte represents a color channel).
/// ARGB is more compatible with DirectX, but not used much in Godot.
/// </summary>
/// <returns>A uint representing this color in ARGB32 format.</returns>
/// <returns>A <see langword="uint"/> representing this color in ARGB32 format.</returns>
public uint ToArgb32()
{
uint c = (byte)Math.Round(a * 255);
@ -419,7 +424,7 @@ namespace Godot
/// format (each word represents a color channel).
/// ARGB is more compatible with DirectX, but not used much in Godot.
/// </summary>
/// <returns>A ulong representing this color in ARGB64 format.</returns>
/// <returns>A <see langword="ulong"/> representing this color in ARGB64 format.</returns>
public ulong ToArgb64()
{
ulong c = (ushort)Math.Round(a * 65535);
@ -438,7 +443,7 @@ namespace Godot
/// format (each byte represents a color channel).
/// RGBA is Godot's default and recommended format.
/// </summary>
/// <returns>A uint representing this color in RGBA32 format.</returns>
/// <returns>A <see langword="uint"/> representing this color in RGBA32 format.</returns>
public uint ToRgba32()
{
uint c = (byte)Math.Round(r * 255);
@ -457,7 +462,7 @@ namespace Godot
/// format (each word represents a color channel).
/// RGBA is Godot's default and recommended format.
/// </summary>
/// <returns>A ulong representing this color in RGBA64 format.</returns>
/// <returns>A <see langword="ulong"/> representing this color in RGBA64 format.</returns>
public ulong ToRgba64()
{
ulong c = (ushort)Math.Round(r * 65535);
@ -474,7 +479,9 @@ namespace Godot
/// <summary>
/// Returns the color's HTML hexadecimal color string in RGBA format.
/// </summary>
/// <param name="includeAlpha">Whether or not to include alpha. If false, the color is RGB instead of RGBA.</param>
/// <param name="includeAlpha">
/// Whether or not to include alpha. If <see langword="false"/>, the color is RGB instead of RGBA.
/// </param>
/// <returns>A string for the HTML hexadecimal representation of this color.</returns>
public string ToHTML(bool includeAlpha = true)
{
@ -493,7 +500,7 @@ namespace Godot
}
/// <summary>
/// Constructs a color from RGBA values, typically on the range of 0 to 1.
/// Constructs a <see cref="Color"/> from RGBA values, typically on the range of 0 to 1.
/// </summary>
/// <param name="r">The color's red component, typically on the range of 0 to 1.</param>
/// <param name="g">The color's green component, typically on the range of 0 to 1.</param>
@ -508,7 +515,7 @@ namespace Godot
}
/// <summary>
/// Constructs a color from an existing color and an alpha value.
/// Constructs a <see cref="Color"/> from an existing color and an alpha value.
/// </summary>
/// <param name="c">The color to construct from. Only its RGB values are used.</param>
/// <param name="a">The color's alpha (transparency) value, typically on the range of 0 to 1. Default: 1.</param>
@ -521,10 +528,10 @@ namespace Godot
}
/// <summary>
/// Constructs a color from an unsigned 32-bit integer in RGBA format
/// Constructs a <see cref="Color"/> from an unsigned 32-bit integer in RGBA format
/// (each byte represents a color channel).
/// </summary>
/// <param name="rgba">The uint representing the color.</param>
/// <param name="rgba">The <see langword="uint"/> representing the color.</param>
public Color(uint rgba)
{
a = (rgba & 0xFF) / 255.0f;
@ -537,10 +544,10 @@ namespace Godot
}
/// <summary>
/// Constructs a color from an unsigned 64-bit integer in RGBA format
/// Constructs a <see cref="Color"/> from an unsigned 64-bit integer in RGBA format
/// (each word represents a color channel).
/// </summary>
/// <param name="rgba">The ulong representing the color.</param>
/// <param name="rgba">The <see langword="ulong"/> representing the color.</param>
public Color(ulong rgba)
{
a = (rgba & 0xFFFF) / 65535.0f;
@ -553,9 +560,9 @@ namespace Godot
}
/// <summary>
/// Constructs a color either from an HTML color code or from a
/// standardized color name. Supported
/// color names are the same as the <see cref="Colors"/> constants.
/// Constructs a <see cref="Color"/> either from an HTML color code or from a
/// standardized color name. Supported color names are the same as the
/// <see cref="Colors"/> constants.
/// </summary>
/// <param name="code">The HTML color code or color name to construct from.</param>
public Color(string code)
@ -571,8 +578,8 @@ namespace Godot
}
/// <summary>
/// Constructs a color either from an HTML color code or from a
/// standardized color name, with `alpha` on the range of 0 to 1. Supported
/// Constructs a <see cref="Color"/> either from an HTML color code or from a
/// standardized color name, with <paramref name="alpha"/> on the range of 0 to 1. Supported
/// color names are the same as the <see cref="Colors"/> constants.
/// </summary>
/// <param name="code">The HTML color code or color name to construct from.</param>
@ -584,9 +591,12 @@ namespace Godot
}
/// <summary>
/// Constructs a color from the HTML hexadecimal color string in RGBA format.
/// Constructs a <see cref="Color"/> from the HTML hexadecimal color string in RGBA format.
/// </summary>
/// <param name="rgba">A string for the HTML hexadecimal representation of this color.</param>
/// <exception name="ArgumentOutOfRangeException">
/// Thrown when the given <paramref name="rgba"/> color code is invalid.
/// </exception>
private static Color FromHTML(string rgba)
{
Color c;
@ -716,7 +726,7 @@ namespace Godot
/// <summary>
/// Constructs a color from an HSV profile, with values on the
/// range of 0 to 1. This is equivalent to using each of
/// the `h`/`s`/`v` properties, but much more efficient.
/// the <c>h</c>/<c>s</c>/<c>v</c> properties, but much more efficient.
/// </summary>
/// <param name="hue">The HSV hue, typically on the range of 0 to 1.</param>
/// <param name="saturation">The HSV saturation, typically on the range of 0 to 1.</param>
@ -762,7 +772,7 @@ namespace Godot
/// <summary>
/// Converts a color to HSV values. This is equivalent to using each of
/// the `h`/`s`/`v` properties, but much more efficient.
/// the <c>h</c>/<c>s</c>/<c>v</c> properties, but much more efficient.
/// </summary>
/// <param name="hue">Output parameter for the HSV hue.</param>
/// <param name="saturation">Output parameter for the HSV saturation.</param>
@ -980,6 +990,11 @@ namespace Godot
return left.r > right.r;
}
/// <summary>
/// Returns <see langword="true"/> if this color and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the color and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Color)
@ -990,14 +1005,19 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this color and <paramref name="other"/> are equal
/// </summary>
/// <param name="other">The other color to compare.</param>
/// <returns>Whether or not the colors are equal.</returns>
public bool Equals(Color other)
{
return r == other.r && g == other.g && b == other.b && a == other.a;
}
/// <summary>
/// Returns true if this color and `other` are approximately equal, by running
/// <see cref="Godot.Mathf.IsEqualApprox(float, float)"/> on each component.
/// Returns <see langword="true"/> if this color and <paramref name="other"/> are approximately equal,
/// by running <see cref="Mathf.IsEqualApprox(float, float)"/> on each component.
/// </summary>
/// <param name="other">The other color to compare.</param>
/// <returns>Whether or not the colors are approximately equal.</returns>
@ -1006,16 +1026,28 @@ namespace Godot
return Mathf.IsEqualApprox(r, other.r) && Mathf.IsEqualApprox(g, other.g) && Mathf.IsEqualApprox(b, other.b) && Mathf.IsEqualApprox(a, other.a);
}
/// <summary>
/// Serves as the hash function for <see cref="Color"/>.
/// </summary>
/// <returns>A hash code for this color.</returns>
public override int GetHashCode()
{
return r.GetHashCode() ^ g.GetHashCode() ^ b.GetHashCode() ^ a.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Color"/> to a string.
/// </summary>
/// <returns>A string representation of this color.</returns>
public override string ToString()
{
return $"({r}, {g}, {b}, {a})";
}
/// <summary>
/// Converts this <see cref="Color"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this color.</returns>
public string ToString(string format)
{
return $"({r.ToString(format)}, {g.ToString(format)}, {b.ToString(format)}, {a.ToString(format)})";

30
modules/mono/glue/GodotSharp/GodotSharp/Core/DynamicObject.cs
View file

@ -7,20 +7,20 @@ using System.Runtime.CompilerServices;
namespace Godot
{
/// <summary>
/// Represents an <see cref="Godot.Object"/> whose members can be dynamically accessed at runtime through the Variant API.
/// Represents an <see cref="Object"/> whose members can be dynamically accessed at runtime through the Variant API.
/// </summary>
/// <remarks>
/// <para>
/// The <see cref="Godot.DynamicGodotObject"/> class enables access to the Variant
/// members of a <see cref="Godot.Object"/> instance at runtime.
/// The <see cref="DynamicGodotObject"/> class enables access to the Variant
/// members of a <see cref="Object"/> instance at runtime.
/// </para>
/// <para>
/// This allows accessing the class members using their original names in the engine as well as the members from the
/// script attached to the <see cref="Godot.Object"/>, regardless of the scripting language it was written in.
/// script attached to the <see cref="Object"/>, regardless of the scripting language it was written in.
/// </para>
/// </remarks>
/// <example>
/// This sample shows how to use <see cref="Godot.DynamicGodotObject"/> to dynamically access the engine members of a <see cref="Godot.Object"/>.
/// This sample shows how to use <see cref="DynamicGodotObject"/> to dynamically access the engine members of a <see cref="Object"/>.
/// <code>
/// dynamic sprite = GetNode("Sprite2D").DynamicGodotObject;
/// sprite.add_child(this);
@ -30,7 +30,7 @@ namespace Godot
/// </code>
/// </example>
/// <example>
/// This sample shows how to use <see cref="Godot.DynamicGodotObject"/> to dynamically access the members of the script attached to a <see cref="Godot.Object"/>.
/// This sample shows how to use <see cref="DynamicGodotObject"/> to dynamically access the members of the script attached to a <see cref="Object"/>.
/// <code>
/// dynamic childNode = GetNode("ChildNode").DynamicGodotObject;
///
@ -54,18 +54,18 @@ namespace Godot
public class DynamicGodotObject : DynamicObject
{
/// <summary>
/// Gets the <see cref="Godot.Object"/> associated with this <see cref="Godot.DynamicGodotObject"/>.
/// Gets the <see cref="Object"/> associated with this <see cref="DynamicGodotObject"/>.
/// </summary>
public Object Value { get; }
/// <summary>
/// Initializes a new instance of the <see cref="Godot.DynamicGodotObject"/> class.
/// Initializes a new instance of the <see cref="DynamicGodotObject"/> class.
/// </summary>
/// <param name="godotObject">
/// The <see cref="Godot.Object"/> that will be associated with this <see cref="Godot.DynamicGodotObject"/>.
/// The <see cref="Object"/> that will be associated with this <see cref="DynamicGodotObject"/>.
/// </param>
/// <exception cref="System.ArgumentNullException">
/// Thrown when the <paramref name="godotObject"/> parameter is null.
/// <exception cref="ArgumentNullException">
/// Thrown when the <paramref name="godotObject"/> parameter is <see langword="null"/>.
/// </exception>
public DynamicGodotObject(Object godotObject)
{
@ -75,11 +75,13 @@ namespace Godot
Value = godotObject;
}
/// <inheritdoc/>
public override IEnumerable<string> GetDynamicMemberNames()
{
return godot_icall_DynamicGodotObject_SetMemberList(Object.GetPtr(Value));
}
/// <inheritdoc/>
public override bool TryBinaryOperation(BinaryOperationBinder binder, object arg, out object result)
{
switch (binder.Operation)
@ -121,6 +123,7 @@ namespace Godot
return base.TryBinaryOperation(binder, arg, out result);
}
/// <inheritdoc/>
public override bool TryConvert(ConvertBinder binder, out object result)
{
if (binder.Type == typeof(Object))
@ -139,6 +142,7 @@ namespace Godot
return base.TryConvert(binder, out result);
}
/// <inheritdoc/>
public override bool TryGetIndex(GetIndexBinder binder, object[] indexes, out object result)
{
if (indexes.Length == 1)
@ -152,16 +156,19 @@ namespace Godot
return base.TryGetIndex(binder, indexes, out result);
}
/// <inheritdoc/>
public override bool TryGetMember(GetMemberBinder binder, out object result)
{
return godot_icall_DynamicGodotObject_GetMember(Object.GetPtr(Value), binder.Name, out result);
}
/// <inheritdoc/>
public override bool TryInvokeMember(InvokeMemberBinder binder, object[] args, out object result)
{
return godot_icall_DynamicGodotObject_InvokeMember(Object.GetPtr(Value), binder.Name, args, out result);
}
/// <inheritdoc/>
public override bool TrySetIndex(SetIndexBinder binder, object[] indexes, object value)
{
if (indexes.Length == 1)
@ -175,6 +182,7 @@ namespace Godot
return base.TrySetIndex(binder, indexes, value);
}
/// <inheritdoc/>
public override bool TrySetMember(SetMemberBinder binder, object value)
{
return godot_icall_DynamicGodotObject_SetMember(Object.GetPtr(Value), binder.Name, value);

148
modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/NodeExtensions.cs
View file

@ -1,42 +1,190 @@
using System;
namespace Godot
{
public partial class Node
{
/// <summary>
/// Fetches a node. The <see cref="NodePath"/> can be either a relative path (from
/// the current node) or an absolute path (in the scene tree) to a node. If the path
/// does not exist, a <see langword="null"/> instance is returned and an error
/// is logged. Attempts to access methods on the return value will result in an
/// "Attempt to call &lt;method&gt; on a null instance." error.
/// Note: Fetching absolute paths only works when the node is inside the scene tree
/// (see <see cref="IsInsideTree"/>).
/// </summary>
/// <example>
/// Example: Assume your current node is Character and the following tree:
/// <code>
/// /root
/// /root/Character
/// /root/Character/Sword
/// /root/Character/Backpack/Dagger
/// /root/MyGame
/// /root/Swamp/Alligator
/// /root/Swamp/Mosquito
/// /root/Swamp/Goblin
/// </code>
/// Possible paths are:
/// <code>
/// GetNode("Sword");
/// GetNode("Backpack/Dagger");
/// GetNode("../Swamp/Alligator");
/// GetNode("/root/MyGame");
/// </code>
/// </example>
/// <seealso cref="GetNodeOrNull{T}(NodePath)"/>
/// <param name="path">The path to the node to fetch.</param>
/// <exception cref="InvalidCastException">
/// Thrown when the given the fetched node can't be casted to the given type <typeparamref name="T"/>.
/// </exception>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
/// <returns>
/// The <see cref="Node"/> at the given <paramref name="path"/>.
/// </returns>
public T GetNode<T>(NodePath path) where T : class
{
return (T)(object)GetNode(path);
}
/// <summary>
/// Fetches a node. The <see cref="NodePath"/> can be either a relative path (from
/// the current node) or an absolute path (in the scene tree) to a node. If the path
/// does not exist, a <see langword="null"/> instance is returned and an error
/// is logged. Attempts to access methods on the return value will result in an
/// "Attempt to call &lt;method&gt; on a null instance." error.
/// Note: Fetching absolute paths only works when the node is inside the scene tree
/// (see <see cref="IsInsideTree"/>).
/// </summary>
/// <example>
/// Example: Assume your current node is Character and the following tree:
/// <code>
/// /root
/// /root/Character
/// /root/Character/Sword
/// /root/Character/Backpack/Dagger
/// /root/MyGame
/// /root/Swamp/Alligator
/// /root/Swamp/Mosquito
/// /root/Swamp/Goblin
/// </code>
/// Possible paths are:
/// <code>
/// GetNode("Sword");
/// GetNode("Backpack/Dagger");
/// GetNode("../Swamp/Alligator");
/// GetNode("/root/MyGame");
/// </code>
/// </example>
/// <seealso cref="GetNode{T}(NodePath)"/>
/// <param name="path">The path to the node to fetch.</param>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>/// ///////// <returns>
/// The <see cref="Node"/> at the given <paramref name="path"/>, or <see langword="null"/> if not found.
/// </returns>
public T GetNodeOrNull<T>(NodePath path) where T : class
{
return GetNodeOrNull(path) as T;
}
/// <summary>
/// Returns a child node by its index (see <see cref="GetChildCount"/>).
/// This method is often used for iterating all children of a node.
/// Negative indices access the children from the last one.
/// To access a child node via its name, use <see cref="GetNode"/>.
/// </summary>
/// <seealso cref="GetChildOrNull{T}(int)"/>
/// <param name="idx">Child index.</param>
/// <exception cref="InvalidCastException">
/// Thrown when the given the fetched node can't be casted to the given type <typeparamref name="T"/>.
/// </exception>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>/// ///////// <returns>
/// The child <see cref="Node"/> at the given index <paramref name="idx"/>.
/// </returns>
public T GetChild<T>(int idx) where T : class
{
return (T)(object)GetChild(idx);
}
/// <summary>
/// Returns a child node by its index (see <see cref="GetChildCount"/>).
/// This method is often used for iterating all children of a node.
/// Negative indices access the children from the last one.
/// To access a child node via its name, use <see cref="GetNode"/>.
/// </summary>
/// <seealso cref="GetChild{T}(int)"/>
/// <param name="idx">Child index.</param>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
/// <returns>
/// The child <see cref="Node"/> at the given index <paramref name="idx"/>, or <see langword="null"/> if not found.
/// </returns>
public T GetChildOrNull<T>(int idx) where T : class
{
return GetChild(idx) as T;
}
/// <summary>
/// The node owner. A node can have any other node as owner (as long as it is
/// a valid parent, grandparent, etc. ascending in the tree). When saving a
/// node (using <see cref="PackedScene"/>), all the nodes it owns will be saved
/// with it. This allows for the creation of complex <see cref="SceneTree"/>s,
/// with instancing and subinstancing.
/// </summary>
/// <seealso cref="GetOwnerOrNull{T}"/>
/// <exception cref="InvalidCastException">
/// Thrown when the given the fetched node can't be casted to the given type <typeparamref name="T"/>.
/// </exception>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
/// <returns>
/// The owner <see cref="Node"/>.
/// </returns>
public T GetOwner<T>() where T : class
{
return (T)(object)Owner;
}
/// <summary>
/// The node owner. A node can have any other node as owner (as long as it is
/// a valid parent, grandparent, etc. ascending in the tree). When saving a
/// node (using <see cref="PackedScene"/>), all the nodes it owns will be saved
/// with it. This allows for the creation of complex <see cref="SceneTree"/>s,
/// with instancing and subinstancing.
/// </summary>
/// <seealso cref="GetOwner{T}"/>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
/// <returns>
/// The owner <see cref="Node"/>, or <see langword="null"/> if there is no owner.
/// </returns>
public T GetOwnerOrNull<T>() where T : class
{
return Owner as T;
}
/// <summary>
/// Returns the parent node of the current node, or a <see langword="null"/> instance
/// if the node lacks a parent.
/// </summary>
/// <seealso cref="GetParentOrNull{T}"/>
/// <exception cref="InvalidCastException">
/// Thrown when the given the fetched node can't be casted to the given type <typeparamref name="T"/>.
/// </exception>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
/// <returns>
/// The parent <see cref="Node"/>.
/// </returns>
public T GetParent<T>() where T : class
{
return (T)(object)GetParent();
}
/// <summary>
/// Returns the parent node of the current node, or a <see langword="null"/> instance
/// if the node lacks a parent.
/// </summary>
/// <seealso cref="GetParent{T}"/>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
/// <returns>
/// The parent <see cref="Node"/>, or <see langword="null"/> if the node has no parent.
/// </returns>
public T GetParentOrNull<T>() where T : class
{
return GetParent() as T;

22
modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ObjectExtensions.cs
View file

@ -5,14 +5,34 @@ namespace Godot
{
public partial class Object
{
/// <summary>
/// Returns whether <paramref name="instance"/> is a valid object
/// (e.g. has not been deleted from memory).
/// </summary>
/// <param name="instance">The instance to check.</param>
/// <returns>If the instance is a valid object.</returns>
public static bool IsInstanceValid(Object instance)
{
return instance != null && instance.NativeInstance != IntPtr.Zero;
}
/// <summary>
/// Returns a weak reference to an object, or <see langword="null"/>
/// if the argument is invalid.
/// A weak reference to an object is not enough to keep the object alive:
/// when the only remaining references to a referent are weak references,
/// garbage collection is free to destroy the referent and reuse its memory
/// for something else. However, until the object is actually destroyed the
/// weak reference may return the object even if there are no strong references
/// to it.
/// </summary>
/// <param name="obj">The object.</param>
/// <returns>
/// The <see cref="WeakRef"/> reference to the object or <see langword="null"/>.
/// </returns>
public static WeakRef WeakRef(Object obj)
{
return godot_icall_Object_weakref(Object.GetPtr(obj));
return godot_icall_Object_weakref(GetPtr(obj));
}
[MethodImpl(MethodImplOptions.InternalCall)]

19
modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/PackedSceneExtensions.cs
View file

@ -1,3 +1,5 @@
using System;
namespace Godot
{
public partial class PackedScene
@ -5,20 +7,27 @@ namespace Godot
/// <summary>
/// Instantiates the scene's node hierarchy, erroring on failure.
/// Triggers child scene instantiation(s). Triggers a
/// `Node.NotificationInstanced` notification on the root node.
/// <see cref="Node.NotificationInstanced"/> notification on the root node.
/// </summary>
/// <typeparam name="T">The type to cast to. Should be a descendant of Node.</typeparam>
/// <seealso cref="InstantiateOrNull{T}(GenEditState)"/>
/// <exception cref="InvalidCastException">
/// Thrown when the given the instantiated node can't be casted to the given type <typeparamref name="T"/>.
/// </exception>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
/// <returns>The instantiated scene.</returns>
public T Instantiate<T>(PackedScene.GenEditState editState = (PackedScene.GenEditState)0) where T : class
{
return (T)(object)Instantiate(editState);
}
/// <summary>
/// Instantiates the scene's node hierarchy, returning null on failure.
/// Instantiates the scene's node hierarchy, returning <see langword="null"/> on failure.
/// Triggers child scene instantiation(s). Triggers a
/// `Node.NotificationInstanced` notification on the root node.
/// <see cref="Node.NotificationInstanced"/> notification on the root node.
/// </summary>
/// <typeparam name="T">The type to cast to. Should be a descendant of Node.</typeparam>
/// <seealso cref="Instantiate{T}(GenEditState)"/>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
/// <returns>The instantiated scene.</returns>
public T InstantiateOrNull<T>(PackedScene.GenEditState editState = (PackedScene.GenEditState)0) where T : class
{
return Instantiate(editState) as T;

24
modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/ResourceLoaderExtensions.cs
View file

@ -1,10 +1,30 @@
using System;
namespace Godot
{
public static partial class ResourceLoader
{
public static T Load<T>(string path, string typeHint = null, CacheMode noCache = CacheMode.Reuse) where T : class
/// <summary>
/// Loads a resource at the given <paramref name="path"/>, caching the result
/// for further access.
/// The registered <see cref="ResourceFormatLoader"/> instances are queried sequentially
/// to find the first one which can handle the file's extension, and then attempt
/// loading. If loading fails, the remaining ResourceFormatLoaders are also attempted.
/// An optional <paramref name="typeHint"/> can be used to further specify the
/// <see cref="Resource"/> type that should be handled by the <see cref="ResourceFormatLoader"/>.
/// Anything that inherits from <see cref="Resource"/> can be used as a type hint,
/// for example <see cref="Image"/>.
/// The <paramref name="cacheMode"/> property defines whether and how the cache should
/// be used or updated when loading the resource. See <see cref="CacheMode"/> for details.
/// Returns an empty resource if no <see cref="ResourceFormatLoader"/> could handle the file.
/// </summary>
/// <exception cref="InvalidCastException">
/// Thrown when the given the loaded resource can't be casted to the given type <typeparamref name="T"/>.
/// </exception>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Resource"/>.</typeparam>
public static T Load<T>(string path, string typeHint = null, CacheMode cacheMode = CacheMode.Reuse) where T : class
{
return (T)(object)Load(path, typeHint, noCache);
return (T)(object)Load(path, typeHint, cacheMode);
}
}
}

6
modules/mono/glue/GodotSharp/GodotSharp/Core/Extensions/SceneTreeExtensions.cs
View file

@ -6,9 +6,13 @@ namespace Godot
{
public partial class SceneTree
{
/// <summary>
/// Returns a list of all nodes assigned to the given <paramref name="group"/>.
/// </summary>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Node"/>.</typeparam>
public Array<T> GetNodesInGroup<T>(StringName group) where T : class
{
return new Array<T>(godot_icall_SceneTree_get_nodes_in_group_Generic(Object.GetPtr(this), StringName.GetPtr(group), typeof(T)));
return new Array<T>(godot_icall_SceneTree_get_nodes_in_group_Generic(GetPtr(this), StringName.GetPtr(group), typeof(T)));
}
[MethodImpl(MethodImplOptions.InternalCall)]

342
modules/mono/glue/GodotSharp/GodotSharp/Core/GD.cs
View file

@ -7,22 +7,56 @@ using System;
using System.Collections.Generic;
using System.Runtime.CompilerServices;
// TODO: Add comments describing what this class does. It is not obvious.
namespace Godot
{
/// <summary>
/// Godot's global functions.
/// </summary>
public static partial class GD
{
/// <summary>
/// Decodes a byte array back to a <c>Variant</c> value.
/// If <paramref name="allowObjects"/> is <see langword="true"/> decoding objects is allowed.
///
/// WARNING: Deserialized object can contain code which gets executed.
/// Do not set <paramref name="allowObjects"/> to <see langword="true"/>
/// if the serialized object comes from untrusted sources to avoid
/// potential security threats (remote code execution).
/// </summary>
/// <param name="bytes">Byte array that will be decoded to a <c>Variant</c>.</param>
/// <param name="allowObjects">If objects should be decoded.</param>
/// <returns>The decoded <c>Variant</c>.</returns>
public static object Bytes2Var(byte[] bytes, bool allowObjects = false)
{
return godot_icall_GD_bytes2var(bytes, allowObjects);
}
/// <summary>
/// Converts from a <c>Variant</c> type to another in the best way possible.
/// The <paramref name="type"/> parameter uses the <see cref="Variant.Type"/> values.
/// </summary>
/// <example>
/// <code>
/// var a = new Vector2(1, 0);
/// // Prints 1
/// GD.Print(a.Length());
/// var b = GD.Convert(a, Variant.Type.String)
/// // Prints 6 as "(1, 0)" is 6 characters
/// GD.Print(b.Length);
/// </code>
/// </example>
/// <returns>The <c>Variant</c> converted to the given <paramref name="type"/>.</returns>
public static object Convert(object what, Variant.Type type)
{
return godot_icall_GD_convert(what, type);
}
/// <summary>
/// Converts from decibels to linear energy (audio).
/// </summary>
/// <seealso cref="Linear2Db(real_t)"/>
/// <param name="db">Decibels to convert.</param>
/// <returns>Audio volume as linear energy.</returns>
public static real_t Db2Linear(real_t db)
{
return (real_t)Math.Exp(db * 0.11512925464970228420089957273422);
@ -38,111 +72,360 @@ namespace Godot
return Array.ConvertAll(parameters, x => x?.ToString() ?? "null");
}
/// <summary>
/// Returns the integer hash of the variable passed.
/// </summary>
/// <example>
/// <code>
/// GD.Print(GD.Hash("a")); // Prints 177670
/// </code>
/// </example>
/// <param name="var">Variable that will be hashed.</param>
/// <returns>Hash of the variable passed.</returns>
public static int Hash(object var)
{
return godot_icall_GD_hash(var);
}
/// <summary>
/// Returns the <see cref="Object"/> that corresponds to <paramref name="instanceId"/>.
/// All Objects have a unique instance ID.
/// </summary>
/// <example>
/// <code>
/// public class MyNode : Node
/// {
/// public string foo = "bar";
///
/// public override void _Ready()
/// {
/// ulong id = GetInstanceId();
/// var inst = (MyNode)GD.InstanceFromId(Id);
/// GD.Print(inst.foo); // Prints bar
/// }
/// }
/// </code>
/// </example>
/// <param name="instanceId">Instance ID of the Object to retrieve.</param>
/// <returns>The <see cref="Object"/> instance.</returns>
public static Object InstanceFromId(ulong instanceId)
{
return godot_icall_GD_instance_from_id(instanceId);
}
/// <summary>
/// Converts from linear energy to decibels (audio).
/// This can be used to implement volume sliders that behave as expected (since volume isn't linear).
/// </summary>
/// <seealso cref="Db2Linear(real_t)"/>
/// <example>
/// <code>
/// // "slider" refers to a node that inherits Range such as HSlider or VSlider.
/// // Its range must be configured to go from 0 to 1.
/// // Change the bus name if you'd like to change the volume of a specific bus only.
/// AudioServer.SetBusVolumeDb(AudioServer.GetBusIndex("Master"), GD.Linear2Db(slider.value));
/// </code>
/// </example>
/// <param name="linear">The linear energy to convert.</param>
/// <returns>Audio as decibels</returns>
public static real_t Linear2Db(real_t linear)
{
return (real_t)(Math.Log(linear) * 8.6858896380650365530225783783321);
}
/// <summary>
/// Loads a resource from the filesystem located at <paramref name="path"/>.
/// The resource is loaded on the method call (unless it's referenced already
/// elsewhere, e.g. in another script or in the scene), which might cause slight delay,
/// especially when loading scenes. To avoid unnecessary delays when loading something
/// multiple times, either store the resource in a variable.
///
/// Note: Resource paths can be obtained by right-clicking on a resource in the FileSystem
/// dock and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script.
///
/// Important: The path must be absolute, a local path will just return <see langword="null"/>.
/// This method is a simplified version of <see cref="ResourceLoader.Load"/>, which can be used
/// for more advanced scenarios.
/// </summary>
/// <example>
/// <code>
/// // Load a scene called main located in the root of the project directory and cache it in a variable.
/// var main = GD.Load("res://main.tscn"); // main will contain a PackedScene resource.
/// </code>
/// </example>
/// <param name="path">Path of the <see cref="Resource"/> to load.</param>
/// <returns>The loaded <see cref="Resource"/>.</returns>
public static Resource Load(string path)
{
return ResourceLoader.Load(path);
}
/// <summary>
/// Loads a resource from the filesystem located at <paramref name="path"/>.
/// The resource is loaded on the method call (unless it's referenced already
/// elsewhere, e.g. in another script or in the scene), which might cause slight delay,
/// especially when loading scenes. To avoid unnecessary delays when loading something
/// multiple times, either store the resource in a variable.
///
/// Note: Resource paths can be obtained by right-clicking on a resource in the FileSystem
/// dock and choosing "Copy Path" or by dragging the file from the FileSystem dock into the script.
///
/// Important: The path must be absolute, a local path will just return <see langword="null"/>.
/// This method is a simplified version of <see cref="ResourceLoader.Load"/>, which can be used
/// for more advanced scenarios.
/// </summary>
/// <example>
/// <code>
/// // Load a scene called main located in the root of the project directory and cache it in a variable.
/// var main = GD.Load&lt;PackedScene&gt;("res://main.tscn"); // main will contain a PackedScene resource.
/// </code>
/// </example>
/// <param name="path">Path of the <see cref="Resource"/> to load.</param>
/// <typeparam name="T">The type to cast to. Should be a descendant of <see cref="Resource"/>.</typeparam>
public static T Load<T>(string path) where T : class
{
return ResourceLoader.Load<T>(path);
}
/// <summary>
/// Pushes an error message to Godot's built-in debugger and to the OS terminal.
///
/// Note: Errors printed this way will not pause project execution.
/// To print an error message and pause project execution in debug builds,
/// use [code]assert(false, "test error")[/code] instead.
/// </summary>
/// <example>
/// <code>
/// GD.PushError("test_error"); // Prints "test error" to debugger and terminal as error call
/// </code>
/// </example>
/// <param name="message">Error message.</param>
public static void PushError(string message)
{
godot_icall_GD_pusherror(message);
}
/// <summary>
/// Pushes a warning message to Godot's built-in debugger and to the OS terminal.
/// </summary>
/// <example>
/// GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as warning call
/// </example>
/// <param name="message">Warning message.</param>
public static void PushWarning(string message)
{
godot_icall_GD_pushwarning(message);
}
/// <summary>
/// Converts one or more arguments of any type to string in the best way possible
/// and prints them to the console.
///
/// Note: Consider using <see cref="PushError(string)"/> and <see cref="PushWarning(string)"/>
/// to print error and warning messages instead of <see cref="Print(object[])"/>.
/// This distinguishes them from print messages used for debugging purposes,
/// while also displaying a stack trace when an error or warning is printed.
/// </summary>
/// <example>
/// <code>
/// var a = new int[] { 1, 2, 3 };
/// GD.Print("a", "b", a); // Prints ab[1, 2, 3]
/// </code>
/// </example>
/// <param name="what">Arguments that will be printed.</param>
public static void Print(params object[] what)
{
godot_icall_GD_print(GetPrintParams(what));
}
/// <summary>
/// Prints the current stack trace information to the console.
/// </summary>
public static void PrintStack()
{
Print(System.Environment.StackTrace);
}
/// <summary>
/// Prints one or more arguments to strings in the best way possible to standard error line.
/// </summary>
/// <example>
/// <code>
/// GD.PrintErr("prints to stderr");
/// </code>
/// </example>
/// <param name="what">Arguments that will be printed.</param>
public static void PrintErr(params object[] what)
{
godot_icall_GD_printerr(GetPrintParams(what));
}
/// <summary>
/// Prints one or more arguments to strings in the best way possible to console.
/// No newline is added at the end.
///
/// Note: Due to limitations with Godot's built-in console, this only prints to the terminal.
/// If you need to print in the editor, use another method, such as <see cref="Print(object[])"/>.
/// </summary>
/// <example>
/// <code>
/// GD.PrintRaw("A");
/// GD.PrintRaw("B");
/// // Prints AB
/// </code>
/// </example>
/// <param name="what">Arguments that will be printed.</param>
public static void PrintRaw(params object[] what)
{
godot_icall_GD_printraw(GetPrintParams(what));
}
/// <summary>
/// Prints one or more arguments to the console with a space between each argument.
/// </summary>
/// <example>
/// <code>
/// GD.PrintS("A", "B", "C"); // Prints A B C
/// </code>
/// </example>
/// <param name="what">Arguments that will be printed.</param>
public static void PrintS(params object[] what)
{
godot_icall_GD_prints(GetPrintParams(what));
}
/// <summary>
/// Prints one or more arguments to the console with a tab between each argument.
/// </summary>
/// <example>
/// <code>
/// GD.PrintT("A", "B", "C"); // Prints A B C
/// </code>
/// </example>
/// <param name="what">Arguments that will be printed.</param>
public static void PrintT(params object[] what)
{
godot_icall_GD_printt(GetPrintParams(what));
}
/// <summary>
/// Returns a random floating point value between <c>0.0</c> and <c>1.0</c> (inclusive).
/// </summary>
/// <example>
/// <code>
/// GD.Randf(); // Returns e.g. 0.375671
/// </code>
/// </example>
/// <returns>A random <see langword="float"/> number.</returns>
public static float Randf()
{
return godot_icall_GD_randf();
}
/// <summary>
/// Returns a random unsigned 32-bit integer.
/// Use remainder to obtain a random value in the interval <c>[0, N - 1]</c> (where N is smaller than 2^32).
/// </summary>
/// <example>
/// <code>
/// GD.Randi(); // Returns random integer between 0 and 2^32 - 1
/// GD.Randi() % 20; // Returns random integer between 0 and 19
/// GD.Randi() % 100; // Returns random integer between 0 and 99
/// GD.Randi() % 100 + 1; // Returns random integer between 1 and 100
/// </code>
/// </example>
/// <returns>A random <see langword="uint"/> number.</returns>
public static uint Randi()
{
return godot_icall_GD_randi();
}
/// <summary>
/// Randomizes the seed (or the internal state) of the random number generator.
/// Current implementation reseeds using a number based on time.
///
/// Note: This method is called automatically when the project is run.
/// If you need to fix the seed to have reproducible results, use <see cref="Seed(ulong)"/>
/// to initialize the random number generator.
/// </summary>
public static void Randomize()
{
godot_icall_GD_randomize();
}
/// <summary>
/// Returns a random floating point value on the interval between <paramref name="from"/>
/// and <paramref name="to"/> (inclusive).
/// </summary>
/// <example>
/// <code>
/// GD.PrintS(GD.RandRange(-10.0, 10.0), GD.RandRange(-10.0, 10.0)); // Prints e.g. -3.844535 7.45315
/// </code>
/// </example>
/// <returns>A random <see langword="double"/> number inside the given range.</returns>
public static double RandRange(double from, double to)
{
return godot_icall_GD_randf_range(from, to);
}
/// <summary>
/// Returns a random signed 32-bit integer between <paramref name="from"/>
/// and <paramref name="to"/> (inclusive). If <paramref name="to"/> is lesser than
/// <paramref name="from"/>, they are swapped.
/// </summary>
/// <example>
/// <code>
/// GD.Print(GD.RandRange(0, 1)); // Prints 0 or 1
/// GD.Print(GD.RangeRange(-10, 1000)); // Prints any number from -10 to 1000
/// </code>
/// </example>
/// <returns>A random <see langword="int"/> number inside the given range.</returns>
public static int RandRange(int from, int to)
{
return godot_icall_GD_randi_range(from, to);
}
/// <summary>
/// Returns a random unsigned 32-bit integer, using the given <paramref name="seed"/>.
/// </summary>
/// <param name="seed">
/// Seed to use to generate the random number.
/// If a different seed is used, its value will be modfied.
/// </param>
/// <returns>A random <see langword="uint"/> number.</returns>
public static uint RandFromSeed(ref ulong seed)
{
return godot_icall_GD_rand_seed(seed, out seed);
}
/// <summary>
/// Returns a <see cref="IEnumerable{T}"/> that iterates from
/// <c>0</c> to <paramref name="end"/> in steps of <c>1</c>.
/// </summary>
/// <param name="end">The last index.</param>
public static IEnumerable<int> Range(int end)
{
return Range(0, end, 1);
}
/// <summary>
/// Returns a <see cref="IEnumerable{T}"/> that iterates from
/// <paramref name="start"/> to <paramref name="end"/> in steps of <c>1</c>.
/// </summary>
/// <param name="start">The first index.</param>
/// <param name="end">The last index.</param>
public static IEnumerable<int> Range(int start, int end)
{
return Range(start, end, 1);
}
/// <summary>
/// Returns a <see cref="IEnumerable{T}"/> that iterates from
/// <paramref name="start"/> to <paramref name="end"/> in steps of <paramref name="step"/>.
/// </summary>
/// <param name="start">The first index.</param>
/// <param name="end">The last index.</param>
/// <param name="step">The amount by which to increment the index on each iteration.</param>
public static IEnumerable<int> Range(int start, int end, int step)
{
if (end < start && step > 0)
@ -163,36 +446,91 @@ namespace Godot
}
}
/// <summary>
/// Sets seed for the random number generator.
/// </summary>
/// <param name="seed">Seed that will be used.</param>
public static void Seed(ulong seed)
{
godot_icall_GD_seed(seed);
}
/// <summary>
/// Converts one or more arguments of any type to string in the best way possible.
/// </summary>
/// <param name="what">Arguments that will converted to string.</param>
/// <returns>The string formed by the given arguments.</returns>
public static string Str(params object[] what)
{
return godot_icall_GD_str(what);
}
/// <summary>
/// Converts a formatted string that was returned by <see cref="Var2Str(object)"/> to the original value.
/// </summary>
/// <example>
/// <code>
/// string a = "{\"a\": 1, \"b\": 2 }";
/// var b = (Godot.Collections.Dictionary)GD.Str2Var(a);
/// GD.Print(b["a"]); // Prints 1
/// </code>
/// </example>
/// <param name="str">String that will be converted to Variant.</param>
/// <returns>The decoded <c>Variant</c>.</returns>
public static object Str2Var(string str)
{
return godot_icall_GD_str2var(str);
}
/// <summary>
/// Returns whether the given class exists in <see cref="ClassDB"/>.
/// </summary>
/// <returns>If the class exists in <see cref="ClassDB"/>.</returns>
public static bool TypeExists(StringName type)
{
return godot_icall_GD_type_exists(StringName.GetPtr(type));
}
/// <summary>
/// Encodes a <c>Variant</c> value to a byte array.
/// If <paramref name="fullObjects"/> is <see langword="true"/> encoding objects is allowed
/// (and can potentially include code).
/// Deserialization can be done with <see cref="Bytes2Var(byte[], bool)"/>.
/// </summary>
/// <param name="var">Variant that will be encoded.</param>
/// <param name="fullObjects">If objects should be serialized.</param>
/// <returns>The <c>Variant</c> encoded as an array of bytes.</returns>
public static byte[] Var2Bytes(object var, bool fullObjects = false)
{
return godot_icall_GD_var2bytes(var, fullObjects);
}
/// <summary>
/// Converts a <c>Variant</c> <paramref name="var"/> to a formatted string that
/// can later be parsed using <see cref="Str2Var(string)"/>.
/// </summary>
/// <example>
/// <code>
/// var a = new Godot.Collections.Dictionary { ["a"] = 1, ["b"] = 2 };
/// GD.Print(GD.Var2Str(a));
/// // Prints
/// // {
/// // "a": 1,
/// // "b": 2
/// // }
/// </code>
/// </example>
/// <param name="var">Variant that will be converted to string.</param>
/// <returns>The <c>Variant</c> encoded as a string.</returns>
public static string Var2Str(object var)
{
return godot_icall_GD_var2str(var);
}
/// <summary>
/// Get the <see cref="Variant.Type"/> that corresponds for the given <see cref="Type"/>.
/// </summary>
/// <returns>The <see cref="Variant.Type"/> for the given <paramref name="type"/>.</returns>
public static Variant.Type TypeToVariantType(Type type)
{
return godot_icall_TypeToVariantType(type);

99
modules/mono/glue/GodotSharp/GodotSharp/Core/MarshalUtils.cs
View file

@ -7,41 +7,102 @@ namespace Godot
{
/// <summary>
/// Returns <see langword="true"/> if the generic type definition of <paramref name="type"/>
/// is <see cref="Godot.Collections.Array{T}"/>; otherwise returns <see langword="false"/>.
/// is <see cref="Collections.Array{T}"/>; otherwise returns <see langword="false"/>.
/// </summary>
/// <exception cref="System.InvalidOperationException">
/// <paramref name="type"/> is not a generic type. That is, IsGenericType returns false.
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="type"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static bool TypeIsGenericArray(Type type) =>
type.GetGenericTypeDefinition() == typeof(Godot.Collections.Array<>);
type.GetGenericTypeDefinition() == typeof(Collections.Array<>);
/// <summary>
/// Returns <see langword="true"/> if the generic type definition of <paramref name="type"/>
/// is <see cref="Godot.Collections.Dictionary{TKey, TValue}"/>; otherwise returns <see langword="false"/>.
/// is <see cref="Collections.Dictionary{TKey, TValue}"/>; otherwise returns <see langword="false"/>.
/// </summary>
/// <exception cref="System.InvalidOperationException">
/// <paramref name="type"/> is not a generic type. That is, IsGenericType returns false.
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="type"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static bool TypeIsGenericDictionary(Type type) =>
type.GetGenericTypeDefinition() == typeof(Godot.Collections.Dictionary<,>);
type.GetGenericTypeDefinition() == typeof(Collections.Dictionary<,>);
/// <summary>
/// Returns <see langword="true"/> if the generic type definition of <paramref name="type"/>
/// is <see cref="List{T}"/>; otherwise returns <see langword="false"/>.
/// </summary>
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="type"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static bool TypeIsSystemGenericList(Type type) =>
type.GetGenericTypeDefinition() == typeof(System.Collections.Generic.List<>);
type.GetGenericTypeDefinition() == typeof(List<>);
/// <summary>
/// Returns <see langword="true"/> if the generic type definition of <paramref name="type"/>
/// is <see cref="Dictionary{TKey, TValue}"/>; otherwise returns <see langword="false"/>.
/// </summary>
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="type"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static bool TypeIsSystemGenericDictionary(Type type) =>
type.GetGenericTypeDefinition() == typeof(System.Collections.Generic.Dictionary<,>);
type.GetGenericTypeDefinition() == typeof(Dictionary<,>);
/// <summary>
/// Returns <see langword="true"/> if the generic type definition of <paramref name="type"/>
/// is <see cref="IEnumerable{T}"/>; otherwise returns <see langword="false"/>.
/// </summary>
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="type"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static bool TypeIsGenericIEnumerable(Type type) => type.GetGenericTypeDefinition() == typeof(IEnumerable<>);
/// <summary>
/// Returns <see langword="true"/> if the generic type definition of <paramref name="type"/>
/// is <see cref="ICollection{T}"/>; otherwise returns <see langword="false"/>.
/// </summary>
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="type"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static bool TypeIsGenericICollection(Type type) => type.GetGenericTypeDefinition() == typeof(ICollection<>);
/// <summary>
/// Returns <see langword="true"/> if the generic type definition of <paramref name="type"/>
/// is <see cref="IDictionary{TKey, TValue}"/>; otherwise returns <see langword="false"/>.
/// </summary>
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="type"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static bool TypeIsGenericIDictionary(Type type) => type.GetGenericTypeDefinition() == typeof(IDictionary<,>);
/// <summary>
/// Gets the element type for the given <paramref name="arrayType"/>.
/// </summary>
/// <param name="arrayType">Type for the generic array.</param>
/// <param name="elementType">Element type for the generic array.</param>
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="arrayType"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static void ArrayGetElementType(Type arrayType, out Type elementType)
{
elementType = arrayType.GetGenericArguments()[0];
}
/// <summary>
/// Gets the key type and the value type for the given <paramref name="dictionaryType"/>.
/// </summary>
/// <param name="dictionaryType">The type for the generic dictionary.</param>
/// <param name="keyType">Key type for the generic dictionary.</param>
/// <param name="valueType">Value type for the generic dictionary.</param>
/// <exception cref="InvalidOperationException">
/// Thrown when the given <paramref name="dictionaryType"/> is not a generic type.
/// That is, <see cref="Type.IsGenericType"/> returns <see langword="false"/>.
/// </exception>
private static void DictionaryGetKeyValueTypes(Type dictionaryType, out Type keyType, out Type valueType)
{
var genericArgs = dictionaryType.GetGenericArguments();
@ -49,14 +110,28 @@ namespace Godot
valueType = genericArgs[1];
}
/// <summary>
/// Constructs a new <see cref="Type"/> from <see cref="Collections.Array{T}"/>
/// where the generic type for the elements is <paramref name="elemType"/>.
/// </summary>
/// <param name="elemType">Element type for the array.</param>
/// <returns>The generic array type with the specified element type.</returns>
private static Type MakeGenericArrayType(Type elemType)
{
return typeof(Godot.Collections.Array<>).MakeGenericType(elemType);
return typeof(Collections.Array<>).MakeGenericType(elemType);
}
/// <summary>
/// Constructs a new <see cref="Type"/> from <see cref="Collections.Dictionary{TKey, TValue}"/>
/// where the generic type for the keys is <paramref name="keyType"/> and
/// for the values is <paramref name="valueType"/>.
/// </summary>
/// <param name="keyType">Key type for the dictionary.</param>
/// <param name="valueType">Key type for the dictionary.</param>
/// <returns>The generic dictionary type with the specified key and value types.</returns>
private static Type MakeGenericDictionaryType(Type keyType, Type valueType)
{
return typeof(Godot.Collections.Dictionary<,>).MakeGenericType(keyType, valueType);
return typeof(Collections.Dictionary<,>).MakeGenericType(keyType, valueType);
}
}
}

162
modules/mono/glue/GodotSharp/GodotSharp/Core/Mathf.cs
View file

@ -7,6 +7,9 @@ using System;
namespace Godot
{
/// <summary>
/// Provides constants and static methods for common mathematical functions.
/// </summary>
public static partial class Mathf
{
// Define constants with Decimal precision and cast down to double or float.
@ -19,18 +22,18 @@ namespace Godot
/// <summary>
/// Constant that represents how many times the diameter of a circle
/// fits around its perimeter. This is equivalent to `Mathf.Tau / 2`.
/// fits around its perimeter. This is equivalent to <c>Mathf.Tau / 2</c>.
/// </summary>
// 3.1415927f and 3.14159265358979
public const real_t Pi = (real_t)3.1415926535897932384626433833M;
/// <summary>
/// Positive infinity. For negative infinity, use `-Mathf.Inf`.
/// Positive infinity. For negative infinity, use <c>-Mathf.Inf</c>.
/// </summary>
public const real_t Inf = real_t.PositiveInfinity;
/// <summary>
/// "Not a Number", an invalid value. `NaN` has special properties, including
/// "Not a Number", an invalid value. <c>NaN</c> has special properties, including
/// that it is not equal to itself. It is output by some invalid operations,
/// such as dividing zero by zero.
/// </summary>
@ -42,85 +45,97 @@ namespace Godot
private const real_t _rad2DegConst = (real_t)57.295779513082320876798154814M;
/// <summary>
/// Returns the absolute value of `s` (i.e. positive value).
/// Returns the absolute value of <paramref name="s"/> (i.e. positive value).
/// </summary>
/// <param name="s">The input number.</param>
/// <returns>The absolute value of `s`.</returns>
/// <returns>The absolute value of <paramref name="s"/>.</returns>
public static int Abs(int s)
{
return Math.Abs(s);
}
/// <summary>
/// Returns the absolute value of `s` (i.e. positive value).
/// Returns the absolute value of <paramref name="s"/> (i.e. positive value).
/// </summary>
/// <param name="s">The input number.</param>
/// <returns>The absolute value of `s`.</returns>
/// <returns>The absolute value of <paramref name="s"/>.</returns>
public static real_t Abs(real_t s)
{
return Math.Abs(s);
}
/// <summary>
/// Returns the arc cosine of `s` in radians. Use to get the angle of cosine s.
/// Returns the arc cosine of <paramref name="s"/> in radians.
/// Use to get the angle of cosine <paramref name="s"/>.
/// </summary>
/// <param name="s">The input cosine value. Must be on the range of -1.0 to 1.0.</param>
/// <returns>An angle that would result in the given cosine value. On the range `0` to `Tau/2`.</returns>
/// <returns>
/// An angle that would result in the given cosine value. On the range <c>0</c> to <c>Tau/2</c>.
/// </returns>
public static real_t Acos(real_t s)
{
return (real_t)Math.Acos(s);
}
/// <summary>
/// Returns the arc sine of `s` in radians. Use to get the angle of sine s.
/// Returns the arc sine of <paramref name="s"/> in radians.
/// Use to get the angle of sine <paramref name="s"/>.
/// </summary>
/// <param name="s">The input sine value. Must be on the range of -1.0 to 1.0.</param>
/// <returns>An angle that would result in the given sine value. On the range `-Tau/4` to `Tau/4`.</returns>
/// <returns>
/// An angle that would result in the given sine value. On the range <c>-Tau/4</c> to <c>Tau/4</c>.
/// </returns>
public static real_t Asin(real_t s)
{
return (real_t)Math.Asin(s);
}
/// <summary>
/// Returns the arc tangent of `s` in radians. Use to get the angle of tangent s.
/// Returns the arc tangent of <paramref name="s"/> in radians.
/// Use to get the angle of tangent <paramref name="s"/>.
///
/// The method cannot know in which quadrant the angle should fall.
/// See <see cref="Atan2(real_t, real_t)"/> if you have both `y` and `x`.
/// See <see cref="Atan2(real_t, real_t)"/> if you have both <c>y</c> and <c>x</c>.
/// </summary>
/// <param name="s">The input tangent value.</param>
/// <returns>An angle that would result in the given tangent value. On the range `-Tau/4` to `Tau/4`.</returns>
/// <returns>
/// An angle that would result in the given tangent value. On the range <c>-Tau/4</c> to <c>Tau/4</c>.
/// </returns>
public static real_t Atan(real_t s)
{
return (real_t)Math.Atan(s);
}
/// <summary>
/// Returns the arc tangent of `y` and `x` in radians. Use to get the angle
/// of the tangent of `y/x`. To compute the value, the method takes into
/// Returns the arc tangent of <paramref name="y"/> and <paramref name="x"/> in radians.
/// Use to get the angle of the tangent of <c>y/x</c>. To compute the value, the method takes into
/// account the sign of both arguments in order to determine the quadrant.
///
/// Important note: The Y coordinate comes first, by convention.
/// </summary>
/// <param name="y">The Y coordinate of the point to find the angle to.</param>
/// <param name="x">The X coordinate of the point to find the angle to.</param>
/// <returns>An angle that would result in the given tangent value. On the range `-Tau/2` to `Tau/2`.</returns>
/// <returns>
/// An angle that would result in the given tangent value. On the range <c>-Tau/2</c> to <c>Tau/2</c>.
/// </returns>
public static real_t Atan2(real_t y, real_t x)
{
return (real_t)Math.Atan2(y, x);
}
/// <summary>
/// Rounds `s` upward (towards positive infinity).
/// Rounds <paramref name="s"/> upward (towards positive infinity).
/// </summary>
/// <param name="s">The number to ceil.</param>
/// <returns>The smallest whole number that is not less than `s`.</returns>
/// <returns>The smallest whole number that is not less than <paramref name="s"/>.</returns>
public static real_t Ceil(real_t s)
{
return (real_t)Math.Ceiling(s);
}
/// <summary>
/// Clamps a `value` so that it is not less than `min` and not more than `max`.
/// Clamps a <paramref name="value"/> so that it is not less than <paramref name="min"/>
/// and not more than <paramref name="max"/>.
/// </summary>
/// <param name="value">The value to clamp.</param>
/// <param name="min">The minimum allowed value.</param>
@ -132,7 +147,8 @@ namespace Godot
}
/// <summary>
/// Clamps a `value` so that it is not less than `min` and not more than `max`.
/// Clamps a <paramref name="value"/> so that it is not less than <paramref name="min"/>
/// and not more than <paramref name="max"/>.
/// </summary>
/// <param name="value">The value to clamp.</param>
/// <param name="min">The minimum allowed value.</param>
@ -144,7 +160,7 @@ namespace Godot
}
/// <summary>
/// Returns the cosine of angle `s` in radians.
/// Returns the cosine of angle <paramref name="s"/> in radians.
/// </summary>
/// <param name="s">The angle in radians.</param>
/// <returns>The cosine of that angle.</returns>
@ -154,7 +170,7 @@ namespace Godot
}
/// <summary>
/// Returns the hyperbolic cosine of angle `s` in radians.
/// Returns the hyperbolic cosine of angle <paramref name="s"/> in radians.
/// </summary>
/// <param name="s">The angle in radians.</param>
/// <returns>The hyperbolic cosine of that angle.</returns>
@ -174,12 +190,14 @@ namespace Godot
}
/// <summary>
/// Easing function, based on exponent. The curve values are:
/// `0` is constant, `1` is linear, `0` to `1` is ease-in, `1` or more is ease-out.
/// Easing function, based on exponent. The <paramref name="curve"/> values are:
/// <c>0</c> is constant, <c>1</c> is linear, <c>0</c> to <c>1</c> is ease-in, <c>1</c> or more is ease-out.
/// Negative values are in-out/out-in.
/// </summary>
/// <param name="s">The value to ease.</param>
/// <param name="curve">`0` is constant, `1` is linear, `0` to `1` is ease-in, `1` or more is ease-out.</param>
/// <param name="curve">
/// <c>0</c> is constant, <c>1</c> is linear, <c>0</c> to <c>1</c> is ease-in, <c>1</c> or more is ease-out.
/// </param>
/// <returns>The eased value.</returns>
public static real_t Ease(real_t s, real_t curve)
{
@ -217,20 +235,20 @@ namespace Godot
/// <summary>
/// The natural exponential function. It raises the mathematical
/// constant `e` to the power of `s` and returns it.
/// constant <c>e</c> to the power of <paramref name="s"/> and returns it.
/// </summary>
/// <param name="s">The exponent to raise `e` to.</param>
/// <returns>`e` raised to the power of `s`.</returns>
/// <param name="s">The exponent to raise <c>e</c> to.</param>
/// <returns><c>e</c> raised to the power of <paramref name="s"/>.</returns>
public static real_t Exp(real_t s)
{
return (real_t)Math.Exp(s);
}
/// <summary>
/// Rounds `s` downward (towards negative infinity).
/// Rounds <paramref name="s"/> downward (towards negative infinity).
/// </summary>
/// <param name="s">The number to floor.</param>
/// <returns>The largest whole number that is not more than `s`.</returns>
/// <returns>The largest whole number that is not more than <paramref name="s"/>.</returns>
public static real_t Floor(real_t s)
{
return (real_t)Math.Floor(s);
@ -250,12 +268,13 @@ namespace Godot
}
/// <summary>
/// Returns true if `a` and `b` are approximately equal to each other.
/// Returns <see langword="true"/> if <paramref name="a"/> and <paramref name="b"/> are approximately equal
/// to each other.
/// The comparison is done using a tolerance calculation with <see cref="Epsilon"/>.
/// </summary>
/// <param name="a">One of the values.</param>
/// <param name="b">The other value.</param>
/// <returns>A bool for whether or not the two values are approximately equal.</returns>
/// <returns>A <see langword="bool"/> for whether or not the two values are approximately equal.</returns>
public static bool IsEqualApprox(real_t a, real_t b)
{
// Check for exact equality first, required to handle "infinity" values.
@ -273,33 +292,33 @@ namespace Godot
}
/// <summary>
/// Returns whether `s` is an infinity value (either positive infinity or negative infinity).
/// Returns whether <paramref name="s"/> is an infinity value (either positive infinity or negative infinity).
/// </summary>
/// <param name="s">The value to check.</param>
/// <returns>A bool for whether or not the value is an infinity value.</returns>
/// <returns>A <see langword="bool"/> for whether or not the value is an infinity value.</returns>
public static bool IsInf(real_t s)
{
return real_t.IsInfinity(s);
}
/// <summary>
/// Returns whether `s` is a `NaN` ("Not a Number" or invalid) value.
/// Returns whether <paramref name="s"/> is a <c>NaN</c> ("Not a Number" or invalid) value.
/// </summary>
/// <param name="s">The value to check.</param>
/// <returns>A bool for whether or not the value is a `NaN` value.</returns>
/// <returns>A <see langword="bool"/> for whether or not the value is a <c>NaN</c> value.</returns>
public static bool IsNaN(real_t s)
{
return real_t.IsNaN(s);
}
/// <summary>
/// Returns true if `s` is approximately zero.
/// Returns <see langword="true"/> if <paramref name="s"/> is approximately zero.
/// The comparison is done using a tolerance calculation with <see cref="Epsilon"/>.
///
/// This method is faster than using <see cref="IsEqualApprox(real_t, real_t)"/> with one value as zero.
/// </summary>
/// <param name="s">The value to check.</param>
/// <returns>A bool for whether or not the value is nearly zero.</returns>
/// <returns>A <see langword="bool"/> for whether or not the value is nearly zero.</returns>
public static bool IsZeroApprox(real_t s)
{
return Abs(s) < Epsilon;
@ -341,7 +360,7 @@ namespace Godot
/// Note: This is not the same as the "log" function on most calculators, which uses a base 10 logarithm.
/// </summary>
/// <param name="s">The input value.</param>
/// <returns>The natural log of `s`.</returns>
/// <returns>The natural log of <paramref name="s"/>.</returns>
public static real_t Log(real_t s)
{
return (real_t)Math.Log(s);
@ -392,9 +411,9 @@ namespace Godot
}
/// <summary>
/// Moves `from` toward `to` by the `delta` value.
/// Moves <paramref name="from"/> toward <paramref name="to"/> by the <paramref name="delta"/> value.
///
/// Use a negative delta value to move away.
/// Use a negative <paramref name="delta"/> value to move away.
/// </summary>
/// <param name="from">The start value.</param>
/// <param name="to">The value to move towards.</param>
@ -409,7 +428,7 @@ namespace Godot
}
/// <summary>
/// Returns the nearest larger power of 2 for the integer `value`.
/// Returns the nearest larger power of 2 for the integer <paramref name="value"/>.
/// </summary>
/// <param name="value">The input value.</param>
/// <returns>The nearest larger power of 2.</returns>
@ -426,10 +445,10 @@ namespace Godot
}
/// <summary>
/// Performs a canonical Modulus operation, where the output is on the range `[0, b)`.
/// Performs a canonical Modulus operation, where the output is on the range [0, <paramref name="b"/>).
/// </summary>
/// <param name="a">The dividend, the primary input.</param>
/// <param name="b">The divisor. The output is on the range `[0, b)`.</param>
/// <param name="b">The divisor. The output is on the range [0, <paramref name="b"/>).</param>
/// <returns>The resulting output.</returns>
public static int PosMod(int a, int b)
{
@ -442,10 +461,10 @@ namespace Godot
}
/// <summary>
/// Performs a canonical Modulus operation, where the output is on the range `[0, b)`.
/// Performs a canonical Modulus operation, where the output is on the range [0, <paramref name="b"/>).
/// </summary>
/// <param name="a">The dividend, the primary input.</param>
/// <param name="b">The divisor. The output is on the range `[0, b)`.</param>
/// <param name="b">The divisor. The output is on the range [0, <paramref name="b"/>).</param>
/// <returns>The resulting output.</returns>
public static real_t PosMod(real_t a, real_t b)
{
@ -458,11 +477,11 @@ namespace Godot
}
/// <summary>
/// Returns the result of `x` raised to the power of `y`.
/// Returns the result of <paramref name="x"/> raised to the power of <paramref name="y"/>.
/// </summary>
/// <param name="x">The base.</param>
/// <param name="y">The exponent.</param>
/// <returns>`x` raised to the power of `y`.</returns>
/// <returns><paramref name="x"/> raised to the power of <paramref name="y"/>.</returns>
public static real_t Pow(real_t x, real_t y)
{
return (real_t)Math.Pow(x, y);
@ -479,7 +498,7 @@ namespace Godot
}
/// <summary>
/// Rounds `s` to the nearest whole number,
/// Rounds <paramref name="s"/> to the nearest whole number,
/// with halfway cases rounded towards the nearest multiple of two.
/// </summary>
/// <param name="s">The number to round.</param>
@ -490,10 +509,11 @@ namespace Godot
}
/// <summary>
/// Returns the sign of `s`: `-1` or `1`. Returns `0` if `s` is `0`.
/// Returns the sign of <paramref name="s"/>: <c>-1</c> or <c>1</c>.
/// Returns <c>0</c> if <paramref name="s"/> is <c>0</c>.
/// </summary>
/// <param name="s">The input number.</param>
/// <returns>One of three possible values: `1`, `-1`, or `0`.</returns>
/// <returns>One of three possible values: <c>1</c>, <c>-1</c>, or <c>0</c>.</returns>
public static int Sign(int s)
{
if (s == 0)
@ -502,10 +522,11 @@ namespace Godot
}
/// <summary>
/// Returns the sign of `s`: `-1` or `1`. Returns `0` if `s` is `0`.
/// Returns the sign of <paramref name="s"/>: <c>-1</c> or <c>1</c>.
/// Returns <c>0</c> if <paramref name="s"/> is <c>0</c>.
/// </summary>
/// <param name="s">The input number.</param>
/// <returns>One of three possible values: `1`, `-1`, or `0`.</returns>
/// <returns>One of three possible values: <c>1</c>, <c>-1</c>, or <c>0</c>.</returns>
public static int Sign(real_t s)
{
if (s == 0)
@ -514,7 +535,7 @@ namespace Godot
}
/// <summary>
/// Returns the sine of angle `s` in radians.
/// Returns the sine of angle <paramref name="s"/> in radians.
/// </summary>
/// <param name="s">The angle in radians.</param>
/// <returns>The sine of that angle.</returns>
@ -524,7 +545,7 @@ namespace Godot
}
/// <summary>
/// Returns the hyperbolic sine of angle `s` in radians.
/// Returns the hyperbolic sine of angle <paramref name="s"/> in radians.
/// </summary>
/// <param name="s">The angle in radians.</param>
/// <returns>The hyperbolic sine of that angle.</returns>
@ -534,8 +555,8 @@ namespace Godot
}
/// <summary>
/// Returns a number smoothly interpolated between `from` and `to`,
/// based on the `weight`. Similar to <see cref="Lerp(real_t, real_t, real_t)"/>,
/// Returns a number smoothly interpolated between <paramref name="from"/> and <paramref name="to"/>,
/// based on the <paramref name="weight"/>. Similar to <see cref="Lerp(real_t, real_t, real_t)"/>,
/// but interpolates faster at the beginning and slower at the end.
/// </summary>
/// <param name="from">The start value for interpolation.</param>
@ -553,12 +574,12 @@ namespace Godot
}
/// <summary>
/// Returns the square root of `s`, where `s` is a non-negative number.
/// Returns the square root of <paramref name="s"/>, where <paramref name="s"/> is a non-negative number.
///
/// If you need negative inputs, use `System.Numerics.Complex`.
/// If you need negative inputs, use <see cref="System.Numerics.Complex"/>.
/// </summary>
/// <param name="s">The input number. Must not be negative.</param>
/// <returns>The square root of `s`.</returns>
/// <returns>The square root of <paramref name="s"/>.</returns>
public static real_t Sqrt(real_t s)
{
return (real_t)Math.Sqrt(s);
@ -598,9 +619,8 @@ namespace Godot
}
/// <summary>
/// Snaps float value `s` to a given `step`.
/// This can also be used to round a floating point
/// number to an arbitrary number of decimals.
/// Snaps float value <paramref name="s"/> to a given <paramref name="step"/>.
/// This can also be used to round a floating point number to an arbitrary number of decimals.
/// </summary>
/// <param name="s">The value to snap.</param>
/// <param name="step">The step size to snap to.</param>
@ -616,7 +636,7 @@ namespace Godot
}
/// <summary>
/// Returns the tangent of angle `s` in radians.
/// Returns the tangent of angle <paramref name="s"/> in radians.
/// </summary>
/// <param name="s">The angle in radians.</param>
/// <returns>The tangent of that angle.</returns>
@ -626,7 +646,7 @@ namespace Godot
}
/// <summary>
/// Returns the hyperbolic tangent of angle `s` in radians.
/// Returns the hyperbolic tangent of angle <paramref name="s"/> in radians.
/// </summary>
/// <param name="s">The angle in radians.</param>
/// <returns>The hyperbolic tangent of that angle.</returns>
@ -636,8 +656,9 @@ namespace Godot
}
/// <summary>
/// Wraps `value` between `min` and `max`. Usable for creating loop-alike
/// behavior or infinite surfaces. If `min` is `0`, this is equivalent
/// Wraps <paramref name="value"/> between <paramref name="min"/> and <paramref name="max"/>.
/// Usable for creating loop-alike behavior or infinite surfaces.
/// If <paramref name="min"/> is <c>0</c>, this is equivalent
/// to <see cref="PosMod(int, int)"/>, so prefer using that instead.
/// </summary>
/// <param name="value">The value to wrap.</param>
@ -654,8 +675,9 @@ namespace Godot
}
/// <summary>
/// Wraps `value` between `min` and `max`. Usable for creating loop-alike
/// behavior or infinite surfaces. If `min` is `0`, this is equivalent
/// Wraps <paramref name="value"/> between <paramref name="min"/> and <paramref name="max"/>.
/// Usable for creating loop-alike behavior or infinite surfaces.
/// If <paramref name="min"/> is <c>0</c>, this is equivalent
/// to <see cref="PosMod(real_t, real_t)"/>, so prefer using that instead.
/// </summary>
/// <param name="value">The value to wrap.</param>

29
modules/mono/glue/GodotSharp/GodotSharp/Core/MathfEx.cs
View file

@ -12,7 +12,7 @@ namespace Godot
// Define constants with Decimal precision and cast down to double or float.
/// <summary>
/// The natural number `e`.
/// The natural number <c>e</c>.
/// </summary>
public const real_t E = (real_t)2.7182818284590452353602874714M; // 2.7182817f and 2.718281828459045
@ -23,7 +23,7 @@ namespace Godot
/// <summary>
/// A very small number used for float comparison with error tolerance.
/// 1e-06 with single-precision floats, but 1e-14 if `REAL_T_IS_DOUBLE`.
/// 1e-06 with single-precision floats, but 1e-14 if <c>REAL_T_IS_DOUBLE</c>.
/// </summary>
#if REAL_T_IS_DOUBLE
public const real_t Epsilon = 1e-14; // Epsilon size should depend on the precision used.
@ -44,7 +44,7 @@ namespace Godot
/// <summary>
/// Returns the amount of digits after the decimal place.
/// </summary>
/// <param name="s">The input <see cref="System.Decimal"/> value.</param>
/// <param name="s">The input <see cref="decimal"/> value.</param>
/// <returns>The amount of digits.</returns>
public static int DecimalCount(decimal s)
{
@ -52,48 +52,51 @@ namespace Godot
}
/// <summary>
/// Rounds `s` upward (towards positive infinity).
/// Rounds <paramref name="s"/> upward (towards positive infinity).
///
/// This is the same as <see cref="Ceil(real_t)"/>, but returns an `int`.
/// This is the same as <see cref="Ceil(real_t)"/>, but returns an <c>int</c>.
/// </summary>
/// <param name="s">The number to ceil.</param>
/// <returns>The smallest whole number that is not less than `s`.</returns>
/// <returns>The smallest whole number that is not less than <paramref name="s"/>.</returns>
public static int CeilToInt(real_t s)
{
return (int)Math.Ceiling(s);
}
/// <summary>
/// Rounds `s` downward (towards negative infinity).
/// Rounds <paramref name="s"/> downward (towards negative infinity).
///
/// This is the same as <see cref="Floor(real_t)"/>, but returns an `int`.
/// This is the same as <see cref="Floor(real_t)"/>, but returns an <c>int</c>.
/// </summary>
/// <param name="s">The number to floor.</param>
/// <returns>The largest whole number that is not more than `s`.</returns>
/// <returns>The largest whole number that is not more than <paramref name="s"/>.</returns>
public static int FloorToInt(real_t s)
{
return (int)Math.Floor(s);
}
/// <summary>
/// Rounds <paramref name="s"/> to the nearest whole number.
///
/// This is the same as <see cref="Round(real_t)"/>, but returns an <c>int</c>.
/// </summary>
/// <param name="s"></param>
/// <returns></returns>
/// <param name="s">The number to round.</param>
/// <returns>The rounded number.</returns>
public static int RoundToInt(real_t s)
{
return (int)Math.Round(s);
}
/// <summary>
/// Returns true if `a` and `b` are approximately equal to each other.
/// Returns <see langword="true"/> if <paramref name="a"/> and <paramref name="b"/> are approximately
/// equal to each other.
/// The comparison is done using the provided tolerance value.
/// If you want the tolerance to be calculated for you, use <see cref="IsEqualApprox(real_t, real_t)"/>.
/// </summary>
/// <param name="a">One of the values.</param>
/// <param name="b">The other value.</param>
/// <param name="tolerance">The pre-calculated tolerance value.</param>
/// <returns>A bool for whether or not the two values are equal.</returns>
/// <returns>A <see langword="bool"/> for whether or not the two values are equal.</returns>
public static bool IsEqualApprox(real_t a, real_t b, real_t tolerance)
{
// Check for exact equality first, required to handle "infinity" values.

152
modules/mono/glue/GodotSharp/GodotSharp/Core/NodePath.cs
View file

@ -3,6 +3,42 @@ using System.Runtime.CompilerServices;
namespace Godot
{
/// <summary>
/// A pre-parsed relative or absolute path in a scene tree,
/// for use with <see cref="Node.GetNode(NodePath)"/> and similar functions.
/// It can reference a node, a resource within a node, or a property
/// of a node or resource.
/// For instance, <c>"Path2D/PathFollow2D/Sprite2D:texture:size"</c>
/// would refer to the <c>size</c> property of the <c>texture</c>
/// resource on the node named <c>"Sprite2D"</c> which is a child of
/// the other named nodes in the path.
/// You will usually just pass a string to <see cref="Node.GetNode(NodePath)"/>
/// and it will be automatically converted, but you may occasionally
/// want to parse a path ahead of time with NodePath.
/// Exporting a NodePath variable will give you a node selection widget
/// in the properties panel of the editor, which can often be useful.
/// A NodePath is composed of a list of slash-separated node names
/// (like a filesystem path) and an optional colon-separated list of
/// "subnames" which can be resources or properties.
///
/// Note: In the editor, NodePath properties are automatically updated when moving,
/// renaming or deleting a node in the scene tree, but they are never updated at runtime.
/// </summary>
/// <example>
/// Some examples of NodePaths include the following:
/// <code>
/// // No leading slash means it is relative to the current node.
/// new NodePath("A"); // Immediate child A.
/// new NodePath("A/B"); // A's child B.
/// new NodePath("."); // The current node.
/// new NodePath(".."); // The parent node.
/// new NodePath("../C"); // A sibling node C.
/// // A leading slash means it is absolute from the SceneTree.
/// new NodePath("/root"); // Equivalent to GetTree().Root
/// new NodePath("/root/Main"); // If your main scene's root node were named "Main".
/// new NodePath("/root/MyAutoload"); // If you have an autoloaded node or scene.
/// </code>
/// </example>
public sealed partial class NodePath : IDisposable
{
private bool _disposed = false;
@ -25,6 +61,9 @@ namespace Godot
Dispose(false);
}
/// <summary>
/// Disposes of this <see cref="NodePath"/>.
/// </summary>
public void Dispose()
{
Dispose(true);
@ -50,57 +89,168 @@ namespace Godot
this.ptr = ptr;
}
public NodePath() : this(string.Empty) {}
/// <summary>
/// Constructs an empty <see cref="NodePath"/>.
/// </summary>
public NodePath() : this(string.Empty) { }
/// <summary>
/// Constructs a <see cref="NodePath"/> from a string <paramref name="path"/>,
/// e.g.: <c>"Path2D/PathFollow2D/Sprite2D:texture:size"</c>.
/// A path is absolute if it starts with a slash. Absolute paths
/// are only valid in the global scene tree, not within individual
/// scenes. In a relative path, <c>"."</c> and <c>".."</c> indicate
/// the current node and its parent.
/// The "subnames" optionally included after the path to the target
/// node can point to resources or properties, and can also be nested.
/// </summary>
/// <example>
/// Examples of valid NodePaths (assuming that those nodes exist and
/// have the referenced resources or properties):
/// <code>
/// // Points to the Sprite2D node.
/// "Path2D/PathFollow2D/Sprite2D"
/// // Points to the Sprite2D node and its "texture" resource.
/// // GetNode() would retrieve "Sprite2D", while GetNodeAndResource()
/// // would retrieve both the Sprite2D node and the "texture" resource.
/// "Path2D/PathFollow2D/Sprite2D:texture"
/// // Points to the Sprite2D node and its "position" property.
/// "Path2D/PathFollow2D/Sprite2D:position"
/// // Points to the Sprite2D node and the "x" component of its "position" property.
/// "Path2D/PathFollow2D/Sprite2D:position:x"
/// // Absolute path (from "root")
/// "/root/Level/Path2D"
/// </code>
/// </example>
/// <param name="path"></param>
public NodePath(string path)
{
ptr = godot_icall_NodePath_Ctor(path);
}
/// <summary>
/// Converts a string to a <see cref="NodePath"/>.
/// </summary>
/// <param name="from">The string to convert.</param>
public static implicit operator NodePath(string from) => new NodePath(from);
/// <summary>
/// Converts this <see cref="NodePath"/> to a string.
/// </summary>
/// <param name="from">The <see cref="NodePath"/> to convert.</param>
public static implicit operator string(NodePath from) => from.ToString();
/// <summary>
/// Converts this <see cref="NodePath"/> to a string.
/// </summary>
/// <returns>A string representation of this <see cref="NodePath"/>.</returns>
public override string ToString()
{
return godot_icall_NodePath_operator_String(GetPtr(this));
}
/// <summary>
/// Returns a node path with a colon character (<c>:</c>) prepended,
/// transforming it to a pure property path with no node name (defaults
/// to resolving from the current node).
/// </summary>
/// <example>
/// <code>
/// // This will be parsed as a node path to the "x" property in the "position" node.
/// var nodePath = new NodePath("position:x");
/// // This will be parsed as a node path to the "x" component of the "position" property in the current node.
/// NodePath propertyPath = nodePath.GetAsPropertyPath();
/// GD.Print(propertyPath); // :position:x
/// </code>
/// </example>
/// <returns>The <see cref="NodePath"/> as a pure property path.</returns>
public NodePath GetAsPropertyPath()
{
return new NodePath(godot_icall_NodePath_get_as_property_path(GetPtr(this)));
}
/// <summary>
/// Returns all subnames concatenated with a colon character (<c>:</c>)
/// as separator, i.e. the right side of the first colon in a node path.
/// </summary>
/// <example>
/// <code>
/// var nodepath = new NodePath("Path2D/PathFollow2D/Sprite2D:texture:load_path");
/// GD.Print(nodepath.GetConcatenatedSubnames()); // texture:load_path
/// </code>
/// </example>
/// <returns>The subnames concatenated with <c>:</c>.</returns>
public string GetConcatenatedSubnames()
{
return godot_icall_NodePath_get_concatenated_subnames(GetPtr(this));
}
/// <summary>
/// Gets the node name indicated by <paramref name="idx"/> (0 to <see cref="GetNameCount"/>).
/// </summary>
/// <example>
/// <code>
/// var nodePath = new NodePath("Path2D/PathFollow2D/Sprite2D");
/// GD.Print(nodePath.GetName(0)); // Path2D
/// GD.Print(nodePath.GetName(1)); // PathFollow2D
/// GD.Print(nodePath.GetName(2)); // Sprite
/// </code>
/// </example>
/// <param name="idx">The name index.</param>
/// <returns>The name at the given index <paramref name="idx"/>.</returns>
public string GetName(int idx)
{
return godot_icall_NodePath_get_name(GetPtr(this), idx);
}
/// <summary>
/// Gets the number of node names which make up the path.
/// Subnames (see <see cref="GetSubnameCount"/>) are not included.
/// For example, <c>"Path2D/PathFollow2D/Sprite2D"</c> has 3 names.
/// </summary>
/// <returns>The number of node names which make up the path.</returns>
public int GetNameCount()
{
return godot_icall_NodePath_get_name_count(GetPtr(this));
}
/// <summary>
/// Gets the resource or property name indicated by <paramref name="idx"/> (0 to <see cref="GetSubnameCount"/>).
/// </summary>
/// <param name="idx">The subname index.</param>
/// <returns>The subname at the given index <paramref name="idx"/>.</returns>
public string GetSubname(int idx)
{
return godot_icall_NodePath_get_subname(GetPtr(this), idx);
}
/// <summary>
/// Gets the number of resource or property names ("subnames") in the path.
/// Each subname is listed after a colon character (<c>:</c>) in the node path.
/// For example, <c>"Path2D/PathFollow2D/Sprite2D:texture:load_path"</c> has 2 subnames.
/// </summary>
/// <returns>The number of subnames in the path.</returns>
public int GetSubnameCount()
{
return godot_icall_NodePath_get_subname_count(GetPtr(this));
}
/// <summary>
/// Returns <see langword="true"/> if the node path is absolute (as opposed to relative),
/// which means that it starts with a slash character (<c>/</c>). Absolute node paths can
/// be used to access the root node (<c>"/root"</c>) or autoloads (e.g. <c>"/global"</c>
/// if a "global" autoload was registered).
/// </summary>
/// <returns>If the <see cref="NodePath"/> is an absolute path.</returns>
public bool IsAbsolute()
{
return godot_icall_NodePath_is_absolute(GetPtr(this));
}
/// <summary>
/// Returns <see langword="true"/> if the node path is empty.
/// </summary>
/// <returns>If the <see cref="NodePath"/> is empty.</returns>
public bool IsEmpty()
{
return godot_icall_NodePath_is_empty(GetPtr(this));

24
modules/mono/glue/GodotSharp/GodotSharp/Core/Object.base.cs
View file

@ -12,6 +12,9 @@ namespace Godot
internal IntPtr ptr;
internal bool memoryOwn;
/// <summary>
/// Constructs a new <see cref="Object"/>.
/// </summary>
public Object() : this(false)
{
if (ptr == IntPtr.Zero)
@ -29,6 +32,9 @@ namespace Godot
this.memoryOwn = memoryOwn;
}
/// <summary>
/// The pointer to the native instance of this <see cref="Object"/>.
/// </summary>
public IntPtr NativeInstance
{
get { return ptr; }
@ -50,12 +56,18 @@ namespace Godot
Dispose(false);
}
/// <summary>
/// Disposes of this <see cref="Object"/>.
/// </summary>
public void Dispose()
{
Dispose(true);
GC.SuppressFinalize(this);
}
/// <summary>
/// Disposes implementation of this <see cref="Object"/>.
/// </summary>
protected virtual void Dispose(bool disposing)
{
if (_disposed)
@ -79,13 +91,17 @@ namespace Godot
_disposed = true;
}
/// <summary>
/// Converts this <see cref="Object"/> to a string.
/// </summary>
/// <returns>A string representation of this object.</returns>
public override string ToString()
{
return godot_icall_Object_ToString(GetPtr(this));
}
/// <summary>
/// Returns a new <see cref="Godot.SignalAwaiter"/> awaiter configured to complete when the instance
/// Returns a new <see cref="SignalAwaiter"/> awaiter configured to complete when the instance
/// <paramref name="source"/> emits the signal specified by the <paramref name="signal"/> parameter.
/// </summary>
/// <param name="source">
@ -107,13 +123,17 @@ namespace Godot
/// }
/// </code>
/// </example>
/// <returns>
/// A <see cref="SignalAwaiter"/> that completes when
/// <paramref name="source"/> emits the <paramref name="signal"/>.
/// </returns>
public SignalAwaiter ToSignal(Object source, StringName signal)
{
return new SignalAwaiter(source, signal, this);
}
/// <summary>
/// Gets a new <see cref="Godot.DynamicGodotObject"/> associated with this instance.
/// Gets a new <see cref="DynamicGodotObject"/> associated with this instance.
/// </summary>
public dynamic DynamicObject => new DynamicGodotObject(this);

92
modules/mono/glue/GodotSharp/GodotSharp/Core/Plane.cs
View file

@ -21,10 +21,10 @@ namespace Godot
/// <summary>
/// The normal of the plane, which must be normalized.
/// In the scalar equation of the plane `ax + by + cz = d`, this is
/// the vector `(a, b, c)`, where `d` is the <see cref="D"/> property.
/// In the scalar equation of the plane <c>ax + by + cz = d</c>, this is
/// the vector <c>(a, b, c)</c>, where <c>d</c> is the <see cref="D"/> property.
/// </summary>
/// <value>Equivalent to `x`, `y`, and `z`.</value>
/// <value>Equivalent to <see cref="x"/>, <see cref="y"/>, and <see cref="z"/>.</value>
public Vector3 Normal
{
get { return _normal; }
@ -82,8 +82,8 @@ namespace Godot
/// <summary>
/// The distance from the origin to the plane (in the direction of
/// <see cref="Normal"/>). This value is typically non-negative.
/// In the scalar equation of the plane `ax + by + cz = d`,
/// this is `d`, while the `(a, b, c)` coordinates are represented
/// In the scalar equation of the plane <c>ax + by + cz = d</c>,
/// this is <c>d</c>, while the <c>(a, b, c)</c> coordinates are represented
/// by the <see cref="Normal"/> property.
/// </summary>
/// <value>The plane's distance from the origin.</value>
@ -92,7 +92,7 @@ namespace Godot
/// <summary>
/// The center of the plane, the point where the normal line intersects the plane.
/// </summary>
/// <value>Equivalent to <see cref="Normal"/> multiplied by `D`.</value>
/// <value>Equivalent to <see cref="Normal"/> multiplied by <see cref="D"/>.</value>
public Vector3 Center
{
get
@ -107,7 +107,7 @@ namespace Godot
}
/// <summary>
/// Returns the shortest distance from this plane to the position `point`.
/// Returns the shortest distance from this plane to the position <paramref name="point"/>.
/// </summary>
/// <param name="point">The position to use for the calculation.</param>
/// <returns>The shortest distance.</returns>
@ -117,12 +117,12 @@ namespace Godot
}
/// <summary>
/// Returns true if point is inside the plane.
/// Returns <see langword="true"/> if point is inside the plane.
/// Comparison uses a custom minimum epsilon threshold.
/// </summary>
/// <param name="point">The point to check.</param>
/// <param name="epsilon">The tolerance threshold.</param>
/// <returns>A bool for whether or not the plane has the point.</returns>
/// <returns>A <see langword="bool"/> for whether or not the plane has the point.</returns>
public bool HasPoint(Vector3 point, real_t epsilon = Mathf.Epsilon)
{
real_t dist = _normal.Dot(point) - D;
@ -130,12 +130,12 @@ namespace Godot
}
/// <summary>
/// Returns the intersection point of the three planes: `b`, `c`,
/// and this plane. If no intersection is found, `null` is returned.
/// Returns the intersection point of the three planes: <paramref name="b"/>, <paramref name="c"/>,
/// and this plane. If no intersection is found, <see langword="null"/> is returned.
/// </summary>
/// <param name="b">One of the three planes to use in the calculation.</param>
/// <param name="c">One of the three planes to use in the calculation.</param>
/// <returns>The intersection, or `null` if none is found.</returns>
/// <returns>The intersection, or <see langword="null"/> if none is found.</returns>
public Vector3? Intersect3(Plane b, Plane c)
{
real_t denom = _normal.Cross(b._normal).Dot(c._normal);
@ -153,13 +153,13 @@ namespace Godot
}
/// <summary>
/// Returns the intersection point of a ray consisting of the
/// position `from` and the direction normal `dir` with this plane.
/// If no intersection is found, `null` is returned.
/// Returns the intersection point of a ray consisting of the position <paramref name="from"/>
/// and the direction normal <paramref name="dir"/> with this plane.
/// If no intersection is found, <see langword="null"/> is returned.
/// </summary>
/// <param name="from">The start of the ray.</param>
/// <param name="dir">The direction of the ray, normalized.</param>
/// <returns>The intersection, or `null` if none is found.</returns>
/// <returns>The intersection, or <see langword="null"/> if none is found.</returns>
public Vector3? IntersectRay(Vector3 from, Vector3 dir)
{
real_t den = _normal.Dot(dir);
@ -182,12 +182,12 @@ namespace Godot
/// <summary>
/// Returns the intersection point of a line segment from
/// position `begin` to position `end` with this plane.
/// If no intersection is found, `null` is returned.
/// position <paramref name="begin"/> to position <paramref name="end"/> with this plane.
/// If no intersection is found, <see langword="null"/> is returned.
/// </summary>
/// <param name="begin">The start of the line segment.</param>
/// <param name="end">The end of the line segment.</param>
/// <returns>The intersection, or `null` if none is found.</returns>
/// <returns>The intersection, or <see langword="null"/> if none is found.</returns>
public Vector3? IntersectSegment(Vector3 begin, Vector3 end)
{
Vector3 segment = begin - end;
@ -210,10 +210,10 @@ namespace Godot
}
/// <summary>
/// Returns true if `point` is located above the plane.
/// Returns <see langword="true"/> if <paramref name="point"/> is located above the plane.
/// </summary>
/// <param name="point">The point to check.</param>
/// <returns>A bool for whether or not the point is above the plane.</returns>
/// <returns>A <see langword="bool"/> for whether or not the point is above the plane.</returns>
public bool IsPointOver(Vector3 point)
{
return _normal.Dot(point) > D;
@ -236,7 +236,7 @@ namespace Godot
}
/// <summary>
/// Returns the orthogonal projection of `point` into the plane.
/// Returns the orthogonal projection of <paramref name="point"/> into the plane.
/// </summary>
/// <param name="point">The point to project.</param>
/// <returns>The projected point.</returns>
@ -251,27 +251,28 @@ namespace Godot
private static readonly Plane _planeXY = new Plane(0, 0, 1, 0);
/// <summary>
/// A plane that extends in the Y and Z axes (normal vector points +X).
/// A <see cref="Plane"/> that extends in the Y and Z axes (normal vector points +X).
/// </summary>
/// <value>Equivalent to `new Plane(1, 0, 0, 0)`.</value>
/// <value>Equivalent to <c>new Plane(1, 0, 0, 0)</c>.</value>
public static Plane PlaneYZ { get { return _planeYZ; } }
/// <summary>
/// A plane that extends in the X and Z axes (normal vector points +Y).
/// A <see cref="Plane"/> that extends in the X and Z axes (normal vector points +Y).
/// </summary>
/// <value>Equivalent to `new Plane(0, 1, 0, 0)`.</value>
/// <value>Equivalent to <c>new Plane(0, 1, 0, 0)</c>.</value>
public static Plane PlaneXZ { get { return _planeXZ; } }
/// <summary>
/// A plane that extends in the X and Y axes (normal vector points +Z).
/// A <see cref="Plane"/> that extends in the X and Y axes (normal vector points +Z).
/// </summary>
/// <value>Equivalent to `new Plane(0, 0, 1, 0)`.</value>
/// <value>Equivalent to <c>new Plane(0, 0, 1, 0)</c>.</value>
public static Plane PlaneXY { get { return _planeXY; } }
/// <summary>
/// Constructs a plane from four values. `a`, `b` and `c` become the
/// Constructs a <see cref="Plane"/> from four values.
/// <paramref name="a"/>, <paramref name="b"/> and <paramref name="c"/> become the
/// components of the resulting plane's <see cref="Normal"/> vector.
/// `d` becomes the plane's distance from the origin.
/// <paramref name="d"/> becomes the plane's distance from the origin.
/// </summary>
/// <param name="a">The X component of the plane's normal vector.</param>
/// <param name="b">The Y component of the plane's normal vector.</param>
@ -284,7 +285,8 @@ namespace Godot
}
/// <summary>
/// Constructs a plane from a normal vector and the plane's distance to the origin.
/// Constructs a <see cref="Plane"/> from a <paramref name="normal"/> vector and
/// the plane's distance to the origin <paramref name="d"/>.
/// </summary>
/// <param name="normal">The normal of the plane, must be normalized.</param>
/// <param name="d">The plane's distance from the origin. This value is typically non-negative.</param>
@ -295,7 +297,7 @@ namespace Godot
}
/// <summary>
/// Constructs a plane from the three points, given in clockwise order.
/// Constructs a <see cref="Plane"/> from the three points, given in clockwise order.
/// </summary>
/// <param name="v1">The first point.</param>
/// <param name="v2">The second point.</param>
@ -322,6 +324,11 @@ namespace Godot
return !left.Equals(right);
}
/// <summary>
/// Returns <see langword="true"/> if this plane and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the plane and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Plane)
@ -332,14 +339,19 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this plane and <paramref name="other"/> are equal.
/// </summary>
/// <param name="other">The other plane to compare.</param>
/// <returns>Whether or not the planes are equal.</returns>
public bool Equals(Plane other)
{
return _normal == other._normal && D == other.D;
}
/// <summary>
/// Returns true if this plane and `other` are approximately equal, by running
/// <see cref="Mathf.IsEqualApprox(real_t, real_t)"/> on each component.
/// Returns <see langword="true"/> if this plane and <paramref name="other"/> are
/// approximately equal, by running <see cref="Mathf.IsEqualApprox(real_t, real_t)"/> on each component.
/// </summary>
/// <param name="other">The other plane to compare.</param>
/// <returns>Whether or not the planes are approximately equal.</returns>
@ -348,16 +360,28 @@ namespace Godot
return _normal.IsEqualApprox(other._normal) && Mathf.IsEqualApprox(D, other.D);
}
/// <summary>
/// Serves as the hash function for <see cref="Plane"/>.
/// </summary>
/// <returns>A hash code for this plane.</returns>
public override int GetHashCode()
{
return _normal.GetHashCode() ^ D.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Plane"/> to a string.
/// </summary>
/// <returns>A string representation of this plane.</returns>
public override string ToString()
{
return $"{_normal}, {D}";
}
/// <summary>
/// Converts this <see cref="Plane"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this plane.</returns>
public string ToString(string format)
{
return $"{_normal.ToString(format)}, {D.ToString(format)}";

91
modules/mono/glue/GodotSharp/GodotSharp/Core/Quaternion.cs
View file

@ -12,10 +12,10 @@ namespace Godot
/// A unit quaternion used for representing 3D rotations.
/// Quaternions need to be normalized to be used for rotation.
///
/// It is similar to Basis, which implements matrix representation of
/// rotations, and can be parametrized using both an axis-angle pair
/// or Euler angles. Basis stores rotation, scale, and shearing,
/// while Quaternion only stores rotation.
/// It is similar to <see cref="Basis"/>, which implements matrix
/// representation of rotations, and can be parametrized using both
/// an axis-angle pair or Euler angles. Basis stores rotation, scale,
/// and shearing, while Quaternion only stores rotation.
///
/// Due to its compactness and the way it is stored in memory, certain
/// operations (obtaining axis-angle and performing SLERP, in particular)
@ -26,19 +26,19 @@ namespace Godot
public struct Quaternion : IEquatable<Quaternion>
{
/// <summary>
/// X component of the quaternion (imaginary `i` axis part).
/// X component of the quaternion (imaginary <c>i</c> axis part).
/// Quaternion components should usually not be manipulated directly.
/// </summary>
public real_t x;
/// <summary>
/// Y component of the quaternion (imaginary `j` axis part).
/// Y component of the quaternion (imaginary <c>j</c> axis part).
/// Quaternion components should usually not be manipulated directly.
/// </summary>
public real_t y;
/// <summary>
/// Z component of the quaternion (imaginary `k` axis part).
/// Z component of the quaternion (imaginary <c>k</c> axis part).
/// Quaternion components should usually not be manipulated directly.
/// </summary>
public real_t z;
@ -52,7 +52,12 @@ namespace Godot
/// <summary>
/// Access quaternion components using their index.
/// </summary>
/// <value>`[0]` is equivalent to `.x`, `[1]` is equivalent to `.y`, `[2]` is equivalent to `.z`, `[3]` is equivalent to `.w`.</value>
/// <value>
/// <c>[0]</c> is equivalent to <see cref="x"/>,
/// <c>[1]</c> is equivalent to <see cref="y"/>,
/// <c>[2]</c> is equivalent to <see cref="z"/>,
/// <c>[3]</c> is equivalent to <see cref="w"/>.
/// </value>
public real_t this[int index]
{
get
@ -96,7 +101,8 @@ namespace Godot
/// <summary>
/// Returns the length (magnitude) of the quaternion.
/// </summary>
/// <value>Equivalent to `Mathf.Sqrt(LengthSquared)`.</value>
/// <seealso cref="LengthSquared"/>
/// <value>Equivalent to <c>Mathf.Sqrt(LengthSquared)</c>.</value>
public real_t Length
{
get { return Mathf.Sqrt(LengthSquared); }
@ -107,14 +113,14 @@ namespace Godot
/// This method runs faster than <see cref="Length"/>, so prefer it if
/// you need to compare quaternions or need the squared length for some formula.
/// </summary>
/// <value>Equivalent to `Dot(this)`.</value>
/// <value>Equivalent to <c>Dot(this)</c>.</value>
public real_t LengthSquared
{
get { return Dot(this); }
}
/// <summary>
/// Returns the angle between this quaternion and `to`.
/// Returns the angle between this quaternion and <paramref name="to"/>.
/// This is the magnitude of the angle you would need to rotate
/// by to get from one to the other.
///
@ -131,12 +137,12 @@ namespace Godot
}
/// <summary>
/// Performs a cubic spherical interpolation between quaternions `preA`,
/// this vector, `b`, and `postB`, by the given amount `t`.
/// Performs a cubic spherical interpolation between quaternions <paramref name="preA"/>, this quaternion,
/// <paramref name="b"/>, and <paramref name="postB"/>, by the given amount <paramref name="weight"/>.
/// </summary>
/// <param name="b">The destination quaternion.</param>
/// <param name="preA">A quaternion before this quaternion.</param>
/// <param name="postB">A quaternion after `b`.</param>
/// <param name="postB">A quaternion after <paramref name="b"/>.</param>
/// <param name="weight">A value on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
/// <returns>The interpolated quaternion.</returns>
public Quaternion CubicSlerp(Quaternion b, Quaternion preA, Quaternion postB, real_t weight)
@ -194,7 +200,7 @@ namespace Godot
/// <summary>
/// Returns whether the quaternion is normalized or not.
/// </summary>
/// <returns>A bool for whether the quaternion is normalized or not.</returns>
/// <returns>A <see langword="bool"/> for whether the quaternion is normalized or not.</returns>
public bool IsNormalized()
{
return Mathf.Abs(LengthSquared - 1) <= Mathf.Epsilon;
@ -211,7 +217,7 @@ namespace Godot
/// <summary>
/// Returns the result of the spherical linear interpolation between
/// this quaternion and `to` by amount `weight`.
/// this quaternion and <paramref name="to"/> by amount <paramref name="weight"/>.
///
/// Note: Both quaternions must be normalized.
/// </summary>
@ -283,7 +289,7 @@ namespace Godot
/// <summary>
/// Returns the result of the spherical linear interpolation between
/// this quaternion and `to` by amount `weight`, but without
/// this quaternion and <paramref name="to"/> by amount <paramref name="weight"/>, but without
/// checking if the rotation path is not bigger than 90 degrees.
/// </summary>
/// <param name="to">The destination quaternion for interpolation. Must be normalized.</param>
@ -338,15 +344,15 @@ namespace Godot
/// Equivalent to an identity <see cref="Basis"/> matrix. If a vector is transformed by
/// an identity quaternion, it will not change.
/// </summary>
/// <value>Equivalent to `new Quaternion(0, 0, 0, 1)`.</value>
/// <value>Equivalent to <c>new Quaternion(0, 0, 0, 1)</c>.</value>
public static Quaternion Identity { get { return _identity; } }
/// <summary>
/// Constructs a quaternion defined by the given values.
/// Constructs a <see cref="Quaternion"/> defined by the given values.
/// </summary>
/// <param name="x">X component of the quaternion (imaginary `i` axis part).</param>
/// <param name="y">Y component of the quaternion (imaginary `j` axis part).</param>
/// <param name="z">Z component of the quaternion (imaginary `k` axis part).</param>
/// <param name="x">X component of the quaternion (imaginary <c>i</c> axis part).</param>
/// <param name="y">Y component of the quaternion (imaginary <c>j</c> axis part).</param>
/// <param name="z">Z component of the quaternion (imaginary <c>k</c> axis part).</param>
/// <param name="w">W component of the quaternion (real part).</param>
public Quaternion(real_t x, real_t y, real_t z, real_t w)
{
@ -357,7 +363,7 @@ namespace Godot
}
/// <summary>
/// Constructs a quaternion from the given quaternion.
/// Constructs a <see cref="Quaternion"/> from the given <see cref="Quaternion"/>.
/// </summary>
/// <param name="q">The existing quaternion.</param>
public Quaternion(Quaternion q)
@ -366,21 +372,20 @@ namespace Godot
}
/// <summary>
/// Constructs a quaternion from the given <see cref="Basis"/>.
/// Constructs a <see cref="Quaternion"/> from the given <see cref="Basis"/>.
/// </summary>
/// <param name="basis">The basis to construct from.</param>
/// <param name="basis">The <see cref="Basis"/> to construct from.</param>
public Quaternion(Basis basis)
{
this = basis.Quaternion();
}
/// <summary>
/// Constructs a quaternion that will perform a rotation specified by
/// Euler angles (in the YXZ convention: when decomposing,
/// first Z, then X, and Y last),
/// Constructs a <see cref="Quaternion"/> that will perform a rotation specified by
/// Euler angles (in the YXZ convention: when decomposing, first Z, then X, and Y last),
/// given in the vector format as (X angle, Y angle, Z angle).
/// </summary>
/// <param name="eulerYXZ"></param>
/// <param name="eulerYXZ">Euler angles that the quaternion will be rotated by.</param>
public Quaternion(Vector3 eulerYXZ)
{
real_t halfA1 = eulerYXZ.y * 0.5f;
@ -405,7 +410,7 @@ namespace Godot
}
/// <summary>
/// Constructs a quaternion that will rotate around the given axis
/// Constructs a <see cref="Quaternion"/> that will rotate around the given axis
/// by the specified angle. The axis must be a normalized vector.
/// </summary>
/// <param name="axis">The axis to rotate around. Must be normalized.</param>
@ -514,6 +519,11 @@ namespace Godot
return !left.Equals(right);
}
/// <summary>
/// Returns <see langword="true"/> if this quaternion and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the quaternion and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Quaternion)
@ -524,14 +534,19 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this quaternion and <paramref name="other"/> are equal.
/// </summary>
/// <param name="other">The other quaternion to compare.</param>
/// <returns>Whether or not the quaternions are equal.</returns>
public bool Equals(Quaternion other)
{
return x == other.x && y == other.y && z == other.z && w == other.w;
}
/// <summary>
/// Returns true if this quaternion and `other` are approximately equal, by running
/// <see cref="Mathf.IsEqualApprox(real_t, real_t)"/> on each component.
/// Returns <see langword="true"/> if this quaternion and <paramref name="other"/> are approximately equal,
/// by running <see cref="Mathf.IsEqualApprox(real_t, real_t)"/> on each component.
/// </summary>
/// <param name="other">The other quaternion to compare.</param>
/// <returns>Whether or not the quaternions are approximately equal.</returns>
@ -540,16 +555,28 @@ namespace Godot
return Mathf.IsEqualApprox(x, other.x) && Mathf.IsEqualApprox(y, other.y) && Mathf.IsEqualApprox(z, other.z) && Mathf.IsEqualApprox(w, other.w);
}
/// <summary>
/// Serves as the hash function for <see cref="Quaternion"/>.
/// </summary>
/// <returns>A hash code for this quaternion.</returns>
public override int GetHashCode()
{
return y.GetHashCode() ^ x.GetHashCode() ^ z.GetHashCode() ^ w.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Quaternion"/> to a string.
/// </summary>
/// <returns>A string representation of this quaternion.</returns>
public override string ToString()
{
return $"({x}, {y}, {z}, {w})";
}
/// <summary>
/// Converts this <see cref="Quaternion"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this quaternion.</returns>
public string ToString(string format)
{
return $"({x.ToString(format)}, {y.ToString(format)}, {z.ToString(format)}, {w.ToString(format)})";

25
modules/mono/glue/GodotSharp/GodotSharp/Core/RID.cs
View file

@ -3,6 +3,12 @@ using System.Runtime.CompilerServices;
namespace Godot
{
/// <summary>
/// The RID type is used to access the unique integer ID of a resource.
/// They are opaque, which means they do not grant access to the associated
/// resource by themselves. They are used by and with the low-level Server
/// classes such as <see cref="RenderingServer"/>.
/// </summary>
public sealed partial class RID : IDisposable
{
private bool _disposed = false;
@ -25,6 +31,9 @@ namespace Godot
Dispose(false);
}
/// <summary>
/// Disposes of this <see cref="RID"/>.
/// </summary>
public void Dispose()
{
Dispose(true);
@ -50,6 +59,9 @@ namespace Godot
this.ptr = ptr;
}
/// <summary>
/// The pointer to the native instance of this <see cref="RID"/>.
/// </summary>
public IntPtr NativeInstance
{
get { return ptr; }
@ -60,16 +72,27 @@ namespace Godot
this.ptr = IntPtr.Zero;
}
/// <summary>
/// Constructs a new <see cref="RID"/> for the given <see cref="Object"/> <paramref name="from"/>.
/// </summary>
public RID(Object from)
{
this.ptr = godot_icall_RID_Ctor(Object.GetPtr(from));
}
/// <summary>
/// Returns the ID of the referenced resource.
/// </summary>
/// <returns>The ID of the referenced resource.</returns>
public int GetId()
{
return godot_icall_RID_get_id(RID.GetPtr(this));
return godot_icall_RID_get_id(GetPtr(this));
}
/// <summary>
/// Converts this <see cref="RID"/> to a string.
/// </summary>
/// <returns>A string representation of this RID.</returns>
public override string ToString() => "[RID]";
[MethodImpl(MethodImplOptions.InternalCall)]

134
modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2.cs
View file

@ -20,7 +20,7 @@ namespace Godot
private Vector2 _size;
/// <summary>
/// Beginning corner. Typically has values lower than End.
/// Beginning corner. Typically has values lower than <see cref="End"/>.
/// </summary>
/// <value>Directly uses a private field.</value>
public Vector2 Position
@ -30,7 +30,7 @@ namespace Godot
}
/// <summary>
/// Size from Position to End. Typically all components are positive.
/// Size from <see cref="Position"/> to <see cref="End"/>. Typically all components are positive.
/// If the size is negative, you can use <see cref="Abs"/> to fix it.
/// </summary>
/// <value>Directly uses a private field.</value>
@ -41,10 +41,13 @@ namespace Godot
}
/// <summary>
/// Ending corner. This is calculated as <see cref="Position"/> plus
/// <see cref="Size"/>. Setting this value will change the size.
/// Ending corner. This is calculated as <see cref="Position"/> plus <see cref="Size"/>.
/// Setting this value will change the size.
/// </summary>
/// <value>Getting is equivalent to `value = Position + Size`, setting is equivalent to `Size = value - Position`.</value>
/// <value>
/// Getting is equivalent to <paramref name="value"/> = <see cref="Position"/> + <see cref="Size"/>,
/// setting is equivalent to <see cref="Size"/> = <paramref name="value"/> - <see cref="Position"/>
/// </value>
public Vector2 End
{
get { return _position + _size; }
@ -52,7 +55,7 @@ namespace Godot
}
/// <summary>
/// The area of this Rect2.
/// The area of this <see cref="Rect2"/>.
/// </summary>
/// <value>Equivalent to <see cref="GetArea()"/>.</value>
public real_t Area
@ -61,10 +64,10 @@ namespace Godot
}
/// <summary>
/// Returns a Rect2 with equivalent position and size, modified so that
/// Returns a <see cref="Rect2"/> with equivalent position and size, modified so that
/// the top-left corner is the origin and width and height are positive.
/// </summary>
/// <returns>The modified Rect2.</returns>
/// <returns>The modified <see cref="Rect2"/>.</returns>
public Rect2 Abs()
{
Vector2 end = End;
@ -73,11 +76,14 @@ namespace Godot
}
/// <summary>
/// Returns the intersection of this Rect2 and `b`.
/// If the rectangles do not intersect, an empty Rect2 is returned.
/// Returns the intersection of this <see cref="Rect2"/> and <paramref name="b"/>.
/// If the rectangles do not intersect, an empty <see cref="Rect2"/> is returned.
/// </summary>
/// <param name="b">The other Rect2.</param>
/// <returns>The intersection of this Rect2 and `b`, or an empty Rect2 if they do not intersect.</returns>
/// <param name="b">The other <see cref="Rect2"/>.</param>
/// <returns>
/// The intersection of this <see cref="Rect2"/> and <paramref name="b"/>,
/// or an empty <see cref="Rect2"/> if they do not intersect.
/// </returns>
public Rect2 Intersection(Rect2 b)
{
Rect2 newRect = b;
@ -100,10 +106,12 @@ namespace Godot
}
/// <summary>
/// Returns true if this Rect2 completely encloses another one.
/// Returns <see langword="true"/> if this <see cref="Rect2"/> completely encloses another one.
/// </summary>
/// <param name="b">The other Rect2 that may be enclosed.</param>
/// <returns>A bool for whether or not this Rect2 encloses `b`.</returns>
/// <param name="b">The other <see cref="Rect2"/> that may be enclosed.</param>
/// <returns>
/// A <see langword="bool"/> for whether or not this <see cref="Rect2"/> encloses <paramref name="b"/>.
/// </returns>
public bool Encloses(Rect2 b)
{
return b._position.x >= _position.x && b._position.y >= _position.y &&
@ -112,10 +120,10 @@ namespace Godot
}
/// <summary>
/// Returns this Rect2 expanded to include a given point.
/// Returns this <see cref="Rect2"/> expanded to include a given point.
/// </summary>
/// <param name="to">The point to include.</param>
/// <returns>The expanded Rect2.</returns>
/// <returns>The expanded <see cref="Rect2"/>.</returns>
public Rect2 Expand(Vector2 to)
{
Rect2 expanded = this;
@ -148,7 +156,7 @@ namespace Godot
}
/// <summary>
/// Returns the area of the Rect2.
/// Returns the area of the <see cref="Rect2"/>.
/// </summary>
/// <returns>The area.</returns>
public real_t GetArea()
@ -157,10 +165,13 @@ namespace Godot
}
/// <summary>
/// Returns a copy of the Rect2 grown by the specified amount on all sides.
/// Returns a copy of the <see cref="Rect2"/> grown by the specified amount
/// on all sides.
/// </summary>
/// <seealso cref="GrowIndividual(real_t, real_t, real_t, real_t)"/>
/// <seealso cref="GrowSide(Side, real_t)"/>
/// <param name="by">The amount to grow by.</param>
/// <returns>The grown Rect2.</returns>
/// <returns>The grown <see cref="Rect2"/>.</returns>
public Rect2 Grow(real_t by)
{
Rect2 g = this;
@ -174,13 +185,16 @@ namespace Godot
}
/// <summary>
/// Returns a copy of the Rect2 grown by the specified amount on each side individually.
/// Returns a copy of the <see cref="Rect2"/> grown by the specified amount
/// on each side individually.
/// </summary>
/// <seealso cref="Grow(real_t)"/>
/// <seealso cref="GrowSide(Side, real_t)"/>
/// <param name="left">The amount to grow by on the left side.</param>
/// <param name="top">The amount to grow by on the top side.</param>
/// <param name="right">The amount to grow by on the right side.</param>
/// <param name="bottom">The amount to grow by on the bottom side.</param>
/// <returns>The grown Rect2.</returns>
/// <returns>The grown <see cref="Rect2"/>.</returns>
public Rect2 GrowIndividual(real_t left, real_t top, real_t right, real_t bottom)
{
Rect2 g = this;
@ -194,11 +208,14 @@ namespace Godot
}
/// <summary>
/// Returns a copy of the Rect2 grown by the specified amount on the specified Side.
/// Returns a copy of the <see cref="Rect2"/> grown by the specified amount
/// on the specified <see cref="Side"/>.
/// </summary>
/// <seealso cref="Grow(real_t)"/>
/// <seealso cref="GrowIndividual(real_t, real_t, real_t, real_t)"/>
/// <param name="side">The side to grow.</param>
/// <param name="by">The amount to grow by.</param>
/// <returns>The grown Rect2.</returns>
/// <returns>The grown <see cref="Rect2"/>.</returns>
public Rect2 GrowSide(Side side, real_t by)
{
Rect2 g = this;
@ -212,19 +229,25 @@ namespace Godot
}
/// <summary>
/// Returns true if the Rect2 is flat or empty, or false otherwise.
/// Returns <see langword="true"/> if the <see cref="Rect2"/> is flat or empty,
/// or <see langword="false"/> otherwise.
/// </summary>
/// <returns>A bool for whether or not the Rect2 has area.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="Rect2"/> has area.
/// </returns>
public bool HasNoArea()
{
return _size.x <= 0 || _size.y <= 0;
}
/// <summary>
/// Returns true if the Rect2 contains a point, or false otherwise.
/// Returns <see langword="true"/> if the <see cref="Rect2"/> contains a point,
/// or <see langword="false"/> otherwise.
/// </summary>
/// <param name="point">The point to check.</param>
/// <returns>A bool for whether or not the Rect2 contains `point`.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="Rect2"/> contains <paramref name="point"/>.
/// </returns>
public bool HasPoint(Vector2 point)
{
if (point.x < _position.x)
@ -241,15 +264,16 @@ namespace Godot
}
/// <summary>
/// Returns true if the Rect2 overlaps with `b`
/// Returns <see langword="true"/> if the <see cref="Rect2"/> overlaps with <paramref name="b"/>
/// (i.e. they have at least one point in common).
///
/// If `includeBorders` is true, they will also be considered overlapping
/// if their borders touch, even without intersection.
/// If <paramref name="includeBorders"/> is <see langword="true"/>,
/// they will also be considered overlapping if their borders touch,
/// even without intersection.
/// </summary>
/// <param name="b">The other Rect2 to check for intersections with.</param>
/// <param name="b">The other <see cref="Rect2"/> to check for intersections with.</param>
/// <param name="includeBorders">Whether or not to consider borders.</param>
/// <returns>A bool for whether or not they are intersecting.</returns>
/// <returns>A <see langword="bool"/> for whether or not they are intersecting.</returns>
public bool Intersects(Rect2 b, bool includeBorders = false)
{
if (includeBorders)
@ -295,10 +319,10 @@ namespace Godot
}
/// <summary>
/// Returns a larger Rect2 that contains this Rect2 and `b`.
/// Returns a larger <see cref="Rect2"/> that contains this <see cref="Rect2"/> and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other Rect2.</param>
/// <returns>The merged Rect2.</returns>
/// <param name="b">The other <see cref="Rect2"/>.</param>
/// <returns>The merged <see cref="Rect2"/>.</returns>
public Rect2 Merge(Rect2 b)
{
Rect2 newRect;
@ -315,7 +339,7 @@ namespace Godot
}
/// <summary>
/// Constructs a Rect2 from a position and size.
/// Constructs a <see cref="Rect2"/> from a position and size.
/// </summary>
/// <param name="position">The position.</param>
/// <param name="size">The size.</param>
@ -326,7 +350,7 @@ namespace Godot
}
/// <summary>
/// Constructs a Rect2 from a position, width, and height.
/// Constructs a <see cref="Rect2"/> from a position, width, and height.
/// </summary>
/// <param name="position">The position.</param>
/// <param name="width">The width.</param>
@ -338,7 +362,7 @@ namespace Godot
}
/// <summary>
/// Constructs a Rect2 from x, y, and size.
/// Constructs a <see cref="Rect2"/> from x, y, and size.
/// </summary>
/// <param name="x">The position's X coordinate.</param>
/// <param name="y">The position's Y coordinate.</param>
@ -350,7 +374,7 @@ namespace Godot
}
/// <summary>
/// Constructs a Rect2 from x, y, width, and height.
/// Constructs a <see cref="Rect2"/> from x, y, width, and height.
/// </summary>
/// <param name="x">The position's X coordinate.</param>
/// <param name="y">The position's Y coordinate.</param>
@ -372,6 +396,11 @@ namespace Godot
return !left.Equals(right);
}
/// <summary>
/// Returns <see langword="true"/> if this rect and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the rect and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Rect2)
@ -382,32 +411,49 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this rect and <paramref name="other"/> are equal.
/// </summary>
/// <param name="other">The other rect to compare.</param>
/// <returns>Whether or not the rects are equal.</returns>
public bool Equals(Rect2 other)
{
return _position.Equals(other._position) && _size.Equals(other._size);
}
/// <summary>
/// Returns true if this Rect2 and `other` are approximately equal, by running
/// <see cref="Vector2.IsEqualApprox(Vector2)"/> on each component.
/// Returns <see langword="true"/> if this rect and <paramref name="other"/> are approximately equal,
/// by running <see cref="Vector2.IsEqualApprox(Vector2)"/> on each component.
/// </summary>
/// <param name="other">The other Rect2 to compare.</param>
/// <returns>Whether or not the Rect2s are approximately equal.</returns>
/// <param name="other">The other rect to compare.</param>
/// <returns>Whether or not the rects are approximately equal.</returns>
public bool IsEqualApprox(Rect2 other)
{
return _position.IsEqualApprox(other._position) && _size.IsEqualApprox(other.Size);
}
/// <summary>
/// Serves as the hash function for <see cref="Rect2"/>.
/// </summary>
/// <returns>A hash code for this rect.</returns>
public override int GetHashCode()
{
return _position.GetHashCode() ^ _size.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Rect2"/> to a string.
/// </summary>
/// <returns>A string representation of this rect.</returns>
public override string ToString()
{
return $"{_position}, {_size}";
}
/// <summary>
/// Converts this <see cref="Rect2"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this rect.</returns>
public string ToString(string format)
{
return $"{_position.ToString(format)}, {_size.ToString(format)}";

134
modules/mono/glue/GodotSharp/GodotSharp/Core/Rect2i.cs
View file

@ -15,7 +15,7 @@ namespace Godot
private Vector2i _size;
/// <summary>
/// Beginning corner. Typically has values lower than End.
/// Beginning corner. Typically has values lower than <see cref="End"/>.
/// </summary>
/// <value>Directly uses a private field.</value>
public Vector2i Position
@ -25,7 +25,7 @@ namespace Godot
}
/// <summary>
/// Size from Position to End. Typically all components are positive.
/// Size from <see cref="Position"/> to <see cref="End"/>. Typically all components are positive.
/// If the size is negative, you can use <see cref="Abs"/> to fix it.
/// </summary>
/// <value>Directly uses a private field.</value>
@ -36,10 +36,13 @@ namespace Godot
}
/// <summary>
/// Ending corner. This is calculated as <see cref="Position"/> plus
/// <see cref="Size"/>. Setting this value will change the size.
/// Ending corner. This is calculated as <see cref="Position"/> plus <see cref="Size"/>.
/// Setting this value will change the size.
/// </summary>
/// <value>Getting is equivalent to `value = Position + Size`, setting is equivalent to `Size = value - Position`.</value>
/// <value>
/// Getting is equivalent to <paramref name="value"/> = <see cref="Position"/> + <see cref="Size"/>,
/// setting is equivalent to <see cref="Size"/> = <paramref name="value"/> - <see cref="Position"/>
/// </value>
public Vector2i End
{
get { return _position + _size; }
@ -47,7 +50,7 @@ namespace Godot
}
/// <summary>
/// The area of this Rect2i.
/// The area of this <see cref="Rect2i"/>.
/// </summary>
/// <value>Equivalent to <see cref="GetArea()"/>.</value>
public int Area
@ -56,10 +59,10 @@ namespace Godot
}
/// <summary>
/// Returns a Rect2i with equivalent position and size, modified so that
/// Returns a <see cref="Rect2i"/> with equivalent position and size, modified so that
/// the top-left corner is the origin and width and height are positive.
/// </summary>
/// <returns>The modified Rect2i.</returns>
/// <returns>The modified <see cref="Rect2i"/>.</returns>
public Rect2i Abs()
{
Vector2i end = End;
@ -68,11 +71,14 @@ namespace Godot
}
/// <summary>
/// Returns the intersection of this Rect2i and `b`.
/// If the rectangles do not intersect, an empty Rect2i is returned.
/// Returns the intersection of this <see cref="Rect2i"/> and <paramref name="b"/>.
/// If the rectangles do not intersect, an empty <see cref="Rect2i"/> is returned.
/// </summary>
/// <param name="b">The other Rect2i.</param>
/// <returns>The intersection of this Rect2i and `b`, or an empty Rect2i if they do not intersect.</returns>
/// <param name="b">The other <see cref="Rect2i"/>.</param>
/// <returns>
/// The intersection of this <see cref="Rect2i"/> and <paramref name="b"/>,
/// or an empty <see cref="Rect2i"/> if they do not intersect.
/// </returns>
public Rect2i Intersection(Rect2i b)
{
Rect2i newRect = b;
@ -95,10 +101,12 @@ namespace Godot
}
/// <summary>
/// Returns true if this Rect2i completely encloses another one.
/// Returns <see langword="true"/> if this <see cref="Rect2i"/> completely encloses another one.
/// </summary>
/// <param name="b">The other Rect2i that may be enclosed.</param>
/// <returns>A bool for whether or not this Rect2i encloses `b`.</returns>
/// <param name="b">The other <see cref="Rect2i"/> that may be enclosed.</param>
/// <returns>
/// A <see langword="bool"/> for whether or not this <see cref="Rect2i"/> encloses <paramref name="b"/>.
/// </returns>
public bool Encloses(Rect2i b)
{
return b._position.x >= _position.x && b._position.y >= _position.y &&
@ -107,10 +115,10 @@ namespace Godot
}
/// <summary>
/// Returns this Rect2i expanded to include a given point.
/// Returns this <see cref="Rect2i"/> expanded to include a given point.
/// </summary>
/// <param name="to">The point to include.</param>
/// <returns>The expanded Rect2i.</returns>
/// <returns>The expanded <see cref="Rect2i"/>.</returns>
public Rect2i Expand(Vector2i to)
{
Rect2i expanded = this;
@ -143,7 +151,7 @@ namespace Godot
}
/// <summary>
/// Returns the area of the Rect2.
/// Returns the area of the <see cref="Rect2"/>.
/// </summary>
/// <returns>The area.</returns>
public int GetArea()
@ -152,10 +160,13 @@ namespace Godot
}
/// <summary>
/// Returns a copy of the Rect2i grown by the specified amount on all sides.
/// Returns a copy of the <see cref="Rect2i"/> grown by the specified amount
/// on all sides.
/// </summary>
/// <seealso cref="GrowIndividual(int, int, int, int)"/>
/// <seealso cref="GrowSide(Side, int)"/>
/// <param name="by">The amount to grow by.</param>
/// <returns>The grown Rect2i.</returns>
/// <returns>The grown <see cref="Rect2i"/>.</returns>
public Rect2i Grow(int by)
{
Rect2i g = this;
@ -169,13 +180,16 @@ namespace Godot
}
/// <summary>
/// Returns a copy of the Rect2i grown by the specified amount on each side individually.
/// Returns a copy of the <see cref="Rect2i"/> grown by the specified amount
/// on each side individually.
/// </summary>
/// <seealso cref="Grow(int)"/>
/// <seealso cref="GrowSide(Side, int)"/>
/// <param name="left">The amount to grow by on the left side.</param>
/// <param name="top">The amount to grow by on the top side.</param>
/// <param name="right">The amount to grow by on the right side.</param>
/// <param name="bottom">The amount to grow by on the bottom side.</param>
/// <returns>The grown Rect2i.</returns>
/// <returns>The grown <see cref="Rect2i"/>.</returns>
public Rect2i GrowIndividual(int left, int top, int right, int bottom)
{
Rect2i g = this;
@ -189,11 +203,14 @@ namespace Godot
}
/// <summary>
/// Returns a copy of the Rect2i grown by the specified amount on the specified Side.
/// Returns a copy of the <see cref="Rect2i"/> grown by the specified amount
/// on the specified <see cref="Side"/>.
/// </summary>
/// <seealso cref="Grow(int)"/>
/// <seealso cref="GrowIndividual(int, int, int, int)"/>
/// <param name="side">The side to grow.</param>
/// <param name="by">The amount to grow by.</param>
/// <returns>The grown Rect2i.</returns>
/// <returns>The grown <see cref="Rect2i"/>.</returns>
public Rect2i GrowSide(Side side, int by)
{
Rect2i g = this;
@ -207,19 +224,25 @@ namespace Godot
}
/// <summary>
/// Returns true if the Rect2i is flat or empty, or false otherwise.
/// Returns <see langword="true"/> if the <see cref="Rect2i"/> is flat or empty,
/// or <see langword="false"/> otherwise.
/// </summary>
/// <returns>A bool for whether or not the Rect2i has area.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="Rect2i"/> has area.
/// </returns>
public bool HasNoArea()
{
return _size.x <= 0 || _size.y <= 0;
}
/// <summary>
/// Returns true if the Rect2i contains a point, or false otherwise.
/// Returns <see langword="true"/> if the <see cref="Rect2i"/> contains a point,
/// or <see langword="false"/> otherwise.
/// </summary>
/// <param name="point">The point to check.</param>
/// <returns>A bool for whether or not the Rect2i contains `point`.</returns>
/// <returns>
/// A <see langword="bool"/> for whether or not the <see cref="Rect2i"/> contains <paramref name="point"/>.
/// </returns>
public bool HasPoint(Vector2i point)
{
if (point.x < _position.x)
@ -236,15 +259,16 @@ namespace Godot
}
/// <summary>
/// Returns true if the Rect2i overlaps with `b`
/// Returns <see langword="true"/> if the <see cref="Rect2i"/> overlaps with <paramref name="b"/>
/// (i.e. they have at least one point in common).
///
/// If `includeBorders` is true, they will also be considered overlapping
/// if their borders touch, even without intersection.
/// If <paramref name="includeBorders"/> is <see langword="true"/>,
/// they will also be considered overlapping if their borders touch,
/// even without intersection.
/// </summary>
/// <param name="b">The other Rect2i to check for intersections with.</param>
/// <param name="b">The other <see cref="Rect2i"/> to check for intersections with.</param>
/// <param name="includeBorders">Whether or not to consider borders.</param>
/// <returns>A bool for whether or not they are intersecting.</returns>
/// <returns>A <see langword="bool"/> for whether or not they are intersecting.</returns>
public bool Intersects(Rect2i b, bool includeBorders = false)
{
if (includeBorders)
@ -274,10 +298,10 @@ namespace Godot
}
/// <summary>
/// Returns a larger Rect2i that contains this Rect2i and `b`.
/// Returns a larger <see cref="Rect2i"/> that contains this <see cref="Rect2i"/> and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other Rect2i.</param>
/// <returns>The merged Rect2i.</returns>
/// <param name="b">The other <see cref="Rect2i"/>.</param>
/// <returns>The merged <see cref="Rect2i"/>.</returns>
public Rect2i Merge(Rect2i b)
{
Rect2i newRect;
@ -294,7 +318,7 @@ namespace Godot
}
/// <summary>
/// Constructs a Rect2i from a position and size.
/// Constructs a <see cref="Rect2i"/> from a position and size.
/// </summary>
/// <param name="position">The position.</param>
/// <param name="size">The size.</param>
@ -305,7 +329,7 @@ namespace Godot
}
/// <summary>
/// Constructs a Rect2i from a position, width, and height.
/// Constructs a <see cref="Rect2i"/> from a position, width, and height.
/// </summary>
/// <param name="position">The position.</param>
/// <param name="width">The width.</param>
@ -317,7 +341,7 @@ namespace Godot
}
/// <summary>
/// Constructs a Rect2i from x, y, and size.
/// Constructs a <see cref="Rect2i"/> from x, y, and size.
/// </summary>
/// <param name="x">The position's X coordinate.</param>
/// <param name="y">The position's Y coordinate.</param>
@ -329,7 +353,7 @@ namespace Godot
}
/// <summary>
/// Constructs a Rect2i from x, y, width, and height.
/// Constructs a <see cref="Rect2i"/> from x, y, width, and height.
/// </summary>
/// <param name="x">The position's X coordinate.</param>
/// <param name="y">The position's Y coordinate.</param>
@ -351,16 +375,29 @@ namespace Godot
return !left.Equals(right);
}
/// <summary>
/// Converts this <see cref="Rect2i"/> to a <see cref="Rect2"/>.
/// </summary>
/// <param name="value">The rect to convert.</param>
public static implicit operator Rect2(Rect2i value)
{
return new Rect2(value._position, value._size);
}
/// <summary>
/// Converts a <see cref="Rect2"/> to a <see cref="Rect2i"/>.
/// </summary>
/// <param name="value">The rect to convert.</param>
public static explicit operator Rect2i(Rect2 value)
{
return new Rect2i((Vector2i)value.Position, (Vector2i)value.Size);
}
/// <summary>
/// Returns <see langword="true"/> if this rect and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the rect and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Rect2i)
@ -371,21 +408,38 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this rect and <paramref name="other"/> are equal.
/// </summary>
/// <param name="other">The other rect to compare.</param>
/// <returns>Whether or not the rects are equal.</returns>
public bool Equals(Rect2i other)
{
return _position.Equals(other._position) && _size.Equals(other._size);
}
/// <summary>
/// Serves as the hash function for <see cref="Rect2i"/>.
/// </summary>
/// <returns>A hash code for this rect.</returns>
public override int GetHashCode()
{
return _position.GetHashCode() ^ _size.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Rect2i"/> to a string.
/// </summary>
/// <returns>A string representation of this rect.</returns>
public override string ToString()
{
return $"{_position}, {_size}";
}
/// <summary>
/// Converts this <see cref="Rect2i"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this rect.</returns>
public string ToString(string format)
{
return $"{_position.ToString(format)}, {_size.ToString(format)}";

15
modules/mono/glue/GodotSharp/GodotSharp/Core/SignalInfo.cs
View file

@ -1,13 +1,28 @@
namespace Godot
{
/// <summary>
/// Represents a signal defined in an object.
/// </summary>
public struct SignalInfo
{
private readonly Object _owner;
private readonly StringName _signalName;
/// <summary>
/// Object that contains the signal.
/// </summary>
public Object Owner => _owner;
/// <summary>
/// Name of the signal.
/// </summary>
public StringName Name => _signalName;
/// <summary>
/// Creates a new <see cref="Signal"/> with the name <paramref name="name"/>
/// in the specified <paramref name="owner"/>.
/// </summary>
/// <param name="owner">Object that contains the signal.</param>
/// <param name="name">Name of the signal.</param>
public SignalInfo(Object owner, StringName name)
{
_owner = owner;

369
modules/mono/glue/GodotSharp/GodotSharp/Core/StringExtensions.cs
View file

@ -8,6 +8,9 @@ using System.Text.RegularExpressions;
namespace Godot
{
/// <summary>
/// Extension methods to manipulate strings.
/// </summary>
public static class StringExtensions
{
private static int GetSliceCount(this string instance, string splitter)
@ -64,6 +67,11 @@ namespace Godot
/// <summary>
/// If the string is a path to a file, return the path to the file without the extension.
/// </summary>
/// <seealso cref="GetExtension(string)"/>
/// <seealso cref="GetBaseDir(string)"/>
/// <seealso cref="GetFile(string)"/>
/// <param name="instance">The path to a file.</param>
/// <returns>The path to the file without the extension.</returns>
public static string GetBaseName(this string instance)
{
int index = instance.LastIndexOf('.');
@ -75,16 +83,22 @@ namespace Godot
}
/// <summary>
/// Return <see langword="true"/> if the strings begins with the given string.
/// Returns <see langword="true"/> if the strings begins
/// with the given string <paramref name="text"/>.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <param name="text">The beginning string.</param>
/// <returns>If the string begins with the given string.</returns>
public static bool BeginsWith(this string instance, string text)
{
return instance.StartsWith(text);
}
/// <summary>
/// Return the bigrams (pairs of consecutive letters) of this string.
/// Returns the bigrams (pairs of consecutive letters) of this string.
/// </summary>
/// <param name="instance">The string that will be used.</param>
/// <returns>The bigrams of this string.</returns>
public static string[] Bigrams(this string instance)
{
string[] b = new string[instance.Length - 1];
@ -99,8 +113,8 @@ namespace Godot
/// <summary>
/// Converts a string containing a binary number into an integer.
/// Binary strings can either be prefixed with `0b` or not,
/// and they can also start with a `-` before the optional prefix.
/// Binary strings can either be prefixed with <c>0b</c> or not,
/// and they can also start with a <c>-</c> before the optional prefix.
/// </summary>
/// <param name="instance">The string to convert.</param>
/// <returns>The converted string.</returns>
@ -128,8 +142,14 @@ namespace Godot
}
/// <summary>
/// Return the amount of substrings in string.
/// Returns the amount of substrings <paramref name="what"/> in the string.
/// </summary>
/// <param name="instance">The string where the substring will be searched.</param>
/// <param name="what">The substring that will be counted.</param>
/// <param name="caseSensitive">If the search is case sensitive.</param>
/// <param name="from">Index to start searching from.</param>
/// <param name="to">Index to stop searching at.</param>
/// <returns>Amount of substrings in the string.</returns>
public static int Count(this string instance, string what, bool caseSensitive = true, int from = 0, int to = 0)
{
if (what.Length == 0)
@ -188,8 +208,10 @@ namespace Godot
}
/// <summary>
/// Return a copy of the string with special characters escaped using the C language standard.
/// Returns a copy of the string with special characters escaped using the C language standard.
/// </summary>
/// <param name="instance">The string to escape.</param>
/// <returns>The escaped string.</returns>
public static string CEscape(this string instance)
{
var sb = new StringBuilder(string.Copy(instance));
@ -210,9 +232,11 @@ namespace Godot
}
/// <summary>
/// Return a copy of the string with escaped characters replaced by their meanings
/// Returns a copy of the string with escaped characters replaced by their meanings
/// according to the C language standard.
/// </summary>
/// <param name="instance">The string to unescape.</param>
/// <returns>The unescaped string.</returns>
public static string CUnescape(this string instance)
{
var sb = new StringBuilder(string.Copy(instance));
@ -233,11 +257,13 @@ namespace Godot
}
/// <summary>
/// Change the case of some letters. Replace underscores with spaces, convert all letters
/// Changes the case of some letters. Replace underscores with spaces, convert all letters
/// to lowercase then capitalize first and every letter following the space character.
/// For <c>capitalize camelCase mixed_with_underscores</c> it will return
/// <c>Capitalize Camelcase Mixed With Underscores</c>.
/// </summary>
/// <param name="instance">The string to capitalize.</param>
/// <returns>The capitalized string.</returns>
public static string Capitalize(this string instance)
{
string aux = instance.Replace("_", " ").ToLower();
@ -259,16 +285,27 @@ namespace Godot
}
/// <summary>
/// Perform a case-sensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater.
/// Performs a case-sensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater.
/// </summary>
/// <seealso cref="NocasecmpTo(string, string)"/>
/// <seealso cref="CompareTo(string, string, bool)"/>
/// <param name="instance">The string to compare.</param>
/// <param name="to">The other string to compare.</param>
/// <returns>-1 if less, 0 if equal and +1 if greater.</returns>
public static int CasecmpTo(this string instance, string to)
{
return instance.CompareTo(to, caseSensitive: true);
}
/// <summary>
/// Perform a comparison to another string, return -1 if less, 0 if equal and +1 if greater.
/// Performs a comparison to another string, return -1 if less, 0 if equal and +1 if greater.
/// </summary>
/// <param name="instance">The string to compare.</param>
/// <param name="to">The other string to compare.</param>
/// <param name="caseSensitive">
/// If <see langword="true"/>, the comparison will be case sensitive.
/// </param>
/// <returns>-1 if less, 0 if equal and +1 if greater.</returns>
public static int CompareTo(this string instance, string to, bool caseSensitive = true)
{
if (string.IsNullOrEmpty(instance))
@ -321,8 +358,12 @@ namespace Godot
}
/// <summary>
/// Return <see langword="true"/> if the strings ends with the given string.
/// Returns <see langword="true"/> if the strings ends
/// with the given string <paramref name="text"/>.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <param name="text">The ending string.</param>
/// <returns>If the string ends with the given string.</returns>
public static bool EndsWith(this string instance, string text)
{
return instance.EndsWith(text);
@ -331,14 +372,36 @@ namespace Godot
/// <summary>
/// Erase <paramref name="chars"/> characters from the string starting from <paramref name="pos"/>.
/// </summary>
/// <param name="instance">The string to modify.</param>
/// <param name="pos">Starting position from which to erase.</param>
/// <param name="chars">Amount of characters to erase.</param>
public static void Erase(this StringBuilder instance, int pos, int chars)
{
instance.Remove(pos, chars);
}
/// <summary>
/// If the string is a path to a file, return the extension.
/// Returns the extension without the leading period character (<c>.</c>)
/// if the string is a valid file name or path. If the string does not contain
/// an extension, returns an empty string instead.
/// </summary>
/// <example>
/// <code>
/// GD.Print("/path/to/file.txt".GetExtension()) // "txt"
/// GD.Print("file.txt".GetExtension()) // "txt"
/// GD.Print("file.sample.txt".GetExtension()) // "txt"
/// GD.Print(".txt".GetExtension()) // "txt"
/// GD.Print("file.txt.".GetExtension()) // "" (empty string)
/// GD.Print("file.txt..".GetExtension()) // "" (empty string)
/// GD.Print("txt".GetExtension()) // "" (empty string)
/// GD.Print("".GetExtension()) // "" (empty string)
/// </code>
/// </example>
/// <seealso cref="GetBaseName(string)"/>
/// <seealso cref="GetBaseDir(string)"/>
/// <seealso cref="GetFile(string)"/>
/// <param name="instance">The path to a file.</param>
/// <returns>The extension of the file or an empty string.</returns>
public static string GetExtension(this string instance)
{
int pos = instance.FindLast(".");
@ -352,6 +415,10 @@ namespace Godot
/// <summary>
/// Find the first occurrence of a substring. Optionally, the search starting position can be passed.
/// </summary>
/// <param name="instance">The string that will be searched.</param>
/// <param name="what">The substring to find.</param>
/// <param name="from">The search starting position.</param>
/// <param name="caseSensitive">If <see langword="true"/>, the search is case sensitive.</param>
/// <returns>The starting position of the substring, or -1 if not found.</returns>
public static int Find(this string instance, string what, int from = 0, bool caseSensitive = true)
{
@ -361,6 +428,14 @@ namespace Godot
/// <summary>
/// Find the first occurrence of a char. Optionally, the search starting position can be passed.
/// </summary>
/// <seealso cref="Find(string, string, int, bool)"/>
/// <seealso cref="FindLast(string, string, bool)"/>
/// <seealso cref="FindLast(string, string, int, bool)"/>
/// <seealso cref="FindN(string, string, int)"/>
/// <param name="instance">The string that will be searched.</param>
/// <param name="what">The substring to find.</param>
/// <param name="from">The search starting position.</param>
/// <param name="caseSensitive">If <see langword="true"/>, the search is case sensitive.</param>
/// <returns>The first instance of the char, or -1 if not found.</returns>
public static int Find(this string instance, char what, int from = 0, bool caseSensitive = true)
{
@ -370,6 +445,13 @@ namespace Godot
}
/// <summary>Find the last occurrence of a substring.</summary>
/// <seealso cref="Find(string, string, int, bool)"/>
/// <seealso cref="Find(string, char, int, bool)"/>
/// <seealso cref="FindLast(string, string, int, bool)"/>
/// <seealso cref="FindN(string, string, int)"/>
/// <param name="instance">The string that will be searched.</param>
/// <param name="what">The substring to find.</param>
/// <param name="caseSensitive">If <see langword="true"/>, the search is case sensitive.</param>
/// <returns>The starting position of the substring, or -1 if not found.</returns>
public static int FindLast(this string instance, string what, bool caseSensitive = true)
{
@ -377,6 +459,14 @@ namespace Godot
}
/// <summary>Find the last occurrence of a substring specifying the search starting position.</summary>
/// <seealso cref="Find(string, string, int, bool)"/>
/// <seealso cref="Find(string, char, int, bool)"/>
/// <seealso cref="FindLast(string, string, bool)"/>
/// <seealso cref="FindN(string, string, int)"/>
/// <param name="instance">The string that will be searched.</param>
/// <param name="what">The substring to find.</param>
/// <param name="from">The search starting position.</param>
/// <param name="caseSensitive">If <see langword="true"/>, the search is case sensitive.</param>
/// <returns>The starting position of the substring, or -1 if not found.</returns>
public static int FindLast(this string instance, string what, int from, bool caseSensitive = true)
{
@ -387,6 +477,13 @@ namespace Godot
/// Find the first occurrence of a substring but search as case-insensitive.
/// Optionally, the search starting position can be passed.
/// </summary>
/// <seealso cref="Find(string, string, int, bool)"/>
/// <seealso cref="Find(string, char, int, bool)"/>
/// <seealso cref="FindLast(string, string, bool)"/>
/// <seealso cref="FindLast(string, string, int, bool)"/>
/// <param name="instance">The string that will be searched.</param>
/// <param name="what">The substring to find.</param>
/// <param name="from">The search starting position.</param>
/// <returns>The starting position of the substring, or -1 if not found.</returns>
public static int FindN(this string instance, string what, int from = 0)
{
@ -396,6 +493,11 @@ namespace Godot
/// <summary>
/// If the string is a path to a file, return the base directory.
/// </summary>
/// <seealso cref="GetBaseName(string)"/>
/// <seealso cref="GetExtension(string)"/>
/// <seealso cref="GetFile(string)"/>
/// <param name="instance">The path to a file.</param>
/// <returns>The base directory.</returns>
public static string GetBaseDir(this string instance)
{
int basepos = instance.Find("://");
@ -433,6 +535,11 @@ namespace Godot
/// <summary>
/// If the string is a path to a file, return the file and ignore the base directory.
/// </summary>
/// <seealso cref="GetBaseName(string)"/>
/// <seealso cref="GetExtension(string)"/>
/// <seealso cref="GetBaseDir(string)"/>
/// <param name="instance">The path to a file.</param>
/// <returns>The file name.</returns>
public static string GetFile(this string instance)
{
int sep = Mathf.Max(instance.FindLast("/"), instance.FindLast("\\"));
@ -475,6 +582,8 @@ namespace Godot
/// <summary>
/// Hash the string and return a 32 bits unsigned integer.
/// </summary>
/// <param name="instance">The string to hash.</param>
/// <returns>The calculated hash of the string.</returns>
public static uint Hash(this string instance)
{
uint hash = 5381;
@ -536,8 +645,8 @@ namespace Godot
/// <summary>
/// Converts a string containing a hexadecimal number into an integer.
/// Hexadecimal strings can either be prefixed with `0x` or not,
/// and they can also start with a `-` before the optional prefix.
/// Hexadecimal strings can either be prefixed with <c>0x</c> or not,
/// and they can also start with a <c>-</c> before the optional prefix.
/// </summary>
/// <param name="instance">The string to convert.</param>
/// <returns>The converted string.</returns>
@ -565,16 +674,28 @@ namespace Godot
}
/// <summary>
/// Insert a substring at a given position.
/// Inserts a substring at a given position.
/// </summary>
/// <param name="instance">The string to modify.</param>
/// <param name="pos">Position at which to insert the substring.</param>
/// <param name="what">Substring to insert.</param>
/// <returns>
/// The string with <paramref name="what"/> inserted at the given
/// position <paramref name="pos"/>.
/// </returns>
public static string Insert(this string instance, int pos, string what)
{
return instance.Insert(pos, what);
}
/// <summary>
/// If the string is a path to a file or directory, return <see langword="true"/> if the path is absolute.
/// Returns <see langword="true"/> if the string is a path to a file or
/// directory and its startign point is explicitly defined. This includes
/// <c>res://</c>, <c>user://</c>, <c>C:\</c>, <c>/</c>, etc.
/// </summary>
/// <seealso cref="IsRelativePath(string)"/>
/// <param name="instance">The string to check.</param>
/// <returns>If the string is an absolute path.</returns>
public static bool IsAbsolutePath(this string instance)
{
if (string.IsNullOrEmpty(instance))
@ -586,8 +707,14 @@ namespace Godot
}
/// <summary>
/// If the string is a path to a file or directory, return <see langword="true"/> if the path is relative.
/// Returns <see langword="true"/> if the string is a path to a file or
/// directory and its starting point is implicitly defined within the
/// context it is being used. The starting point may refer to the current
/// directory (<c>./</c>), or the current <see cref="Node"/>.
/// </summary>
/// <seealso cref="IsAbsolutePath(string)"/>
/// <param name="instance">The string to check.</param>
/// <returns>If the string is a relative path.</returns>
public static bool IsRelativePath(this string instance)
{
return !IsAbsolutePath(instance);
@ -596,6 +723,11 @@ namespace Godot
/// <summary>
/// Check whether this string is a subsequence of the given string.
/// </summary>
/// <seealso cref="IsSubsequenceOfI(string, string)"/>
/// <param name="instance">The subsequence to search.</param>
/// <param name="text">The string that contains the subsequence.</param>
/// <param name="caseSensitive">If <see langword="true"/>, the check is case sensitive.</param>
/// <returns>If the string is a subsequence of the given string.</returns>
public static bool IsSubsequenceOf(this string instance, string text, bool caseSensitive = true)
{
int len = instance.Length;
@ -639,6 +771,10 @@ namespace Godot
/// <summary>
/// Check whether this string is a subsequence of the given string, ignoring case differences.
/// </summary>
/// <seealso cref="IsSubsequenceOf(string, string, bool)"/>
/// <param name="instance">The subsequence to search.</param>
/// <param name="text">The string that contains the subsequence.</param>
/// <returns>If the string is a subsequence of the given string.</returns>
public static bool IsSubsequenceOfI(this string instance, string text)
{
return instance.IsSubsequenceOf(text, caseSensitive: false);
@ -647,6 +783,8 @@ namespace Godot
/// <summary>
/// Check whether the string contains a valid <see langword="float"/>.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <returns>If the string contains a valid floating point number.</returns>
public static bool IsValidFloat(this string instance)
{
float f;
@ -656,6 +794,8 @@ namespace Godot
/// <summary>
/// Check whether the string contains a valid color in HTML notation.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <returns>If the string contains a valid HTML color.</returns>
public static bool IsValidHtmlColor(this string instance)
{
return Color.HtmlIsValid(instance);
@ -666,6 +806,8 @@ namespace Godot
/// programming languages, a valid identifier may contain only letters,
/// digits and underscores (_) and the first character may not be a digit.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <returns>If the string contains a valid identifier.</returns>
public static bool IsValidIdentifier(this string instance)
{
int len = instance.Length;
@ -693,6 +835,8 @@ namespace Godot
/// <summary>
/// Check whether the string contains a valid integer.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <returns>If the string contains a valid integer.</returns>
public static bool IsValidInteger(this string instance)
{
int f;
@ -702,6 +846,8 @@ namespace Godot
/// <summary>
/// Check whether the string contains a valid IP address.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <returns>If the string contains a valid IP address.</returns>
public static bool IsValidIPAddress(this string instance)
{
// TODO: Support IPv6 addresses
@ -725,8 +871,10 @@ namespace Godot
}
/// <summary>
/// Return a copy of the string with special characters escaped using the JSON standard.
/// Returns a copy of the string with special characters escaped using the JSON standard.
/// </summary>
/// <param name="instance">The string to escape.</param>
/// <returns>The escaped string.</returns>
public static string JSONEscape(this string instance)
{
var sb = new StringBuilder(string.Copy(instance));
@ -744,8 +892,12 @@ namespace Godot
}
/// <summary>
/// Return an amount of characters from the left of the string.
/// Returns an amount of characters from the left of the string.
/// </summary>
/// <seealso cref="Right(string, int)"/>
/// <param name="instance">The original string.</param>
/// <param name="pos">The position in the string where the left side ends.</param>
/// <returns>The left side of the string from the given position.</returns>
public static string Left(this string instance, int pos)
{
if (pos <= 0)
@ -758,8 +910,10 @@ namespace Godot
}
/// <summary>
/// Return the length of the string in characters.
/// Returns the length of the string in characters.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <returns>The length of the string.</returns>
public static int Length(this string instance)
{
return instance.Length;
@ -768,6 +922,7 @@ namespace Godot
/// <summary>
/// Returns a copy of the string with characters removed from the left.
/// </summary>
/// <seealso cref="RStrip(string, string)"/>
/// <param name="instance">The string to remove characters from.</param>
/// <param name="chars">The characters to be removed.</param>
/// <returns>A copy of the string with characters removed from the left.</returns>
@ -796,6 +951,12 @@ namespace Godot
/// Do a simple expression match, where '*' matches zero or more
/// arbitrary characters and '?' matches any single character except '.'.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <param name="expr">Expression to check.</param>
/// <param name="caseSensitive">
/// If <see langword="true"/>, the check will be case sensitive.
/// </param>
/// <returns>If the expression has any matches.</returns>
private static bool ExprMatch(this string instance, string expr, bool caseSensitive)
{
// case '\0':
@ -821,6 +982,13 @@ namespace Godot
/// Do a simple case sensitive expression match, using ? and * wildcards
/// (see <see cref="ExprMatch(string, string, bool)"/>).
/// </summary>
/// <seealso cref="MatchN(string, string)"/>
/// <param name="instance">The string to check.</param>
/// <param name="expr">Expression to check.</param>
/// <param name="caseSensitive">
/// If <see langword="true"/>, the check will be case sensitive.
/// </param>
/// <returns>If the expression has any matches.</returns>
public static bool Match(this string instance, string expr, bool caseSensitive = true)
{
if (instance.Length == 0 || expr.Length == 0)
@ -833,6 +1001,10 @@ namespace Godot
/// Do a simple case insensitive expression match, using ? and * wildcards
/// (see <see cref="ExprMatch(string, string, bool)"/>).
/// </summary>
/// <seealso cref="Match(string, string, bool)"/>
/// <param name="instance">The string to check.</param>
/// <param name="expr">Expression to check.</param>
/// <returns>If the expression has any matches.</returns>
public static bool MatchN(this string instance, string expr)
{
if (instance.Length == 0 || expr.Length == 0)
@ -842,8 +1014,11 @@ namespace Godot
}
/// <summary>
/// Return the MD5 hash of the string as an array of bytes.
/// Returns the MD5 hash of the string as an array of bytes.
/// </summary>
/// <seealso cref="MD5Text(string)"/>
/// <param name="instance">The string to hash.</param>
/// <returns>The MD5 hash of the string.</returns>
public static byte[] MD5Buffer(this string instance)
{
return godot_icall_String_md5_buffer(instance);
@ -853,8 +1028,11 @@ namespace Godot
internal static extern byte[] godot_icall_String_md5_buffer(string str);
/// <summary>
/// Return the MD5 hash of the string as a string.
/// Returns the MD5 hash of the string as a string.
/// </summary>
/// <seealso cref="MD5Buffer(string)"/>
/// <param name="instance">The string to hash.</param>
/// <returns>The MD5 hash of the string.</returns>
public static string MD5Text(this string instance)
{
return godot_icall_String_md5_text(instance);
@ -866,22 +1044,35 @@ namespace Godot
/// <summary>
/// Perform a case-insensitive comparison to another string, return -1 if less, 0 if equal and +1 if greater.
/// </summary>
/// <seealso cref="CasecmpTo(string, string)"/>
/// <seealso cref="CompareTo(string, string, bool)"/>
/// <param name="instance">The string to compare.</param>
/// <param name="to">The other string to compare.</param>
/// <returns>-1 if less, 0 if equal and +1 if greater.</returns>
public static int NocasecmpTo(this string instance, string to)
{
return instance.CompareTo(to, caseSensitive: false);
}
/// <summary>
/// Return the character code at position <paramref name="at"/>.
/// Returns the character code at position <paramref name="at"/>.
/// </summary>
/// <param name="instance">The string to check.</param>
/// <param name="at">The position int the string for the character to check.</param>
/// <returns>The character code.</returns>
public static int OrdAt(this string instance, int at)
{
return instance[at];
}
/// <summary>
/// Format a number to have an exact number of <paramref name="digits"/> after the decimal point.
/// Format a number to have an exact number of <paramref name="digits"/>
/// after the decimal point.
/// </summary>
/// <seealso cref="PadZeros(string, int)"/>
/// <param name="instance">The string to pad.</param>
/// <param name="digits">Amount of digits after the decimal point.</param>
/// <returns>The string padded with zeroes.</returns>
public static string PadDecimals(this string instance, int digits)
{
int c = instance.Find(".");
@ -916,8 +1107,13 @@ namespace Godot
}
/// <summary>
/// Format a number to have an exact number of <paramref name="digits"/> before the decimal point.
/// Format a number to have an exact number of <paramref name="digits"/>
/// before the decimal point.
/// </summary>
/// <seealso cref="PadDecimals(string, int)"/>
/// <param name="instance">The string to pad.</param>
/// <param name="digits">Amount of digits before the decimal point.</param>
/// <returns>The string padded with zeroes.</returns>
public static string PadZeros(this string instance, int digits)
{
string s = instance;
@ -949,9 +1145,13 @@ namespace Godot
}
/// <summary>
/// If the string is a path, this concatenates <paramref name="file"/> at the end of the string as a subpath.
/// If the string is a path, this concatenates <paramref name="file"/>
/// at the end of the string as a subpath.
/// E.g. <c>"this/is".PlusFile("path") == "this/is/path"</c>.
/// </summary>
/// <param name="instance">The path that will be concatenated.</param>
/// <param name="file">File name to concatenate with the path.</param>
/// <returns>The concatenated path with the given file name.</returns>
public static string PlusFile(this string instance, string file)
{
if (instance.Length > 0 && instance[instance.Length - 1] == '/')
@ -962,6 +1162,11 @@ namespace Godot
/// <summary>
/// Replace occurrences of a substring for different ones inside the string.
/// </summary>
/// <seealso cref="ReplaceN(string, string, string)"/>
/// <param name="instance">The string to modify.</param>
/// <param name="what">The substring to be replaced in the string.</param>
/// <param name="forwhat">The substring that replaces <paramref name="what"/>.</param>
/// <returns>The string with the substring occurrences replaced.</returns>
public static string Replace(this string instance, string what, string forwhat)
{
return instance.Replace(what, forwhat);
@ -970,6 +1175,11 @@ namespace Godot
/// <summary>
/// Replace occurrences of a substring for different ones inside the string, but search case-insensitive.
/// </summary>
/// <seealso cref="Replace(string, string, string)"/>
/// <param name="instance">The string to modify.</param>
/// <param name="what">The substring to be replaced in the string.</param>
/// <param name="forwhat">The substring that replaces <paramref name="what"/>.</param>
/// <returns>The string with the substring occurrences replaced.</returns>
public static string ReplaceN(this string instance, string what, string forwhat)
{
return Regex.Replace(instance, what, forwhat, RegexOptions.IgnoreCase);
@ -978,6 +1188,11 @@ namespace Godot
/// <summary>
/// Perform a search for a substring, but start from the end of the string instead of the beginning.
/// </summary>
/// <seealso cref="RFindN(string, string, int)"/>
/// <param name="instance">The string that will be searched.</param>
/// <param name="what">The substring to search in the string.</param>
/// <param name="from">The position at which to start searching.</param>
/// <returns>The position at which the substring was found, or -1 if not found.</returns>
public static int RFind(this string instance, string what, int from = -1)
{
return godot_icall_String_rfind(instance, what, from);
@ -990,6 +1205,11 @@ namespace Godot
/// Perform a search for a substring, but start from the end of the string instead of the beginning.
/// Also search case-insensitive.
/// </summary>
/// <seealso cref="RFind(string, string, int)"/>
/// <param name="instance">The string that will be searched.</param>
/// <param name="what">The substring to search in the string.</param>
/// <param name="from">The position at which to start searching.</param>
/// <returns>The position at which the substring was found, or -1 if not found.</returns>
public static int RFindN(this string instance, string what, int from = -1)
{
return godot_icall_String_rfindn(instance, what, from);
@ -999,8 +1219,12 @@ namespace Godot
internal static extern int godot_icall_String_rfindn(string str, string what, int from);
/// <summary>
/// Return the right side of the string from a given position.
/// Returns the right side of the string from a given position.
/// </summary>
/// <seealso cref="Left(string, int)"/>
/// <param name="instance">The original string.</param>
/// <param name="pos">The position in the string from which the right side starts.</param>
/// <returns>The right side of the string from the given position.</returns>
public static string Right(this string instance, int pos)
{
if (pos >= instance.Length)
@ -1015,6 +1239,7 @@ namespace Godot
/// <summary>
/// Returns a copy of the string with characters removed from the right.
/// </summary>
/// <seealso cref="LStrip(string, string)"/>
/// <param name="instance">The string to remove characters from.</param>
/// <param name="chars">The characters to be removed.</param>
/// <returns>A copy of the string with characters removed from the right.</returns>
@ -1039,6 +1264,12 @@ namespace Godot
return instance.Substr(0, end + 1);
}
/// <summary>
/// Returns the SHA-256 hash of the string as an array of bytes.
/// </summary>
/// <seealso cref="SHA256Text(string)"/>
/// <param name="instance">The string to hash.</param>
/// <returns>The SHA-256 hash of the string.</returns>
public static byte[] SHA256Buffer(this string instance)
{
return godot_icall_String_sha256_buffer(instance);
@ -1048,8 +1279,11 @@ namespace Godot
internal static extern byte[] godot_icall_String_sha256_buffer(string str);
/// <summary>
/// Return the SHA-256 hash of the string as a string.
/// Returns the SHA-256 hash of the string as a string.
/// </summary>
/// <seealso cref="SHA256Buffer(string)"/>
/// <param name="instance">The string to hash.</param>
/// <returns>The SHA-256 hash of the string.</returns>
public static string SHA256Text(this string instance)
{
return godot_icall_String_sha256_text(instance);
@ -1059,9 +1293,12 @@ namespace Godot
internal static extern string godot_icall_String_sha256_text(string str);
/// <summary>
/// Return the similarity index of the text compared to this string.
/// Returns the similarity index of the text compared to this string.
/// 1 means totally similar and 0 means totally dissimilar.
/// </summary>
/// <param name="instance">The string to compare.</param>
/// <param name="text">The other string to compare.</param>
/// <returns>The similarity index.</returns>
public static float Similarity(this string instance, string text)
{
if (instance == text)
@ -1114,6 +1351,13 @@ namespace Godot
/// Split the string by a divisor string, return an array of the substrings.
/// Example "One,Two,Three" will return ["One","Two","Three"] if split by ",".
/// </summary>
/// <seealso cref="SplitFloats(string, string, bool)"/>
/// <param name="instance">The string to split.</param>
/// <param name="divisor">The divisor string that splits the string.</param>
/// <param name="allowEmpty">
/// If <see langword="true"/>, the array may include empty strings.
/// </param>
/// <returns>The array of strings split from the string.</returns>
public static string[] Split(this string instance, string divisor, bool allowEmpty = true)
{
return instance.Split(new[] { divisor }, allowEmpty ? StringSplitOptions.None : StringSplitOptions.RemoveEmptyEntries);
@ -1123,6 +1367,13 @@ namespace Godot
/// Split the string in floats by using a divisor string, return an array of the substrings.
/// Example "1,2.5,3" will return [1,2.5,3] if split by ",".
/// </summary>
/// <seealso cref="Split(string, string, bool)"/>
/// <param name="instance">The string to split.</param>
/// <param name="divisor">The divisor string that splits the string.</param>
/// <param name="allowEmpty">
/// If <see langword="true"/>, the array may include empty floats.
/// </param>
/// <returns>The array of floats split from the string.</returns>
public static float[] SplitFloats(this string instance, string divisor, bool allowEmpty = true)
{
var ret = new List<float>();
@ -1156,9 +1407,13 @@ namespace Godot
};
/// <summary>
/// Return a copy of the string stripped of any non-printable character at the beginning and the end.
/// Returns a copy of the string stripped of any non-printable character at the beginning and the end.
/// The optional arguments are used to toggle stripping on the left and right edges respectively.
/// </summary>
/// <param name="instance">The string to strip.</param>
/// <param name="left">If the left side should be stripped.</param>
/// <param name="right">If the right side should be stripped.</param>
/// <returns>The string stripped of any non-printable characters.</returns>
public static string StripEdges(this string instance, bool left = true, bool right = true)
{
if (left)
@ -1172,8 +1427,14 @@ namespace Godot
}
/// <summary>
/// Return part of the string from the position <paramref name="from"/>, with length <paramref name="len"/>.
/// Returns part of the string from the position <paramref name="from"/>, with length <paramref name="len"/>.
/// </summary>
/// <param name="instance">The string to slice.</param>
/// <param name="from">The position in the string that the part starts from.</param>
/// <param name="len">The length of the returned part.</param>
/// <returns>
/// Part of the string from the position <paramref name="from"/>, with length <paramref name="len"/>.
/// </returns>
public static string Substr(this string instance, int from, int len)
{
int max = instance.Length - from;
@ -1181,52 +1442,70 @@ namespace Godot
}
/// <summary>
/// Convert the String (which is a character array) to PackedByteArray (which is an array of bytes).
/// Converts the String (which is a character array) to PackedByteArray (which is an array of bytes).
/// The conversion is speeded up in comparison to <see cref="ToUTF8(string)"/> with the assumption
/// that all the characters the String contains are only ASCII characters.
/// </summary>
/// <seealso cref="ToUTF8(string)"/>
/// <param name="instance">The string to convert.</param>
/// <returns>The string as ASCII encoded bytes.</returns>
public static byte[] ToAscii(this string instance)
{
return Encoding.ASCII.GetBytes(instance);
}
/// <summary>
/// Convert a string, containing a decimal number, into a <see langword="float" />.
/// Converts a string, containing a decimal number, into a <see langword="float" />.
/// </summary>
/// <seealso cref="ToInt(string)"/>
/// <param name="instance">The string to convert.</param>
/// <returns>The number representation of the string.</returns>
public static float ToFloat(this string instance)
{
return float.Parse(instance);
}
/// <summary>
/// Convert a string, containing an integer number, into an <see langword="int" />.
/// Converts a string, containing an integer number, into an <see langword="int" />.
/// </summary>
/// <seealso cref="ToFloat(string)"/>
/// <param name="instance">The string to convert.</param>
/// <returns>The number representation of the string.</returns>
public static int ToInt(this string instance)
{
return int.Parse(instance);
}
/// <summary>
/// Return the string converted to lowercase.
/// Returns the string converted to lowercase.
/// </summary>
/// <seealso cref="ToUpper(string)"/>
/// <param name="instance">The string to convert.</param>
/// <returns>The string converted to lowercase.</returns>
public static string ToLower(this string instance)
{
return instance.ToLower();
}
/// <summary>
/// Return the string converted to uppercase.
/// Returns the string converted to uppercase.
/// </summary>
/// <seealso cref="ToLower(string)"/>
/// <param name="instance">The string to convert.</param>
/// <returns>The string converted to uppercase.</returns>
public static string ToUpper(this string instance)
{
return instance.ToUpper();
}
/// <summary>
/// Convert the String (which is an array of characters) to PackedByteArray (which is an array of bytes).
/// Converts the String (which is an array of characters) to PackedByteArray (which is an array of bytes).
/// The conversion is a bit slower than <see cref="ToAscii(string)"/>, but supports all UTF-8 characters.
/// Therefore, you should prefer this function over <see cref="ToAscii(string)"/>.
/// </summary>
/// <seealso cref="ToAscii(string)"/>
/// <param name="instance">The string to convert.</param>
/// <returns>The string as UTF-8 encoded bytes.</returns>
public static byte[] ToUTF8(this string instance)
{
return Encoding.UTF8.GetBytes(instance);
@ -1235,8 +1514,8 @@ namespace Godot
/// <summary>
/// Decodes a string in URL encoded format. This is meant to
/// decode parameters in a URL when receiving an HTTP request.
/// This mostly wraps around `System.Uri.UnescapeDataString()`,
/// but also handles `+`.
/// This mostly wraps around <see cref="Uri.UnescapeDataString"/>,
/// but also handles <c>+</c>.
/// See <see cref="URIEncode"/> for encoding.
/// </summary>
/// <param name="instance">The string to decode.</param>
@ -1249,7 +1528,7 @@ namespace Godot
/// <summary>
/// Encodes a string to URL friendly format. This is meant to
/// encode parameters in a URL when sending an HTTP request.
/// This wraps around `System.Uri.EscapeDataString()`.
/// This wraps around <see cref="Uri.EscapeDataString"/>.
/// See <see cref="URIDecode"/> for decoding.
/// </summary>
/// <param name="instance">The string to encode.</param>
@ -1260,17 +1539,23 @@ namespace Godot
}
/// <summary>
/// Return a copy of the string with special characters escaped using the XML standard.
/// Returns a copy of the string with special characters escaped using the XML standard.
/// </summary>
/// <seealso cref="XMLUnescape(string)"/>
/// <param name="instance">The string to escape.</param>
/// <returns>The escaped string.</returns>
public static string XMLEscape(this string instance)
{
return SecurityElement.Escape(instance);
}
/// <summary>
/// Return a copy of the string with escaped characters replaced by their meanings
/// Returns a copy of the string with escaped characters replaced by their meanings
/// according to the XML standard.
/// </summary>
/// <seealso cref="XMLEscape(string)"/>
/// <param name="instance">The string to unescape.</param>
/// <returns>The unescaped string.</returns>
public static string XMLUnescape(this string instance)
{
return SecurityElement.FromString(instance).Text;

33
modules/mono/glue/GodotSharp/GodotSharp/Core/StringName.cs
View file

@ -3,6 +3,13 @@ using System.Runtime.CompilerServices;
namespace Godot
{
/// <summary>
/// StringNames are immutable strings designed for general-purpose representation of unique names.
/// StringName ensures that only one instance of a given name exists (so two StringNames with the
/// same value are the same object).
/// Comparing them is much faster than with regular strings, because only the pointers are compared,
/// not the whole strings.
/// </summary>
public sealed partial class StringName : IDisposable
{
private IntPtr ptr;
@ -23,6 +30,9 @@ namespace Godot
Dispose(false);
}
/// <summary>
/// Disposes of this <see cref="StringName"/>.
/// </summary>
public void Dispose()
{
Dispose(true);
@ -43,25 +53,48 @@ namespace Godot
this.ptr = ptr;
}
/// <summary>
/// Constructs an empty <see cref="StringName"/>.
/// </summary>
public StringName()
{
ptr = IntPtr.Zero;
}
/// <summary>
/// Constructs a <see cref="StringName"/> from the given <paramref name="path"/> string.
/// </summary>
/// <param name="path">String to construct the <see cref="StringName"/> from.</param>
public StringName(string path)
{
ptr = path == null ? IntPtr.Zero : godot_icall_StringName_Ctor(path);
}
/// <summary>
/// Converts a string to a <see cref="StringName"/>.
/// </summary>
/// <param name="from">The string to convert.</param>
public static implicit operator StringName(string from) => new StringName(from);
/// <summary>
/// Converts a <see cref="StringName"/> to a string.
/// </summary>
/// <param name="from">The <see cref="StringName"/> to convert.</param>
public static implicit operator string(StringName from) => from.ToString();
/// <summary>
/// Converts this <see cref="StringName"/> to a string.
/// </summary>
/// <returns>A string representation of this <see cref="StringName"/>.</returns>
public override string ToString()
{
return ptr == IntPtr.Zero ? string.Empty : godot_icall_StringName_operator_String(GetPtr(this));
}
/// <summary>
/// Check whether this <see cref="StringName"/> is empty.
/// </summary>
/// <returns>If the <see cref="StringName"/> is empty.</returns>
public bool IsEmpty()
{
return ptr == IntPtr.Zero || godot_icall_StringName_is_empty(GetPtr(this));

90
modules/mono/glue/GodotSharp/GodotSharp/Core/Transform2D.cs
View file

@ -21,18 +21,18 @@ namespace Godot
public struct Transform2D : IEquatable<Transform2D>
{
/// <summary>
/// The basis matrix's X vector (column 0). Equivalent to array index `[0]`.
/// The basis matrix's X vector (column 0). Equivalent to array index <c>[0]</c>.
/// </summary>
/// <value></value>
public Vector2 x;
/// <summary>
/// The basis matrix's Y vector (column 1). Equivalent to array index `[1]`.
/// The basis matrix's Y vector (column 1). Equivalent to array index <c>[1]</c>.
/// </summary>
public Vector2 y;
/// <summary>
/// The origin vector (column 2, the third column). Equivalent to array index `[2]`.
/// The origin vector (column 2, the third column). Equivalent to array index <c>[2]</c>.
/// The origin vector represents translation.
/// </summary>
public Vector2 origin;
@ -77,7 +77,8 @@ namespace Godot
}
/// <summary>
/// Access whole columns in the form of Vector2. The third column is the origin vector.
/// Access whole columns in the form of <see cref="Vector2"/>.
/// The third column is the <see cref="origin"/> vector.
/// </summary>
/// <param name="column">Which column vector.</param>
public Vector2 this[int column]
@ -116,7 +117,8 @@ namespace Godot
}
/// <summary>
/// Access matrix elements in column-major order. The third column is the origin vector.
/// Access matrix elements in column-major order.
/// The third column is the <see cref="origin"/> vector.
/// </summary>
/// <param name="column">Which column, the matrix horizontal position.</param>
/// <param name="row">Which row, the matrix vertical position.</param>
@ -138,6 +140,7 @@ namespace Godot
/// Returns the inverse of the transform, under the assumption that
/// the transformation is composed of rotation, scaling, and translation.
/// </summary>
/// <seealso cref="Inverse"/>
/// <returns>The inverse transformation matrix.</returns>
public Transform2D AffineInverse()
{
@ -178,8 +181,9 @@ namespace Godot
/// <summary>
/// Returns a vector transformed (multiplied) by the basis matrix.
/// This method does not account for translation (the origin vector).
/// This method does not account for translation (the <see cref="origin"/> vector).
/// </summary>
/// <seealso cref="BasisXformInv(Vector2)"/>
/// <param name="v">A vector to transform.</param>
/// <returns>The transformed vector.</returns>
public Vector2 BasisXform(Vector2 v)
@ -189,11 +193,12 @@ namespace Godot
/// <summary>
/// Returns a vector transformed (multiplied) by the inverse basis matrix.
/// This method does not account for translation (the origin vector).
/// This method does not account for translation (the <see cref="origin"/> vector).
///
/// Note: This results in a multiplication by the inverse of the
/// basis matrix only if it represents a rotation-reflection.
/// </summary>
/// <seealso cref="BasisXform(Vector2)"/>
/// <param name="v">A vector to inversely transform.</param>
/// <returns>The inversely transformed vector.</returns>
public Vector2 BasisXformInv(Vector2 v)
@ -202,7 +207,7 @@ namespace Godot
}
/// <summary>
/// Interpolates this transform to the other `transform` by `weight`.
/// Interpolates this transform to the other <paramref name="transform"/> by <paramref name="weight"/>.
/// </summary>
/// <param name="transform">The other transform.</param>
/// <param name="weight">A value on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
@ -293,7 +298,7 @@ namespace Godot
}
/// <summary>
/// Rotates the transform by `phi` (in radians), using matrix multiplication.
/// Rotates the transform by <paramref name="phi"/> (in radians), using matrix multiplication.
/// </summary>
/// <param name="phi">The angle to rotate, in radians.</param>
/// <returns>The rotated transformation matrix.</returns>
@ -335,7 +340,7 @@ namespace Godot
}
/// <summary>
/// Translates the transform by the given `offset`,
/// Translates the transform by the given <paramref name="offset"/>,
/// relative to the transform's basis vectors.
///
/// Unlike <see cref="Rotated"/> and <see cref="Scaled"/>,
@ -353,6 +358,7 @@ namespace Godot
/// <summary>
/// Returns a vector transformed (multiplied) by this transformation matrix.
/// </summary>
/// <seealso cref="XformInv(Vector2)"/>
/// <param name="v">A vector to transform.</param>
/// <returns>The transformed vector.</returns>
public Vector2 Xform(Vector2 v)
@ -363,6 +369,7 @@ namespace Godot
/// <summary>
/// Returns a vector transformed (multiplied) by the inverse transformation matrix.
/// </summary>
/// <seealso cref="Xform(Vector2)"/>
/// <param name="v">A vector to inversely transform.</param>
/// <returns>The inversely transformed vector.</returns>
public Vector2 XformInv(Vector2 v)
@ -378,20 +385,20 @@ namespace Godot
/// <summary>
/// The identity transform, with no translation, rotation, or scaling applied.
/// This is used as a replacement for `Transform2D()` in GDScript.
/// Do not use `new Transform2D()` with no arguments in C#, because it sets all values to zero.
/// This is used as a replacement for <c>Transform2D()</c> in GDScript.
/// Do not use <c>new Transform2D()</c> with no arguments in C#, because it sets all values to zero.
/// </summary>
/// <value>Equivalent to `new Transform2D(Vector2.Right, Vector2.Down, Vector2.Zero)`.</value>
/// <value>Equivalent to <c>new Transform2D(Vector2.Right, Vector2.Down, Vector2.Zero)</c>.</value>
public static Transform2D Identity { get { return _identity; } }
/// <summary>
/// The transform that will flip something along the X axis.
/// </summary>
/// <value>Equivalent to `new Transform2D(Vector2.Left, Vector2.Down, Vector2.Zero)`.</value>
/// <value>Equivalent to <c>new Transform2D(Vector2.Left, Vector2.Down, Vector2.Zero)</c>.</value>
public static Transform2D FlipX { get { return _flipX; } }
/// <summary>
/// The transform that will flip something along the Y axis.
/// </summary>
/// <value>Equivalent to `new Transform2D(Vector2.Right, Vector2.Up, Vector2.Zero)`.</value>
/// <value>Equivalent to <c>new Transform2D(Vector2.Right, Vector2.Up, Vector2.Zero)</c>.</value>
public static Transform2D FlipY { get { return _flipY; } }
/// <summary>
@ -411,12 +418,12 @@ namespace Godot
/// Constructs a transformation matrix from the given components.
/// Arguments are named such that xy is equal to calling x.y
/// </summary>
/// <param name="xx">The X component of the X column vector, accessed via `t.x.x` or `[0][0]`</param>
/// <param name="xy">The Y component of the X column vector, accessed via `t.x.y` or `[0][1]`</param>
/// <param name="yx">The X component of the Y column vector, accessed via `t.y.x` or `[1][0]`</param>
/// <param name="yy">The Y component of the Y column vector, accessed via `t.y.y` or `[1][1]`</param>
/// <param name="ox">The X component of the origin vector, accessed via `t.origin.x` or `[2][0]`</param>
/// <param name="oy">The Y component of the origin vector, accessed via `t.origin.y` or `[2][1]`</param>
/// <param name="xx">The X component of the X column vector, accessed via <c>t.x.x</c> or <c>[0][0]</c></param>
/// <param name="xy">The Y component of the X column vector, accessed via <c>t.x.y</c> or <c>[0][1]</c></param>
/// <param name="yx">The X component of the Y column vector, accessed via <c>t.y.x</c> or <c>[1][0]</c></param>
/// <param name="yy">The Y component of the Y column vector, accessed via <c>t.y.y</c> or <c>[1][1]</c></param>
/// <param name="ox">The X component of the origin vector, accessed via <c>t.origin.x</c> or <c>[2][0]</c></param>
/// <param name="oy">The Y component of the origin vector, accessed via <c>t.origin.y</c> or <c>[2][1]</c></param>
public Transform2D(real_t xx, real_t xy, real_t yx, real_t yy, real_t ox, real_t oy)
{
x = new Vector2(xx, xy);
@ -425,16 +432,17 @@ namespace Godot
}
/// <summary>
/// Constructs a transformation matrix from a rotation value and origin vector.
/// Constructs a transformation matrix from a <paramref name="rotation"/> value and
/// <paramref name="origin"/> vector.
/// </summary>
/// <param name="rot">The rotation of the new transform, in radians.</param>
/// <param name="pos">The origin vector, or column index 2.</param>
public Transform2D(real_t rot, Vector2 pos)
/// <param name="rotation">The rotation of the new transform, in radians.</param>
/// <param name="origin">The origin vector, or column index 2.</param>
public Transform2D(real_t rotation, Vector2 origin)
{
x.x = y.y = Mathf.Cos(rot);
x.y = y.x = Mathf.Sin(rot);
x.x = y.y = Mathf.Cos(rotation);
x.y = y.x = Mathf.Sin(rotation);
y.x *= -1;
origin = pos;
this.origin = origin;
}
public static Transform2D operator *(Transform2D left, Transform2D right)
@ -464,19 +472,29 @@ namespace Godot
return !left.Equals(right);
}
/// <summary>
/// Returns <see langword="true"/> if this transform and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the transform and the other object are equal.</returns>
public override bool Equals(object obj)
{
return obj is Transform2D transform2D && Equals(transform2D);
}
/// <summary>
/// Returns <see langword="true"/> if this transform and <paramref name="other"/> are equal.
/// </summary>
/// <param name="other">The other transform to compare.</param>
/// <returns>Whether or not the matrices are equal.</returns>
public bool Equals(Transform2D other)
{
return x.Equals(other.x) && y.Equals(other.y) && origin.Equals(other.origin);
}
/// <summary>
/// Returns true if this transform and `other` are approximately equal, by running
/// <see cref="Vector2.IsEqualApprox(Vector2)"/> on each component.
/// Returns <see langword="true"/> if this transform and <paramref name="other"/> are approximately equal,
/// by running <see cref="Vector2.IsEqualApprox(Vector2)"/> on each component.
/// </summary>
/// <param name="other">The other transform to compare.</param>
/// <returns>Whether or not the matrices are approximately equal.</returns>
@ -485,16 +503,28 @@ namespace Godot
return x.IsEqualApprox(other.x) && y.IsEqualApprox(other.y) && origin.IsEqualApprox(other.origin);
}
/// <summary>
/// Serves as the hash function for <see cref="Transform2D"/>.
/// </summary>
/// <returns>A hash code for this transform.</returns>
public override int GetHashCode()
{
return x.GetHashCode() ^ y.GetHashCode() ^ origin.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Transform2D"/> to a string.
/// </summary>
/// <returns>A string representation of this transform.</returns>
public override string ToString()
{
return $"[X: {x}, Y: {y}, O: {origin}]";
}
/// <summary>
/// Converts this <see cref="Transform2D"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this transform.</returns>
public string ToString(string format)
{
return $"[X: {x.ToString(format)}, Y: {y.ToString(format)}, O: {origin.ToString(format)}]";

73
modules/mono/glue/GodotSharp/GodotSharp/Core/Transform3D.cs
View file

@ -28,12 +28,13 @@ namespace Godot
public Basis basis;
/// <summary>
/// The origin vector (column 3, the fourth column). Equivalent to array index `[3]`.
/// The origin vector (column 3, the fourth column). Equivalent to array index <c>[3]</c>.
/// </summary>
public Vector3 origin;
/// <summary>
/// Access whole columns in the form of Vector3. The fourth column is the origin vector.
/// Access whole columns in the form of <see cref="Vector3"/>.
/// The fourth column is the <see cref="origin"/> vector.
/// </summary>
/// <param name="column">Which column vector.</param>
public Vector3 this[int column]
@ -77,7 +78,8 @@ namespace Godot
}
/// <summary>
/// Access matrix elements in column-major order. The fourth column is the origin vector.
/// Access matrix elements in column-major order.
/// The fourth column is the <see cref="origin"/> vector.
/// </summary>
/// <param name="column">Which column, the matrix horizontal position.</param>
/// <param name="row">Which row, the matrix vertical position.</param>
@ -106,6 +108,7 @@ namespace Godot
/// Returns the inverse of the transform, under the assumption that
/// the transformation is composed of rotation, scaling, and translation.
/// </summary>
/// <seealso cref="Inverse"/>
/// <returns>The inverse transformation matrix.</returns>
public Transform3D AffineInverse()
{
@ -114,7 +117,7 @@ namespace Godot
}
/// <summary>
/// Interpolates this transform to the other `transform` by `weight`.
/// Interpolates this transform to the other <paramref name="transform"/> by <paramref name="weight"/>.
/// </summary>
/// <param name="transform">The other transform.</param>
/// <param name="weight">A value on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
@ -154,11 +157,11 @@ namespace Godot
/// <summary>
/// Returns a copy of the transform rotated such that its
/// -Z axis (forward) points towards the target position.
/// -Z axis (forward) points towards the <paramref name="target"/> position.
///
/// The transform will first be rotated around the given up vector,
/// and then fully aligned to the target by a further rotation around
/// an axis perpendicular to both the target and up vectors.
/// The transform will first be rotated around the given <paramref name="up"/> vector,
/// and then fully aligned to the <paramref name="target"/> by a further rotation around
/// an axis perpendicular to both the <paramref name="target"/> and <paramref name="up"/> vectors.
///
/// Operations take place in global space.
/// </summary>
@ -183,7 +186,7 @@ namespace Godot
}
/// <summary>
/// Rotates the transform around the given `axis` by `phi` (in radians),
/// Rotates the transform around the given <paramref name="axis"/> by <paramref name="phi"/> (in radians),
/// using matrix multiplication. The axis must be a normalized vector.
/// </summary>
/// <param name="axis">The axis to rotate around. Must be normalized.</param>
@ -228,7 +231,7 @@ namespace Godot
}
/// <summary>
/// Translates the transform by the given `offset`,
/// Translates the transform by the given <paramref name="offset"/>,
/// relative to the transform's basis vectors.
///
/// Unlike <see cref="Rotated"/> and <see cref="Scaled"/>,
@ -249,6 +252,7 @@ namespace Godot
/// <summary>
/// Returns a vector transformed (multiplied) by this transformation matrix.
/// </summary>
/// <seealso cref="XformInv(Vector3)"/>
/// <param name="v">A vector to transform.</param>
/// <returns>The transformed vector.</returns>
public Vector3 Xform(Vector3 v)
@ -267,6 +271,7 @@ namespace Godot
/// Note: This results in a multiplication by the inverse of the
/// transformation matrix only if it represents a rotation-reflection.
/// </summary>
/// <seealso cref="Xform(Vector3)"/>
/// <param name="v">A vector to inversely transform.</param>
/// <returns>The inversely transformed vector.</returns>
public Vector3 XformInv(Vector3 v)
@ -289,25 +294,25 @@ namespace Godot
/// <summary>
/// The identity transform, with no translation, rotation, or scaling applied.
/// This is used as a replacement for `Transform()` in GDScript.
/// Do not use `new Transform()` with no arguments in C#, because it sets all values to zero.
/// This is used as a replacement for <c>Transform()</c> in GDScript.
/// Do not use <c>new Transform()</c> with no arguments in C#, because it sets all values to zero.
/// </summary>
/// <value>Equivalent to `new Transform(Vector3.Right, Vector3.Up, Vector3.Back, Vector3.Zero)`.</value>
/// <value>Equivalent to <c>new Transform(Vector3.Right, Vector3.Up, Vector3.Back, Vector3.Zero)</c>.</value>
public static Transform3D Identity { get { return _identity; } }
/// <summary>
/// The transform that will flip something along the X axis.
/// </summary>
/// <value>Equivalent to `new Transform(Vector3.Left, Vector3.Up, Vector3.Back, Vector3.Zero)`.</value>
/// <value>Equivalent to <c>new Transform(Vector3.Left, Vector3.Up, Vector3.Back, Vector3.Zero)</c>.</value>
public static Transform3D FlipX { get { return _flipX; } }
/// <summary>
/// The transform that will flip something along the Y axis.
/// </summary>
/// <value>Equivalent to `new Transform(Vector3.Right, Vector3.Down, Vector3.Back, Vector3.Zero)`.</value>
/// <value>Equivalent to <c>new Transform(Vector3.Right, Vector3.Down, Vector3.Back, Vector3.Zero)</c>.</value>
public static Transform3D FlipY { get { return _flipY; } }
/// <summary>
/// The transform that will flip something along the Z axis.
/// </summary>
/// <value>Equivalent to `new Transform(Vector3.Right, Vector3.Up, Vector3.Forward, Vector3.Zero)`.</value>
/// <value>Equivalent to <c>new Transform(Vector3.Right, Vector3.Up, Vector3.Forward, Vector3.Zero)</c>.</value>
public static Transform3D FlipZ { get { return _flipZ; } }
/// <summary>
@ -324,9 +329,10 @@ namespace Godot
}
/// <summary>
/// Constructs a transformation matrix from the given quaternion and origin vector.
/// Constructs a transformation matrix from the given <paramref name="quaternion"/>
/// and <paramref name="origin"/> vector.
/// </summary>
/// <param name="quaternion">The <see cref="Godot.Quaternion"/> to create the basis from.</param>
/// <param name="quaternion">The <see cref="Quaternion"/> to create the basis from.</param>
/// <param name="origin">The origin vector, or column index 3.</param>
public Transform3D(Quaternion quaternion, Vector3 origin)
{
@ -335,9 +341,10 @@ namespace Godot
}
/// <summary>
/// Constructs a transformation matrix from the given basis and origin vector.
/// Constructs a transformation matrix from the given <paramref name="basis"/> and
/// <paramref name="origin"/> vector.
/// </summary>
/// <param name="basis">The <see cref="Godot.Basis"/> to create the basis from.</param>
/// <param name="basis">The <see cref="Basis"/> to create the basis from.</param>
/// <param name="origin">The origin vector, or column index 3.</param>
public Transform3D(Basis basis, Vector3 origin)
{
@ -362,6 +369,11 @@ namespace Godot
return !left.Equals(right);
}
/// <summary>
/// Returns <see langword="true"/> if this transform and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the transform and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Transform3D)
@ -372,14 +384,19 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this transform and <paramref name="other"/> are equal.
/// </summary>
/// <param name="other">The other transform to compare.</param>
/// <returns>Whether or not the matrices are equal.</returns>
public bool Equals(Transform3D other)
{
return basis.Equals(other.basis) && origin.Equals(other.origin);
}
/// <summary>
/// Returns true if this transform and `other` are approximately equal, by running
/// <see cref="Vector3.IsEqualApprox(Vector3)"/> on each component.
/// Returns <see langword="true"/> if this transform and <paramref name="other"/> are approximately equal,
/// by running <see cref="Vector3.IsEqualApprox(Vector3)"/> on each component.
/// </summary>
/// <param name="other">The other transform to compare.</param>
/// <returns>Whether or not the matrices are approximately equal.</returns>
@ -388,16 +405,28 @@ namespace Godot
return basis.IsEqualApprox(other.basis) && origin.IsEqualApprox(other.origin);
}
/// <summary>
/// Serves as the hash function for <see cref="Transform3D"/>.
/// </summary>
/// <returns>A hash code for this transform.</returns>
public override int GetHashCode()
{
return basis.GetHashCode() ^ origin.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Transform3D"/> to a string.
/// </summary>
/// <returns>A string representation of this transform.</returns>
public override string ToString()
{
return $"[X: {basis.x}, Y: {basis.y}, Z: {basis.z}, O: {origin}]";
}
/// <summary>
/// Converts this <see cref="Transform3D"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this transform.</returns>
public string ToString(string format)
{
return $"[X: {basis.x.ToString(format)}, Y: {basis.y.ToString(format)}, Z: {basis.z.ToString(format)}, O: {origin.ToString(format)}]";

2
modules/mono/glue/GodotSharp/GodotSharp/Core/UnhandledExceptionArgs.cs
View file

@ -8,7 +8,7 @@ namespace Godot
public class UnhandledExceptionArgs
{
/// <summary>
/// Exception object
/// Exception object.
/// </summary>
public Exception Exception { get; private set; }

142
modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2.cs
View file

@ -21,24 +21,36 @@ namespace Godot
/// </summary>
public enum Axis
{
/// <summary>
/// The vector's X axis.
/// </summary>
X = 0,
/// <summary>
/// The vector's Y axis.
/// </summary>
Y
}
/// <summary>
/// The vector's X component. Also accessible by using the index position `[0]`.
/// The vector's X component. Also accessible by using the index position <c>[0]</c>.
/// </summary>
public real_t x;
/// <summary>
/// The vector's Y component. Also accessible by using the index position `[1]`.
/// The vector's Y component. Also accessible by using the index position <c>[1]</c>.
/// </summary>
public real_t y;
/// <summary>
/// Access vector components using their index.
/// </summary>
/// <value>`[0]` is equivalent to `.x`, `[1]` is equivalent to `.y`.</value>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when the given the <paramref name="index"/> is not 0 or 1.
/// </exception>
/// <value>
/// <c>[0]</c> is equivalent to <see cref="x"/>,
/// <c>[1]</c> is equivalent to <see cref="y"/>.
/// </value>
public real_t this[int index]
{
get
@ -98,7 +110,7 @@ namespace Godot
/// Returns this vector's angle with respect to the X axis, or (1, 0) vector, in radians.
///
/// Equivalent to the result of <see cref="Mathf.Atan2(real_t, real_t)"/> when
/// called with the vector's `y` and `x` as parameters: `Mathf.Atan2(v.y, v.x)`.
/// called with the vector's <see cref="y"/> and <see cref="x"/> as parameters: <c>Mathf.Atan2(v.y, v.x)</c>.
/// </summary>
/// <returns>The angle of this vector, in radians.</returns>
public real_t Angle()
@ -127,9 +139,9 @@ namespace Godot
}
/// <summary>
/// Returns the aspect ratio of this vector, the ratio of `x` to `y`.
/// Returns the aspect ratio of this vector, the ratio of <see cref="x"/> to <see cref="y"/>.
/// </summary>
/// <returns>The `x` component divided by the `y` component.</returns>
/// <returns>The <see cref="x"/> component divided by the <see cref="y"/> component.</returns>
public real_t Aspect()
{
return x / y;
@ -156,7 +168,7 @@ namespace Godot
/// <summary>
/// Returns a new vector with all components clamped between the
/// components of `min` and `max` using
/// components of <paramref name="min"/> and <paramref name="max"/> using
/// <see cref="Mathf.Clamp(real_t, real_t, real_t)"/>.
/// </summary>
/// <param name="min">The vector with minimum allowed values.</param>
@ -172,7 +184,7 @@ namespace Godot
}
/// <summary>
/// Returns the cross product of this vector and `b`.
/// Returns the cross product of this vector and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector.</param>
/// <returns>The cross product value.</returns>
@ -182,11 +194,12 @@ namespace Godot
}
/// <summary>
/// Performs a cubic interpolation between vectors `preA`, this vector, `b`, and `postB`, by the given amount `t`.
/// Performs a cubic interpolation between vectors <paramref name="preA"/>, this vector,
/// <paramref name="b"/>, and <paramref name="postB"/>, by the given amount <paramref name="weight"/>.
/// </summary>
/// <param name="b">The destination vector.</param>
/// <param name="preA">A vector before this vector.</param>
/// <param name="postB">A vector after `b`.</param>
/// <param name="postB">A vector after <paramref name="b"/>.</param>
/// <param name="weight">A value on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
/// <returns>The interpolated vector.</returns>
public Vector2 CubicInterpolate(Vector2 b, Vector2 preA, Vector2 postB, real_t weight)
@ -209,17 +222,17 @@ namespace Godot
}
/// <summary>
/// Returns the normalized vector pointing from this vector to `b`.
/// Returns the normalized vector pointing from this vector to <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector to point towards.</param>
/// <returns>The direction from this vector to `b`.</returns>
/// <returns>The direction from this vector to <paramref name="b"/>.</returns>
public Vector2 DirectionTo(Vector2 b)
{
return new Vector2(b.x - x, b.y - y).Normalized();
}
/// <summary>
/// Returns the squared distance between this vector and `to`.
/// Returns the squared distance between this vector and <paramref name="to"/>.
/// This method runs faster than <see cref="DistanceTo"/>, so prefer it if
/// you need to compare vectors or need the squared distance for some formula.
/// </summary>
@ -231,7 +244,7 @@ namespace Godot
}
/// <summary>
/// Returns the distance between this vector and `to`.
/// Returns the distance between this vector and <paramref name="to"/>.
/// </summary>
/// <param name="to">The other vector to use.</param>
/// <returns>The distance between the two vectors.</returns>
@ -241,7 +254,7 @@ namespace Godot
}
/// <summary>
/// Returns the dot product of this vector and `with`.
/// Returns the dot product of this vector and <paramref name="with"/>.
/// </summary>
/// <param name="with">The other vector to use.</param>
/// <returns>The dot product of the two vectors.</returns>
@ -260,7 +273,7 @@ namespace Godot
}
/// <summary>
/// Returns the inverse of this vector. This is the same as `new Vector2(1 / v.x, 1 / v.y)`.
/// Returns the inverse of this vector. This is the same as <c>new Vector2(1 / v.x, 1 / v.y)</c>.
/// </summary>
/// <returns>The inverse of this vector.</returns>
public Vector2 Inverse()
@ -269,9 +282,9 @@ namespace Godot
}
/// <summary>
/// Returns true if the vector is normalized, and false otherwise.
/// Returns <see langword="true"/> if the vector is normalized, and <see langword="false"/> otherwise.
/// </summary>
/// <returns>A bool indicating whether or not the vector is normalized.</returns>
/// <returns>A <see langword="bool"/> indicating whether or not the vector is normalized.</returns>
public bool IsNormalized()
{
return Mathf.Abs(LengthSquared() - 1.0f) < Mathf.Epsilon;
@ -280,6 +293,7 @@ namespace Godot
/// <summary>
/// Returns the length (magnitude) of this vector.
/// </summary>
/// <seealso cref="LengthSquared"/>
/// <returns>The length of this vector.</returns>
public real_t Length()
{
@ -299,7 +313,7 @@ namespace Godot
/// <summary>
/// Returns the result of the linear interpolation between
/// this vector and `to` by amount `weight`.
/// this vector and <paramref name="to"/> by amount <paramref name="weight"/>.
/// </summary>
/// <param name="to">The destination vector for interpolation.</param>
/// <param name="weight">A value on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
@ -315,10 +329,12 @@ namespace Godot
/// <summary>
/// Returns the result of the linear interpolation between
/// this vector and `to` by the vector amount `weight`.
/// this vector and <paramref name="to"/> by the vector amount <paramref name="weight"/>.
/// </summary>
/// <param name="to">The destination vector for interpolation.</param>
/// <param name="weight">A vector with components on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
/// <param name="weight">
/// A vector with components on the range of 0.0 to 1.0, representing the amount of interpolation.
/// </param>
/// <returns>The resulting vector of the interpolation.</returns>
public Vector2 Lerp(Vector2 to, Vector2 weight)
{
@ -330,7 +346,7 @@ namespace Godot
}
/// <summary>
/// Returns the vector with a maximum length by limiting its length to `length`.
/// Returns the vector with a maximum length by limiting its length to <paramref name="length"/>.
/// </summary>
/// <param name="length">The length to limit to.</param>
/// <returns>The vector with its length limited.</returns>
@ -369,7 +385,7 @@ namespace Godot
}
/// <summary>
/// Moves this vector toward `to` by the fixed `delta` amount.
/// Moves this vector toward <paramref name="to"/> by the fixed <paramref name="delta"/> amount.
/// </summary>
/// <param name="to">The vector to move towards.</param>
/// <param name="delta">The amount to move towards by.</param>
@ -386,7 +402,7 @@ namespace Godot
}
/// <summary>
/// Returns the vector scaled to unit length. Equivalent to `v / v.Length()`.
/// Returns the vector scaled to unit length. Equivalent to <c>v / v.Length()</c>.
/// </summary>
/// <returns>A normalized version of the vector.</returns>
public Vector2 Normalized()
@ -397,10 +413,13 @@ namespace Godot
}
/// <summary>
/// Returns a vector composed of the <see cref="Mathf.PosMod(real_t, real_t)"/> of this vector's components and `mod`.
/// Returns a vector composed of the <see cref="Mathf.PosMod(real_t, real_t)"/> of this vector's components
/// and <paramref name="mod"/>.
/// </summary>
/// <param name="mod">A value representing the divisor of the operation.</param>
/// <returns>A vector with each component <see cref="Mathf.PosMod(real_t, real_t)"/> by `mod`.</returns>
/// <returns>
/// A vector with each component <see cref="Mathf.PosMod(real_t, real_t)"/> by <paramref name="mod"/>.
/// </returns>
public Vector2 PosMod(real_t mod)
{
Vector2 v;
@ -410,10 +429,13 @@ namespace Godot
}
/// <summary>
/// Returns a vector composed of the <see cref="Mathf.PosMod(real_t, real_t)"/> of this vector's components and `modv`'s components.
/// Returns a vector composed of the <see cref="Mathf.PosMod(real_t, real_t)"/> of this vector's components
/// and <paramref name="modv"/>'s components.
/// </summary>
/// <param name="modv">A vector representing the divisors of the operation.</param>
/// <returns>A vector with each component <see cref="Mathf.PosMod(real_t, real_t)"/> by `modv`'s components.</returns>
/// <returns>
/// A vector with each component <see cref="Mathf.PosMod(real_t, real_t)"/> by <paramref name="modv"/>'s components.
/// </returns>
public Vector2 PosMod(Vector2 modv)
{
Vector2 v;
@ -423,7 +445,7 @@ namespace Godot
}
/// <summary>
/// Returns this vector projected onto another vector `b`.
/// Returns this vector projected onto another vector <paramref name="onNormal"/>.
/// </summary>
/// <param name="onNormal">The vector to project onto.</param>
/// <returns>The projected vector.</returns>
@ -433,7 +455,7 @@ namespace Godot
}
/// <summary>
/// Returns this vector reflected from a plane defined by the given `normal`.
/// Returns this vector reflected from a plane defined by the given <paramref name="normal"/>.
/// </summary>
/// <param name="normal">The normal vector defining the plane to reflect from. Must be normalized.</param>
/// <returns>The reflected vector.</returns>
@ -449,7 +471,7 @@ namespace Godot
}
/// <summary>
/// Rotates this vector by `phi` radians.
/// Rotates this vector by <paramref name="phi"/> radians.
/// </summary>
/// <param name="phi">The angle to rotate by, in radians.</param>
/// <returns>The rotated vector.</returns>
@ -477,7 +499,7 @@ namespace Godot
/// on the signs of this vector's components, or zero if the component is zero,
/// by calling <see cref="Mathf.Sign(real_t)"/> on each component.
/// </summary>
/// <returns>A vector with all components as either `1`, `-1`, or `0`.</returns>
/// <returns>A vector with all components as either <c>1</c>, <c>-1</c>, or <c>0</c>.</returns>
public Vector2 Sign()
{
Vector2 v;
@ -488,7 +510,7 @@ namespace Godot
/// <summary>
/// Returns the result of the spherical linear interpolation between
/// this vector and `to` by amount `weight`.
/// this vector and <paramref name="to"/> by amount <paramref name="weight"/>.
///
/// Note: Both vectors must be normalized.
/// </summary>
@ -504,14 +526,14 @@ namespace Godot
}
if (!to.IsNormalized())
{
throw new InvalidOperationException("Vector2.Slerp: `to` is not normalized.");
throw new InvalidOperationException($"Vector2.Slerp: `{nameof(to)}` is not normalized.");
}
#endif
return Rotated(AngleTo(to) * weight);
}
/// <summary>
/// Returns this vector slid along a plane defined by the given normal.
/// Returns this vector slid along a plane defined by the given <paramref name="normal"/>.
/// </summary>
/// <param name="normal">The normal vector defining the plane to slide on.</param>
/// <returns>The slid vector.</returns>
@ -521,7 +543,7 @@ namespace Godot
}
/// <summary>
/// Returns this vector with each component snapped to the nearest multiple of `step`.
/// Returns this vector with each component snapped to the nearest multiple of <paramref name="step"/>.
/// This can also be used to round to an arbitrary number of decimals.
/// </summary>
/// <param name="step">A vector value representing the step size to snap to.</param>
@ -552,40 +574,40 @@ namespace Godot
private static readonly Vector2 _left = new Vector2(-1, 0);
/// <summary>
/// Zero vector, a vector with all components set to `0`.
/// Zero vector, a vector with all components set to <c>0</c>.
/// </summary>
/// <value>Equivalent to `new Vector2(0, 0)`</value>
/// <value>Equivalent to <c>new Vector2(0, 0)</c>.</value>
public static Vector2 Zero { get { return _zero; } }
/// <summary>
/// One vector, a vector with all components set to `1`.
/// One vector, a vector with all components set to <c>1</c>.
/// </summary>
/// <value>Equivalent to `new Vector2(1, 1)`</value>
/// <value>Equivalent to <c>new Vector2(1, 1)</c>.</value>
public static Vector2 One { get { return _one; } }
/// <summary>
/// Infinity vector, a vector with all components set to `Mathf.Inf`.
/// Infinity vector, a vector with all components set to <see cref="Mathf.Inf"/>.
/// </summary>
/// <value>Equivalent to `new Vector2(Mathf.Inf, Mathf.Inf)`</value>
/// <value>Equivalent to <c>new Vector2(Mathf.Inf, Mathf.Inf)</c>.</value>
public static Vector2 Inf { get { return _inf; } }
/// <summary>
/// Up unit vector. Y is down in 2D, so this vector points -Y.
/// </summary>
/// <value>Equivalent to `new Vector2(0, -1)`</value>
/// <value>Equivalent to <c>new Vector2(0, -1)</c>.</value>
public static Vector2 Up { get { return _up; } }
/// <summary>
/// Down unit vector. Y is down in 2D, so this vector points +Y.
/// </summary>
/// <value>Equivalent to `new Vector2(0, 1)`</value>
/// <value>Equivalent to <c>new Vector2(0, 1)</c>.</value>
public static Vector2 Down { get { return _down; } }
/// <summary>
/// Right unit vector. Represents the direction of right.
/// </summary>
/// <value>Equivalent to `new Vector2(1, 0)`</value>
/// <value>Equivalent to <c>new Vector2(1, 0)</c>.</value>
public static Vector2 Right { get { return _right; } }
/// <summary>
/// Left unit vector. Represents the direction of left.
/// </summary>
/// <value>Equivalent to `new Vector2(-1, 0)`</value>
/// <value>Equivalent to <c>new Vector2(-1, 0)</c>.</value>
public static Vector2 Left { get { return _left; } }
/// <summary>
@ -611,7 +633,7 @@ namespace Godot
/// <summary>
/// Creates a unit Vector2 rotated to the given angle. This is equivalent to doing
/// `Vector2(Mathf.Cos(angle), Mathf.Sin(angle))` or `Vector2.Right.Rotated(angle)`.
/// <c>Vector2(Mathf.Cos(angle), Mathf.Sin(angle))</c> or <c>Vector2.Right.Rotated(angle)</c>.
/// </summary>
/// <param name="angle">Angle of the vector, in radians.</param>
/// <returns>The resulting vector.</returns>
@ -736,6 +758,11 @@ namespace Godot
return left.x >= right.x;
}
/// <summary>
/// Returns <see langword="true"/> if this vector and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the vector and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Vector2)
@ -745,14 +772,19 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this vector and <paramref name="other"/> are equal.
/// </summary>
/// <param name="other">The other vector to compare.</param>
/// <returns>Whether or not the vectors are equal.</returns>
public bool Equals(Vector2 other)
{
return x == other.x && y == other.y;
}
/// <summary>
/// Returns true if this vector and `other` are approximately equal, by running
/// <see cref="Mathf.IsEqualApprox(real_t, real_t)"/> on each component.
/// Returns <see langword="true"/> if this vector and <paramref name="other"/> are approximately equal,
/// by running <see cref="Mathf.IsEqualApprox(real_t, real_t)"/> on each component.
/// </summary>
/// <param name="other">The other vector to compare.</param>
/// <returns>Whether or not the vectors are approximately equal.</returns>
@ -761,16 +793,28 @@ namespace Godot
return Mathf.IsEqualApprox(x, other.x) && Mathf.IsEqualApprox(y, other.y);
}
/// <summary>
/// Serves as the hash function for <see cref="Vector2"/>.
/// </summary>
/// <returns>A hash code for this vector.</returns>
public override int GetHashCode()
{
return y.GetHashCode() ^ x.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Vector2"/> to a string.
/// </summary>
/// <returns>A string representation of this vector.</returns>
public override string ToString()
{
return $"({x}, {y})";
}
/// <summary>
/// Converts this <see cref="Vector2"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this vector.</returns>
public string ToString(string format)
{
return $"({x.ToString(format)}, {y.ToString(format)})";

97
modules/mono/glue/GodotSharp/GodotSharp/Core/Vector2i.cs
View file

@ -21,24 +21,36 @@ namespace Godot
/// </summary>
public enum Axis
{
/// <summary>
/// The vector's X axis.
/// </summary>
X = 0,
/// <summary>
/// The vector's Y axis.
/// </summary>
Y
}
/// <summary>
/// The vector's X component. Also accessible by using the index position `[0]`.
/// The vector's X component. Also accessible by using the index position <c>[0]</c>.
/// </summary>
public int x;
/// <summary>
/// The vector's Y component. Also accessible by using the index position `[1]`.
/// The vector's Y component. Also accessible by using the index position <c>[1]</c>.
/// </summary>
public int y;
/// <summary>
/// Access vector components using their index.
/// </summary>
/// <value>`[0]` is equivalent to `.x`, `[1]` is equivalent to `.y`.</value>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when the given the <paramref name="index"/> is not 0 or 1.
/// </exception>
/// <value>
/// <c>[0]</c> is equivalent to <see cref="x"/>,
/// <c>[1]</c> is equivalent to <see cref="y"/>.
/// </value>
public int this[int index]
{
get
@ -82,7 +94,7 @@ namespace Godot
/// Returns this vector's angle with respect to the X axis, or (1, 0) vector, in radians.
///
/// Equivalent to the result of <see cref="Mathf.Atan2(real_t, real_t)"/> when
/// called with the vector's `y` and `x` as parameters: `Mathf.Atan2(v.y, v.x)`.
/// called with the vector's <see cref="y"/> and <see cref="x"/> as parameters: <c>Mathf.Atan2(v.y, v.x)</c>.
/// </summary>
/// <returns>The angle of this vector, in radians.</returns>
public real_t Angle()
@ -111,9 +123,9 @@ namespace Godot
}
/// <summary>
/// Returns the aspect ratio of this vector, the ratio of `x` to `y`.
/// Returns the aspect ratio of this vector, the ratio of <see cref="x"/> to <see cref="y"/>.
/// </summary>
/// <returns>The `x` component divided by the `y` component.</returns>
/// <returns>The <see cref="x"/> component divided by the <see cref="y"/> component.</returns>
public real_t Aspect()
{
return x / (real_t)y;
@ -121,7 +133,7 @@ namespace Godot
/// <summary>
/// Returns a new vector with all components clamped between the
/// components of `min` and `max` using
/// components of <paramref name="min"/> and <paramref name="max"/> using
/// <see cref="Mathf.Clamp(int, int, int)"/>.
/// </summary>
/// <param name="min">The vector with minimum allowed values.</param>
@ -137,7 +149,7 @@ namespace Godot
}
/// <summary>
/// Returns the cross product of this vector and `b`.
/// Returns the cross product of this vector and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector.</param>
/// <returns>The cross product vector.</returns>
@ -147,7 +159,7 @@ namespace Godot
}
/// <summary>
/// Returns the squared distance between this vector and `b`.
/// Returns the squared distance between this vector and <paramref name="b"/>.
/// This method runs faster than <see cref="DistanceTo"/>, so prefer it if
/// you need to compare vectors or need the squared distance for some formula.
/// </summary>
@ -159,7 +171,7 @@ namespace Godot
}
/// <summary>
/// Returns the distance between this vector and `b`.
/// Returns the distance between this vector and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector to use.</param>
/// <returns>The distance between the two vectors.</returns>
@ -169,7 +181,7 @@ namespace Godot
}
/// <summary>
/// Returns the dot product of this vector and `b`.
/// Returns the dot product of this vector and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector to use.</param>
/// <returns>The dot product of the two vectors.</returns>
@ -181,6 +193,7 @@ namespace Godot
/// <summary>
/// Returns the length (magnitude) of this vector.
/// </summary>
/// <seealso cref="LengthSquared"/>
/// <returns>The length of this vector.</returns>
public real_t Length()
{
@ -225,10 +238,13 @@ namespace Godot
}
/// <summary>
/// Returns a vector composed of the <see cref="Mathf.PosMod(int, int)"/> of this vector's components and `mod`.
/// Returns a vector composed of the <see cref="Mathf.PosMod(int, int)"/> of this vector's components
/// and <paramref name="mod"/>.
/// </summary>
/// <param name="mod">A value representing the divisor of the operation.</param>
/// <returns>A vector with each component <see cref="Mathf.PosMod(int, int)"/> by `mod`.</returns>
/// <returns>
/// A vector with each component <see cref="Mathf.PosMod(int, int)"/> by <paramref name="mod"/>.
/// </returns>
public Vector2i PosMod(int mod)
{
Vector2i v = this;
@ -238,10 +254,13 @@ namespace Godot
}
/// <summary>
/// Returns a vector composed of the <see cref="Mathf.PosMod(int, int)"/> of this vector's components and `modv`'s components.
/// Returns a vector composed of the <see cref="Mathf.PosMod(int, int)"/> of this vector's components
/// and <paramref name="modv"/>'s components.
/// </summary>
/// <param name="modv">A vector representing the divisors of the operation.</param>
/// <returns>A vector with each component <see cref="Mathf.PosMod(int, int)"/> by `modv`'s components.</returns>
/// <returns>
/// A vector with each component <see cref="Mathf.PosMod(int, int)"/> by <paramref name="modv"/>'s components.
/// </returns>
public Vector2i PosMod(Vector2i modv)
{
Vector2i v = this;
@ -255,7 +274,7 @@ namespace Godot
/// on the signs of this vector's components, or zero if the component is zero,
/// by calling <see cref="Mathf.Sign(int)"/> on each component.
/// </summary>
/// <returns>A vector with all components as either `1`, `-1`, or `0`.</returns>
/// <returns>A vector with all components as either <c>1</c>, <c>-1</c>, or <c>0</c>.</returns>
public Vector2i Sign()
{
Vector2i v = this;
@ -284,35 +303,35 @@ namespace Godot
private static readonly Vector2i _left = new Vector2i(-1, 0);
/// <summary>
/// Zero vector, a vector with all components set to `0`.
/// Zero vector, a vector with all components set to <c>0</c>.
/// </summary>
/// <value>Equivalent to `new Vector2i(0, 0)`</value>
/// <value>Equivalent to <c>new Vector2i(0, 0)</c>.</value>
public static Vector2i Zero { get { return _zero; } }
/// <summary>
/// One vector, a vector with all components set to `1`.
/// One vector, a vector with all components set to <c>1</c>.
/// </summary>
/// <value>Equivalent to `new Vector2i(1, 1)`</value>
/// <value>Equivalent to <c>new Vector2i(1, 1)</c>.</value>
public static Vector2i One { get { return _one; } }
/// <summary>
/// Up unit vector. Y is down in 2D, so this vector points -Y.
/// </summary>
/// <value>Equivalent to `new Vector2i(0, -1)`</value>
/// <value>Equivalent to <c>new Vector2i(0, -1)</c>.</value>
public static Vector2i Up { get { return _up; } }
/// <summary>
/// Down unit vector. Y is down in 2D, so this vector points +Y.
/// </summary>
/// <value>Equivalent to `new Vector2i(0, 1)`</value>
/// <value>Equivalent to <c>new Vector2i(0, 1)</c>.</value>
public static Vector2i Down { get { return _down; } }
/// <summary>
/// Right unit vector. Represents the direction of right.
/// </summary>
/// <value>Equivalent to `new Vector2i(1, 0)`</value>
/// <value>Equivalent to <c>new Vector2i(1, 0)</c>.</value>
public static Vector2i Right { get { return _right; } }
/// <summary>
/// Left unit vector. Represents the direction of left.
/// </summary>
/// <value>Equivalent to `new Vector2i(-1, 0)`</value>
/// <value>Equivalent to <c>new Vector2i(-1, 0)</c>.</value>
public static Vector2i Left { get { return _left; } }
/// <summary>
@ -477,16 +496,29 @@ namespace Godot
return left.x >= right.x;
}
/// <summary>
/// Converts this <see cref="Vector2i"/> to a <see cref="Vector2"/>.
/// </summary>
/// <param name="value">The vector to convert.</param>
public static implicit operator Vector2(Vector2i value)
{
return new Vector2(value.x, value.y);
}
/// <summary>
/// Converts a <see cref="Vector2"/> to a <see cref="Vector2i"/>.
/// </summary>
/// <param name="value">The vector to convert.</param>
public static explicit operator Vector2i(Vector2 value)
{
return new Vector2i(value);
}
/// <summary>
/// Returns <see langword="true"/> if this vector and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the vector and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Vector2i)
@ -497,21 +529,38 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this vector and <paramref name="other"/> are equal.
/// </summary>
/// <param name="other">The other vector to compare.</param>
/// <returns>Whether or not the vectors are equal.</returns>
public bool Equals(Vector2i other)
{
return x == other.x && y == other.y;
}
/// <summary>
/// Serves as the hash function for <see cref="Vector2i"/>.
/// </summary>
/// <returns>A hash code for this vector.</returns>
public override int GetHashCode()
{
return y.GetHashCode() ^ x.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Vector2i"/> to a string.
/// </summary>
/// <returns>A string representation of this vector.</returns>
public override string ToString()
{
return $"({x}, {y})";
}
/// <summary>
/// Converts this <see cref="Vector2i"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this vector.</returns>
public string ToString(string format)
{
return $"({x.ToString(format)}, {y.ToString(format)})";

152
modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3.cs
View file

@ -21,30 +21,46 @@ namespace Godot
/// </summary>
public enum Axis
{
/// <summary>
/// The vector's X axis.
/// </summary>
X = 0,
/// <summary>
/// The vector's Y axis.
/// </summary>
Y,
/// <summary>
/// The vector's Z axis.
/// </summary>
Z
}
/// <summary>
/// The vector's X component. Also accessible by using the index position `[0]`.
/// The vector's X component. Also accessible by using the index position <c>[0]</c>.
/// </summary>
public real_t x;
/// <summary>
/// The vector's Y component. Also accessible by using the index position `[1]`.
/// The vector's Y component. Also accessible by using the index position <c>[1]</c>.
/// </summary>
public real_t y;
/// <summary>
/// The vector's Z component. Also accessible by using the index position `[2]`.
/// The vector's Z component. Also accessible by using the index position <c>[2]</c>.
/// </summary>
public real_t z;
/// <summary>
/// Access vector components using their index.
/// </summary>
/// <value>`[0]` is equivalent to `.x`, `[1]` is equivalent to `.y`, `[2]` is equivalent to `.z`.</value>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when the given the <paramref name="index"/> is not 0, 1 or 2.
/// </exception>
/// <value>
/// <c>[0]</c> is equivalent to <see cref="x"/>,
/// <c>[1]</c> is equivalent to <see cref="y"/>,
/// <c>[2]</c> is equivalent to <see cref="z"/>.
/// </value>
public real_t this[int index]
{
get
@ -137,7 +153,7 @@ namespace Godot
/// <summary>
/// Returns a new vector with all components clamped between the
/// components of `min` and `max` using
/// components of <paramref name="min"/> and <paramref name="max"/> using
/// <see cref="Mathf.Clamp(real_t, real_t, real_t)"/>.
/// </summary>
/// <param name="min">The vector with minimum allowed values.</param>
@ -154,7 +170,7 @@ namespace Godot
}
/// <summary>
/// Returns the cross product of this vector and `b`.
/// Returns the cross product of this vector and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector.</param>
/// <returns>The cross product vector.</returns>
@ -169,12 +185,12 @@ namespace Godot
}
/// <summary>
/// Performs a cubic interpolation between vectors `preA`, this vector,
/// `b`, and `postB`, by the given amount `t`.
/// Performs a cubic interpolation between vectors <paramref name="preA"/>, this vector,
/// <paramref name="b"/>, and <paramref name="postB"/>, by the given amount <paramref name="weight"/>.
/// </summary>
/// <param name="b">The destination vector.</param>
/// <param name="preA">A vector before this vector.</param>
/// <param name="postB">A vector after `b`.</param>
/// <param name="postB">A vector after <paramref name="b"/>.</param>
/// <param name="weight">A value on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
/// <returns>The interpolated vector.</returns>
public Vector3 CubicInterpolate(Vector3 b, Vector3 preA, Vector3 postB, real_t weight)
@ -196,17 +212,17 @@ namespace Godot
}
/// <summary>
/// Returns the normalized vector pointing from this vector to `b`.
/// Returns the normalized vector pointing from this vector to <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector to point towards.</param>
/// <returns>The direction from this vector to `b`.</returns>
/// <returns>The direction from this vector to <paramref name="b"/>.</returns>
public Vector3 DirectionTo(Vector3 b)
{
return new Vector3(b.x - x, b.y - y, b.z - z).Normalized();
}
/// <summary>
/// Returns the squared distance between this vector and `b`.
/// Returns the squared distance between this vector and <paramref name="b"/>.
/// This method runs faster than <see cref="DistanceTo"/>, so prefer it if
/// you need to compare vectors or need the squared distance for some formula.
/// </summary>
@ -218,8 +234,9 @@ namespace Godot
}
/// <summary>
/// Returns the distance between this vector and `b`.
/// Returns the distance between this vector and <paramref name="b"/>.
/// </summary>
/// <seealso cref="DistanceSquaredTo(Vector3)"/>
/// <param name="b">The other vector to use.</param>
/// <returns>The distance between the two vectors.</returns>
public real_t DistanceTo(Vector3 b)
@ -228,7 +245,7 @@ namespace Godot
}
/// <summary>
/// Returns the dot product of this vector and `b`.
/// Returns the dot product of this vector and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector to use.</param>
/// <returns>The dot product of the two vectors.</returns>
@ -247,7 +264,7 @@ namespace Godot
}
/// <summary>
/// Returns the inverse of this vector. This is the same as `new Vector3(1 / v.x, 1 / v.y, 1 / v.z)`.
/// Returns the inverse of this vector. This is the same as <c>new Vector3(1 / v.x, 1 / v.y, 1 / v.z)</c>.
/// </summary>
/// <returns>The inverse of this vector.</returns>
public Vector3 Inverse()
@ -256,9 +273,9 @@ namespace Godot
}
/// <summary>
/// Returns true if the vector is normalized, and false otherwise.
/// Returns <see langword="true"/> if the vector is normalized, and <see langword="false"/> otherwise.
/// </summary>
/// <returns>A bool indicating whether or not the vector is normalized.</returns>
/// <returns>A <see langword="bool"/> indicating whether or not the vector is normalized.</returns>
public bool IsNormalized()
{
return Mathf.Abs(LengthSquared() - 1.0f) < Mathf.Epsilon;
@ -267,6 +284,7 @@ namespace Godot
/// <summary>
/// Returns the length (magnitude) of this vector.
/// </summary>
/// <seealso cref="LengthSquared"/>
/// <returns>The length of this vector.</returns>
public real_t Length()
{
@ -294,7 +312,7 @@ namespace Godot
/// <summary>
/// Returns the result of the linear interpolation between
/// this vector and `to` by amount `weight`.
/// this vector and <paramref name="to"/> by amount <paramref name="weight"/>.
/// </summary>
/// <param name="to">The destination vector for interpolation.</param>
/// <param name="weight">A value on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
@ -311,7 +329,7 @@ namespace Godot
/// <summary>
/// Returns the result of the linear interpolation between
/// this vector and `to` by the vector amount `weight`.
/// this vector and <paramref name="to"/> by the vector amount <paramref name="weight"/>.
/// </summary>
/// <param name="to">The destination vector for interpolation.</param>
/// <param name="weight">A vector with components on the range of 0.0 to 1.0, representing the amount of interpolation.</param>
@ -327,7 +345,7 @@ namespace Godot
}
/// <summary>
/// Returns the vector with a maximum length by limiting its length to `length`.
/// Returns the vector with a maximum length by limiting its length to <paramref name="length"/>.
/// </summary>
/// <param name="length">The length to limit to.</param>
/// <returns>The vector with its length limited.</returns>
@ -366,7 +384,7 @@ namespace Godot
}
/// <summary>
/// Moves this vector toward `to` by the fixed `delta` amount.
/// Moves this vector toward <paramref name="to"/> by the fixed <paramref name="delta"/> amount.
/// </summary>
/// <param name="to">The vector to move towards.</param>
/// <param name="delta">The amount to move towards by.</param>
@ -383,7 +401,7 @@ namespace Godot
}
/// <summary>
/// Returns the vector scaled to unit length. Equivalent to `v / v.Length()`.
/// Returns the vector scaled to unit length. Equivalent to <c>v / v.Length()</c>.
/// </summary>
/// <returns>A normalized version of the vector.</returns>
public Vector3 Normalized()
@ -394,7 +412,7 @@ namespace Godot
}
/// <summary>
/// Returns the outer product with `b`.
/// Returns the outer product with <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector.</param>
/// <returns>A <see cref="Basis"/> representing the outer product matrix.</returns>
@ -408,10 +426,13 @@ namespace Godot
}
/// <summary>
/// Returns a vector composed of the <see cref="Mathf.PosMod(real_t, real_t)"/> of this vector's components and `mod`.
/// Returns a vector composed of the <see cref="Mathf.PosMod(real_t, real_t)"/> of this vector's components
/// and <paramref name="mod"/>.
/// </summary>
/// <param name="mod">A value representing the divisor of the operation.</param>
/// <returns>A vector with each component <see cref="Mathf.PosMod(real_t, real_t)"/> by `mod`.</returns>
/// <returns>
/// A vector with each component <see cref="Mathf.PosMod(real_t, real_t)"/> by <paramref name="mod"/>.
/// </returns>
public Vector3 PosMod(real_t mod)
{
Vector3 v;
@ -422,10 +443,13 @@ namespace Godot
}
/// <summary>
/// Returns a vector composed of the <see cref="Mathf.PosMod(real_t, real_t)"/> of this vector's components and `modv`'s components.
/// Returns a vector composed of the <see cref="Mathf.PosMod(real_t, real_t)"/> of this vector's components
/// and <paramref name="modv"/>'s components.
/// </summary>
/// <param name="modv">A vector representing the divisors of the operation.</param>
/// <returns>A vector with each component <see cref="Mathf.PosMod(real_t, real_t)"/> by `modv`'s components.</returns>
/// <returns>
/// A vector with each component <see cref="Mathf.PosMod(real_t, real_t)"/> by <paramref name="modv"/>'s components.
/// </returns>
public Vector3 PosMod(Vector3 modv)
{
Vector3 v;
@ -436,7 +460,7 @@ namespace Godot
}
/// <summary>
/// Returns this vector projected onto another vector `b`.
/// Returns this vector projected onto another vector <paramref name="onNormal"/>.
/// </summary>
/// <param name="onNormal">The vector to project onto.</param>
/// <returns>The projected vector.</returns>
@ -446,7 +470,7 @@ namespace Godot
}
/// <summary>
/// Returns this vector reflected from a plane defined by the given `normal`.
/// Returns this vector reflected from a plane defined by the given <paramref name="normal"/>.
/// </summary>
/// <param name="normal">The normal vector defining the plane to reflect from. Must be normalized.</param>
/// <returns>The reflected vector.</returns>
@ -462,8 +486,8 @@ namespace Godot
}
/// <summary>
/// Rotates this vector around a given `axis` vector by `phi` radians.
/// The `axis` vector must be a normalized vector.
/// Rotates this vector around a given <paramref name="axis"/> vector by <paramref name="phi"/> radians.
/// The <paramref name="axis"/> vector must be a normalized vector.
/// </summary>
/// <param name="axis">The vector to rotate around. Must be normalized.</param>
/// <param name="phi">The angle to rotate by, in radians.</param>
@ -494,7 +518,7 @@ namespace Godot
/// on the signs of this vector's components, or zero if the component is zero,
/// by calling <see cref="Mathf.Sign(real_t)"/> on each component.
/// </summary>
/// <returns>A vector with all components as either `1`, `-1`, or `0`.</returns>
/// <returns>A vector with all components as either <c>1</c>, <c>-1</c>, or <c>0</c>.</returns>
public Vector3 Sign()
{
Vector3 v;
@ -508,7 +532,7 @@ namespace Godot
/// Returns the signed angle to the given vector, in radians.
/// The sign of the angle is positive in a counter-clockwise
/// direction and negative in a clockwise direction when viewed
/// from the side specified by the `axis`.
/// from the side specified by the <paramref name="axis"/>.
/// </summary>
/// <param name="to">The other vector to compare this vector to.</param>
/// <param name="axis">The reference axis to use for the angle sign.</param>
@ -523,7 +547,7 @@ namespace Godot
/// <summary>
/// Returns the result of the spherical linear interpolation between
/// this vector and `to` by amount `weight`.
/// this vector and <paramref name="to"/> by amount <paramref name="weight"/>.
///
/// Note: Both vectors must be normalized.
/// </summary>
@ -539,7 +563,7 @@ namespace Godot
}
if (!to.IsNormalized())
{
throw new InvalidOperationException("Vector3.Slerp: `to` is not normalized.");
throw new InvalidOperationException($"Vector3.Slerp: `{nameof(to)}` is not normalized.");
}
#endif
real_t theta = AngleTo(to);
@ -547,7 +571,7 @@ namespace Godot
}
/// <summary>
/// Returns this vector slid along a plane defined by the given normal.
/// Returns this vector slid along a plane defined by the given <paramref name="normal"/>.
/// </summary>
/// <param name="normal">The normal vector defining the plane to slide on.</param>
/// <returns>The slid vector.</returns>
@ -557,7 +581,7 @@ namespace Godot
}
/// <summary>
/// Returns this vector with each component snapped to the nearest multiple of `step`.
/// Returns this vector with each component snapped to the nearest multiple of <paramref name="step"/>.
/// This can also be used to round to an arbitrary number of decimals.
/// </summary>
/// <param name="step">A vector value representing the step size to snap to.</param>
@ -575,10 +599,10 @@ namespace Godot
/// <summary>
/// Returns a diagonal matrix with the vector as main diagonal.
///
/// This is equivalent to a Basis with no rotation or shearing and
/// This is equivalent to a <see cref="Basis"/> with no rotation or shearing and
/// this vector's components set as the scale.
/// </summary>
/// <returns>A Basis with the vector as its main diagonal.</returns>
/// <returns>A <see cref="Basis"/> with the vector as its main diagonal.</returns>
public Basis ToDiagonalMatrix()
{
return new Basis(
@ -601,54 +625,54 @@ namespace Godot
private static readonly Vector3 _back = new Vector3(0, 0, 1);
/// <summary>
/// Zero vector, a vector with all components set to `0`.
/// Zero vector, a vector with all components set to <c>0</c>.
/// </summary>
/// <value>Equivalent to `new Vector3(0, 0, 0)`</value>
/// <value>Equivalent to <c>new Vector3(0, 0, 0)</c>.</value>
public static Vector3 Zero { get { return _zero; } }
/// <summary>
/// One vector, a vector with all components set to `1`.
/// One vector, a vector with all components set to <c>1</c>.
/// </summary>
/// <value>Equivalent to `new Vector3(1, 1, 1)`</value>
/// <value>Equivalent to <c>new Vector3(1, 1, 1)</c>.</value>
public static Vector3 One { get { return _one; } }
/// <summary>
/// Infinity vector, a vector with all components set to `Mathf.Inf`.
/// Infinity vector, a vector with all components set to <see cref="Mathf.Inf"/>.
/// </summary>
/// <value>Equivalent to `new Vector3(Mathf.Inf, Mathf.Inf, Mathf.Inf)`</value>
/// <value>Equivalent to <c>new Vector3(Mathf.Inf, Mathf.Inf, Mathf.Inf)</c>.</value>
public static Vector3 Inf { get { return _inf; } }
/// <summary>
/// Up unit vector.
/// </summary>
/// <value>Equivalent to `new Vector3(0, 1, 0)`</value>
/// <value>Equivalent to <c>new Vector3(0, 1, 0)</c>.</value>
public static Vector3 Up { get { return _up; } }
/// <summary>
/// Down unit vector.
/// </summary>
/// <value>Equivalent to `new Vector3(0, -1, 0)`</value>
/// <value>Equivalent to <c>new Vector3(0, -1, 0)</c>.</value>
public static Vector3 Down { get { return _down; } }
/// <summary>
/// Right unit vector. Represents the local direction of right,
/// and the global direction of east.
/// </summary>
/// <value>Equivalent to `new Vector3(1, 0, 0)`</value>
/// <value>Equivalent to <c>new Vector3(1, 0, 0)</c>.</value>
public static Vector3 Right { get { return _right; } }
/// <summary>
/// Left unit vector. Represents the local direction of left,
/// and the global direction of west.
/// </summary>
/// <value>Equivalent to `new Vector3(-1, 0, 0)`</value>
/// <value>Equivalent to <c>new Vector3(-1, 0, 0)</c>.</value>
public static Vector3 Left { get { return _left; } }
/// <summary>
/// Forward unit vector. Represents the local direction of forward,
/// and the global direction of north.
/// </summary>
/// <value>Equivalent to `new Vector3(0, 0, -1)`</value>
/// <value>Equivalent to <c>new Vector3(0, 0, -1)</c>.</value>
public static Vector3 Forward { get { return _forward; } }
/// <summary>
/// Back unit vector. Represents the local direction of back,
/// and the global direction of south.
/// </summary>
/// <value>Equivalent to `new Vector3(0, 0, 1)`</value>
/// <value>Equivalent to <c>new Vector3(0, 0, 1)</c>.</value>
public static Vector3 Back { get { return _back; } }
/// <summary>
@ -817,6 +841,11 @@ namespace Godot
return left.x > right.x;
}
/// <summary>
/// Returns <see langword="true"/> if this vector and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the vector and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Vector3)
@ -827,14 +856,19 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this vector and <paramref name="other"/> are equal
/// </summary>
/// <param name="other">The other vector to compare.</param>
/// <returns>Whether or not the vectors are equal.</returns>
public bool Equals(Vector3 other)
{
return x == other.x && y == other.y && z == other.z;
}
/// <summary>
/// Returns true if this vector and `other` are approximately equal, by running
/// <see cref="Mathf.IsEqualApprox(real_t, real_t)"/> on each component.
/// Returns <see langword="true"/> if this vector and <paramref name="other"/> are approximately equal,
/// by running <see cref="Mathf.IsEqualApprox(real_t, real_t)"/> on each component.
/// </summary>
/// <param name="other">The other vector to compare.</param>
/// <returns>Whether or not the vectors are approximately equal.</returns>
@ -843,16 +877,28 @@ namespace Godot
return Mathf.IsEqualApprox(x, other.x) && Mathf.IsEqualApprox(y, other.y) && Mathf.IsEqualApprox(z, other.z);
}
/// <summary>
/// Serves as the hash function for <see cref="Vector3"/>.
/// </summary>
/// <returns>A hash code for this vector.</returns>
public override int GetHashCode()
{
return y.GetHashCode() ^ x.GetHashCode() ^ z.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Vector3"/> to a string.
/// </summary>
/// <returns>A string representation of this vector.</returns>
public override string ToString()
{
return $"({x}, {y}, {z})";
}
/// <summary>
/// Converts this <see cref="Vector3"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this vector.</returns>
public string ToString(string format)
{
return $"({x.ToString(format)}, {y.ToString(format)}, {z.ToString(format)})";

102
modules/mono/glue/GodotSharp/GodotSharp/Core/Vector3i.cs
View file

@ -21,30 +21,46 @@ namespace Godot
/// </summary>
public enum Axis
{
/// <summary>
/// The vector's X axis.
/// </summary>
X = 0,
/// <summary>
/// The vector's Y axis.
/// </summary>
Y,
/// <summary>
/// The vector's Z axis.
/// </summary>
Z
}
/// <summary>
/// The vector's X component. Also accessible by using the index position `[0]`.
/// The vector's X component. Also accessible by using the index position <c>[0]</c>.
/// </summary>
public int x;
/// <summary>
/// The vector's Y component. Also accessible by using the index position `[1]`.
/// The vector's Y component. Also accessible by using the index position <c>[1]</c>.
/// </summary>
public int y;
/// <summary>
/// The vector's Z component. Also accessible by using the index position `[2]`.
/// The vector's Z component. Also accessible by using the index position <c>[2]</c>.
/// </summary>
public int z;
/// <summary>
/// Access vector components using their index.
/// Access vector components using their <paramref name="index"/>.
/// </summary>
/// <value>`[0]` is equivalent to `.x`, `[1]` is equivalent to `.y`, `[2]` is equivalent to `.z`.</value>
/// <exception cref="IndexOutOfRangeException">
/// Thrown when the given the <paramref name="index"/> is not 0, 1 or 2.
/// </exception>
/// <value>
/// <c>[0]</c> is equivalent to <see cref="x"/>,
/// <c>[1]</c> is equivalent to <see cref="y"/>,
/// <c>[2]</c> is equivalent to <see cref="z"/>.
/// </value>
public int this[int index]
{
get
@ -91,7 +107,7 @@ namespace Godot
/// <summary>
/// Returns a new vector with all components clamped between the
/// components of `min` and `max` using
/// components of <paramref name="min"/> and <paramref name="max"/> using
/// <see cref="Mathf.Clamp(int, int, int)"/>.
/// </summary>
/// <param name="min">The vector with minimum allowed values.</param>
@ -108,7 +124,7 @@ namespace Godot
}
/// <summary>
/// Returns the squared distance between this vector and `b`.
/// Returns the squared distance between this vector and <paramref name="b"/>.
/// This method runs faster than <see cref="DistanceTo"/>, so prefer it if
/// you need to compare vectors or need the squared distance for some formula.
/// </summary>
@ -120,8 +136,9 @@ namespace Godot
}
/// <summary>
/// Returns the distance between this vector and `b`.
/// Returns the distance between this vector and <paramref name="b"/>.
/// </summary>
/// <seealso cref="DistanceSquaredTo(Vector3i)"/>
/// <param name="b">The other vector to use.</param>
/// <returns>The distance between the two vectors.</returns>
public real_t DistanceTo(Vector3i b)
@ -130,7 +147,7 @@ namespace Godot
}
/// <summary>
/// Returns the dot product of this vector and `b`.
/// Returns the dot product of this vector and <paramref name="b"/>.
/// </summary>
/// <param name="b">The other vector to use.</param>
/// <returns>The dot product of the two vectors.</returns>
@ -142,6 +159,7 @@ namespace Godot
/// <summary>
/// Returns the length (magnitude) of this vector.
/// </summary>
/// <seealso cref="LengthSquared"/>
/// <returns>The length of this vector.</returns>
public real_t Length()
{
@ -188,10 +206,13 @@ namespace Godot
}
/// <summary>
/// Returns a vector composed of the <see cref="Mathf.PosMod(int, int)"/> of this vector's components and `mod`.
/// Returns a vector composed of the <see cref="Mathf.PosMod(int, int)"/> of this vector's components
/// and <paramref name="mod"/>.
/// </summary>
/// <param name="mod">A value representing the divisor of the operation.</param>
/// <returns>A vector with each component <see cref="Mathf.PosMod(int, int)"/> by `mod`.</returns>
/// <returns>
/// A vector with each component <see cref="Mathf.PosMod(int, int)"/> by <paramref name="mod"/>.
/// </returns>
public Vector3i PosMod(int mod)
{
Vector3i v = this;
@ -202,10 +223,13 @@ namespace Godot
}
/// <summary>
/// Returns a vector composed of the <see cref="Mathf.PosMod(int, int)"/> of this vector's components and `modv`'s components.
/// Returns a vector composed of the <see cref="Mathf.PosMod(int, int)"/> of this vector's components
/// and <paramref name="modv"/>'s components.
/// </summary>
/// <param name="modv">A vector representing the divisors of the operation.</param>
/// <returns>A vector with each component <see cref="Mathf.PosMod(int, int)"/> by `modv`'s components.</returns>
/// <returns>
/// A vector with each component <see cref="Mathf.PosMod(int, int)"/> by <paramref name="modv"/>'s components.
/// </returns>
public Vector3i PosMod(Vector3i modv)
{
Vector3i v = this;
@ -220,7 +244,7 @@ namespace Godot
/// on the signs of this vector's components, or zero if the component is zero,
/// by calling <see cref="Mathf.Sign(int)"/> on each component.
/// </summary>
/// <returns>A vector with all components as either `1`, `-1`, or `0`.</returns>
/// <returns>A vector with all components as either <c>1</c>, <c>-1</c>, or <c>0</c>.</returns>
public Vector3i Sign()
{
Vector3i v = this;
@ -242,49 +266,49 @@ namespace Godot
private static readonly Vector3i _back = new Vector3i(0, 0, 1);
/// <summary>
/// Zero vector, a vector with all components set to `0`.
/// Zero vector, a vector with all components set to <c>0</c>.
/// </summary>
/// <value>Equivalent to `new Vector3i(0, 0, 0)`</value>
/// <value>Equivalent to <c>new Vector3i(0, 0, 0)</c>.</value>
public static Vector3i Zero { get { return _zero; } }
/// <summary>
/// One vector, a vector with all components set to `1`.
/// One vector, a vector with all components set to <c>1</c>.
/// </summary>
/// <value>Equivalent to `new Vector3i(1, 1, 1)`</value>
/// <value>Equivalent to <c>new Vector3i(1, 1, 1)</c>.</value>
public static Vector3i One { get { return _one; } }
/// <summary>
/// Up unit vector.
/// </summary>
/// <value>Equivalent to `new Vector3i(0, 1, 0)`</value>
/// <value>Equivalent to <c>new Vector3i(0, 1, 0)</c>.</value>
public static Vector3i Up { get { return _up; } }
/// <summary>
/// Down unit vector.
/// </summary>
/// <value>Equivalent to `new Vector3i(0, -1, 0)`</value>
/// <value>Equivalent to <c>new Vector3i(0, -1, 0)</c>.</value>
public static Vector3i Down { get { return _down; } }
/// <summary>
/// Right unit vector. Represents the local direction of right,
/// and the global direction of east.
/// </summary>
/// <value>Equivalent to `new Vector3i(1, 0, 0)`</value>
/// <value>Equivalent to <c>new Vector3i(1, 0, 0)</c>.</value>
public static Vector3i Right { get { return _right; } }
/// <summary>
/// Left unit vector. Represents the local direction of left,
/// and the global direction of west.
/// </summary>
/// <value>Equivalent to `new Vector3i(-1, 0, 0)`</value>
/// <value>Equivalent to <c>new Vector3i(-1, 0, 0)</c>.</value>
public static Vector3i Left { get { return _left; } }
/// <summary>
/// Forward unit vector. Represents the local direction of forward,
/// and the global direction of north.
/// </summary>
/// <value>Equivalent to `new Vector3i(0, 0, -1)`</value>
/// <value>Equivalent to <c>new Vector3i(0, 0, -1)</c>.</value>
public static Vector3i Forward { get { return _forward; } }
/// <summary>
/// Back unit vector. Represents the local direction of back,
/// and the global direction of south.
/// </summary>
/// <value>Equivalent to `new Vector3i(0, 0, 1)`</value>
/// <value>Equivalent to <c>new Vector3i(0, 0, 1)</c>.</value>
public static Vector3i Back { get { return _back; } }
/// <summary>
@ -481,16 +505,29 @@ namespace Godot
return left.x > right.x;
}
/// <summary>
/// Converts this <see cref="Vector3i"/> to a <see cref="Vector3"/>.
/// </summary>
/// <param name="value">The vector to convert.</param>
public static implicit operator Vector3(Vector3i value)
{
return new Vector3(value.x, value.y, value.z);
}
/// <summary>
/// Converts a <see cref="Vector3"/> to a <see cref="Vector3i"/>.
/// </summary>
/// <param name="value">The vector to convert.</param>
public static explicit operator Vector3i(Vector3 value)
{
return new Vector3i(value);
}
/// <summary>
/// Returns <see langword="true"/> if this vector and <paramref name="obj"/> are equal.
/// </summary>
/// <param name="obj">The other object to compare.</param>
/// <returns>Whether or not the vector and the other object are equal.</returns>
public override bool Equals(object obj)
{
if (obj is Vector3i)
@ -501,21 +538,38 @@ namespace Godot
return false;
}
/// <summary>
/// Returns <see langword="true"/> if this vector and <paramref name="other"/> are equal
/// </summary>
/// <param name="other">The other vector to compare.</param>
/// <returns>Whether or not the vectors are equal.</returns>
public bool Equals(Vector3i other)
{
return x == other.x && y == other.y && z == other.z;
}
/// <summary>
/// Serves as the hash function for <see cref="Vector3i"/>.
/// </summary>
/// <returns>A hash code for this vector.</returns>
public override int GetHashCode()
{
return y.GetHashCode() ^ x.GetHashCode() ^ z.GetHashCode();
}
/// <summary>
/// Converts this <see cref="Vector3i"/> to a string.
/// </summary>
/// <returns>A string representation of this vector.</returns>
public override string ToString()
{
return $"({x}, {y}, {z})";
}
/// <summary>
/// Converts this <see cref="Vector3i"/> to a string with the given <paramref name="format"/>.
/// </summary>
/// <returns>A string representation of this vector.</returns>
public string ToString(string format)
{
return $"({x.ToString(format)}, {y.ToString(format)}, {z.ToString(format)})";