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)