SGScript eXtended Game Math library

Table of Contents

Description

The goal of this library is to provide the mathematical objects commonly used in games:

The library is compiled to a 'sgsxgmath' shared library so it can be included this way (assuming that, on Linux and similar systems, LD_LIBRARY_PATH is set correctly): 

include "sgsxgmath";

It is extremely important that only one instance of this library is loaded in the application for constant sharing to enable object interface recognition.

SGScript API

Objects:

Functions:

vec2 [object]

vec2.rotate [method]

vec2.rotate( real angle )

return vec2, rotated by angle in radians

vec2 [function]

vec2( real x[, real y ])

create a vec2 value from 1 - 2 real values

vec2_dot [function]

vec2_dot( vec2 v1, vec2 v2 )

return the dot product of both vectors

vec3 [object]

vec3 [function]

vec3( real x[, real y[, real z ]])

create a vec3 value from 1 or 3 real values

vec3_dot [function]

vec3_dot( vec3 v1, vec3 v2 )

return the dot product of both vectors

vec3_cross [function]

vec3_cross( vec3 v1, vec3 v2 )

return the cross product of both vectors

vec4 [object]

vec4 [function]

vec4( real x[, real y[, real z[, real w ]]])

create a vec4 value from 1, 2 or 4 real values

vec4_dot [function]

vec4_dot( vec4 v1, vec4 v2 )

return the dot product of both vectors

aabb2 [object]

In this object, assume 1 = min and 2 = max.

aabb2.expand( ... ) [function]

aabb2.expand( ... )

include other vec2/aabb2 items in current AABB

aabb2 [function]

aabb2( real x1, real y1, real x2, real y2 )

create a 2D AABB object from 4 real values

aabb2v [function]

aabb2v( vec2 p1, vec2 p2 )

create a 2D AABB object from 2 vec2 values

aabb2_intersect [function]

aabb2_intersect( aabb2 bb1, aabb2 bb2 )

check if two AABBs intersect

aabb3 [object]

In this object, assume 1 = min and 2 = max.

aabb3.expand( ... ) [function]

aabb3.expand( ... )

include other vec3/aabb3 items in current AABB

aabb3 [function]

aabb3( real x1, real y1, real x2, real y2 )

create a 2D AABB object from 4 real values

aabb3v [function]

aabb3v( vec3 p1, vec3 p2 )

create a 2D AABB object from 2 vec3 values

aabb3_intersect [function]

aabb3_intersect( aabb3 bb1, aabb3 bb2 )

check if two AABBs intersect

color [object]

color [function]

color( real r[, real g[, real b[, real a ]]])

create a color value from 1 to 4 real values

quat [object]

A quaternion 

quat(<x>;<y>;<z>|<w>)

quat.identity [method]

quat.identity()

set the quaternion to identity

quat.multiply [method]

quat.multiply( quat m )

multiply this quaternion and another quaternion, putting the other quaternion on the right side of multiplication

quat.multiply_left [method]

quat.multiply_left( quat m )

multiply this quaternion and another quaternion, putting the other quaternion on the left side of multiplication

quat.multiply2 [method]

quat.multiply2( quat m1, quat m2 )

multiply two matrices into this quaternion

quat.invert [method]

quat.invert()

invert this quaternion into itself

quat.invert_from [method]

quat.invert_from( quat m )

invert another quaternion into this quaternion

quat.rotateX [method]

quat.rotateX( real a[, bool reset ])

generate a rotation quaternion (rotation around X axis) and multiply or set it to this quaternion

quat.rotateY [method]

quat.rotateY( real a[, bool reset ])

generate a rotation quaternion (rotation around Y axis) and multiply or set it to this quaternion

quat.rotateZ [method]

quat.rotateZ( real a[, bool reset ])

generate a rotation quaternion (rotation around Z axis) and multiply or set it to this quaternion

quat.rotate_axis_angle [method]

quat.rotate_axis_angle( real x, real y, real z, real a[, bool reset ])

generate a rotation quaternion (rotation around specified axis) and multiply or set it to this quaternion

quat.rotate_axis_angle_v3 [method]

quat.rotate_axis_angle( vec3 v, real a[, bool reset ])

generate a rotation quaternion (rotation around specified axis) and multiply or set it to this quaternion

quat.transform [method]

quat.transform( vec3 v )

multiply a 3D vector by this quaternion

quat [function]

