math3d
[math]

3D Mathematics functions More...

Classes
struct	__vec3f
	3D point or vector More...
struct	__vec4f
	4D vector More...
struct	GF_Matrix
	3D matrix More...
struct	GF_BBox
	3D Bounding Box More...
struct	GF_Plane
	Plane object. More...
struct	GF_Ray
	3D Ray More...
Defines
#define	gf_vec_equal(v1, v2)
#define	gf_vec_rev(v)
#define	gf_vec_diff(res, v1, v2)
#define	gf_vec_add(res, v1, v2)
#define	gf_quat_len(v)
#define	gf_quat_norm(v)
#define	gf_mx_init(_obj)
	matrix initialization
#define	gf_mx_copy(_obj, from)
	matrix copy
Typedefs
typedef struct __vec3f	GF_Vec
	3D point or vector
typedef struct __vec4f	GF_Vec4
	4D vector
Enumerations
enum	{ GF_BBOX_FRONT, GF_BBOX_INTER, GF_BBOX_BACK }
Functions
Fixed	gf_vec_len (GF_Vec v)
	get 3D vector length
Fixed	gf_vec_lensq (GF_Vec v)
	get 3D vector square length
Fixed	gf_vec_dot (GF_Vec v1, GF_Vec v2)
	get 3D vector dot product
void	gf_vec_norm (GF_Vec *v)
	vector normalization
GF_Vec	gf_vec_scale (GF_Vec v, Fixed f)
	vector scaling
GF_Vec	gf_vec_cross (GF_Vec v1, GF_Vec v2)
	vector cross product
GF_Vec4	gf_quat_to_rotation (GF_Vec4 *quat)
	quaternion to rotation
GF_Vec4	gf_quat_from_rotation (GF_Vec4 rot)
	quaternion from rotation
GF_Vec4	gf_quat_get_inv (GF_Vec4 *quat)
GF_Vec4	gf_quat_multiply (GF_Vec4 *q1, GF_Vec4 *q2)
	quaternion multiplication
GF_Vec	gf_quat_rotate (GF_Vec4 *quat, GF_Vec *vec)
	quaternion vector rotating
GF_Vec4	gf_quat_from_axis_cos (GF_Vec axis, Fixed cos_a)
	quaternion from axis and cos
GF_Vec4	gf_quat_slerp (GF_Vec4 q1, GF_Vec4 q2, Fixed frac)
	quaternion interpolation
void	gf_bbox_refresh (GF_BBox *b)
void	gf_bbox_from_rect (GF_BBox *box, GF_Rect *rc)
void	gf_rect_from_bbox (GF_Rect *rc, GF_BBox *box)
void	gf_bbox_grow_point (GF_BBox *box, GF_Vec pt)
	bounding box expansion
void	gf_bbox_union (GF_BBox *b1, GF_BBox *b2)
Bool	gf_bbox_equal (GF_BBox *b1, GF_BBox *b2)
Bool	gf_bbox_point_inside (GF_BBox *box, GF_Vec *p)
void	gf_bbox_get_vertices (GF_Vec bmin, GF_Vec bmax, GF_Vec *vecs)
	get box vertices
void	gf_mx_from_mx2d (GF_Matrix *mx, GF_Matrix2D *mat2D)
	matrix constructor from 2D
Bool	gf_mx_equal (GF_Matrix *mx1, GF_Matrix *mx2)
	matrix identity testing
void	gf_mx_add_translation (GF_Matrix *mx, Fixed tx, Fixed ty, Fixed tz)
	matrix translation
void	gf_mx_add_scale (GF_Matrix *mx, Fixed sx, Fixed sy, Fixed sz)
	matrix scaling
void	gf_mx_add_rotation (GF_Matrix *mx, Fixed angle, Fixed x, Fixed y, Fixed z)
	matrix rotating
void	gf_mx_add_matrix (GF_Matrix *mx, GF_Matrix *mul)
	matrices multiplication
void	gf_mx_add_matrix_2d (GF_Matrix *mx, GF_Matrix2D *mat2D)
	2D matrix multiplication
void	gf_mx_inverse (GF_Matrix *mx)
	affine matrix inversion
void	gf_mx_apply_vec (GF_Matrix *mx, GF_Vec *pt)
	matrix point transformation
