# TkMath Documentation Main Page

TkMath is a plugin library for the Tks Script Engine

As not every Application needs a sophisticated math library loaded, it was decided to divide the provided methods from the Core. This Documentation will provide you with a detailed description of how to install and use this library.

1. ## What does it provide?

2. ## Prerequisites

3. ## How to install TkMath?

   - Linux
   - Windows

4. ## Generic compile time problems

   - #include <yac.h> not found
   - #include <complex> not found

5. ## How to check if TkMath is working?

6. ## How to use TkMath?

7. ## The API of TkMath

   1. Common Scalar Functions
   2. Single Precision Complexf Class
   3. Single Precision Vector2f Class
   4. Single Precision Vector3f Class
   5. Single Precision Vector4f Class
   6. Single Precision Matrix2f Class
   7. Single Precision Matrix3f Class
   8. Single Precision Matrix4f Class

8. ## Alphabetical Index of API functions, methods and properties

9. ## Authors

1. ## What does it provide?

   The TkMath Plugin provides with several kinds of Tools. First and foremost it expands the Core with scalar trigonometric and hyperbolic functions as well as the usual exp, log, pow etc methods found in common math libraries.

   As an extension it also provides Classes for easy usage of Vector and Complex Number Mathematics.

   It provides Vector2f, Vector3f and Vector4f for single precision Vector Mathematics

   It provides Complexf for single precision complex calculation.

   It provides Matrix2f, Matrix3f and Matrix4f for single precision advanced Vector Mathematics.

2. ## Prerequisites

   To compile and use TkMath you need first of all the TKS SDK, please see the following paragraph on how to install it.

   First you need a supported C++ Compiler like GCC, VisualC or the Intel C Compiler. Additional libraries needed are:

   - zlib
   - C++ Standard Library Components (should come with your compiler)

   as core requirements

   Additional plugins (not required for tkmath) need the following

   - libSDL and development files for tksdl
   - libSDL_net and development files for tksdl
   - OpenGL library and development files for tkopengl
   - libglu and development files for tkopengl
   - freetype2 for tkfreetype2

   TkMath itself has no further requirements than the standard math library.

3. ## How to install TkMath?

   - ### Linux

     Download the library from http://tkscript.de/files/tkmath.zip or get the development version from http://tkscript.de/files/current/tkmath.zip

     If you have the TKS SDK already installed, you can omit the next steps, change to your TKS SDK directory , and go on unzipping tkmath.zip.

     Make sure that you also have the latest tkscript installed, download the Linux Installation Shell file and run

     `sh install_linux.sh compile`

     and after that

     `sudo sh install_linux.sh install`

     if you don't want or can't install it as root user, make sure that you have LD_LIBRARY_PATH set to the library directory and the have the Path to the binary include in your PATH environment variable.

     Now unzip tkmath.zip into your TKS Development Direcotry you just prepared

     `unzip <PATH_TO_ARCHIVE>/tkmath.zip`

     Now you can enter the directoy and compile tkmath:

     `cd tkmath; make -f makefile.linux clean shared`

     If all went fine, it will look like this:

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c commonmath.cpp -o commonmath.o -I../yac`

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c vector2f.cpp -o vector2f.o -I../yac`

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c matrix2f.cpp -o matrix2f.o -I../yac`

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c complexf.cpp -o complexf.o -I../yac`

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c vector3f.cpp -o vector3f.o -I../yac`

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c matrix3f.cpp -o matrix3f.o -I../yac`

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c vector4f.cpp -o vector4f.o -I../yac`

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c matrix4f.cpp -o matrix4f.o -I../yac`

     `c++ -O3 -Wall -fPIC -g -DDX_USE_C99_COMPLEX -c tkmath.cpp -o tkmath.o -I../yac`

     `c++ -shared -o tkmath.so commonmath.o vector2f.o matrix2f.o complexf.o vector3f.o matrix3f.o vector4f.o matrix4f.o tkmath.o -Wl,-soname,tkmath.so -lm`

     `Build finished at 16:17.`

     When no error appeared, you can go on and install the library to your TKS Installation:

     `sudo make -f makefile.linux install`

     That's it! You are done now and can go on using TkMath.

     If not, please contact us.

   - ### Windows

     Hier darfst du tippern :P

