Package com.badlogic.gdx.math
Class MathUtils
- java.lang.Object
-
- com.badlogic.gdx.math.MathUtils
-
public final class MathUtils extends java.lang.Object
Utility and fast math functions.Thanks to Riven on JavaGaming.org for the basis of sin/cos/floor/ceil.
-
-
Field Summary
Fields Modifier and Type Field Description static float
degRad
static float
degreesToRadians
multiply by this to convert from degrees to radiansstatic float
E
static float
FLOAT_ROUNDING_ERROR
static float
HALF_PI
static float
nanoToSec
static float
PI
static float
PI2
static float
radDeg
static float
radiansToDegrees
multiply by this to convert from radians to degreesstatic java.util.Random
random
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static float
acos(float a)
Returns acos in radians; less accurate than Math.acos but may be faster.static float
acosDeg(float a)
Returns arccosine in degrees.static float
asin(float a)
Returns asin in radians; less accurate than Math.asin but may be faster.static float
asinDeg(float a)
Returns arcsine in degrees.static float
atan(float i)
Arc tangent approximation with very low error, using an algorithm from the 1955 research study "Approximations for Digital Computers," by RAND Corporation (this is sheet 11's algorithm, which is the fourth-fastest and fourth-least precise).static float
atan2(float y, float x)
Close approximation of the frequently-used trigonometric method atan2.static float
atan2Deg(float y, float x)
Close approximation of the frequently-used trigonometric method atan2, using positive or negative degrees.static float
atan2Deg360(float y, float x)
Close approximation of the frequently-used trigonometric method atan2, using non-negative degrees only.static float
atanDeg(float i)
Arc tangent approximation returning a value measured in positive or negative degrees, using an algorithm from the 1955 research study "Approximations for Digital Computers," by RAND Corporation (this is sheet 11's algorithm, which is the fourth-fastest and fourth-least precise).static float
atanUnchecked(double i)
A variant onatan(float)
that does not tolerate infinite inputs for speed reasons.static double
atanUncheckedDeg(double i)
A variant onatanDeg(float)
that does not tolerate infinite inputs for speed reasons.static int
ceil(float value)
Returns the smallest integer greater than or equal to the specified float.static int
ceilPositive(float value)
Returns the smallest integer greater than or equal to the specified float.static double
clamp(double value, double min, double max)
static float
clamp(float value, float min, float max)
static int
clamp(int value, int min, int max)
static long
clamp(long value, long min, long max)
static short
clamp(short value, short min, short max)
static float
cos(float radians)
Returns the cosine in radians from a lookup table.static float
cosDeg(float degrees)
Returns the cosine in degrees from a lookup table.static int
floor(float value)
Returns the largest integer less than or equal to the specified float.static int
floorPositive(float value)
Returns the largest integer less than or equal to the specified float.static boolean
isEqual(float a, float b)
Returns true if a is nearly equal to b.static boolean
isEqual(float a, float b, float tolerance)
Returns true if a is nearly equal to b.static boolean
isPowerOfTwo(int value)
static boolean
isZero(float value)
Returns true if the value is zero (using the default tolerance as upper bound)static boolean
isZero(float value, float tolerance)
Returns true if the value is zero.static float
lerp(float fromValue, float toValue, float progress)
Linearly interpolates between fromValue to toValue on progress position.static float
lerpAngle(float fromRadians, float toRadians, float progress)
Linearly interpolates between two angles in radians.static float
lerpAngleDeg(float fromDegrees, float toDegrees, float progress)
Linearly interpolates between two angles in degrees.static float
log(float a, float value)
static float
log2(float value)
static float
map(float inRangeStart, float inRangeEnd, float outRangeStart, float outRangeEnd, float value)
Linearly map a value from one range to another.static int
nextPowerOfTwo(int value)
Returns the next power of two.static float
norm(float rangeStart, float rangeEnd, float value)
Linearly normalizes value from a range.static float
random()
Returns random number between 0.0 (inclusive) and 1.0 (exclusive).static float
random(float range)
Returns a random number between 0 (inclusive) and the specified value (exclusive).static float
random(float start, float end)
Returns a random number between start (inclusive) and end (exclusive).static int
random(int range)
Returns a random number between 0 (inclusive) and the specified value (inclusive).static int
random(int start, int end)
Returns a random number between start (inclusive) and end (inclusive).static long
random(long range)
Returns a random number between 0 (inclusive) and the specified value (inclusive).static long
random(long start, long end)
Returns a random number between start (inclusive) and end (inclusive).static boolean
randomBoolean()
Returns a random boolean value.static boolean
randomBoolean(float chance)
Returns true if a random value between 0 and 1 is less than the specified value.static int
randomSign()
Returns -1 or 1, randomly.static float
randomTriangular()
Returns a triangularly distributed random number between -1.0 (exclusive) and 1.0 (exclusive), where values around zero are more likely.static float
randomTriangular(float max)
Returns a triangularly distributed random number between-max
(exclusive) andmax
(exclusive), where values around zero are more likely.static float
randomTriangular(float min, float max)
Returns a triangularly distributed random number betweenmin
(inclusive) andmax
(exclusive), where themode
argument defaults to the midpoint between the bounds, giving a symmetric distribution.static float
randomTriangular(float min, float max, float mode)
Returns a triangularly distributed random number betweenmin
(inclusive) andmax
(exclusive), where values aroundmode
are more likely.static int
round(float value)
Returns the closest integer to the specified float.static int
roundPositive(float value)
Returns the closest integer to the specified float.static float
sin(float radians)
Returns the sine in radians from a lookup table.static float
sinDeg(float degrees)
Returns the sine in degrees from a lookup table.static float
tan(float radians)
Returns the tangent given an input in radians, using a Padé approximant.static float
tanDeg(float degrees)
Returns the tangent given an input in degrees, using a Padé approximant.
-
-
-
Field Detail
-
nanoToSec
public static final float nanoToSec
- See Also:
- Constant Field Values
-
FLOAT_ROUNDING_ERROR
public static final float FLOAT_ROUNDING_ERROR
- See Also:
- Constant Field Values
-
PI
public static final float PI
- See Also:
- Constant Field Values
-
PI2
public static final float PI2
- See Also:
- Constant Field Values
-
HALF_PI
public static final float HALF_PI
- See Also:
- Constant Field Values
-
E
public static final float E
- See Also:
- Constant Field Values
-
radiansToDegrees
public static final float radiansToDegrees
multiply by this to convert from radians to degrees- See Also:
- Constant Field Values
-
radDeg
public static final float radDeg
- See Also:
- Constant Field Values
-
degreesToRadians
public static final float degreesToRadians
multiply by this to convert from degrees to radians- See Also:
- Constant Field Values
-
degRad
public static final float degRad
- See Also:
- Constant Field Values
-
random
public static java.util.Random random
-
-
Method Detail
-
sin
public static float sin(float radians)
Returns the sine in radians from a lookup table. For optimal precision, use radians between -PI2 and PI2 (both inclusive).
-
cos
public static float cos(float radians)
Returns the cosine in radians from a lookup table. For optimal precision, use radians between -PI2 and PI2 (both inclusive).
-
sinDeg
public static float sinDeg(float degrees)
Returns the sine in degrees from a lookup table. For optimal precision, use degrees between -360 and 360 (both inclusive).
-
cosDeg
public static float cosDeg(float degrees)
Returns the cosine in degrees from a lookup table. For optimal precision, use degrees between -360 and 360 (both inclusive).
-
tan
public static float tan(float radians)
Returns the tangent given an input in radians, using a Padé approximant.
Padé approximants tend to be most accurate when they aren't producing results of extreme magnitude; in the tan() function, those results occur on and near odd multiples ofPI/2
, and this method is least accurate when given inputs near those multiples.
For inputs between -1.57 to 1.57 (just inside half-pi), separated by 0x1p-20f, absolute error is 0.00890192, relative error is 0.00000090, and the maximum error is 17.98901367 when given 1.56999838. The maximum error might seem concerning, but it's the difference between the correct 1253.22167969 and the 1235.23266602 this returns, so for many purposes the difference won't be noticeable.
For inputs between -1.55 to 1.55 (getting less close to half-pi), separated by 0x1p-20f, absolute error is 0.00023368, relative error is -0.00000009, and the maximum error is 0.02355957 when given -1.54996467. The maximum error is the difference between the correct -47.99691010 and the -47.97335052 this returns.
While you don't have to use a dedicated method for tan(), and you can usesin(x)/cos(x)
, approximating tan() in that way is very susceptible to error building up from any of sin(), cos() or the division. Where this tan() has a maximum error in the -1.55 to 1.55 range of 0.02355957, that simpler division technique on the same range has a maximum error of 1.25724030 (about 50 times worse), as well as larger absolute and relative errors. Casting the double result ofMath.tan(double)
to float will get the highest precision, but can be anywhere from 2.5x to nearly 4x slower than this, depending on JVM.
Based on this Stack Exchange answer by Soonts.- Parameters:
radians
- a float angle in radians, where 0 toPI2
is one rotation- Returns:
- a float approximation of tan()
-
tanDeg
public static float tanDeg(float degrees)
Returns the tangent given an input in degrees, using a Padé approximant. Based on this Stack Exchange answer.- Parameters:
degrees
- an angle in degrees, where 0 to 360 is one rotation- Returns:
- a float approximation of tan()
-
atanUnchecked
public static float atanUnchecked(double i)
A variant onatan(float)
that does not tolerate infinite inputs for speed reasons. This can be given a double parameter, but is otherwise the same as atan(float), and returns a float like that method. It uses the same approximation, from sheet 11 of "Approximations for Digital Computers." This is mostly meant to be used insideatan2(float, float)
, but it may be a tiny bit faster than atan(float) in other code.- Parameters:
i
- any finite double or float, but more commonly a float- Returns:
- an output from the inverse tangent function, from
-HALF_PI
toHALF_PI
inclusive
-
atan2
public static float atan2(float y, float x)
Close approximation of the frequently-used trigonometric method atan2. Average error is 1.057E-6 radians; maximum error is 1.922E-6. Takes y and x (in that unusual order) as floats, and returns the angle from the origin to that point in radians. It is about 4 times faster thanMath.atan2(double, double)
(roughly 15 ns instead of roughly 60 ns for Math, on Java 8 HotSpot).
Credit for this goes to the 1955 research study "Approximations for Digital Computers," by RAND Corporation. This is sheet 11's algorithm, which is the fourth-fastest and fourth-least precise. The algorithms on sheets 8-10 are faster, but only by a very small degree, and are considerably less precise. That study provides anatan(float)
method, and that cleanly translates to atan2().- Parameters:
y
- y-component of the point to find the angle towards; note the parameter order is unusual by conventionx
- x-component of the point to find the angle towards; note the parameter order is unusual by convention- Returns:
- the angle to the given point, in radians as a float; ranges from
-PI
toPI
-
atanUncheckedDeg
public static double atanUncheckedDeg(double i)
A variant onatanDeg(float)
that does not tolerate infinite inputs for speed reasons. This can be given a double parameter, but is otherwise the same as atanDeg(float), and returns a float like that method. It uses the same approximation, from sheet 11 of "Approximations for Digital Computers." This is mostly meant to be used insideatan2(float, float)
, but it may be a tiny bit faster than atanDeg(float) in other code.- Parameters:
i
- any finite double or float, but more commonly a float- Returns:
- an output from the inverse tangent function in degrees, from
-90
to90
inclusive
-
atan2Deg
public static float atan2Deg(float y, float x)
Close approximation of the frequently-used trigonometric method atan2, using positive or negative degrees. Average absolute error is 0.00006037 degrees; relative error is 0 degrees, maximum error is 0.00010396 degrees. Takes y and x (in that unusual order) as floats, and returns the angle from the origin to that point in degrees.
Credit for this goes to the 1955 research study "Approximations for Digital Computers," by RAND Corporation. This is sheet 11's algorithm, which is the fourth-fastest and fourth-least precise. The algorithms on sheets 8-10 are faster, but only by a very small degree, and are considerably less precise. That study provides anatan(float)
method, and that cleanly translates to atan2().- Parameters:
y
- y-component of the point to find the angle towards; note the parameter order is unusual by conventionx
- x-component of the point to find the angle towards; note the parameter order is unusual by convention- Returns:
- the angle to the given point, in degrees as a float; ranges from
-180
to180
-
atan2Deg360
public static float atan2Deg360(float y, float x)
Close approximation of the frequently-used trigonometric method atan2, using non-negative degrees only. Average absolute error is 0.00006045 degrees; relative error is 0 degrees; maximum error is 0.00011178 degrees. Takes y and x (in that unusual order) as floats, and returns the angle from the origin to that point in degrees.
This can be useful when a negative result from atan() would require extra work to handle.
Credit for this goes to the 1955 research study "Approximations for Digital Computers," by RAND Corporation. This is sheet 11's algorithm, which is the fourth-fastest and fourth-least precise. The algorithms on sheets 8-10 are faster, but only by a very small degree, and are considerably less precise. That study provides anatan(float)
method, and that cleanly translates to atan2Deg360().- Parameters:
y
- y-component of the point to find the angle towards; note the parameter order is unusual by conventionx
- x-component of the point to find the angle towards; note the parameter order is unusual by convention- Returns:
- the angle to the given point, in degrees as a float; ranges from
0
to360
-
acos
public static float acos(float a)
Returns acos in radians; less accurate than Math.acos but may be faster. Average error of 0.00002845 radians (0.0016300649 degrees), largest error of 0.000067548 radians (0.0038702153 degrees). This implementation does not return NaN if given an out-of-range input (Math.acos does return NaN), unless the input is NaN.- Parameters:
a
- acos is defined only when a is between -1f and 1f, inclusive- Returns:
- between
0
andPI
when a is in the defined range
-
asin
public static float asin(float a)
Returns asin in radians; less accurate than Math.asin but may be faster. Average error of 0.000028447 radians (0.0016298931 degrees), largest error of 0.000067592 radians (0.0038727364 degrees). This implementation does not return NaN if given an out-of-range input (Math.asin does return NaN), unless the input is NaN.- Parameters:
a
- asin is defined only when a is between -1f and 1f, inclusive- Returns:
- between
-HALF_PI
andHALF_PI
when a is in the defined range
-
atan
public static float atan(float i)
Arc tangent approximation with very low error, using an algorithm from the 1955 research study "Approximations for Digital Computers," by RAND Corporation (this is sheet 11's algorithm, which is the fourth-fastest and fourth-least precise). This method is usually about 4x faster thanMath.atan(double)
, but is somewhat less precise than Math's implementation. For finite inputs only, you may get a tiny speedup by usingatanUnchecked(double)
, but this method will be correct enough for infinite inputs, and atanUnchecked() will not be.- Parameters:
i
- an input to the inverse tangent function; any float is accepted- Returns:
- an output from the inverse tangent function, from
-HALF_PI
toHALF_PI
inclusive - See Also:
If you know the input will be finite, you can use atanUnchecked() instead.
-
asinDeg
public static float asinDeg(float a)
Returns arcsine in degrees. This implementation does not return NaN if given an out-of-range input (Math.asin does return NaN), unless the input is NaN.- Parameters:
a
- asin is defined only when a is between -1f and 1f, inclusive- Returns:
- between
-90
and90
when a is in the defined range
-
acosDeg
public static float acosDeg(float a)
Returns arccosine in degrees. This implementation does not return NaN if given an out-of-range input (Math.acos does return NaN), unless the input is NaN.- Parameters:
a
- acos is defined only when a is between -1f and 1f, inclusive- Returns:
- between
0
and180
when a is in the defined range
-
atanDeg
public static float atanDeg(float i)
Arc tangent approximation returning a value measured in positive or negative degrees, using an algorithm from the 1955 research study "Approximations for Digital Computers," by RAND Corporation (this is sheet 11's algorithm, which is the fourth-fastest and fourth-least precise). For finite inputs only, you may get a tiny speedup by usingatanUncheckedDeg(double)
, but this method will be correct enough for infinite inputs, and atanUnchecked() will not be.- Parameters:
i
- an input to the inverse tangent function; any float is accepted- Returns:
- an output from the inverse tangent function in degrees, from
-90
to90
inclusive - See Also:
If you know the input will be finite, you can use atanUncheckedDeg() instead.
-
random
public static int random(int range)
Returns a random number between 0 (inclusive) and the specified value (inclusive).
-
random
public static int random(int start, int end)
Returns a random number between start (inclusive) and end (inclusive).
-
random
public static long random(long range)
Returns a random number between 0 (inclusive) and the specified value (inclusive).
-
random
public static long random(long start, long end)
Returns a random number between start (inclusive) and end (inclusive).
-
randomBoolean
public static boolean randomBoolean()
Returns a random boolean value.
-
randomBoolean
public static boolean randomBoolean(float chance)
Returns true if a random value between 0 and 1 is less than the specified value.
-
random
public static float random()
Returns random number between 0.0 (inclusive) and 1.0 (exclusive).
-
random
public static float random(float range)
Returns a random number between 0 (inclusive) and the specified value (exclusive).
-
random
public static float random(float start, float end)
Returns a random number between start (inclusive) and end (exclusive).
-
randomSign
public static int randomSign()
Returns -1 or 1, randomly.
-
randomTriangular
public static float randomTriangular()
Returns a triangularly distributed random number between -1.0 (exclusive) and 1.0 (exclusive), where values around zero are more likely.This is an optimized version of
randomTriangular(-1, 1, 0)
-
randomTriangular
public static float randomTriangular(float max)
Returns a triangularly distributed random number between-max
(exclusive) andmax
(exclusive), where values around zero are more likely.This is an optimized version of
randomTriangular(-max, max, 0)
- Parameters:
max
- the upper limit
-
randomTriangular
public static float randomTriangular(float min, float max)
Returns a triangularly distributed random number betweenmin
(inclusive) andmax
(exclusive), where themode
argument defaults to the midpoint between the bounds, giving a symmetric distribution.This method is equivalent of
randomTriangular(min, max, (min + max) * 0.5f)
- Parameters:
min
- the lower limitmax
- the upper limit
-
randomTriangular
public static float randomTriangular(float min, float max, float mode)
Returns a triangularly distributed random number betweenmin
(inclusive) andmax
(exclusive), where values aroundmode
are more likely.- Parameters:
min
- the lower limitmax
- the upper limitmode
- the point around which the values are more likely
-
nextPowerOfTwo
public static int nextPowerOfTwo(int value)
Returns the next power of two. Returns the specified value if the value is already a power of two.
-
isPowerOfTwo
public static boolean isPowerOfTwo(int value)
-
clamp
public static short clamp(short value, short min, short max)
-
clamp
public static int clamp(int value, int min, int max)
-
clamp
public static long clamp(long value, long min, long max)
-
clamp
public static float clamp(float value, float min, float max)
-
clamp
public static double clamp(double value, double min, double max)
-
lerp
public static float lerp(float fromValue, float toValue, float progress)
Linearly interpolates between fromValue to toValue on progress position.
-
norm
public static float norm(float rangeStart, float rangeEnd, float value)
Linearly normalizes value from a range. Range must not be empty. This is the inverse oflerp(float, float, float)
.- Parameters:
rangeStart
- Range start normalized to 0rangeEnd
- Range end normalized to 1value
- Value to normalize- Returns:
- Normalized value. Values outside of the range are not clamped to 0 and 1
-
map
public static float map(float inRangeStart, float inRangeEnd, float outRangeStart, float outRangeEnd, float value)
Linearly map a value from one range to another. Input range must not be empty. This is the same as chainingnorm(float, float, float)
from input range andlerp(float, float, float)
to output range.- Parameters:
inRangeStart
- Input range startinRangeEnd
- Input range endoutRangeStart
- Output range startoutRangeEnd
- Output range endvalue
- Value to map- Returns:
- Mapped value. Values outside of the input range are not clamped to output range
-
lerpAngle
public static float lerpAngle(float fromRadians, float toRadians, float progress)
Linearly interpolates between two angles in radians. Takes into account that angles wrap at two pi and always takes the direction with the smallest delta angle.- Parameters:
fromRadians
- start angle in radianstoRadians
- target angle in radiansprogress
- interpolation value in the range [0, 1]- Returns:
- the interpolated angle in the range [0, PI2[
-
lerpAngleDeg
public static float lerpAngleDeg(float fromDegrees, float toDegrees, float progress)
Linearly interpolates between two angles in degrees. Takes into account that angles wrap at 360 degrees and always takes the direction with the smallest delta angle.- Parameters:
fromDegrees
- start angle in degreestoDegrees
- target angle in degreesprogress
- interpolation value in the range [0, 1]- Returns:
- the interpolated angle in the range [0, 360[
-
floor
public static int floor(float value)
Returns the largest integer less than or equal to the specified float. This method will only properly floor floats from -(2^14) to (Float.MAX_VALUE - 2^14).
-
floorPositive
public static int floorPositive(float value)
Returns the largest integer less than or equal to the specified float. This method will only properly floor floats that are positive. Note this method simply casts the float to int.
-
ceil
public static int ceil(float value)
Returns the smallest integer greater than or equal to the specified float. This method will only properly ceil floats from -(2^14) to (Float.MAX_VALUE - 2^14).
-
ceilPositive
public static int ceilPositive(float value)
Returns the smallest integer greater than or equal to the specified float. This method will only properly ceil floats that are positive.
-
round
public static int round(float value)
Returns the closest integer to the specified float. This method will only properly round floats from -(2^14) to (Float.MAX_VALUE - 2^14).
-
roundPositive
public static int roundPositive(float value)
Returns the closest integer to the specified float. This method will only properly round floats that are positive.
-
isZero
public static boolean isZero(float value)
Returns true if the value is zero (using the default tolerance as upper bound)
-
isZero
public static boolean isZero(float value, float tolerance)
Returns true if the value is zero.- Parameters:
tolerance
- represent an upper bound below which the value is considered zero.
-
isEqual
public static boolean isEqual(float a, float b)
Returns true if a is nearly equal to b. The function uses the default floating error tolerance.- Parameters:
a
- the first value.b
- the second value.
-
isEqual
public static boolean isEqual(float a, float b, float tolerance)
Returns true if a is nearly equal to b.- Parameters:
a
- the first value.b
- the second value.tolerance
- represent an upper bound below which the two values are considered equal.
-
log
public static float log(float a, float value)
- Returns:
- the logarithm of value with base a
-
log2
public static float log2(float value)
- Returns:
- the logarithm of value with base 2
-
-