void	gf_mx_apply_rect (GF_Matrix *_this, GF_Rect *rc)
	matrix rectangle transformation
void	gf_mx_ortho (GF_Matrix *mx, Fixed left, Fixed right, Fixed bottom, Fixed top, Fixed z_near, Fixed z_far)
	ortho matrix construction
void	gf_mx_perspective (GF_Matrix *mx, Fixed foc, Fixed aspect_ratio, Fixed z_near, Fixed z_far)
	perspective matrix construction
void	gf_mx_lookat (GF_Matrix *mx, GF_Vec position, GF_Vec target, GF_Vec up_vector)
	creates look matrix
void	gf_mx_apply_bbox (GF_Matrix *mx, GF_BBox *b)
	matrix box transformation
void	gf_mx_apply_bbox_sphere (GF_Matrix *mx, GF_BBox *box)
	matrix box sphere transformation
void	gf_mx_add_matrix_4x4 (GF_Matrix *mat, GF_Matrix *mul)
	non-affine matrix multiplication
Bool	gf_mx_inverse_4x4 (GF_Matrix *mx)
	non-affine matrix inversion
void	gf_mx_apply_vec_4x4 (GF_Matrix *mx, GF_Vec4 *vec)
	matrix 4D vector transformation
void	gf_mx_decompose (GF_Matrix *mx, GF_Vec *translate, GF_Vec *scale, GF_Vec4 *rotate, GF_Vec *shear)
	matrix decomposition
void	gf_mx_rotate_vector (GF_Matrix *mx, GF_Vec *pt)
	matrix vector rotation
void	gf_mx_rotation_matrix_from_vectors (GF_Matrix *mx, GF_Vec x_axis, GF_Vec y_axis, GF_Vec z_axis)
	matrix initialization from vectors
void	gf_mx2d_from_mx (GF_Matrix2D *mx2d, GF_Matrix *mx)
	matrix to 2D matrix
void	gf_mx_apply_plane (GF_Matrix *mx, GF_Plane *plane)
	matrix plane transformation
Fixed	gf_plane_get_distance (GF_Plane *plane, GF_Vec *p)
	point to plane distance
GF_Vec	gf_closest_point_to_line (GF_Vec line_pt, GF_Vec line_vec, GF_Vec pt)
	closest point on a line
u32	gf_plane_get_p_vertex_idx (GF_Plane *p)
	box p-vertex index
Bool	gf_plane_intersect_line (GF_Plane *plane, GF_Vec *linepoint, GF_Vec *linevec, GF_Vec *outPoint)
	plane line intersection
u32	gf_bbox_plane_relation (GF_BBox *box, GF_Plane *p)
	box-plane relation
GF_Ray	gf_ray (GF_Vec start, GF_Vec end)
	ray constructor
void	gf_mx_apply_ray (GF_Matrix *mx, GF_Ray *r)
	matrix ray transformation
Bool	gf_ray_hit_box (GF_Ray *ray, GF_Vec min_edge, GF_Vec max_edge, GF_Vec *out_point)
	ray box intersection test
Bool	gf_ray_hit_sphere (GF_Ray *ray, GF_Vec *center, Fixed radius, GF_Vec *out_point)
	ray sphere intersection test
Bool	gf_ray_hit_triangle (GF_Ray *ray, GF_Vec *v0, GF_Vec *v1, GF_Vec *v2, Fixed *dist)
	ray triangle intersection test
Bool	gf_ray_hit_triangle_backcull (GF_Ray *ray, GF_Vec *v0, GF_Vec *v1, GF_Vec *v2, Fixed *dist)
	ray triangle intersection test

---

Detailed Description

This section documents mathematic tools for 3D geometry operations

---

Define Documentation

#define gf_vec_equal	(	v1,
		v2		)

macro evaluating to 1 if vectors are equal, 0 otherwise

#define gf_vec_rev

(

v

)

macro reversing a vector v = v

#define gf_vec_diff	(	res,
		v1,
		v2		)

macro performing the minus operation res = v1 - v2

#define gf_vec_add	(	res,
		v1,
		v2		)

macro performing the add operation res = v1 + v2

#define gf_quat_len

(

v

)

gets the len of a quaternion

#define gf_quat_norm

(

v

)

normalizes a quaternion

#define gf_mx_init