4. ## Generic compile time problems

   If you encounter problems with compilation, you may check here if your problem is known and solved.

   - ### #include <yac.h> is not found

     Please make sure that your parent directoy structure is the one from your TKS SDK, as it looks for the YAC interface in ../yac

   - ### #include <complex> not found, or some problem appears with complex<float>/complex<double> datatype or some accompanying support function like std::sin, std::sqrt etc

     Your system c++ library has bad/no support for the complex datatype template. You can use the alternative implementation in TkMath through editing the appropriate makefile/projectfile and make sure that -DDX_USE_C99_COMPLEX is changed to -UDX_USE_C99_COMPLEX

5. ## How to check if TkMath is working?

   If you want to check if TkMath is working correctly, download first the TkUnit plugin, unzip to your TKS SDK directory and install it. After you are ready, change into the tkmath/math-unittests directory and run

   `tks math-unittests`

   If all is fine with your installation, the last line should print out a big "OK" on your console. After running this, you will also have an updated math_unittests_results.html, which will inform you about what was tested with what kind of result.

6. ## How to use TkMath?

   Usage of TkMath especially and TkScript as a whole is really intuitive and easy. Just look at the following example: of hello_complex.tks:

   `use tkmath;`

   `module Main;`

   `Complex2f a=[1.0,0]; //we dont want a zero element,``a` `s we want to chang` `e polar coordinates on a circle`

   `a.r=5; //we want a radius of 5`

   `a.a=M_PI; // we want an angle of PI`

   `print "Hello Complex Value, your content is "+a;`

   After saving this into hello_complex.tks, you can easily execute it now with

   `tks hello_complex.tks`

   and you will get

   `user@host:~/tks/tkmath/doc-examples$ tks hello_complex.tks`

   `Hello Complex Value, your content is (-5+i*-4.37114e-07)`

   Now you have run your first TKS Script using a TkMath Class, Conagrats!