quat( real v[4] )

create a quaternion from 4 real values

mat3 [object]

A 3x3 column-major matrix 

mat3
(
	<m00> <m10> <m20>
	<m01> <m11> <m21>
	<m02> <m12> <m22>
)

mat3.identity [method]

mat3.identity()

set the matrix to identity

mat3.multiply [method]

mat3.multiply( mat3 m )

multiply this matrix and another matrix, putting the other matrix on the right side of multiplication

mat3.multiply_left [method]

mat3.multiply_left( mat3 m )

multiply this matrix and another matrix, putting the other matrix on the left side of multiplication

mat3.multiply2 [method]

mat3.multiply2( mat3 m1, mat3 m2 )

multiply two matrices into this matrix

mat3.transpose [method]

mat3.transpose()

transpose this matrix into itself

mat3.transpose_from [method]

mat3.transpose_from( mat3 m )

transpose another matrix into this matrix

mat3.invert [method]

mat3.invert()

invert this matrix into itself, return if successful

mat3.invert_from [method]

mat3.invert_from( mat3 m )

invert another matrix into this matrix

mat3.rotateX [method]

mat3.rotateX( real a[, bool reset ])

generate a rotation matrix (rotation around X axis) and multiply or set it to this matrix

mat3.rotateY [method]

mat3.rotateY( real a[, bool reset ])

generate a rotation matrix (rotation around Y axis) and multiply or set it to this matrix

mat3.rotateZ [method]

mat3.rotateZ( real a[, bool reset ])

generate a rotation matrix (rotation around Z axis) and multiply or set it to this matrix

mat3.rotate_axis_angle [method]

mat3.rotate_axis_angle( real x, real y, real z, real a[, bool reset ])

generate a rotation matrix (rotation around specified axis) and multiply or set it to this matrix

mat3.rotate_axis_angle_v3 [method]

mat3.rotate_axis_angle( vec3 v, real a[, bool reset ])

generate a rotation matrix (rotation around specified axis) and multiply or set it to this matrix

mat3.scale [method]

mat3.scale( real x, real y, real z[, bool reset ])

generate a scale matrix and multiply or set it to this matrix

mat3.scale_v3 [method]

mat3.scale_v3( vec3 v[, bool reset ])

generate a scale matrix and multiply or set it to this matrix

mat3.transform [method]

mat3.transform( vec3 v )

multiply a 3D vector by this matrix

mat3 [function]

mat3( mat3 m )

copy the matrix

mat3( vec3 row1, vec3 row2, vec3 row3 )

create a matrix from 3 rows

mat3( real v[9] )

create a matrix from 9 real values

mat4 [object]

A 4x4 column-major matrix 

mat4
(
	<m00> <m10> <m20> <m30>
	<m01> <m11> <m21> <m31>
	<m02> <m12> <m22> <m32>
	<m03> <m13> <m23> <m33>
)

mat4.identity [method]

mat4.identity()

set the matrix to identity

mat4.multiply [method]

mat4.multiply( mat4 m )

multiply this matrix and another matrix, putting the other matrix on the right side of multiplication

mat4.multiply_left [method]

mat4.multiply_left( mat4 m )

multiply this matrix and another matrix, putting the other matrix on the left side of multiplication

mat4.multiply2 [method]

mat4.multiply2( mat4 m1, mat4 m2 )

multiply two matrices into this matrix

mat4.transpose [method]

mat4.transpose()

transpose this matrix into itself

mat4.transpose_from [method]

mat4.transpose_from( mat4 m )

transpose another matrix into this matrix

mat4.invert [method]

mat4.invert()

invert this matrix into itself, return if successful

mat4.invert_from [method]

mat4.invert_from( mat4 m )

invert another matrix into this matrix

mat4.translate [method]

mat4.translate( real x, real y, real z[, bool reset ])

generate a translation matrix and multiply or set it to this matrix

mat4.translate_v3 [method]

mat4.translate_v3( vec3 v[, bool reset ])

generate a translation matrix and multiply or set it to this matrix

mat4.rotateX [method]

mat4.rotateX( real a[, bool reset ])

generate a rotation matrix (rotation around X axis) and multiply or set it to this matrix

mat4.rotateY [method]

mat4.rotateY( real a[, bool reset ])

generate a rotation matrix (rotation around Y axis) and multiply or set it to this matrix

mat4.rotateZ [method]