(

_obj

)

Inits the matrix to the identity matrix

#define gf_mx_copy	(	_obj,
		from		)

Copies the matrix _from to the matrix _obj

---

Typedef Documentation

typedef struct __vec3f GF_Vec

The 3D point object is used in all the GPAC framework for both point and vector representation.

typedef struct __vec4f GF_Vec4

The 4D vector object is used in all the GPAC framework for 4 dimension vectors, VRML Rotations and quaternions representation.

---

Enumeration Type Documentation

anonymous enum

Classification types for box/plane position used in gf_bbox_plane_relation

Enumerator:

GF_BBOX_FRONT	box is in front of the plane
GF_BBOX_INTER	box intersects the plane
GF_BBOX_BACK	box is back of the plane

---

Function Documentation

Fixed gf_vec_len

(

GF_Vec

v

)

Gets the length of a 3D vector

Returns:

length of the vector

Fixed gf_vec_lensq

(

GF_Vec

v

)

Gets the square length of a 3D vector

Returns:

square length of the vector

Fixed gf_vec_dot	(	GF_Vec	v1,
		GF_Vec	v2
	)

Gets the dot product of two vectors

Returns:

dot product of the vectors

void gf_vec_norm

(

GF_Vec *

v

)

Norms the vector, eg make its length equal to FIX_ONE

Parameters:

v

vector to normalize

GF_Vec gf_vec_scale	(	GF_Vec	v,
		Fixed	f
	)

Scales a vector by a given amount

Parameters:

v

vector to scale Parameters: f  scale factor Returns: scaled vector

GF_Vec gf_vec_cross	(	GF_Vec	v1,
		GF_Vec	v2
	)

Gets the cross product of two vectors

Parameters:

v1

first vector Parameters: v2  second vector Returns: cross-product vector

GF_Vec4 gf_quat_to_rotation

(

GF_Vec4 *

quat

)

Transforms a quaternion to a Rotation, expressed as a 4 dimension vector with x,y,z for axis and q for rotation angle

Parameters:

quat

the quaternion to transform Returns: the rotation value

GF_Vec4 gf_quat_from_rotation

(

GF_Vec4

rot

)

Transforms a Rotation to a quaternion

Parameters:

rot

the rotation to transform Returns: the quaternion value

GF_Vec4 gf_quat_get_inv

(

GF_Vec4 *

quat

)

inverses a quaternion

GF_Vec4 gf_quat_multiply	(	GF_Vec4 *	q1,
		GF_Vec4 *	q2
	)

Multiplies two quaternions

Parameters:

q1

the first quaternion Parameters: q2  the second quaternion Returns: the resulting quaternion

GF_Vec gf_quat_rotate	(	GF_Vec4 *	quat,
		GF_Vec *	vec
	)

Rotates a vector with a quaternion

Parameters:

quat

the quaternion modelizing the rotation Parameters: vec  the vector to rotate Returns: the resulting vector

GF_Vec4 gf_quat_from_axis_cos	(	GF_Vec	axis,
		Fixed	cos_a
	)

Constructs a quaternion from an axis and a cosinus value (shortcut to gf_quat_from_rotation)

Parameters:

axis

the rotation axis Parameters: cos_a  the rotation cosinus value Returns: the resulting quaternion

GF_Vec4 gf_quat_slerp	(	GF_Vec4	q1,
		GF_Vec4	q2,
		Fixed	frac
	)

Interpolates two quaternions using spherical linear interpolation

Parameters:

q1

the first quaternion Parameters: q2  the second quaternion Parameters: frac  the fraction of the interpolation, between 0 and FIX_ONE Returns: the interpolated quaternion

void gf_bbox_refresh

(

GF_BBox *

b

)

updates information of the bounding box based on the edge information

void gf_bbox_from_rect	(	GF_BBox *	box,
		GF_Rect *	rc
	)

builds a bounding box from a 2D rectangle

void gf_rect_from_bbox	(	GF_Rect *	rc,
		GF_BBox *	box
	)

builds a rectangle from a 3D bounding box.

Note:

The z dimension is lost and no projection is performed

void gf_bbox_grow_point	(	GF_BBox *	box,
		GF_Vec	pt
	)

Checks if a point is inside a bounding box and updates the bounding box to include it if not the case