7. ## The API of TkMath

   This is a list of categories of methods and function which are supplied by TkMath. All Classes share the ability of memory pooling and also support serialisation through the YAC Interface.

   The following semantics will be used through the API description:

   - Class:method(x)

     The method is to be used with instantiated values only.

     Example:

     Complex:mulConj(Complexf) returns float

     `Complexf a=[1,2],b=[3.4];`

     `trace "a*b_conjugated="+a.mulConj(b); //result is 11`

   - Class.Method(x)

     These are static methods available directly from the class itself.

     Example:

     Complex.New(float, float) returns Complexf

     `Complexf a<=Complexf.New(1,2);`

   - function(x)

     These functions are globally available.

     Example:

     sinf(float) returns float

     `trace "sin(0.5*pi)="+sinf(0.5*M_PI);`

   - <type> Class:value

     These are accessible elements of type <type>. They can be either Read/Write, Read Only or Write Only!

     Examples;

     float Complexf:x

     float Complexf:y

     String Complexf:string

     `Complexf a=[1,2];`

     `a.x=a.x+a.y; //Read/Write`

     `trace "a="+a.string; //this is a readonly property!`

   The API supports the generic RVAL/RARG/RSELF mechanism from tkscript where appropriated. So you can choose to work on the instance itself, copy to another value or use another instance as return object.

   Example:

   `Vector2f v<=vector2f(3,4);`

   RSELF:

   `v.unit(); //saves the normalised value in v`

   RVAL:

   `Vector2f r=v.unit(); //copies the normalised value in r, v unchanged`

   The target class of r can be different to v.

   RARG:

   `Vector2f r;`

   `v.unit() => r; //directly writes the normalised value into r, v unchanged`

   The target class type of r must be the same of the return value (in this example Vector2f).

   Methods with an RSELF implementation return the same class type of the instance called (see *:unit() as example), while methods without an RSELF implementation usually return a different class type (see Matrix*:mulv() as example).

   Please click on the links to find out more about the choosen category!

   1. ### Common Scalar Functions

      1. Common constants known to the core
      2. Common single precision support functions
         1. absf(float) returns float
         2. ceilf(float) returns float
         3. roundf(float) returns float
         4. floorf(float) returns float
         5. modf(float, float) returns float
      3. Single precision log and exp functions
         1. sqrtf(float) returns float
         2. powf(float, float) returns float
         3. expf(float) returns float
         4. exp2f(float) returns float
         5. exp10f(float) returns float
         6. logf(float) returns float
         7. log2f(float) returns float
         8. log10f(float) returns float
      4. Single precision trigonometric functions
         1. sinf(float) returns float
         2. cosf(float) returns float
         3. tanf(float) returns float
         4. asinf(float) returns float
         5. acosf(float) returns float
         6. atanf(float) returns float
         7. atan2f(float, float) returns float
         8. hypotf(float, float) returns float
      5. Single precision hyperbolic functions
         1. sinhf(float) returns float
         2. coshf(float) returns float
         3. tanhf(float) returns float
         4. asinhf(float) returns float
         5. acoshf(float) returns float
         6. atanhf(float) returns float

   2. ### Single Precision Complexf Class

      1. Initialisation of values
         1. Complexf:init(float, float)
         2. Complexf:initPolar(float, float)
         3. Complexf.New(float, float) returns Complexf
         4. Complexf.NewPolar(float, float) returns Complexf
         5. complexf(float, float) returns Complexf
         6. complexfPolar(float, float) returns Complexf
         7. Direct access to elements
            - float Complexf:x
            - float Complexf:y
            - float Complexf:r
            - float Complexf:a
            - String Complexf:string
            - String Complexf:polarString
            - float Complexf:abs
            - float Complexf:absSqr
         8. Importing values from other classes
      2. Operator support
      3. Array support
      4. Supplemental methods
         1. Complexf:add(Complexf)
         2. Complexf:sub(Complexf)
         3. Complexf:mulf(float)
         4. Complexf:mul(Complexf)
         5. Complexf:mulConj(Complexf)
         6. Complexf:div(Complexf)
         7. Complexf:invert()
         8. Complexf:unit()
         9. Complexf:unitScale(float)
      5. Complexf functions
         1. Complexf logarithms and exponential functions
            1. sqrtcf(Complexf) returns Complexf
            2. powcf(Complexf, Complexf) returns Complexf
            3. expcf(Complexf) returns Complexf
            4. logcf(Complexf) returns Complexf
         2. Complexf trigonometric functions
            1. sincf(Complexf) returns Complexf
            2. coscf(Complexf) returns Complexf
            3. tancf(Complexf) returns Complexf
            4. asincf(Complexf) returns Complexf
            5. acoscf(Complexf) returns Complexf
            6. atancf(Complexf) returns Complexf
         3. Complexf hyperbolic functions
            1. sinhcf(Complexf) returns Complexf
            2. coshcf(Complexf) returns Complexf
            3. tanhcf(Complexf) returns Complexf
            4. asinhcf(Complexf) returns Complexf
            5. acoshcf(Complexf) returns Complexf
            6. atanhcf(Complexf) returns Complexf

   3. ### Single Precision Vector2f Class

   4. ### Single Precision Vector3f Class

   5. ### Single Precision Vector4f Class

   6. ### Single Precision Matrix2f Class

   7. ### Single Precision Matrix3f Class

   8. ### Single Precision Matrix4f Class

8. ## Alphabetical Index of API functions, methods and properties

   absf

   acoscf

   acosf

   acoshcf

   acoshf

   asincf

   asinf

   asinhcf

   asinhf

   atancf

   atanf, atan2f

   atanhcf

   atanhf

   ceilf

   complexf

   coscf

   cosf

   coshcf

   coshf

   expcf

   expf, exp2f, exp10f

   floorf

   hypotf

   logcf

   logf, log2f, log10f

   modf

   powcf

   powf

   roundf

   sincf

   sinf

   sinhcf

   sinhf

   sqrtcf

   sqrtf

   tancf

   tanf

   tanhcf

   tanhf

   Complexf:a

   Complexf:abs

   Complexf:absSqr

   Complexf:add

   Complexf:div

   Complexf:init

   Complexf:initPolar

   Complexf:invert

   Complexf:mul

   Complexf:mulConj

   Complexf:mulf

   Complexf.New

   Complexf.NewPolar

   Complexf:polarString

   Complexf:r

   Complexf:string

   Complexf:sub

   Complexf:unit

   Complexf:unitScale

   Complexf:x

   Complexf:y

9. ## Authors

   This documentation and the plugin was written by

   - Carsten Busse <carsten.busse "at" gmail.com>
   - Bastian Spiegel <bs "at" tkscript.de>