mat4.rotateZ( real a[, bool reset ])

generate a rotation matrix (rotation around Z axis) and multiply or set it to this matrix

mat4.rotate_axis_angle [method]

mat4.rotate_axis_angle( real x, real y, real z, real a[, bool reset ])

generate a rotation matrix (rotation around specified axis) and multiply or set it to this matrix

mat4.rotate_axis_angle_v3 [method]

mat4.rotate_axis_angle( vec3 v, real a[, bool reset ])

generate a rotation matrix (rotation around specified axis) and multiply or set it to this matrix

mat4.scale [method]

mat4.scale( real x, real y, real z[, bool reset ])

generate a scale matrix and multiply or set it to this matrix

mat4.scale_v3 [method]

mat4.scale_v3( vec3 v[, bool reset ])

generate a scale matrix and multiply or set it to this matrix

mat4.transform [method]

mat4.transform( vec4 v )

multiply a 4D vector by this matrix

mat4.transform_pos [method]

mat4.transform_pos( vec3 v )

multiply a 3D position vector by this matrix

mat4.transform_normal [method]

mat4.transform_normal( vec3 v )

multiply a 3D normal vector by this matrix

mat4 [function]

mat4( mat4 m )

copy the matrix

mat4( vec4 row1, vec4 row2, vec4 row3[, vec4 row4 ])

create a matrix from 3 or 4 rows

mat4( real v[16] )

create a matrix from 16 real values

floatarray [object]

floatarray data transformation methods

floatarray.clear [method]

floatarray.clear()

set all values to 0

for more info, refer to this page: floatarray data transformation methods

floatarray.set1 [method]

floatarray.set1()

set all values to 1

for more info, refer to this page: floatarray data transformation methods

floatarray.negate [method]

floatarray.negate()

swap the sign on all values

for more info, refer to this page: floatarray data transformation methods

floatarray.assign [method]

floatarray.assign( s1 )

copy values from another source

for more info, refer to this page: floatarray data transformation methods

floatarray.negate_from [method]

floatarray.negate_from( s1 )

copy negated values from another source

for more info, refer to this page: floatarray data transformation methods

floatarray.*[_assign] (add|sub|mul|div|mod|pow) [methods]

floatarray.add( s1, s2 )

add values from two sources to this floatarray (this = s1 + s2)

floatarray.sub( s1, s2 )

subtract values from two sources to this floatarray (this = s1 - s2)

floatarray.mul( s1, s2 )

multiply values from two sources to this floatarray (this = s1 * s2)

floatarray.div( s1, s2 )

divide values from two sources to this floatarray (this = s1 / s2)

floatarray.mod( s1, s2 )

set modulo from two sources to this floatarray (this = s1 % s2)

floatarray.pow( s1, s2 )

set power of two sources to this floatarray (this = s1 ^ s2)

floatarray.add_assign( s1 )

add values from another source to floatarray (this = this + s1)

floatarray.sub_assign( s1 )

subtract values from another source to floatarray (this = this - s1)

floatarray.mul_assign( s1 )

subtract values from another source to floatarray (this = this * s1)

floatarray.div_assign( s1 )

subtract values from another source to floatarray (this = this / s1)

floatarray.mod_assign( s1 )

subtract values from another source to floatarray (this = this % s1)

floatarray.pow_assign( s1 )

subtract values from another source to floatarray (this = this ^ s1)

for more info, refer to this page: floatarray data transformation methods

floatarray.randbox [method]

floatarray.randbox( s1, s2 )

set values to random between two sources (this = lerp( s1, s2, randf() ))

for more info, refer to this page: floatarray data transformation methods

floatarray.randext [method]

floatarray.randext( s1, s2 )

set values to random around source 1 in the range of source 2 (this = lerp( s1 - s2, s1 + s2, randf() ))

for more info, refer to this page: floatarray data transformation methods

floatarray.multiply_add_assign [method]

floatarray.multiply_add_assign( s1, s2 )

multiply two sources and add the result to this one (this += s1 * s2)

for more info, refer to this page: floatarray data transformation methods

floatarray.lerp_to [method]

floatarray.lerp_to( s1, s2 )

linearly interpolate this source and another to the factor of the third one (this = lerp( this, s1, s2 ))

for more info, refer to this page: floatarray data transformation methods

floatarray.to_*_buffer [method]

floatarray.to_int8_buffer( real scale = 1 )