Parameters:

box

the bounding box object Parameters: pt  the 3D point to check

void gf_bbox_union	(	GF_BBox *	b1,
		GF_BBox *	b2
	)

performs the union of two bounding boxes

Bool gf_bbox_equal	(	GF_BBox *	b1,
		GF_BBox *	b2
	)

checks if two bounding boxes are equal or not

Bool gf_bbox_point_inside	(	GF_BBox *	box,
		GF_Vec *	p
	)

checks if a point is inside a bounding box or not

void gf_bbox_get_vertices	(	GF_Vec	bmin,
		GF_Vec	bmax,
		GF_Vec *	vecs
	)

Returns the 8 bounding box vertices given the minimum and maximum edge. Vertices are ordered to respect "p-vertex indexes", (vertex from a box closest to plane) and so that n-vertex (vertex from a box farthest from plane) is 7-p_vx_idx

Parameters:

bmin

minimum edge of the box Parameters: bmax  maximum edge of the box Parameters: vecs  list of 8 3D points used to store the vertices.

void gf_mx_from_mx2d	(	GF_Matrix *	mx,
		GF_Matrix2D *	mat2D
	)

Initializes a 3D matrix from a 2D matrix.

Note:

all z-related coefficients will be set to default.

Bool gf_mx_equal	(	GF_Matrix *	mx1,
		GF_Matrix *	mx2
	)

Tests if two matrices are equal or not.

Returns:

1 if matrices are same, 0 otherwise

void gf_mx_add_translation	(	GF_Matrix *	mx,
		Fixed	tx,
		Fixed	ty,
		Fixed	tz
	)

Translates a matrix

Parameters:

mx

the matrix being transformed. Once the function is called, contains the result matrix Parameters: tx  horizontal translation Parameters: ty  vertical translation Parameters: tz  depth translation

void gf_mx_add_scale	(	GF_Matrix *	mx,
		Fixed	sx,
		Fixed	sy,
		Fixed	sz
	)

Scales a matrix

Parameters:

mx

the matrix being transformed. Once the function is called, contains the result matrix Parameters: sx  horizontal translation scaling Parameters: sy  vertical translation scaling Parameters: sz  depth translation scaling

void gf_mx_add_rotation	(	GF_Matrix *	mx,
		Fixed	angle,
		Fixed	x,
		Fixed	y,
		Fixed	z
	)

Rotates a matrix

Parameters:

mx

the matrix being transformed. Once the function is called, contains the result matrix Parameters: angle  rotation angle in radians Parameters: x  horizontal coordinate of rotation axis Parameters: y  vertical coordinate of rotation axis Parameters: z  depth coordinate of rotation axis

void gf_mx_add_matrix	(	GF_Matrix *	mx,
		GF_Matrix *	mul
	)

Multiplies a matrix with another one mx = mx*mul

Parameters:

mx

the matrix being transformed. Once the function is called, contains the result matrix Parameters: mul  the matrix to add

void gf_mx_add_matrix_2d	(	GF_Matrix *	mx,
		GF_Matrix2D *	mat2D
	)

Adds a 2D affine matrix to a matrix

Parameters:

mx

the matrix Parameters: mat2D  the matrix to premultiply

void gf_mx_inverse

(

GF_Matrix *

mx

)

Inverses an affine matrix.

Warning:

Results are undefined if the matrix is not an affine one

Parameters:

mx

the matrix to inverse

void gf_mx_apply_vec	(	GF_Matrix *	mx,
		GF_Vec *	pt
	)

Applies a 3D matrix transformation to a 3D point

Parameters:

mx

transformation matrix Parameters: pt  pointer to 3D point. Once the function is called, pt contains the transformed point

void gf_mx_apply_rect	(	GF_Matrix *	_this,
		GF_Rect *	rc
	)

Applies a 3D matrix transformation to a rectangle, giving the enclosing rectangle of the transformed one.

Note:

all depth information are discarded.

Parameters:

_this

transformation matrix Parameters: rc  pointer to rectangle. Once the function is called, rc contains the transformed rectangle

void gf_mx_ortho	(	GF_Matrix *	mx,
		Fixed	left,
		Fixed	right,
		Fixed	bottom,
		Fixed	top,
		Fixed	z_near,
		Fixed	z_far
	)

