Classes | Defines | Typedefs | Enumerations | Functions

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
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
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
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
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
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
q2 the second quaternion
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
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
bmax maximum edge of the box
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
tx horizontal translation
ty vertical translation
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
sx horizontal translation scaling
sy vertical translation scaling
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
angle rotation angle in radians
x horizontal coordinate of rotation axis
y vertical coordinate of rotation axis
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
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
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
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
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
left min horizontal coordinate of viewport
right max horizontal coordinate of viewport
bottom min vertical coordinate of viewport
top max vertical coordinate of viewport
z_near min depth coordinate of viewport
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
foc camera field of view angle in radian
aspect_ratio viewport aspect ratio
z_near min depth coordinate of viewport
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
position position
target look direction
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
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
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
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
translate the decomposed translation part
scale the decomposed scaling part
rotate the decomposed rotation part, expressed as a Rotataion (axis + angle)
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
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
x_axis target normalized X axis
y_axis target normalized Y axis
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
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
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
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
line_vec the normalized direction vector of the line
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
linepoint a point on the line to test
linevec normalized direction vector of the line to test
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
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
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
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
min_edge the minimum edge of the box to check
max_edge the maximum edge of the box to check
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
center the center of the sphere to check. If NULL, the origin (0,0,0)is used
radius the radius of the sphere to check
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
v0 first vertex of the triangle
v1 second vertex of the triangle
v2 third vertex of the triangle
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