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


color [object]


color [function]

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

create a color value from 1 to 4 real values


mat4 [object]

A 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


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_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_Init* [functions]

void sgs_InitVec2( SGS_CTX, sgs_Variable* var, XGM_VT x, XGM_VT y )

void sgs_InitVec3( SGS_CTX, sgs_Variable* var, XGM_VT x, XGM_VT y, XGM_VT z )

void sgs_InitVec4( SGS_CTX, sgs_Variable* var, XGM_VT x, XGM_VT y, XGM_VT z, XGM_VT w )

void sgs_InitAABB2( SGS_CTX, sgs_Variable* var, XGM_VT x1, XGM_VT y1, XGM_VT x2, XGM_VT y2 )

void sgs_InitColor( SGS_CTX, sgs_Variable* var, XGM_VT r, XGM_VT g, XGM_VT b, XGM_VT a )

void sgs_InitMat4( SGS_CTX, sgs_Variable* var, const XGM_VT* v16f, int transpose )

void sgs_InitFloatArray( SGS_CTX, sgs_Variable* var, const XGM_VT* vfn, sgs_SizeVal size )

void sgs_InitVec2p( SGS_CTX, sgs_Variable* var, const XGM_VT* v2f )

void sgs_InitVec3p( SGS_CTX, sgs_Variable* var, const XGM_VT* v3f )

void sgs_InitVec4p( SGS_CTX, sgs_Variable* var, const XGM_VT* v4f )

void sgs_InitAABB2p( SGS_CTX, sgs_Variable* var, const XGM_VT* v4f )

void sgs_InitColorp( SGS_CTX, sgs_Variable* var, const XGM_VT* v4f )

void sgs_InitColorvp( SGS_CTX, sgs_Variable* var, const XGM_VT* vf, int numfloats )

initialize a variable of the right type to the specified arguments

Notes:


sgs_Push* [functions]

void sgs_PushVec2( SGS_CTX, XGM_VT x, XGM_VT y )

void sgs_PushVec3( SGS_CTX, XGM_VT x, XGM_VT y, XGM_VT z )

void sgs_PushVec4( SGS_CTX, XGM_VT x, XGM_VT y, XGM_VT z, XGM_VT w )

void sgs_PushAABB2( SGS_CTX, XGM_VT x1, XGM_VT y1, XGM_VT x2, XGM_VT y2 )

void sgs_PushColor( SGS_CTX, XGM_VT r, XGM_VT g, XGM_VT b, XGM_VT a )

void sgs_PushMat4( SGS_CTX, const XGM_VT* v16f, int transpose )

void sgs_PushFloatArray( SGS_CTX, const XGM_VT* vfn, sgs_SizeVal size )

void sgs_PushVec2p( SGS_CTX, const XGM_VT* v2f )

void sgs_PushVec3p( SGS_CTX, const XGM_VT* v3f )

void sgs_PushVec4p( SGS_CTX, const XGM_VT* v4f )

void sgs_PushAABB2p( SGS_CTX, const XGM_VT* v4f )

void sgs_PushColorp( SGS_CTX, const XGM_VT* v4f )

void sgs_PushColorvp( SGS_CTX, const XGM_VT* vf, int numfloats )

push a new variable on stack of the right type, initialized to the specified arguments

For notes, refer to sgs_Init*


sgs_Parse* [functions]

SGSBOOL sgs_ParseVTP( SGS_CTX, sgs_Variable* var, XGM_VT* out )

SGSBOOL sgs_ParseVec2P( SGS_CTX, sgs_Variable* var, XGM_VT* v2f, int strict )

SGSBOOL sgs_ParseVec3P( SGS_CTX, sgs_Variable* var, XGM_VT* v3f, int strict )

SGSBOOL sgs_ParseVec4P( SGS_CTX, sgs_Variable* var, XGM_VT* v4f, int strict )

SGSBOOL sgs_ParseAABB2P( SGS_CTX, sgs_Variable* var, XGM_VT* v4f )

SGSBOOL sgs_ParseColorP( SGS_CTX, sgs_Variable* var, XGM_VT* v4f, int strict )

SGSBOOL sgs_ParseMat4P( SGS_CTX, sgs_Variable* var, XGM_VT* v16f )

SGSBOOL sgs_ParseFloatArrayP( SGS_CTX, sgs_Variable* var, XGM_VT** vfa, sgs_SizeVal* osz )

parse the specified variable to retrieve object data

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_ParseColor( SGS_CTX, sgs_StkIdx item, XGM_VT* v4f, int strict )

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_Color( 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


SGS_RETURN_* [functions]

SGS_RETURN_VEC2( XGM_VT x, XGM_VT y )

SGS_RETURN_VEC3( XGM_VT x, XGM_VT y, XGM_VT z )

SGS_RETURN_VEC4( XGM_VT x, XGM_VT y, XGM_VT z, XGM_VT w )

SGS_RETURN_AABB2( XGM_VT x1, XGM_VT y1, XGM_VT x2, XGM_VT y2 )

SGS_RETURN_COLOR( XGM_VT r, XGM_VT g, XGM_VT b, XGM_VT a )

SGS_RETURN_VEC2P( XGM_VT* v2f )

SGS_RETURN_VEC3P( XGM_VT* v3f )

SGS_RETURN_VEC4P( XGM_VT* v4f )

SGS_RETURN_AABB2P( XGM_VT* v4f )

SGS_RETURN_COLORP( XGM_VT* v4f )

SGS_RETURN_MAT4( XGM_VT* v16f )

push the specified value and return SGS_SUCCESS


SGS_PARSE_* [functions]

SGS_PARSE_VEC2( outptr, strict )

SGS_PARSE_VEC3( outptr, strict )

SGS_PARSE_VEC4( outptr, strict )

SGS_PARSE_AABB2( outptr )

SGS_PARSE_COLOR( outptr, strict )

SGS_PARSE_MAT4( outptr )

parse input variable in a SETINDEX object interface function


All C interfaces (A-Z)


All C functions (A-Z)