Creates an orthogonal projection matrix

Parameters:

mx

matrix to initialize Parameters: left  min horizontal coordinate of viewport Parameters: right  max horizontal coordinate of viewport Parameters: bottom  min vertical coordinate of viewport Parameters: top  max vertical coordinate of viewport Parameters: z_near  min depth coordinate of viewport Parameters: z_far  max depth coordinate of viewport

void gf_mx_perspective	(	GF_Matrix *	mx,
		Fixed	foc,
		Fixed	aspect_ratio,
		Fixed	z_near,
		Fixed	z_far
	)

Creates a perspective projection matrix

Parameters:

mx

matrix to initialize Parameters: foc  camera field of view angle in radian Parameters: aspect_ratio  viewport aspect ratio Parameters: z_near  min depth coordinate of viewport Parameters: z_far  max depth coordinate of viewport

void gf_mx_lookat	(	GF_Matrix *	mx,
		GF_Vec	position,
		GF_Vec	target,
		GF_Vec	up_vector
	)

Creates a transformation matrix looking at a given direction from a given point (camera matrix).

Parameters:

mx

matrix to initialize Parameters: position  position Parameters: target  look direction Parameters: up_vector  vector describing the up direction

void gf_mx_apply_bbox	(	GF_Matrix *	mx,
		GF_BBox *	b
	)

Applies a 3D matrix transformation to a bounding box, giving the enclosing box of the transformed one

Parameters:

mx

transformation matrix Parameters: b  pointer to bounding box. Once the function is called, contains the transformed bounding box

void gf_mx_apply_bbox_sphere	(	GF_Matrix *	mx,
		GF_BBox *	box
	)

Applies a 3D matrix transformation to a bounding box, computing only the enclosing sphere of the transformed one.

Parameters:

mx

transformation matrix Parameters: b  pointer to bounding box. Once the function is called, contains the transformed bounding sphere

void gf_mx_add_matrix_4x4	(	GF_Matrix *	mat,
		GF_Matrix *	mul
	)

Multiplies two non-affine matrices mx = mx*mul

Bool gf_mx_inverse_4x4

(

GF_Matrix *

mx

)

Inverses a non-affine matrices

Returns:

1 if inversion was done, 0 if inversion not possible.

void gf_mx_apply_vec_4x4	(	GF_Matrix *	mx,
		GF_Vec4 *	vec
	)

Applies a 3D non-affine matrix transformation to a 4 dimension vector

Parameters:

mx

transformation matrix Parameters: vec  pointer to the vector. Once the function is called, contains the transformed vector

void gf_mx_decompose	(	GF_Matrix *	mx,
		GF_Vec *	translate,
		GF_Vec *	scale,
		GF_Vec4 *	rotate,
		GF_Vec *	shear
	)

Decomposes a matrix into translation, scale, shear and rotate

Parameters:

mx

the matrix to decompose Parameters: translate  the decomposed translation part Parameters: scale  the decomposed scaling part Parameters: rotate  the decomposed rotation part, expressed as a Rotataion (axis + angle) Parameters: shear  the decomposed shear part

void gf_mx_rotate_vector	(	GF_Matrix *	mx,
		GF_Vec *	pt
	)

Rotates a vector with a given matrix, ignoring any translation.

Parameters:

mx

transformation matrix Parameters: pt  pointer to 3D vector. Once the function is called, pt contains the transformed vector

void gf_mx_rotation_matrix_from_vectors	(	GF_Matrix *	mx,
		GF_Vec	x_axis,
		GF_Vec	y_axis,
		GF_Vec	z_axis
	)

Inits a matrix to rotate the local axis in the given vectors

Parameters:

mx

matrix to initialize Parameters: x_axis  target normalized X axis Parameters: y_axis  target normalized Y axis Parameters: z_axis  target normalized Z axis

void gf_mx2d_from_mx	(	GF_Matrix2D *	mx2d,
		GF_Matrix *	mx
	)

Inits a 2D matrix by removing all depth info from a 3D matrix

Parameters:

mx2d

2D matrix to initialize Parameters: mx  3D matrix to use

void gf_mx_apply_plane	(	GF_Matrix *	mx,
		GF_Plane *	plane
	)

Transorms a plane by a given matrix

Parameters:

mx

