math
****

This module provides mathematical utilities, including fixed-point numbers, sin, cos & div lookup tables, 2D vectors and rectangles.

Fixed-Point Numbers
===================

Fixed-point arithmetic allows you to treat some integer as if it were fractional, which is much faster than using floats on the GBA.

The `Fixed` type makes working with *'24.8'* fixed-point values most convenient. These can be created using the `fp` template. For example:

.. code-block:: nim

  let a = fp(1.25)
  let b = fp(8.5)
  assert a + b == fp(9.75)

..
  (maybe I shouldn't actually document this cause it sucks)
  
  In Nim 1.6 and later, the `'fp` suffix can also be used:

  .. code-block:: nim
    
    let x = 3.5'fp

Working at other precisions can be done with the `FixedN` type, and using a different underlying integer type is supported with `FixedT`.

These are created with the `toFixed` template:

.. code-block:: nim
  
  let k = (1.5).toFixed(int8, 4)  # an 8-bit value with 4 bits of precision
  
  static:
    echo typeof(k)  # prints "FixedT[int8, 4]"

Types
-----
.. autonim:: private.types.FixedT
.. autonim:: private.types.FixedN
.. autonim:: private.types.Fixed

Conversion Templates
--------------------
.. autonim:: math.fp
.. autonim:: math.toFixed
.. autonim:: math.toFixed_2
.. autonim:: math.toFixed_3
.. autonim:: math.toInt
.. autonim:: math.toFloat32
.. autonim:: math.raw

Arithmetic Operators
--------------------

The basic operators available to fixed-point numbers are given below. These are implemented as templates to encourage the Nim compiler to evaluate them at compile-time.

.. note::

  There are operators defined between fixed-point and integer types, so `fp(0.5) * 2` is allowed, and will give a fixed-point result.

  However, there are no implicit `converters <https://nim-lang.org/docs/manual.html#converters>`_ defined, and you can't mix fixed-point types of differing size and precision.

  To add two fixed-point numbers of different precision together, one must be converted to the other:

  .. code-block:: nim

    let a = fp(0.5)               # 8 bits precision
    let b = (0.5).toFixed(10)     # 10 bits precision
    
    # let sum1 = a + b            # Not allowed!
    
    let sum2 = a + fp(b)          # Ok, both 8 fractional bits
    let sum3 = a.toFixed(10) + b  # Ok, both 10 fractional bits


.. container:: group

  .. autonim:: math.`+`
  .. autonim:: math.`-`
  .. autonim:: math.`*`
  .. autonim:: math.`/`
  .. autonim:: math.`==`
  .. autonim:: math.`<`
  .. autonim:: math.`<=`
  .. autonim:: math.`+`_2
  .. autonim:: math.`-`_2
  .. autonim:: math.`+=`
  .. autonim:: math.`-=`
  .. autonim:: math.`*=`
  .. autonim:: math.`/=`
  .. autonim:: math.`+`_3
  .. autonim:: math.`-`_3
  .. autonim:: math.`*`_2
  .. autonim:: math.`/`_2
  .. autonim:: math.`+`_4
  .. autonim:: math.`-`_4
  .. autonim:: math.`*`_3
  .. autonim:: math.`==`_2
  .. autonim:: math.`<`_2
  .. autonim:: math.`<=`_2
  .. autonim:: math.`==`_3
  .. autonim:: math.`<`_3
  .. autonim:: math.`<=`_3
  .. autonim:: math.`+=`_2
  .. autonim:: math.`-=`_2
  .. autonim:: math.`*=`_2
  .. autonim:: math.`/=`_2
  .. autonim:: math.`shr`
  .. autonim:: math.`shl`

.. autonim:: math.mul64
.. autonim:: math.div64
.. autonim:: math.abs

-----------------------------

General Math Functions
======================

.. autonim:: math.flr
.. autonim:: math.ceil

.. nim:proc:: sgn[T: SomeNumber](x: T): int {.inline.}
  
  Get the sign of a number.
  
  Returns `-1` when `x` is negative, `1` when `x` is positive, or `0` when `x` is `0`.
  
  (This procedure comes from the Nim standard library.)
  
  
.. autonim:: math.sgn
.. autonim:: math.sgn2
.. autonim:: math.approach
.. autonim:: math.lerp

-----------------------------

Lookup Tables
=============
.. autonim:: math.Angle
.. autonim:: math.luSin
.. autonim:: math.luCos
.. autonim:: math.luDiv
.. autonim:: math.luLerp

-----------------------------

2D Vectors
==========
.. autonim:: math.Vec2i
.. autonim:: math.Vec2f
.. autonim:: math.vec2i
.. autonim:: math.vec2i_2
.. autonim:: math.vec2i_3
.. autonim:: math.vec2f
.. autonim:: math.vec2f_2
.. autonim:: math.vec2f_3
.. autonim:: math.`+`_5
.. autonim:: math.`-`_5
.. autonim:: math.`*`_4
.. autonim:: math.`*`_5
.. autonim:: math.`*`_6
.. autonim:: math.`/`_3
.. autonim:: math.`/`_4
.. autonim:: math.`/`_5
.. autonim:: math.dot
.. autonim:: math.`-`_6
.. autonim:: math.`+=`_3
.. autonim:: math.`-=`_3
.. autonim:: math.`*=`_3
.. autonim:: math.`*=`_4
.. autonim:: math.`/=`_3
.. autonim:: math.`/=`_4
.. autonim:: math.`+`_5
.. autonim:: math.`-`_7
.. autonim:: math.`*`_7
.. autonim:: math.`*`_8
.. autonim:: math.`*`_9
.. autonim:: math.`/`_6
.. autonim:: math.`/`_7
.. autonim:: math.`/`_8
.. autonim:: math.dot
.. autonim:: math.`-`_8
.. autonim:: math.`+=`_3
.. autonim:: math.`-=`_3
.. autonim:: math.`*=`_5
.. autonim:: math.`/=`_5
.. autonim:: math.`*=`_6
.. autonim:: math.`/=`_6

Vector Conversion
-----------------
.. autonim:: math.initBgPoint
.. autonim:: math.toBgPoint
.. autonim:: math.toBgPoint_2

-----------------------------

Rectangles
==========

.. autonim:: math.Rect
.. autonim:: math.rectBounds
.. autonim:: math.rectAt
.. autonim:: math.x
.. autonim:: math.y
.. autonim:: math.w
.. autonim:: math.h
.. autonim:: math.width
.. autonim:: math.height
.. autonim:: math.`x=`
.. autonim:: math.`y=`
.. autonim:: math.`w=`
.. autonim:: math.`h=`
.. autonim:: math.`width=`
.. autonim:: math.`height=`
.. autonim:: math.move
.. autonim:: math.move_2
.. autonim:: math.inflate
.. autonim:: math.inflate_2
.. autonim:: math.center
.. autonim:: math.`center=`
.. autonim:: math.topLeft
.. autonim:: math.topRight
.. autonim:: math.bottomLeft
.. autonim:: math.bottomRight