Skip to content

Commit

Permalink
Updated readme
Browse files Browse the repository at this point in the history
  • Loading branch information
matthiasferch committed Sep 15, 2018
1 parent 099b610 commit 82f1496
Showing 1 changed file with 21 additions and 87 deletions.
108 changes: 21 additions & 87 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,126 +1,60 @@
TSM: A Typescript vector and matrix math library
tsm: A Typescript vector and matrix math library
=================================================

TSM is a a collection of vector and matrix classes written in Microsoft's new Javascript superset *Typescript*, which compiles to plain Javascript. The library's design is influenced by both [gl-matrix](https://github.com/toji/gl-matrix) and [GLM](https://github.com/g-truc/glm).
tsm is a a collection of vector and matrix classes written in Typescript. The library's design is influenced by both [gl-matrix](https://github.com/toji/gl-matrix) and [glm](https://github.com/g-truc/glm).

What's special about TSM?
What's special about tsm?
-------------------------

- TSM makes use of Typescript's type annotations to reduce the number of possible bugs.
- tsm makes use of Typescript's type annotations to reduce the number of possible bugs.

- TSM makes use of Javascript's new property definitions to enable GLSL-style swizzle operators:
- tsm makes use of Javascript's new property definitions to enable GLSL-style swizzle operators:

var v1 = new TSM.vec2();
var q1 = new TSM.quat();
var v1 = new vec2();
var q1 = new quat();

v1.xy = [0, 1];
q1.w = 1.0;

- TSM offers both non-static and static methods for many operations:
- tsm offers both non-static and static methods for many operations:

var v1 = new TSM.vec3([1, 2, 3]);
var v2 = new TSM.vec3([4, 5, 6]);
var v1 = new vec3([1, 2, 3]);
var v2 = new vec3([4, 5, 6]);

var v3 = TSM.vec3.sum(v1, v2);
var v3 = vec3.sum(v1, v2);
var v4 = v1.copy().add(v2);

console.log(v3.equals(v4)); // output: "true"


Building TSM
------------

This project includes a solution file for *Visual Studio 2012*. It also works with the free Express version of *Visual Studio 2012 for the Web*, which can be downloaded for free from the Microsoft website. Please install the *Typescript plugin for Visual Studio 2012* to get syntax highlighting and IntelliSense support: http://www.microsoft.com/en-us/download/details.aspx?id=34790.

If you do not want to or cannot use Visual Studio, you can use the command line tool which comes with the plugin instead:

tsc --target "ES5" --out "tsm-[x.y].js" -sourcemap -declarations tsm.ts
java -jar ../closure-compiler.jar < tsm-[x.y].js > tsm-[x.y].min.js

The *target* parameter is necessary for the swizzle operators (.xyz, etc.) to work.

After successful compilation, four files will be created:

- *tsm-[x.y].js:*
The compiled Javascript source, readable
- *tsm-[x.y].min.js:*
The compiled Javascript source, minified
- *tsm-[x.y].d.ts:*
The Typescript declarations file, which contains a listing of all classes and methods
- *tsm-[x.y].js.map:*
A source map which maps the compiled JavaScript output to the original Typescript source files


Using TSM
---------

### In Visual Studio

You can use a reference comment to the declarations file or a module import to get access to TSM classes.

**Reference comment:**

///<reference path='./path/to/TSM/tsm-[x.y].d.ts' />

**Module import:**

import TSM = module("path/to/TSM")

### In Javascript

If you want to use the generated JavaScript instead, simply load the compiled .js or .min.js file by use of a script tag:

<script src="/path/to/TSM/tsm-[x.y].js"></script>


Testing TSM
-----------

The solution contains a test application. Open *TSM/Test/index.html* in a browser and bring up the console. You should see the following output:

vec2(1,2,3) + vec2(4,5,6) = vec2(5,7,9)

Perspective projection, 45° FOV:
mat4([
2.4142136573791504, 0, 0, 0
0, 2.4142136573791504, 0, 0
0, 0, -1.0202020406723022, -1
0, 0, -2.0202019214630127, 0
]);

vec3(90,0,0).toQuat() = quat(0.8509035110473633,0,0,0.5253219604492188)

If instead you receive an error message along the lines of "TSM is not defined", please make sure that your script tags are properly set up.


General design notes
--------------------

Swizzle operators return numeric arrays, not vector instances:

var v = new TSM.vec4([1, 2, 3, 4]);
var v = new vec4([1, 2, 3, 4]);
var n = v.xyz; // n = [1, 2, 3]

If, instead, you want to create a new instance of a vector or a matrix, use the copy() method:

var v1 = new TSM.vec4([1, 2, 3, 4]);
var v1 = new vec4([1, 2, 3, 4]);
var v2 = v1.copy();

You can also initialize a new vector with the values of another:

var v1 = new TSM.vec4([1, 2, 3, 4]);
var v2 = new TSM.vec4(v1.xyzw);
var v1 = new vec4([1, 2, 3, 4]);
var v2 = new vec4(v1.xyzw);

Or copy the values of one vector to another using the swizzle operators or the copy() method:

v2.xyzw = v1.xyzw; // same as v1.copy(v2)

The four basic arithmetic operations can be performed on vector instances or using static methods:

var v1 = new TSM.vec4([1, 2, 3, 4]);
var v2 = new TSM.vec4([5, 6, 7, 8]);
var v1 = new vec4([1, 2, 3, 4]);
var v2 = new vec4([5, 6, 7, 8]);

var v3 = TSM.vec4.product(v1, v2); // returns a new vec4 instance
var v3 = vec4.product(v1, v2); // returns a new vec4 instance

v1.multiply(v2); // writes the result of the multiplication into v1
v2.multiply(v1); // writes the result of the multiplication into v2
Expand All @@ -129,12 +63,12 @@ The reason for all of these different ways of doing the same thing is that objec

For this reason, static methods offer an optional destination parameter:

var v3 = TSM.vec3.cross(v1, v2) // allocates a new instance of vec3
var v3 = vec3.cross(v1, v2) // allocates a new instance of vec3

is the same as:

var v3 = new TSM.vec3();
TSM.vec3.cross(v1, v2, v3) // writes into the existing instance
var v3 = new vec3();
vec3.cross(v1, v2, v3) // writes into the existing instance

Matrices do not have swizzle operators. Instead, they provide the all(), row() and col() methods:

Expand Down

0 comments on commit 82f1496

Please sign in to comment.