floatarray.to_int16_buffer( real scale = 1 )

floatarray.to_int32_buffer( real scale = 1 )

floatarray.to_int64_buffer( real scale = 1 )

floatarray.to_uint8_buffer( real scale = 1 )

floatarray.to_uint16_buffer( real scale = 1 )

floatarray.to_uint32_buffer( real scale = 1 )

floatarray.to_uint64_buffer( real scale = 1 )

floatarray.to_float32_buffer( real scale = 1 )

floatarray.to_float64_buffer( real scale = 1 )

create a byte buffer from floatarray contents, optionally scaling the values

floatarray_buffer [function]

floatarray_buffer( int size )

create a floatarray of the specified size, filled with zeroes

floatarray [function]

floatarray([ int/real v0, ... ])

create a floatarray from a list of int/real values

floatarray( array varr )

create a floatarray from an array of int/real values

vec2array [function]

vec2array([ int/real v0, ... ])

create a floatarray from a list of int/real values (must be a multiple of 2)

vec2array([ vec2 v0, ... ])

create a floatarray from a list of vec2 values

vec2array( array varr )

create a floatarray from an array of vec2 values

vec3array [function]

vec3array([ int/real v0, ... ])

create a floatarray from a list of int/real values (must be a multiple of 3)

vec3array([ vec3 v0, ... ])

create a floatarray from a list of vec3 values

vec3array( array varr )

create a floatarray from an array of vec3 values

vec4array [function]

vec4array([ int/real v0, ... ])

create a floatarray from a list of int/real values (must be a multiple of 4)

vec4array([ vec4 v0, ... ])

create a floatarray from a list of vec4 values

vec4array( array varr )

create a floatarray from an array of vec4 values

floatarray_from_*_buffer [function]

floatarray_from_int8_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_int16_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_int32_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_int64_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_uint8_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_uint16_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_uint32_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_uint64_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_float32_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

floatarray_from_float64_buffer( string buffer, scale = 1, stride = 1, offset = 0 )

create a floatarray from byte buffer, optionally specifying scale, stride and offset to first value

ray_plane_intersect [function]

ray_plane_intersect( vec3 ray_pos, vec3 ray_dir, vec4 plane )

tests for an intersection between ray and plane, returning all relevant output data

ray_sphere_intersect [function]

ray_sphere_intersect( vec3 ray_pos, vec3 ray_dir, vec3 sphere_pos, real radius )

tests for an intersection between ray and sphere, returning the distance

distance_lines [function]

distance_lines( vec3 a1, vec3 a2, vec3 b1, vec3 b2 )

returns distance between two straight lines, defined by two intersection points

This function may not return the expected result if either of the lines has zero length. In such cases, prefer using distance_point_line

distance_line_segments [function]

distance_line_segments( vec3 a1, vec3 a2, vec3 b1, vec3 b2 )

returns distance between two line segments

This function may not return the expected result if either of the lines has zero length. In such cases, prefer using distance_point_line_segment

distance_point_line [function]

distance_point_line( vec3 p, vec3 l1, vec3 l2 )

returns distance between point and a straight line, defined by two intersection points

distance_point_line_segment [function]

distance_point_line_segment( vec3 p, vec3 l1, vec3 l2 )

returns distance between point and a line segment

All SGScript objects (A-Z)

All SGScript functions (A-Z)

C API

xgm_vtarray [struct]

xgm_vtarray

floatarray data

xgm_*_iface [interfaces]

sgs_ObjInterface xgm_vec2_iface[1]

interface for vec2 objects

sgs_ObjInterface xgm_vec3_iface[1]

interface for vec3 objects

sgs_ObjInterface xgm_vec4_iface[1]

interface for vec4 objects

sgs_ObjInterface xgm_aabb2_iface[1]

interface for aabb2 objects

sgs_ObjInterface xgm_aabb3_iface[1]

interface for aabb3 objects

sgs_ObjInterface xgm_color_iface[1]

interface for color objects

sgs_ObjInterface xgm_mat4_iface[1]

interface for mat4 objects

sgs_ObjInterface xgm_floatarr_iface[1]

interface for floatarray objects

sgs_Create* [functions]

SGSONE sgs_CreateVec2( SGS_CTX, sgs_Variable* var, XGM_VT x, XGM_VT y )

SGSONE sgs_CreateVec3( SGS_CTX, sgs_Variable* var, XGM_VT x, XGM_VT y, XGM_VT z )