the matrix to use Parameters: plane  pointer to 3D plane. Once the function is called, plane contains the transformed plane

Fixed gf_plane_get_distance	(	GF_Plane *	plane,
		GF_Vec *	p
	)

Gets the distance between a point and a plne

Parameters:

plane

the plane to use Parameters: p  pointer to ^point to check Returns: the distance between the place and the point

GF_Vec gf_closest_point_to_line	(	GF_Vec	line_pt,
		GF_Vec	line_vec,
		GF_Vec	pt
	)

Gets the closest point on a line from a given point in space

Parameters:

line_pt

a point of the line to test Parameters: line_vec  the normalized direction vector of the line Parameters: pt  the point to check Returns: the closest point on the line to the desired point

u32 gf_plane_get_p_vertex_idx

(

GF_Plane *

p

)

Gets the p-vertex index for a given plane. The p-vertex index is the index of the closest vertex of a bounding box to the plane. The vertices of a box are always ordered in GPAC? cf gf_bbox_get_vertices

Parameters:

p

the plane to check Returns: the p-vertex index value, ranging from 0 to 7

Bool gf_plane_intersect_line	(	GF_Plane *	plane,
		GF_Vec *	linepoint,
		GF_Vec *	linevec,
		GF_Vec *	outPoint
	)

Checks for the intersection of a plane and a line

Parameters:

plane

plane to test Parameters: linepoint  a point on the line to test Parameters: linevec  normalized direction vector of the line to test Parameters: outPoint  optional pointer to retrieve the intersection point, NULL otherwise Returns: 1 if line and plane intersect, 0 otherwise

u32 gf_bbox_plane_relation	(	GF_BBox *	box,
		GF_Plane *	p
	)

Gets the spatial relation between a box and a plane

Parameters:

box

the box to check Parameters: p  the plane to check Returns: the relation type

GF_Ray gf_ray	(	GF_Vec	start,
		GF_Vec	end
	)

Constructs a ray object

Parameters:

start

starting point of the ray Parameters: end  end point of the ray, or any point on the ray Returns: the ray object

void gf_mx_apply_ray	(	GF_Matrix *	mx,
		GF_Ray *	r
	)

Transforms a ray by a given transformation matrix

Parameters:

mx

the matrix to use Parameters: r  pointer to the ray. Once the function is called, contains the transformed ray

Bool gf_ray_hit_box	(	GF_Ray *	ray,
		GF_Vec	min_edge,
		GF_Vec	max_edge,
		GF_Vec *	out_point
	)

Checks if a ray intersects a box or not

Parameters:

ray

the ray to check Parameters: min_edge  the minimum edge of the box to check Parameters: max_edge  the maximum edge of the box to check Parameters: out_point  optional location of a 3D point to store the intersection, NULL otherwise. Returns: retuns 1 if the ray intersects the box, 0 otherwise

Bool gf_ray_hit_sphere	(	GF_Ray *	ray,
		GF_Vec *	center,
		Fixed	radius,
		GF_Vec *	out_point
	)

Checks if a ray intersects a box or not

Parameters:

ray

the ray to check Parameters: center  the center of the sphere to check. If NULL, the origin (0,0,0)is used Parameters: radius  the radius of the sphere to check Parameters: out_point  optional location of a 3D point to store the intersection, NULL otherwise Returns: retuns 1 if the ray intersects the sphere, 0 otherwise

Bool gf_ray_hit_triangle	(	GF_Ray *	ray,
		GF_Vec *	v0,
		GF_Vec *	v1,
		GF_Vec *	v2,
		Fixed *	dist
	)

Checks if a ray intersects a triangle or not

Parameters:

ray

the ray to check Parameters: v0  first vertex of the triangle Parameters: v1  second vertex of the triangle Parameters: v2  third vertex of the triangle Parameters: dist  optional location of a fixed number to store the intersection distance from ray origin if any, NULL otherwise Returns: retuns 1 if the ray intersects the triangle, 0 otherwise

Bool gf_ray_hit_triangle_backcull	(	GF_Ray *	ray,
		GF_Vec *	v0,
		GF_Vec *	v1,
		GF_Vec *	v2,
		Fixed *	dist
	)

Checks if a ray intersects a triangle or not, performing backface culling. For parameters details, look at gf_ray_hit_triangle_backcull