SGSONE sgs_CreateVec4( SGS_CTX, sgs_Variable* var, XGM_VT x, XGM_VT y, XGM_VT z, XGM_VT w )

SGSONE sgs_CreateAABB2( SGS_CTX, sgs_Variable* var, XGM_VT x1, XGM_VT y1, XGM_VT x2, XGM_VT y2 )

SGSONE sgs_CreateAABB3( SGS_CTX, sgs_Variable* var, const XGM_VT* v3f1, const XGM_VT* v3f2 )

SGSONE sgs_CreateColor( SGS_CTX, sgs_Variable* var, XGM_VT r, XGM_VT g, XGM_VT b, XGM_VT a )

SGSONE sgs_CreateQuat( SGS_CTX, sgs_Variable* var, XGM_VT x, XGM_VT y, XGM_VT z, XGM_VT w )

SGSONE sgs_CreateMat3( SGS_CTX, sgs_Variable* var, const XGM_VT* v9f, int transpose )

SGSONE sgs_CreateMat4( SGS_CTX, sgs_Variable* var, const XGM_VT* v16f, int transpose )

SGSONE sgs_CreateFloatArray( SGS_CTX, sgs_Variable* var, const XGM_VT* vfn, sgs_SizeVal size )

SGSONE sgs_CreateVec2p( SGS_CTX, sgs_Variable* var, const XGM_VT* v2f )

SGSONE sgs_CreateVec3p( SGS_CTX, sgs_Variable* var, const XGM_VT* v3f )

SGSONE sgs_CreateVec4p( SGS_CTX, sgs_Variable* var, const XGM_VT* v4f )

SGSONE sgs_CreateAABB2p( SGS_CTX, sgs_Variable* var, const XGM_VT* v4f )

SGSONE sgs_CreateAABB3p( SGS_CTX, sgs_Variable* var, const XGM_VT* v6f )

SGSONE sgs_CreateColorp( SGS_CTX, sgs_Variable* var, const XGM_VT* v4f )

SGSONE sgs_CreateColorvp( SGS_CTX, sgs_Variable* var, const XGM_VT* vf, int numfloats )

SGSONE sgs_CreateQuatp( SGS_CTX, sgs_Variable* var, const XGM_VT* v4f )

push/initialize a variable of the right type to the specified arguments

Notes:

sgs_Parse* [functions]

SGSBOOL sgs_ParseVT( SGS_CTX, sgs_StkIdx item, XGM_VT* out )

SGSBOOL sgs_ParseVec2( SGS_CTX, sgs_StkIdx item, XGM_VT* v2f, int strict )

SGSBOOL sgs_ParseVec3( SGS_CTX, sgs_StkIdx item, XGM_VT* v3f, int strict )

SGSBOOL sgs_ParseVec4( SGS_CTX, sgs_StkIdx item, XGM_VT* v4f, int strict )

SGSBOOL sgs_ParseAABB2( SGS_CTX, sgs_StkIdx item, XGM_VT* v4f )

SGSBOOL sgs_ParseAABB3( SGS_CTX, sgs_StkIdx item, XGM_VT* v6f )

SGSBOOL sgs_ParseColor( SGS_CTX, sgs_StkIdx item, XGM_VT* v4f, int strict )

SGSBOOL sgs_ParseQuat( SGS_CTX, sgs_StkIdx item, XGM_VT* v4f, int strict )

SGSBOOL sgs_ParseMat3( SGS_CTX, sgs_StkIdx item, XGM_VT* v9f )

SGSBOOL sgs_ParseMat4( SGS_CTX, sgs_StkIdx item, XGM_VT* v16f )

SGSBOOL sgs_ParseFloatArray( SGS_CTX, sgs_StkIdx item, XGM_VT** vfa, sgs_SizeVal* osz )

parse the specified stack item to retrieve object data

sgs_ArgCheck_* [functions]

int sgs_ArgCheck_Vec2( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_Vec3( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_Vec4( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_AABB2( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_AABB3( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_Color( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_Quat( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_Mat3( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_Mat4( SGS_CTX, int argid, va_list* args, int flags )

int sgs_ArgCheck_FloatArray( SGS_CTX, int argid, va_list* args, int flags )

argument parsing functions for sgs_LoadArgs* function family

All C interfaces (A-Z)

All C functions (A-Z)